You are on page 1of 376

TeamSite ®

Administration Guide
Release 6.7.1
Service Pack 1
Windows
© 1999-2007 Interwoven, Inc. All rights reserved.

No part of this publication (hardcopy or electronic form) may be reproduced or transmitted, in any form
or by any means, electronic, mechanical, photocopying, recording, or otherwise, without the prior
written consent of Interwoven. Information in this manual is furnished under license by Interwoven, Inc.
and may only be used in accordance with the terms of the license agreement. If this software or
documentation directs you to copy materials, you must first have permission from the copyright owner
of the materials to avoid violating the law which could result in damages or other remedies.

Interwoven, ConfirmSite, ControlHub, DataDeploy, DeskSite, FileSite, iManage, LiveSite, MediaBin,


MetaCode, MetaTagger, OffSite, OpenDeploy, Primera, TeamPortal, TeamSite, VisualAnnotate,
WorkDocs, WorkPortal, WorkRoute, WorkSite, WorkTeam, the respective taglines, logos and service
marks are trademarks of Interwoven, Inc., which may be registered in certain jurisdictions. All other
trademarks are owned by their respective owners. Some or all of the information contained herein may
be protected by patent numbers: US # 6,505,212, EP / ATRA / BELG / DENM / FINL / FRAN / GBRI /
GREC / IREL / ITAL / LUXE / NETH / PORT / SPAI / SWED / SWIT # 1053523, US # 6,480,944,
US# 5,845,270, US #5,384,867, US #5,430,812, US #5,754,704, US #5,347,600, AUS #735365, AU
7830068, GB #GB2333619, US #5,845,067, US #6,675,299, US #5,835,037, AUS #632333, CAN
#2,062,965, FRAN / GRBI / SPAI / SWED #480941, GERM #69020564.3, JAPA #2968582, MX
#219522, NZ #516340, SG #89006, SG #89086,# SG #74973, SG #85502 US #5,065,447, US
#6,609,184, US #6,141,017, US #5,990,950, US #5,821,999, US #5,805,217, US #5,838,832, US
#5,867,221, US #5,923,376, US #6,434,273, US #5,867,603, US #4,941,193, US #5,822,721, US
#5,923,785, US #5,982,938, US #5,790,131, US #5,721,543, US #5,982,441, US #5,857,036, US
#6,697,532, US #6,792, 454, US# 6,928,149, GERM #69902752.7 or other patents pending application
for Interwoven, Inc.

Interwoven, Inc.
803 11th Ave.
Sunnyvale, CA 94089

http://www.interwoven.com

TeamSite Administration Guide


Part 01-006-01-EN
August 2007
Table of Contents
List of Figures 13
List of Tables 15
About This Book 17
Notation Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .17
Path Name Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18
Default Paths . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .19
Online Documentation Errata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .19
What’s in This Manual . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .19
Chapter 1: TeamSite Overview 21
TeamSite Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .21
Content Stores . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .21
Branches. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .21
Workareas. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .22
Staging Areas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .22
Editions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .22
User Roles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .23
Reviewer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .24
Author . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .24
Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .24
Administrator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .25
Master . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .25
WorkflowUser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .25
WorkflowAdmin. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .25
TeamSite Workflow. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .25
Jobs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .26
Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .27
TeamSite Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .27
Understanding the TeamSite File System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .28
Specifying VPaths . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .30
Related Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .31
Chapter 2: Configuration File Overview 33
The iw.cfg File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .33
Location of iw.cfg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .34
The iw.cfg File Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .34
Additional Configuration Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .37
Chapter 3: Configuring the TeamSite Server 39
Configuring User Interface Functionality . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .39
Enabling and Disabling VisualPreview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .39
Configuring Domain Lists in the Login Screen . . . . . . . . . . . . . . . . . . . . . . . . . .40
Configuring Email Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .40
Specifying Valid Domains . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .41

TeamSite Administration Guide 3


Contents

Configuring Server Functionality . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .41


Controlling Modification Times . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .41
Modifying Extended Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .42
Specifying the Encoding of the iw.cfg File . . . . . . . . . . . . . . . . . . . . . . . . . . . . .42
Configuring the Web Daemon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .43
Changing the Servlet Engine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .43
Setting Locking Models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .44
Comparing Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .46
Submit and Update Logs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .46
Autoprivate Feature . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .46
Working with the Utility Service. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .49
Starting/Stopping the iwutild Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .50
Enabling the Event Subsystem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .51
Configuring the Event Subsystem Manually . . . . . . . . . . . . . . . . . . . . . . . . . . . .52
Using the Microsoft SQL Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .54
Configuring Server Performance. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .57
Cache Size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .57
External Task Impersonation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .58
Throughput Monitors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .58
Detecting Low Disk Space . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .59
Configuring the TeamSite Server Locale . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .59
Configuring FormsPublisher . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .60
Setting up the Example Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .60
FormsPublisher Settings in iw.cfg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .61
TeamSite Embedded Failsafe . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .62
Chapter 4: Managing the TeamSite Server 63
Verifying Server Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .64
Starting and Stopping the TeamSite Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .65
Checking Request Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .66
Verifying the Server Mount . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .66
Locating the Installation Directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .67
Reviewing TeamSite Log Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .67
Configuration Log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .67
Server Log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .67
Trace Log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .68
Events Log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .68
Workflow Log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .69
Windows Event Viewer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .69
Monitoring the Server Load . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .69
Reconfiguring iwwebd to Recognize a New IP Address . . . . . . . . . . . . . . . . . . . . . .70
Managing Disk Space . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .70
File Locations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .71
Enhancing File System Performance on the TeamSite Server . . . . . . . . . . . . . . .72
Monitoring Disk Space Usage. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .73
Deleting Editions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .74
Metadata Forking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .74
Moving the Content Store and Removing Old Versions . . . . . . . . . . . . . . . . . . . .75

Interwoven, Inc. 4
Contents

Chapter 5: Defining Users and Roles 77


User Roles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .79
Configuring Roles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .82
Managing Roles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .83
Creating New Roles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .84
Editing Roles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .85
Deleting Roles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .88
Managing TeamSite Users. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .88
Adding TeamSite Users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .89
Editing TeamSite Users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .93
Deleting TeamSite Users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .94
Working with TeamSite Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .94
Managing Groups. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .95
Working with Group Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .97
Group Membership . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .97
Viewing Group Managers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .98
Deleting Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .99
The iwgroup CLT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .99
Working with Branches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .99
Controlling Branch Ownership and Administration . . . . . . . . . . . . . . . . . . . . . .100
Creating Branches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .101
Integrating Content From Different Branches . . . . . . . . . . . . . . . . . . . . . . . . . .102
Managing Branches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .103
Working with Branch Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .104
Viewing Branch Users and Roles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .105
Editing Users and Their Roles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .106
Searching by Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .106
Choosing Users or Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .106
Chapter 6: Managing TeamSite Access 107
Access Considerations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .107
Working with Permissions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .108
Workarea Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .114
Branch and Workarea Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .114
Default Permissions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .115
Viewing File Permissions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .115
Sharing TeamSite Assets using Windows Groups . . . . . . . . . . . . . . . . . . . . . . . . . .116
Group Usage with NTLM or Mixed Mode Active Directory . . . . . . . . . . . . . . .116
Group Usage with Native Mode Active Directory . . . . . . . . . . . . . . . . . . . . . . .117
Group Usage for Larger AD Networks. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .118
Managing Windows Groups for Best Performance . . . . . . . . . . . . . . . . . . . . . .119
Enabling the User/Group/Role Disk Cache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .120
Disabling Group Nesting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .121
Enabling the ADSI Debug Flag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .121
Additional Tools for Debugging. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .121
Operating System Group Membership . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .122
Changing Group Ownership of Workareas. . . . . . . . . . . . . . . . . . . . . . . . . . . . .122
Web Server Group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .123

TeamSite Administration Guide 5


Contents

Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .123
Storing TeamSite Users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .123
The user_databases.xml File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .124
Synchronizing LDAP Users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .127
Configuring TeamSite and Active Directory to Work Without an
Anonymous Bind . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .128
LDAP Synchronization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .129
Impact of Using Non-OS Users in TeamSite . . . . . . . . . . . . . . . . . . . . . . . . . . .130
Domains to Use for Group Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . .131
Logging Users and Groups. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .131
Configuring Submit Filtering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .132
The submit.cfg File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .132
Submit Filtering Sequence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .134
Sample submit.cfg file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .134
Testing and Debugging Submit Filtering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .136
Chapter 7: Configuring Interwoven Search 137
Search Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .137
Working with Branches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .138
Indexing Branches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .138
Searching Branches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .139
Deleting Branches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .139
Configuring the Index and Search Managers . . . . . . . . . . . . . . . . . . . . . . . . . . . . .140
Generic Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .140
Generic Agent Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .141
Index Manager Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .142
Index Agent Configuration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .145
Search Manager Configuration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .146
Search Agent Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .147
Logging Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .148
Field Mapping Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .148
Configuring Date Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .150
Example of FieldMapping File. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .151
The standardFields.xml File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .155
Types of Files Being Indexed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .157
Using CLTs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .157
Search Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .158
Example 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .159
Example 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .160
Example 3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .160
Example 4 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .162
Example 5 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .163
Example 6 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .164
Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .165
Files Not Found . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .165
Deleted Edition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .166
Using the CustomDate Extended Attribute . . . . . . . . . . . . . . . . . . . . . . . . . . . .166
Deleted Branches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .167

Interwoven, Inc. 6
Contents

Changes to Content Store IDs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .167


Bringing Down Servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .167
Running on Different Hosts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .168
Configuration Issues. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .168
Using CLTs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .168
Error Messages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .169
Chapter 8: Configuring Metadata Capture 171
Introducing the Tagger GUI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .171
Metadata Capture Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .172
Metadata Capture Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .173
Metadata Capture and Extended Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . .175
Configuring Metadata Capture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .175
The metadata-rules.cfg File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .176
Creating the datacapture.cfg File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .178
Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .188
Modifying the Tagger GUI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .190
Localizing the Tagger GUI. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .190
Using the datacapture.cfg.example2 File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .191
Metadata Capture and TeamSite Workflow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .191
Specifying Files in Workflow Tasks. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .191
Initiating Metadata Capture from a Job Specification File . . . . . . . . . . . . . . . . .192
Chapter 9: Configuring the TeamSite Web Daemon and Proxy Server 193
About the TeamSite Web Daemon. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .194
About the Proxy Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .194
Applying Changes to Proxy Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . .195
Configuring TeamSite Web Daemon and Proxy Server Operation . . . . . . . . . . . . .196
Resolving Relative and Absolute Paths . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .196
Document Roots. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .197
Resolving Fully Qualified URLs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .199
Redirecting Fully Qualified URLs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .200
Configuring the Proxy Server to Redirect Fully Qualified URLs. . . . . . . . . . . .200
Configuring your Web browsers to Use the TeamSite Web Daemon . . . . . . . . .201
Redirecting TeamSite Views to Different Areas . . . . . . . . . . . . . . . . . . . . . . . . . . .202
Using iwproxy_preconnect_remap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .202
Using iwproxy_preconnect_redirect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .204
Configuring TeamSite to Use Different Web Servers . . . . . . . . . . . . . . . . . . . . . . .204
Configuring External Remappings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .205
Using iwproxy_preconnect_remap. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .205
Using iwproxy_external_remap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .205
Host Header Remappings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .206
Enabling iwproxy Access Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .206
Configuring SSI Remapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .207
Configuring Proxy Failover. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .207
Debugging Your Proxy Server Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . .209
Chapter 10: Backing Up TeamSite 211
Integrating with Third-Party Backup Solutions. . . . . . . . . . . . . . . . . . . . . . . . . . . .211
Suggested Strategies for Incremental Backups . . . . . . . . . . . . . . . . . . . . . . . . . . . .213

TeamSite Administration Guide 7


Contents

Appendix A: Configuring TeamSite ReportCenter 215


Installing TeamSite ReportCenter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .215
ReportCenter Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .216
ReportCenter Configuration File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .217
License key . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .219
Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .219
Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .219
CSSDK. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .220
Product . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .220
Receiver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .220
Archived Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .221
Database Schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .224
Crystal Enterprise Configuration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .228
Running on a Windows Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .228
Database Drivers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .228
Displaying Reports in ContentCenter. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .228
Setting up Individual Users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .229
Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .229
Appendix B: ECM Connector 233
Connector Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .233
WorkSite MP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .234
MediaBin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .236
FormsPublisher Configuration Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .238
datacapture.cfg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .238
Presentation Template Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .241
Using ECM Connector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .242
FormsPublisher . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .242
WorkSite MP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .243
MediaBin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .245
TeamSite Workarea . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .248
Editing Imported Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .249
Using MediaBin Search in ECM Connector. . . . . . . . . . . . . . . . . . . . . . . . . . . .249
MetaData XML Record. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .249
attribute Metadata Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .250
WorkSite MP attribute Metadata Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . .251
Representation of Data Types. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .251
Dublin Core Metadata Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .252
Custom Metadata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .253
WorkSite MP Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .254
Configuring WorkSite MP with the User Interface Location . . . . . . . . . . . . . . .254
Configuring WorkSite MP Trusted Login . . . . . . . . . . . . . . . . . . . . . . . . . . . . .254
Setting the PM Password . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .255
MediaBin Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .255
Setting Anonymous Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .255
Configuring MediaBin Trusted Client and LDAP Authentication . . . . . . . . . . .255

Interwoven, Inc. 8
Contents

Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .256
Running ECM 1.1 and ECM 2.0 Toolkits Simultaneously . . . . . . . . . . . . . . . . .256
Import from MediaBin Requires Anonymous Access to the Transfer Directory 256
Using IP Address for WorkSite MP Cluster Prevents Trusted Login . . . . . . . . .257
Patch Required When Using Microsoft Internet Explorer 6.0 SP1. . . . . . . . . . .257
Appendix C: Content Transformation Services 259
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .259
Installation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .260
Installation Procedure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .261
Editing the transform.cfg File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .262
URL Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .262
The convert URL Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .263
The converttask URL Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .263
Demonstrating the Workflow CGI Task . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .263
Removing or Modifying Menu Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .264
Using Content Transformation Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .264
Appendix D: Next Generation Tagger GUI 267
Tagger GUI New Features and Differences. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .268
Sequence of Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .272
Tagging a Single File (Next Generation Tagger GUI) . . . . . . . . . . . . . . . . . . . .272
Tagging Multiple Files (Original Tagger GUI). . . . . . . . . . . . . . . . . . . . . . . . . .273
Compatibility and Default Behavior . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .273
Implications of Configuring the Next Generation Tagger GUI . . . . . . . . . . . . .274
Replicant Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .274
Reverting to the Original CGI Environment . . . . . . . . . . . . . . . . . . . . . . . . . . .277
Dynamic Addition of Select Box Entries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .277
Configuring the Next Generation Tagger GUI . . . . . . . . . . . . . . . . . . . . . . . . . . . .277
Integrating MetaTagger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .278
Creating a Ruleset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .278
Creating a Mapping File. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .279
DTDs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .280
metadata-rules.dtd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .280
metadatacapture6.0.dtd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .281
datacapture6.0.dtd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .284
Appendix E: Using the Derby Database 291
Creating the Derby Database. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .291
Setting User Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .292
Testing Derby . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .293
Managing the Derby Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .293

TeamSite Administration Guide 9


Contents

Appendix F: Specifying Content Encoding 295


regex_map Defined . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .296
Simple regex_map Example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .296
The regex_map Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .297
Rule Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .297
Regular Expression Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .298
Variables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .298
Application Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .299
Intermediate Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .299
Interpolation of Variables and Captured Subexpressions . . . . . . . . . . . . . . . . . .299
Quoting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .302
Strategies for Effective regex_maps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .303
Internationalization and regex_maps. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .304
VisualPreview and file_encoding.cfg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .305
Source Differencing and Merging and file_encoding.cfg . . . . . . . . . . . . . . . . . . . .305
Sample file_encoding.cfg. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .306
Appendix G: Internationalization 309
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .309
Supported Client and Server Platforms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .310
Supported Content. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .310
Limitations and Assumptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .310
Content Stores and Character Encoding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .311
About UTF-8. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .311
URL Commands with Multibyte Characters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .312
Interfacing with Localized Operating Systems . . . . . . . . . . . . . . . . . . . . . . . . . . . .312
Accessing the Localized Interface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .313
Language of the VisualPreview Tool Bar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .313
Running TeamSite CLTs in DOS Console Mode. . . . . . . . . . . . . . . . . . . . . . . . . . .314
Specifying File Encoding of Text Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .314
Text Editor Encodings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .315
Behavior of Netscape Navigator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .315
Configuring Netscape for Multibyte Characters. . . . . . . . . . . . . . . . . . . . . . . . .316
Usage Scenarios . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .317
Appendix H: Single Sign-On 319
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .319
Integrating SiteMinder and TeamSite with an Active Response . . . . . . . . . . . . . . .320
Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .320
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .320
Integration Procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .322
Integrating SiteMinder and TeamSite Without an Active Response . . . . . . . . . . . .325
Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .325
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .326
Integration Procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .327
Integrating an SSO Product Other than SiteMinder with TeamSite. . . . . . . . . . . . .332
Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .332
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .332
Integration Procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .334

Interwoven, Inc. 10
Contents

Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .335
Troubleshooting the SiteMinder Web Agent . . . . . . . . . . . . . . . . . . . . . . . . . . .335
Troubleshooting the Active Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .336
Appendix I: TeamSite Service Monitor 339
Service Monitor Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .339
TeamSiteService Monitor Components and Processes . . . . . . . . . . . . . . . . . . . . . .340
Installing TeamSite Service Monitor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .341
Configuring TeamSite Service Monitor. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .342
iw.powerfail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .342
iw.processfail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .343
Starting and Stopping iwserver Under Service Monitor . . . . . . . . . . . . . . . . . . .344
Uninstalling TeamSite Service Monitor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .344
Related Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .344
Appendix J: Troubleshooting 345
Glossary 349
Index 361

TeamSite Administration Guide 11


Contents

Interwoven, Inc. 12
List of Figures
Figure 1 Using TeamSite for Web site development. . . . . . . . . . . . . . . . . . . . . . . . .23
Figure 2 Assign-edit-approve workflow model . . . . . . . . . . . . . . . . . . . . . . . . . . . .26
Figure 3 Example of a workflow for a job . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .26
Figure 4 Connections from client computer to TeamSite server . . . . . . . . . . . . . . .28
Figure 5 TeamSite file system structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .29
Figure 6 How the Event Subsystem Works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .51
Figure 7 Windows Task Manager, Processes dialog box . . . . . . . . . . . . . . . . . . . . .64
Figure 8 Component Services Control Panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .65
Figure 9 Default Directory Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .66
Figure 10 Registry Editor window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .72
Figure 11 Expanding the directory tree of the TeamSite server . . . . . . . . . . . . . . . . .72
Figure 12 Viewing a shared access drive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .73
Figure 13 Viewing the size of the iw-store . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .74
Figure 14 Roles screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .83
Figure 15 New Role screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .84
Figure 16 Edit Role screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .85
Figure 17 Add Users screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .89
Figure 18 Search tab to search for users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .90
Figure 19 LDAP Browse tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .91
Figure 20 Add Multiple Users screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .92
Figure 21 Add Multiple Users Individually . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .93
Figure 22 Groups screen. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .95
Figure 23 New Group Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .96
Figure 24 Group Properties screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .97
Figure 25 Group Membership screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .98
Figure 26 New Branch screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .101
Figure 27 Manage Branches screen from the Actions menu . . . . . . . . . . . . . . . . . .103
Figure 28 Branch Properties screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .104
Figure 29 Branch Users and Roles screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .105
Figure 30 High-level design of search system . . . . . . . . . . . . . . . . . . . . . . . . . . . . .138
Figure 31 Tagger GUI screens . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .172
Figure 32 Metadata Capture components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .174
Figure 33 Alternate Tagger GUI form . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .191
Figure 34 Browser access to iwwebd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .194
Figure 35 Processing proxy requests through the iw.cfg file . . . . . . . . . . . . . . . . . .195
Figure 36 Local Area Network settings dialog box . . . . . . . . . . . . . . . . . . . . . . . . .201
Figure 37 Proxy failover remap diagram . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .208
Figure 38 ReportCenter System Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .216
Figure 39 Relationship of Reporting database schemas . . . . . . . . . . . . . . . . . . . . . .227
Figure 40 WorkSite MP Properties Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .234
Figure 41 MediaBin Properties Screen. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .236
Figure 42 WorkSite MP Field in FormsPublisher. . . . . . . . . . . . . . . . . . . . . . . . . . .243
Figure 43 WorkSite MP Browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .243

TeamSite Administration Guide 13


List of Figures

Figure 44 WorkSite MP Browser with Selected File . . . . . . . . . . . . . . . . . . . . . . . .244


Figure 45 Document Properties Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .244
Figure 46 WorkSite MP Field with Document File Information . . . . . . . . . . . . . . .245
Figure 47 WorkSite MP Hyperlink in Outputted Web Page . . . . . . . . . . . . . . . . . . .245
Figure 48 MediaBin Field in FormsPublisher . . . . . . . . . . . . . . . . . . . . . . . . . . . . .245
Figure 49 MediaBin Browser Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .246
Figure 50 MediaBin Browser with Selected File . . . . . . . . . . . . . . . . . . . . . . . . . . .246
Figure 51 Asset Properties Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .247
Figure 52 MediaBin Field With Asset File Information . . . . . . . . . . . . . . . . . . . . . .247
Figure 53 MediaBin Asset with Alt Value in Outputted Web Page . . . . . . . . . . . . .248
Figure 54 Import to: Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .248
Figure 55 MediaBin Search . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .249
Figure 56 Installation on Two Servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .260
Figure 57 SiteMinder integrated with TeamSite and Active Response. . . . . . . . . . .321
Figure 58 SiteMinder integrated with TeamSite without Active Response . . . . . . .326
Figure 59 SSO product integrated with TeamSite without Active Response . . . . . .333
Figure 60 TeamSite Service Monitor components and processes . . . . . . . . . . . . . . .340

Interwoven, Inc. 14
List of Tables
Table 1 Notation Conventions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Table 2 TeamSite options configurable in the iw.cfg File . . . . . . . . . . . . . . . . . . 34
Table 3 Functions of Configuration Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Table 4 Autoprivate Encodings. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
Table 5 server_locale Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
Table 6 Types of files controlled by [location] . . . . . . . . . . . . . . . . . . . . . . . . . . 71
Table 7 Role operations and permission checking . . . . . . . . . . . . . . . . . . . . . . 109
Table 8 Attributes for user_databases.xml file . . . . . . . . . . . . . . . . . . . . . . . . . 125
Table 9 Interpretation of Time and Date Patterns . . . . . . . . . . . . . . . . . . . . . . . 150
Table 10 Search CLTs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
Table 11 Index Manager Error Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169
Table 12 Search Manager Error Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169
Table 13 Datatypes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187
Table 14 Archived Server Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221
Table 15 Archived User Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222
Table 16 Archived Workflow Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223
Table 17 Archived FormsPublisher or Tagger GUI Events . . . . . . . . . . . . . . . . . 223
Table 18 WorkSite MP metadata elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253
Table 19 MediaBin metadata elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253
Table 20 Next generation Tagger GUI new features . . . . . . . . . . . . . . . . . . . . . . 268
Table 21 Tagger GUI differences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268
Table 22 Tagger GUI schema support. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273
Table 23 XML Special Characters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302
Table 24 Language Encodings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313
Table 25 Code Pages for CLTs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314
Table 26 Default Encodings for Text Editors . . . . . . . . . . . . . . . . . . . . . . . . . . . 315
Table 27 Realms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323
Table 28 Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323
Table 29 Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323
Table 30 Realm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328
Table 31 Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328
Table 32 Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328
Table 33 Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329
Table 34 Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329
Table 35 Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330
Table 36 Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330
Table 37 Policy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330
Table 38 Troubleshooting options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345

TeamSite Administration Guide 15


List of Tables

Interwoven, Inc. 16
About This Book

The TeamSite Administration Guide is a guide for configuring, customizing, and


maintaining TeamSite. It is primarily intended for TeamSite Administrators and Master
users, web server administrators, and system administrators. Users should be familiar
with IIS and with basic Windows operating system operations such as adding users and
modifying ACLs.

It is also very helpful to be familiar with regular expression syntax. If you are not
familiar with regular expressions, it is recommended that you consult a reference
manual such as Mastering Regular Expressions, by Jeffrey Friedl.

Some TeamSite configuration files make use of XML. For more information about
XML, consult a reference manual or the online specification at
http://www.xml.com/axml/testaxml.htm.

Notation Conventions
This manual uses the following notation conventions:

Table 1 Notation Conventions


Convention Definition and Usage
Bold Text that appears in a GUI element (for example, a menu item,
button, or element of a dialog box) and command names are shown
in bold. For example:
Click Edit File in the Button Bar.
Italic Book titles appear in italics.
Terms are italicized the first time they are introduced. Important
information may be italicized for emphasis.
Monospaced Commands, command-line output, and file names are in
monospaced type. For example:
The iwextattr command-line tool allows you to set and look up
extended attributes on a file.

TeamSite Administration Guide 17


Table 1 Notation Conventions
Convention Definition and Usage
Monospaced Monospaced italics are used for command-line variables.The most
italic common example of this is iw-home, which refers to the directory
where TeamSite is installed. For example:
iw-home\etc\iw.cfg
is the path to the main TeamSite configuration file, iw.cfg, which
is located in the etc directory under the TeamSite installation
directory.
iwckrole role user
means that you must insert the values of role and user yourself.
Monospaced Monospaced bold represents user input. The > character that
bold appears before a line of user input represents the command prompt
and should not be typed. For example:
>iwextattr -s project=proj1
//IWSERVER/default/main/dev/WORKAREA/andre/products/inde
x.html
Monospaced bold Monospaced bold italic text is used to indicate a variable in user
italic input. For example:
>iwextattr -s project=projectname workareavpath
means that you must insert the values of projectname and
workareavpath when you enter this command.
[] Square brackets surrounding a command-line argument mean that
the argument is optional.
| Vertical bars separating command-line arguments mean that only
one of the arguments can be used.

Path Name Conventions


In most cases, you can specify path names using standard Windows naming conventions
(which enable you to include spaces in path names). However, in some situations it
might be necessary to use MS-DOS naming conventions, which stipulate that no single
file or directory name in a path can contain a space or more than eight characters. If you
encounter unexpected system behavior after entering a path name using Windows
naming conventions, enter the path name again using MS-DOS conventions. For
example, instead of:
>C:\Program Files\Interwoven\TeamSite

you can try:


>C:\iw-home\PROGRA~1\INTERW~1\TEAMSI~1

You can use the dir /x command to display the long and short versions of the file
names in the current directory.

Interwoven, Inc. 18
Default Paths
During installation default paths are used unless the installer specifies otherwise. The
default path for TeamSite is:
C:\Program Files\Interwoven\TeamSite

The default path for TeamSite Search is:


C:\Program Files\Interwoven\Search

The installed paths are referred to in this document as iw-home and iwsearch-home.

Online Documentation Errata


Additions and corrections to this document (if necessary) can be downloaded in PDF
format from the following Web site: https://support.interwoven.com.

What’s in This Manual


This manual contains information in the following areas:
„ Chapter 1, “TeamSite Overview,” introduces TeamSite administrators to the
TeamSite architecture and to TeamSite users.
„ Chapter 2, “Configuration File Overview,” describes the configuration files and
provides a table listing the various items to be configured.
„ Chapter 3, “Configuring the TeamSite Server,” describes the various ways in which
the TeamSite server can be configured. Many of these configurations are made in
the iw.cfg file.
„ Chapter 4, “Managing the TeamSite Server,” describes how to manage the TeamSite
server, including verifying operation, viewing log files, and starting and stopping
the server.
„ Chapter 5, “Defining Users and Roles,” describes how to define roles, users, and
groups for TeamSite.
„ Chapter 6, “Managing TeamSite Access,” describes controlling users and groups
through operating system functionality.
„ Chapter 7, “Configuring Interwoven Search,” describes the TeamSite Search feature.
„ Chapter 8, “Configuring Metadata Capture,” describes how to configure the Tagger
GUI to save metadata.
„ Chapter 9, “Configuring the TeamSite Web Daemon and Proxy Server,” describes
how to configure the proxy server.
„ Chapter 10, “Backing Up TeamSite,” suggests strategies for backing up TeamSite
files.

TeamSite Administration Guide 19


„ Appendix A, “Configuring TeamSite ReportCenter,” describes the optional TeamSite
Reporting module, ReportCenter.
„ Appendix B, “ECM Connector,” describes how to configure and use ECM
Connector, which provides access to Interwoven MediaBin and Interwoven
WorkSite from ContentCenter Professional.
„ Appendix C, “Content Transformation Services,” describes the optional Content
Transformation Services that allow users to convert Microsoft Word files into PDF
or HTML output.
„ Appendix D, “Next Generation Tagger GUI,” explains the next generation Tagger
UI.
„ Appendix E, “Using the Derby Database,” explains how to use the Apache Derby
database that ships as the default database for the Event Subsystem.
„ Appendix F, “Specifying Content Encoding,” provides information for encoding
content files.
„ Appendix G, “Internationalization,” provides specific information regarding use of
TeamSite internationally.
„ Appendix H, “Single Sign-On,” describes improvements to TeamSite support for
single sign-on authentication products from third parties. Information includes how
to install and uninstall a single sign-on authentication filter, and how to configure
TeamSite to work with SiteMinder Policy Server and other third-party single
sign-on products.
„ Appendix I, “TeamSite Service Monitor,” describes TeamSite Service Monitor for
monitoring the TeamSite server.
„ Appendix J, “Troubleshooting,” provides information on some issues you may
encounter using TeamSite.
„ The “Glossary” contains definitions of TeamSite terms.

Interwoven, Inc. 20
Chapter 1

TeamSite Overview

This chapter introduces three major TeamSite concepts and concludes with a description
of the TeamSite system architecture:
„ TeamSite Elements
„ User Roles
„ TeamSite Workflow
„ TeamSite Architecture

TeamSite Elements
The following sections describe some common TeamSite concepts that you should be
familiar with before beginning to configure TeamSite.

Content Stores
The Content Store is a large directory created by the TeamSite installation program that
contains TeamSite files and metadata. By default, the Content Store is located in
C:\iw-store.

TeamSite supports as many as eight Content Stores per TeamSite server (the first is
created automatically by the installation program, and the others are created as needed
by the TeamSite system administrator.

Branches
TeamSite provides branches for different paths of development for content. Branches
can be related to each other (for example, alternate language versions of the same Web
site) or they may be completely independent. Typically, each branch contains all the
content for a Web site or a major section of it (such as a department), or a collection of
related content (such as the program files for a software application or the image and
text files for a book). Branches can be indexed and searched.

TeamSite Administration Guide 21


Chapter 1: TeamSite Overview

A single branch contains archived copies of its content as editions, a staging area for
content integration, and individual workareas where users may develop content without
disturbing one another. Branches can also contain subbranches, so that teams may keep
alternate paths of development separate from each other. Content can be easily shared
and synchronized across branches and subbranches. Users may work on one branch or
on several, and the number of branches on a system is not limited.

Branches facilitate distributed workflow because they allow separate teams to work
independently on different projects. Because all branches are located on the same
TeamSite server, it is easy for one team to incorporate the work of another into their
project.

Workareas
Each workarea contains a virtual copy of all related content, which may be modified in
any way without affecting the work of other contributors. Users who have access to a
workarea may modify files within that workarea and view their changes within the
context of all related content before integrating their work with that of other
contributors. Users can lock files in each workarea, eliminating the possibility of
conflicting edits.

All changes made to files in a workarea are kept completely separate from other
workareas and the staging area until the user chooses to submit his changes to the
staging area. Within a workarea, users may add, edit, or delete files, or revert to older
versions of files without affecting other users.

Staging Areas
Each branch contains one staging area where contributors incorporate their changes
with the work of others. Users submit files from their workareas to the staging area to
integrate their work with other contributions, and test the integrity of the resulting
content. Because the staging area is an integrated component of the system, conflicts are
easily identified and different versions of the same file can be merged, rather than
overwritten.

Editions
Editions are read-only snapshots of a branch, taken at sequential points in its
development. Contributors with appropriate permissions can create new editions any
time they feel their work is well integrated, or any time they want to create an updated
snapshot of all content for reference or deployment to a production server. For Web site
content development, each edition is a fully functional version of the Web site, so that
users can see the development of the Web site over time and compare it with current
work.

Interwoven, Inc. 22
Chapter 1: TeamSite Overview

TeamSite branches contain private workareas, which contain complete virtual copies of
the Web site; staging areas, where contributors integrate their work; and editions, which
are read-only snapshots of the Web site at various points in its development. Each area
contains a virtual copy of the entire Web site. Content is submitted from workareas to
the staging area, and the staging area is then published as an edition. Older editions are
available for reference. The following diagram illustrates the use of TeamSite for Web
site development.

Figure 1 Using TeamSite for Web site development


Edit
local
computer
Workarea A
Upload

Production Server
TeamSite Branch

TeamSite Branch
Client

Submit

Get Latest
Workarea B Staging Area Edition 3
Publish Deploy
Production
Server

Workarea C Edition 2

Edition 1

TeamSite Process Time

User Roles
TeamSite ships with out-of-the-box user types, each with specific access permissions
and optimized user interfaces. These user types are known as roles. The roles are:
„ Reviewer
„ Author
„ Editor
„ Administrator

TeamSite Administration Guide 23


Chapter 1: TeamSite Overview

„ Master
„ WorkflowUser
„ WorkflowAdmin

These default roles are summarized in the following sections. Each installation can
create or modify roles to meet the needs of your organization. Refer to Chapter 5,
“Defining Users and Roles,” for details about the roles and for instructions on creating or
modifying roles.

Reviewer
Reviewers generally review work done by others. They may have approval authority.
They can browse workareas and review files and forms, search for content, and work
with tasks. Reviewers usually access TeamSite from the browser-based ContentCenter
Standard interface.

Author
Authors are primary content creators. All work done by Authors goes through an
explicit approval step. They can receive assignments from Editors, which are displayed
in task lists when Authors log in to TeamSite. Authors usually access TeamSite from the
browser-based ContentCenter Standard interface and do not need to be sophisticated
computer users.

In order to test their work, Authors have full access to the content in their Editors’
workareas, but do not need to concern themselves with the larger structure and
functionality of TeamSite. The Author role is appropriate for non-technical users or for
more technical contributors who do not need access to extended TeamSite functionality,
such as advanced version management features.

Editor
Editors own workareas. They create and edit content, just as Authors do, but they are
primarily responsible for managing the development taking place within their
workareas. This includes assigning files to Authors and submitting completed content to
the staging area, and it may include creating editions.

Editors have access to specialized TeamSite content and workflow management


functions. Editors are generally “managerial” users, who primarily supervise the work
of Authors, or self-managing “power” users, who need extended TeamSite functionality
to manage their own content.

Interwoven, Inc. 24
Chapter 1: TeamSite Overview

Administrator
Administrators own branches. They have all the abilities of Editors, but they are
primarily responsible for the content and functioning of their branch. Administrators can
manage project workflow by creating new workareas for Editors and groups and by
creating subbranches of their own branch to explore separate paths of development.
They can assign TeamSite users to groups and assign users to roles on the branch.

An Administrator is the supervisor of the project being developed on his branch.

Master
Master users own the entire TeamSite Content Server. They can create new stores and
perform all the functions of Editors and Administrators on any branch. They can create
or modify roles. The Master user is generally involved in the installation of TeamSite
and can reconfigure TeamSite on a system-wide basis.

Users with the Master role have access to the Administration tab within ContentCenter
Professional. This allows them to add operating system users to TeamSite, assign
groups, create and edit roles, and perform other TeamSite tasks. Most installations only
have a few Master users.

WorkflowUser
By default, all TeamSite users should be able to use workflow models. To achieve this,
the workflowModels branch of the iwadmin store is shared for iwEveryone with role as
WorkflowUser. This role has the minimum privileges required to instantiate a workflow.

WorkflowAdmin
The WorkflowAdmin role has privileges to design workflows using Interwoven
Workflow Modeler and upload them to TeamSite. They have privileges to manage,
configure, and debug the workflow models. Users who can perform these operations
include workflow developers or TeamSite administrators.

TeamSite Workflow
A workflow model is a general workflow configuration that can be used repeatedly. Each
workflow model describes a process that may include user tasks and a wide variety of
automated tasks. Workflow models are configured by the system administrator or by the
Interwoven Client Services organization.

For more information about configuring different workflow models, consult the
TeamSite Workflow Developer’s Guide.

TeamSite Administration Guide 25


Chapter 1: TeamSite Overview

Figure 2 is a diagram of a very simple assign-edit-approve workflow model. Email is


sent to the participants at every stage of the process, and some automated tasks are
performed at the end.

Figure 2 Assign-edit-approve workflow model

Editor Task: Task: Task:


initiates job Email sent Author Email sent
to Author edits files to Editor

Reject Task: Approve Task:


Task: Editor Task: Content
Email sent reviews Email sent submitted
to Author Author’s to Author to the
work staging area

Task:
Automated
deployment

Jobs
A job is a set of interdependent tasks. One example of a TeamSite job would be the set
of tasks needed to prepare a new section in a marketing Web site to support a new
product launch.

Each job is a specific instance of a workflow model. When a job is created, the job
creator must supply all the specific information for that job. For example, the workflow
model in Figure 2 might be used to create the job in Figure 3.

Figure 3 Example of a workflow for a job


Task:
Andre Task: Pat edits Task:
initiates job Email sent index.html Email sent
to Pat and to Andre
banner.gif

Reject Task: Approve Task:


Task: Andre Task: Content
Email sent reviews Email sent submitted
to Pat Pat’s to Pat to the
work staging area

Task:
Automated
deployment

Interwoven, Inc. 26
Chapter 1: TeamSite Overview

Because jobs follow predefined workflow models, tasks cannot be added to or removed
from individual jobs, although not every possible task may actually take place for a
given job.

Tasks
A task is a unit of work performed by a single user or process. Each task in a job is
associated with a particular TeamSite workarea and carries a set of files with it. The user
or process owning a task can modify, add files to, or remove files from the task.

Tasks have two possible states: active and inactive. A task becomes active when its
predecessor task signals it to do so (predecessor tasks and conditions for activation are
all configured as part of the workflow model). Once the task has been activated, users or
external programs can work on it. For example, once a user task has been activated, the
user can work on the files contained in the task. Once an external task has been
activated, the appropriate external program can run on the files contained in the task.
Inactive tasks are tasks that have been completed or that have not been activated yet.

TeamSite Architecture
The TeamSite file system is composed of the TeamSite Content Server and device
driver, the TeamSite Content Store of files and metadata, a suite of command-line tools,
TeamSite CGI, proxy servers for access through the TeamSite browser-based user
interfaces (ContentCenter), and file system mounts for access through the file system
interface.

The TeamSite file system is the core of the TeamSite system, where detailed information
about the Web site, the Web assets, Web asset metadata, the production process and the
users is stored. The TeamSite file system collects and maintains metadata on TeamSite
files, directories, and areas, and allows TeamSite to process and present information
according to who is asking for the information, and under what conditions. By using an
object-oriented design within a file system architecture, TeamSite combines extensive
metadata tagging with open access and file system performance for Web content.

The client computer connects to the TeamSite server in several ways. Requests from the
browser interfaces or Local File Manager are routed through the TeamSite Web daemon,
which allows consistent views of TeamSite areas. The double proxy server redirects
hard-coded links within the Web site. Requests through the file system interface
(TeamSite shared drive) and command-line tools, which do not go through the web
server, are not routed through a proxy server.

TeamSite Administration Guide 27


Chapter 1: TeamSite Overview

Figure 4 Connections from client computer to TeamSite server


TeamSite Content Server Client Computer
TeamSite File System

TeamSite command
Content Command line
Store Line Tools

CSSDK Browser
Soap Interfaces
RPC Web
Server
Daemon
Local File
(port 80) Manager
Servlet
Engine
Content
TeamSite CSSDK Services
Server Content Applications
(iwserver) Web
Server iwproxy
(port 81)
Workarea
TeamSite
Virtualization
Shared
Drive (port 1080) Local File
Manager
Device
Driver
SMB
Network
Share

Understanding the TeamSite File System


The TeamSite file system mount contains a file system view of all the Content Stores,
branches, workareas, staging areas, and editions on the TeamSite server. TeamSite areas
do not contain physical copies of the collection of content, but rather pointers to the files
contained in the collection of content. The only physical files contained within TeamSite
areas are the files that have actually been modified in those areas. That is, the only files
actually contained in a workarea are those files that have been modified in that workarea
but not yet submitted to the staging area. The only files contained in the staging area are
the files that have been submitted since it was last published. The only files in an edition
are the files that have changed since the previous edition was published.

A simple TeamSite file system structure is shown in the following graphic:

Interwoven, Inc. 28
Chapter 1: TeamSite Overview

Figure 5 TeamSite file system structure

default or
store name*

main

WORKAREA STAGING EDITION development

admin INITIAL
WORKAREA STAGING EDITION

Legend: andre pat


pat chris INITIAL ed_0001
System-created
User-created
* Store name is user-assigned in
MultiStore implementations

Each branch contains three system-generated directories:


„ WORKAREA—Contains an individual workarea for each contributor on the branch.
„ STAGING—Staging area common to all workareas on the branch.
„ EDITION—All published editions on the branch.

It may also contain directories that hold subbranches. In the example above, the main
branch (main) contains one workarea (admin), a staging area, an initial edition, and a
subbranch (development). The subbranch contains three user-defined workareas (andre,
pat, and chris), a staging area, and two editions, one of which is user-generated
(ed_0001).

Although many of the files contained within this file system structure are virtual, they
can be treated as if they were real. They appear to exist even when you run link checkers
and scripts against them. However, staging areas, editions, and container directories (for
example, WORKAREA, EDITION, main, or development) are all read-only. Only workareas
can be written to.

TeamSite Administration Guide 29


Chapter 1: TeamSite Overview

Specifying VPaths
The path describing a workarea is its workarea VPath. The path describing a file’s
location within an area is its area relative path. Combined together, a file’s full VPath
describes its precise location in the Interwoven file system.

A vpath (“version path”) is a path within the TeamSite content repository, specified as
one of the following:
\store\branch+\EDITION\edition
\store\branch+\WORKAREA\area\directory*\file
\store\branch+\STAGING\directory*\file

where “+” indicates 1 or more; * indicates 0 or more, and a path may omit the elements
below it in order to specify just a directory, area, branch, or store.

A branch may not be named EDITION, WORKAREA, or STAGING.

STAGING is a special area that every branch has. Thus, an area is either a workarea,
specified as WORKAREA\area, or STAGING.

The following are all valid vpath specifications:


„ \default, a store.
„ \default\main, the branch main.
„ \default\main\pubs, the (sub)branch pubs.
„ \default\main\pubs\EDITION\initial, the edition initial.
„ \default\main\pubs\STAGING, the staging area for the pubs branch.
„ \default\main\pubs\WORKAREA\uitk, the workarea uitk.
„ \default\main\pubs\WORKAREA\uitk\guide\examples, a directory.
„ \default\main\pubs\WORKAREA\uitk\guide\examples/example1, a file.
„ \default\main\pubs\WORKAREA\uitk\README, a file directly under a workarea.

The path delimiter can be either “/” or “\” when specifying a TeamSite path, but will be
output as: “/” (Unix) or “\” (Windows).

Optionally, a vpath can include the server name by prepending //servername to it,
though doing so is generally not needed.

The maximum length of a vpath (including host name, branch, workarea, and folders) is
currently limited to about 600 bytes.The limitation is imposed by the maximum length
of a GET URL command supported by a browser. The 600-byte requirement provides
30 folder levels with average 20-byte folder names.

For multi-byte languages (Chinese, Japanese, Korean), the maximum length is reduced
by a factor of 9 to about 67 bytes. Each CJK character, when used as part of an URL,
must be encoded. The encoding for UTF-8 expands each character to a 9-byte sequence
of the form "%xx%xx%xx" where xx is the hexadecimal UTF-8 code.

Interwoven, Inc. 30
Chapter 1: TeamSite Overview

Related Documentation
For information and preliminary configuration information, consult the TeamSite
Installation Guide.

For more information about configuring different workflow models, consult the
TeamSite Workflow Developer’s Guide.

For more information on specifying a vpath, see the TeamSite Command-Line Tools
manual.

TeamSite Administration Guide 31


Chapter 1: TeamSite Overview

Interwoven, Inc. 32
Chapter 2

Configuration File Overview

Most of the settings for the TeamSite server are configured in the main configuration
file, iw-home\etc\iw.cfg (default location).

Additional settings are configured in a variety of additional files.

Configuration and customization of the ContentCenter interfaces is done through the UI


Toolkit; refer to the TeamSite User Interface Customization Guide for details.

This chapter addresses the following:


„ The iw.cfg File
„ Additional Configuration Files

The iw.cfg File


The TeamSite iw.cfg configuration file is divided into sections that display in square
brackets (the iwwebd section is shown in the following example). The configurable
parameter (http_port) is to the left of the equal sign, and the current setting (80) is to
the right; for example:

[iwwebd]
http_port=80

To edit any of the settings:


1. Open the configuration file in a text editor.
2. Change the current setting.
You cannot have a space before or after the equal sign.
3. Save and close the file.

Changes to most of these configuration settings take effect within a few minutes
(although for options that affect a user interface, users may need to clear their browser
cache in order to see the changes). For these settings to take immediate effect, use the
iwreset.exe command-line tool (CLT). Configuration options that require TeamSite to
be restarted in order to take effect are noted where appropriate.

TeamSite Administration Guide 33


Chapter 2: Configuration File Overview

NOTE
If section headings are duplicated in the iw.cfg file, some or all of the values given for
the parameters in one copy of the section will be ignored. Verify that a section heading
only appears once in your iw.cfg file.

Location of iw.cfg
If iw.cfg does not exist in the default location, TeamSite looks for it in the following
locations, in the following order:
„ iw-home\local\etc\iw.cfg
„ iw-home\etc\iw.cfg

„ HKEY_LOCAL_MACHINE\Software\Interwoven\TeamSite\iw-config (registry key)

If iw.cfg is not found in any of these places, TeamSite assumes the default values for
iw.cfg settings.

The iw.cfg File Options


Table 2 describes the configurable options in iw.cfg, lists the option or section name,
and identifies the page from the manual that describes the option.

Table 2 TeamSite options configurable in the iw.cfg File


Function iw.cfg option Page
Configuring UI functionality
Enabling/disabling [iwproxy_smartcontextedit_allowed] page 39
VisualPreview
Configuring domain lists in the domain_list page 40
login screen
Configuring email settings maildomain, mailserver, page 40
use_mapping_file,
email_mapping_file, debug_output
Specifying valid domains to valid_domains page 41
redirect ContentCenter users
from a public URL
Configuring server functionality
Controlling modification time old_mod_times page 41
Modifying extended attributes force_EA_mod_times page 42
Setting the encoding of iw.cfg encoding page 42
Configuring the Web daemon host, http_port, https_port, page 43
default_protocol
Configuring the servlet engine servlet_port page 43

Interwoven, Inc. 34
Chapter 2: Configuration File Overview

Table 2 TeamSite options configurable in the iw.cfg File (Continued)


Function iw.cfg option Page
Setting the main branch main_lock_model page 44
locking model
Controlling locked file only_lock_owner_creator_submits page 45
submission
Controlling behavior of lockmodel_compatibility page 45
Mandatory Write and Optional
Write locking
Specifying the number of compare_search_limit page 46
versions to check for the
common ancestor of compared
files.
Specifying the number of event_log_size page 46
events logged in the submit
and update logs
Setting the port number for the utild_ext_tasks_portnum page 49
iwutild service
Enabling the Event Subsystem ew_enable page 51
Setting the default size of the ew_rollover_threshhold page 51
event log file
Configuring server performance
Setting cache size cachesize page 57
Controlling impersonation disable_ext_task_impersonation, page 58
impersonate_without_password
Setting throughput monitors thruputmonitoring, thruputmonitorx page 58
Detecting low disk space and disklow_mybtes, disklowpercent page 59
inodes
Configuring the TeamSite server_locale page 59
server locale
Setting TeamSite file locations [locations] page 71
Configuring FormsPublisher
Setting FormsPublisher default data_root page 61
directory
Setting number of previews preview_history_limit page 61
Specifying directory for preview_system_directory page 61
preview files
Formatting data record pretty_print_dcrs page 62
printing
Configuring TeamSite access
Identifying default OS group iwglobal_group page 94
Specifying the default role for branch_owner_role page 100
the owner of a branch
Specifying the role or roles admin_roles page 100
that can administer branches

TeamSite Administration Guide 35


Chapter 2: Configuration File Overview

Table 2 TeamSite options configurable in the iw.cfg File (Continued)


Function iw.cfg option Page
Specifying a secondary master secondary_admin_account page 100
user
Changing branch owner and main_owner, main_group page 100
group
Setting branch and workarea branch_security, workarea_security page 114
security
Setting default permissions branch_default_perm page 115
Using Domain Local Groups domain_local_groups page 116
to share workareas
Using the Active Directory use_adsi, debug_adsi page 116
System Interface
Enabling user/group/role disk enable_user_group_disk_cache page 120
cache
Specifying groups for Active windows_groups_for_users, page 118
Directories windows_groups_for_sharing,
include_nested_groups
Setting the webserver group webserver_group page 123
Managing permissions on the mask_workarea_access page 123
workarea
Specifying information for ldapcache_thread_delay, page 127
iwldapsync updates. log_ldap_sync, ldap_sync_retry

Configuring which domains to domain_list page 131


use for group authentication
Configuring user and group show_user_list page 131
logging
Configuring submit filtering
Specifying debug submit debug_event_handler page 136
handling
Configuring the TeamSite proxy server
Configuring proxy server [iwproxy] page 196
operation
Setting document roots [iwproxy_remap] page 197
Resolving fully-qualified [iwproxy_fullproxy_redirect] page 199
URLs
Redirecting TeamSite views to [iwproxy_preconnect_remap] page 202
different areas [iwproxy_preconnect_redirect]
Configuring TeamSite to use [iwproxy_preconect_remap] page 204
different Web servers [iwproxy_external_remap]
Configuring external [iwproxy_external_remap] page 205
remappings
Setting host header [iwproxy_hostheader_remap] page 206
remappings

Interwoven, Inc. 36
Chapter 2: Configuration File Overview

Table 2 TeamSite options configurable in the iw.cfg File (Continued)


Function iw.cfg option Page
Enabling iwproxy Access [iwproxy_access_control_enabled] page 206
Control
Configuring SSI remappings [iwproxy_plugin_remap] page 207
Configuring proxy failover [iwproxy_failover_remap] page 207
Identifying Content Stores
Defining content stores store_directory_store-name, *
store_comment_store-name
Configuring workflows
Enabling query on workflow delete_jobs_on_completion page 216
events
Controlling adding files to external_task_add_filelist **
command line of external task
command callouts
Controlling nesting depth wftask_nesting_depth_allowed **
Controlling external task external_task_retry_wait **
retries
Checking for locking and presubmit_check **
others conflicts before submit
Controlling jobs being task_areavpath_file_access_check **
assigned to users without
access to files
Controlling whether files are permit_add_locked_files_to_ **
locked when creating jobs and locking_tasks
tasks
* Refer to the TeamSite Installation Guide for information.
** Refer to the TeamSite Workflow Developer’s Guide for information.

Additional Configuration Files


The following files contain information about your TeamSite server configuration:

Table 3 Functions of Configuration Files


Configuration File Function
iw-home\local\config\submit.cfg Specifies all file permissions that are
automatically changed at submit time.
iw-home\local\config\autoprivate.cfg Specifies what types of files are
automatically marked private.
iw-home\local\config\file_encoding.cfg Contains rules that determine the
character encoding of the contents of
files that do not specify their encoding.
See page 295 for information about
creating these rules.

TeamSite Administration Guide 37


Chapter 2: Configuration File Overview

Table 3 Functions of Configuration Files (Continued)


Configuration File Function
iw-home\local\config\templating.cfg Specifies the forms that are used in
which TeamSite areas and how the
forms map to presentation templates as
well as setting form display options.
iw-home\conf\roles\tsusers.xml Contains information on all TeamSite
users.
iw-home\conf\roles\user_databases.xml Identifies the databases that contain
user information.
iw-home\conf\roles\roles.xml Contains information on operations
performed by each role, as set through
the Edit Roles screen.
iw-home\conf\tsgroups.xml Contains information on TeamSite
groups.
iw-home\local\config\transform.cfg Configures Content Transformation
Services.
iwsearch-home\etc\search.properties Configures the index server and search
server.
iwsearch-home\etc\branches.cfg Lists the branches to be indexed by the
index server.
iwsearch-home\etc\FieldMapping.xml Defines extended attributes and
templating attributes to be indexed.
iw-home\tsreport\conf\tsreport.xml Configures the EAs to be used by
TeamSite ReportCenter.
iw-home\eventsusbystem\conf\ Configures the Event Subsystem.
jmsconfignew.xml
iw-home\httpd\webapps\eventsubsystem\ provides additional Event Subsystem
WEB-INF\iw_bridge_cfg.xml configuration.
iw-home\etc\iwutild.cfg Configures commands for the utility
service.
iw-home\local\config\datacapture.cfg Defines rule sets for capturing
metadata or forms.
iw-home\local\config\metadata-rules.cfg Provides information on mapping
vpaths to data capture rules.

Interwoven, Inc. 38
Chapter 3

Configuring the TeamSite


Server

This chapter contains the following information on configuring the TeamSite server:
„ Configuring User Interface Functionality
„ Configuring Server Functionality
„ Working with the Utility Service
„ Enabling the Event Subsystem
„ Configuring Server Performance
„ Configuring the TeamSite Server Locale
„ Configuring FormsPublisher
„ TeamSite Embedded Failsafe

Configuring User Interface Functionality


The following sections describe the configuration settings that enable you to customize
the functionality displayed in the user interfaces.

Enabling and Disabling VisualPreview


You can selectively enable or disable VisualPreview for different workareas or files by
adding lines to the [iwproxy_smartcontextedit_allowed] section of iw.cfg. If this
section does not exist or contains no entries, VisualPreview is enabled by default.

The [iwproxy_smartcontextedit_allowed] section begins with one _default line,


which specifies whether VisualPreview is turned on or off in any area or for any file not
otherwise specified. This line is then followed by any number of _regex lines. Each
_regex line uses a case-insensitive regular expression to specify areas or files, and then
specifies whether VisualPreview is enabled or disabled for the specified items. A
_regex line has the following case-insensitive syntax:
_regex=regular-expression=yes|no

TeamSite Administration Guide 39


Chapter 3: Configuring the TeamSite Server

Lines in the [iwproxy_smartcontextedit_allowed] section are order-dependent. In


the following example, the _default=yes line turns VisualPreview on for all files
managed in TeamSite. The first regex line explicitly turns it on for all files in all of
Andre’s workareas on all branches. The second regex line turns VisualPreview off for
all CGI files. But because the line turning VisualPreview on for Andre’s workareas
comes first, he can use VisualPreview for CGI files in his workarea.
[iwproxy_smartcontextedit_allowed]
_default=yes
_regex=(.*)/WORKAREA/andre/.*=yes
_regex=\.cgi(\?.*)?$=no

Configuring Domain Lists in the Login Screen


The domain_list parameter is a comma-separated list of domains that defines the
options that display in the Domain field of the TeamSite login screen. It is located in the
[iwcgi] section of iw.cfg.

If the [iwcgi] section of iw.cfg does not contain this line, add it as follows:

[iwcgi]
domain_list=This Domain,That Domain,The Other Domain

NOTES
„ You can include any number of domains in this list.
„ If your [iwcgi] section does not contain a domain_list, domains are automatically
detected and displayed.
„ Domains are listed in alphabetical order, not the order listed in iw.cfg.
„ Do not confuse this line with the domain_list line in the [iwserver] section of
iw.cfg.

Configuring Email Settings


The TeamSite Assign feature sends email to the recipient of a task. The following
settings in the [iwsend_mail] section of iw.cfg enable you to configure how this email
is sent:
„ maildomain=domain.topleveldomain

Specifies the domain (for example, maildomain=Interwoven.com)


„ mailserver=servername.domain.topleveldomain

Specifies the mail server to use (for example,


mailserver=factotum.Interwoven.com).
„ use_mapping_file=false|true

Optional entry that specifies whether or not to use a mapping file to configure
individual email addresses or aliases.

Interwoven, Inc. 40
Chapter 3: Configuring the TeamSite Server

„ email_mapping_file=path_to_file

Optional entry that specifies the location of the mapping file to use (a sample file is
located in iw-home\local\config\wft\email_map.cfg).
„ debug_output=path_to_file

An optional entry that specifies that debug output will be sent to the file location
indicated.

Specifying Valid Domains


When ContentCenter users go to a public URL and then return through a done_page
parameter, you can specify the valid domains to which users can be redirected. This
prevents users from being maliciously directed to a harmful domain.

Use the valid_domains setting to provide a comma-separated list of valid domains for
URLs in TeamSite ContentCenter. By default, the TeamSite server host name, domain
and IP address are automatically included and do not have to be specified here.
[teamsite_servlet_ui]
valid_domains=domain,domain,domain

Configuring Server Functionality


The following sections describe the configuration settings that determine the TeamSite
server functionality.

Controlling Modification Times


The old_mod_times setting controls what value is returned for the modification time of
a file through the file system interface.
[iwserver]
old_mod_times=true

By default, old_mod_times is set to true, and the modification time of a file is the time
a user last changed the file's contents. Submitting a file to the staging area or updating it
into your workarea through Get Latest does not affect the modification time; the
modification time will be the same as the modification time of the source file. If
old_mod_times=false, the modification time of a file is the later of the time (1) a user
last changed its contents and (2) the time the file was updated into the workarea (with
get-latest, copy-to-area, or iwupdate operations) or submitted if it is a file in the staging
area or an edition.

This distinction is important when you are using TeamSite for SCM. A lot of build tools,
such as UNIX make, rely on timestamps to determine whether it needs to regenerate
object files. They typically compare the modification time of the source file with the
modification time of the corresponding object file and decide to rebuild the object file

TeamSite Administration Guide 41


Chapter 3: Configuring the TeamSite Server

only if the source file has a later modification date. If you use such a build tool out of a
TeamSite workarea with old_mod_times=true (the default), you could have problems if
your workarea is updated before a build.

For example: You run make to recompile file1.c in your workarea. This generates
object file file1.o, with the current time as its modification time. However, yesterday
another user submitted another version of file1.c, but you did not update your
workarea before running make. This newer version of file.c has a modification time
from yesterday (when it was modified before being submitted). If you now update your
workarea, you will get the new version of file1.c, but its modification time would still
be the time from yesterday. By default, with old_mod_times=yes, the modification time
of a file has no correlation to the time you update your workarea. If you run make again,
it would fail to recompile the new version of file1.c, because the modification time of
file1.o is later than the modification time of the newer file1.c. This can be fixed by
setting old_mod_times=false. The modification time of file1.c would then show in
your workarea with the time when you did the get-latest procedure, and make would
know to regenerate the object file.

The old_mod_times setting only affects the modification time displayed through the file
system interface and not through ContentCenter. The modification time of a file in a
user interface is always the time the contents changed.

Modifying Extended Attributes


Normally when extended attributes (EAs) are modified, the content modification
timestamp of the file is not updated (although there is an attribute modification
timestamp that is updated). This is the default and is equivalent to setting false for this
option.

You can set up TeamSite so that the content modification timestamp is updated
whenever the EAs are modified using the force_EA_mod_times option in the iw.cfg
file.
[iwserver]
force_EA_mod_times=true

Specifying the Encoding of the iw.cfg File


To facilitate the internationalization of TeamSite, you have the ability to use text editors
that save the iw.cfg file in various encodings. The encoding setting in the first section
of the iw.cfg file declares the encoding of the iw.cfg file itself. The default setting is
ascii.

To change the encoding of the iw.cfg file, add the following lines to the beginning of
the file:
[iwcfg]
encoding=encoding_type

Interwoven, Inc. 42
Chapter 3: Configuring the TeamSite Server

where encoding_type is one of the following:


„ ascii (default setting)
„ ISO-8859-1
„ windows1252
„ euc-cn
„ euc-jp
„ euc-kr
„ shift_jis
„ utf-8

NOTE
This must be the first section in the iw.cfg file—no other entry can precede it.

Configuring the Web Daemon


To set Web daemon defaults, edit the [iwwebd] values in the iw.cfg file:
[iwwebd]
host=hostname.domain
http_port=80
https_port=443
default_protocol=http

The default_protocol setting is used by the following scripts when TeamSite


generates URLs:
„ iwsend_servlet_mail.ipl script—uses it to embed URLs into the email messages
it sends. Set this to default_protocol=https to have the email with the https
prefix for the task URL after running a workflow.
„ <iwov_webdesk_url> presentation template tag—uses it when generating
hyperlinks to the TeamSite server (see the presentation template information at
https://support.interwoven.com/library/devel/tst/pt more information).

Set this to default_protocol=https for email messages

For more settings in [iwwebd], refer to Chapter 9, “Configuring the TeamSite Web
Daemon and Proxy Server.”

Changing the Servlet Engine


By default, the servlet port is set to 8080. To change this setting, edit the servlet_port
value in the [teamsite_servlet_ui] section of the iw.cfg file.
[teamsite_servlet_ui]
servlet_port=8080

TeamSite Administration Guide 43


Chapter 3: Configuring the TeamSite Server

Setting Locking Models


Locking prevents users in other workareas on the branch from editing or submitting a
file that is locked. TeamSite supports three types of file locking:
„ Submit. Enables users to ensure that their changes are submitted before others can
submit theirs. When a file is locked, users in different workareas can edit their
version of the file, but cannot submit it until the owner of the lock submits his work
or manually releases the lock. This option is selected by default and is well-suited
for environments where parallel development is desired.
„ Mandatory Write. Ensures that only one user can edit a file at a given time. Users
must lock files while editing them. While files are locked, no other users in any
workarea on the branch can edit their version of those files. This option is suitable
for environments where serial development is required.
„ Optional Write. Enables users to choose whether or not to lock a file. While files
are locked, no other users in any workarea on the branch can edit their version of
those files. This option is suitable for environments where serial development is
desired, but optional.

A branch’s locking model is set when the branch is created. Different branches on one
TeamSite server may use different types of locking. All workareas on a branch use the
same type of locking. The type of locking a branch uses cannot be changed after the
branch has been created.

You can also set these locking models, plus the option None, when creating roles. Since
a branch and a role can have separate file locking, TeamSite uses the more restrictive of
the role locking and branch locking when determining what locking model is in place
for a particular user on that branch. TeamSite also evaluates whether a user has multiple
roles on the branch and uses the least restrictive locking specified in a role. It then
compares locking for the role with the branch locking model and applies the most
restrictive model.

Role locking is useful if you wanted to have a different locking model for users having
different roles on a given branch. For example, the author role may have mandatory
write locking, implying that users who are authors in a branch that has submit locking
should have the lock on the file and lock the file in their workarea before editing the file.
This lowers the need for authors to deal with conflict resolution and merging while other
roles enjoy a more lenient model.

Submit Locking is the least restrictive followed by Optional Write Lock and Mandatory
Write Lock.

ContentCenter configurations may impose additional restrictions on whether a user


needs to lock a file before being able to edit it.

Interwoven, Inc. 44
Chapter 3: Configuring the TeamSite Server

Setting a Locking Model on a Branch

TeamSite enables you to specify the locking model of each branch at the time that it is
created. However, the main branch is created automatically by the TeamSite installation
program and it uses the default option of Submit locking.

Creating a new Content Store also creates a new main branch. You can specify which
locking model to use for the main branch of a new Content Store by completing the
following procedure:
1. Edit the main_lock_model line in the [iwserver] section of iw.cfg as follows:
[iwserver]
main_lock_model=locking_model

where locking_model is either of the non-default models:


‰ optional_write_lock (or o)
‰ mandatory_write_lock (or m)
2. Save and close the iw.cfg file.
3. Run the iwreset CLT to ensure the edit is recognized.
4. Create a new Content Store as described in the TeamSite Installation Guide.
The new Content Store uses the setting specified by the main_lock_model option
when it is created.

Locked File Submission

You can configure TeamSite to allow only the owner or creator of the lock to submit a
locked file to the staging area (as opposed to allowing any member of the workarea
where the file is locked). To configure this option, add the following line to the
[iwserver] section of iw.cfg:
[iwserver]
only_lock_owner_creator_submits=yes

Locking Behavior

The lockmodel_compatibility option in the iw.cfg file controls behavior of


Mandatory Write and Optional Write locking. When the option is set to true, all users
who have access to the same workarea can edit the locked file. When the option is set to
false, the file can be edited only by the lock owner in the workarea where it was
locked.

In TeamSite 6.5 and earlier, Mandatory Write Lock implied that the file was locked in
that workarea. Since TeamSite 6.7, Mandatory Write Lock implies that the file is locked
in that workarea and that the user trying to edit is also the lock owner. To get TeamSite
6.5 Mandatory Write Lock model behavior in TeamSite 6.7, set this option to true.
[iwserver]
lockmodel_compatibility=true|false

TeamSite Administration Guide 45


Chapter 3: Configuring the TeamSite Server

Comparing Files
When TeamSite is comparing two versions of a file, it checks the version history chain
to determine a common ancestor for the two versions. You can specify the number of
versions to check using the compare_search_limit option in iw.cfg, as follows (the
default is 20):
[iwserver]
compare_search_limit=20

Submit and Update Logs


By default, the Submit and Update logs contain the 64 most recent Submit or Get Latest
operations for a workarea (as opposed to the 64 most recent files that were submitted or
updated). You can change this number, by editing the event_log_size line in the
[iwserver] section of iw.cfg.
[iwserver]
event_log_size=64

Autoprivate Feature
TeamSite’s Autoprivate feature enables you to prevent certain file types and directories
from being submitted to the staging area or copied during a Copy To operation.
Examples of these files may include temporary files, backup files and Macintosh
resource forks. File types specified in the Autoprivate configuration file automatically
get marked Private.

NOTE
Changes to Autoprivate only apply to files or directories that are created or renamed
after the changes are made. Changes do not apply to existing files.

Files and directories may also be specified Private by turning on the Do not submit
check box in the Properties screen in ContentCenter.

To activate Autoprivate, create a text file named autoprivate.cfg in your


iw-home\local\config\directory. The Autoprivate file consists of two sections:

„ files (or directories) matched by pattern


„ files (or directories) matched by name

Each section is set off by parentheses on their own lines, and the file begins with a “ ( ”
(open parenthesis) on its own line and ends with a “ ) ” (close parenthesis) on its own
line.

Interwoven, Inc. 46
Chapter 3: Configuring the TeamSite Server

Individual entries in the first section are in the following format:

((filenamepattern)(#_characters_to_match_at_beginning)
(#_characters to match_at_end))

where both #_characters_to_match_at_beginning and


#_characters_to_match_at_end are in hexadecimal.

For example, to have Autoprivate detect any file or directory that ends with .frk, add
the following entry:
((x.frk)(0)(4))

meaning to match zero characters at the beginning of the name and the four characters
(.frk) specified at the end of the name.

To set Autoprivate to detect any filename that ends in .backup.fm, add the following
entry:

((x.backup.fm)(0)(a))

where 0 specifies not to match any characters at the beginning, and a (hexidecimal 10)
specifies to match ten characters at the end of the filename.

Entries in the second section specify exact filename matches, set off by double
parentheses. These filename matches apply across all directories in all workareas on the
TeamSite server. For example, if autoprivate.cfg includes:

((test))

then all files and directories named test that are created after this line is added, in all
directories in all workareas in TeamSite, will be marked private.

The autoprivate.cfg file recognizes the following six special characters: ( ) [ ] #


and a space (spacebar). If your file names contain any of these characters, you must
encode these values when specifying them as a pattern. For example, to have
Autoprivate detect a file name that includes spaces, encode the spaces with a \20, for
example, to match “Network Trash Folder” include:

((Network\20Trash\20Folder))

TeamSite Administration Guide 47


Chapter 3: Configuring the TeamSite Server

Encodings are represented as \xx where xx is the hex value of the corresponding ASCII
character. The following table shows the mappings for the six special characters.

Table 4 Autoprivate Encodings


Special Character Autoprivate Encoding
# \23
[ \5b
] \5d
( \28
) \29
space (spacebar) \20

Encoding examples:

((\23x\23)(1)(1)) matches file names of the form: #*#


((\23bbaax)(2)(0)) matches: #b*
((\28ab\29)(2)(2)) #(ab) matches the file name: (ab), the #(ab) is a comment
((a\5b\5db)(2)(2)) matches: a[]b

The following sample autoprivate.cfg file includes a few common entries:


(
(
((x.o)(0)(2))
((x.a)(0)(2))
((x~)(0)(1))
((.nfsXXX)(4)(0))
((x.bak)(0)(4))
((x.tmp)(0)(4))
)
(
((network\20trash\20folder))
((Network\20Trash\20Folder))
((.HSAncillary))
((.HSResource))
((.hsancillary))
((.hsresource))
((.tnatr:intf))
((.tnatr:reso-fork))
((resource.frk))
((trash))
)
)

For changes to autoprivate.cfg to take effect, restart the TeamSite server or use the
iwreset command-line tool.

Interwoven, Inc. 48
Chapter 3: Configuring the TeamSite Server

Working with the Utility Service


The utility service or daemon named iwutild performs various tasks including
executing commands on behalf of trusted clients with impersonation, reading and
writing configuration files, and reading log files. Programs executed on behalf of trusted
clients are restricted to those explicitly specified in the iw-home/etc/iwutild.cfg file.

All iwat triggers and workflow external tasks are executed by iwutild. However, the
programs executed by iwat triggers and workflow external tasks need not be specified
in iwutild.cfg.

The iwutild.cfg file can be edited to modify error logging, executed commands, and
file locations. The following code shows the default iwutild.cfg file.
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE iwutild SYSTEM "iwutild1.0.dtd">

<iwutild>

<!-- Logging options for the Teamsite utility daemon. -->


<!-- utild log level can be either "quiet", "error" or "debug" -->
<!-- hopi log level can be either "quiet", "panic", "error",
"warn", "info" or "debug" -->
<log
level="error"
path="E:\TeamSite\local\logs\iwutild.log"
cmdoutputpath="E:\TeamSite\local\logs\iwutild_cmdout.log"/>

<!-- optional -->


<!-- ipc tunables -->
<hopi
port-ssl="6689"
ssl-cert-dir="E:\TeamSite\local\config\ssl\iwutild"
log-level="error"/>

<!-- The list of commands executed by the utility daemon. -->


<command-list>
<command
name="iwpt_compile"
path="E:\TeamSite\bin\iwpt_compile.ipl"
script="E:\TeamSite\iw-perl\bin\iwperl.exe"
impersonate="true"/>
</command-list>

TeamSite Administration Guide 49


Chapter 3: Configuring the TeamSite Server

<file-list>
<file
name="iwcfg"
path="E:\TeamSite\etc\iw.cfg"/>
<file
name="iwserverlog"
path="E:\TeamSite\local\logs\iwserver.log"/>
<file
name="iwtracelog"
path="E:\TeamSite\local\logs\iwtrace.log"/>
<file
name="iweventslog"
path="E:\TeamSite\local\logs\iwevents.log"/>
<file
name="templatingcfg"
path="E:\TeamSite\local\config\templating.cfg"/>
<file
name="fileencodingcfg"
path="E:\TeamSite\local\config\file_encoding.cfg"/>
<file
name="availabletemplatescfg"
path="E:\TeamSite\local\config\wft\available_templates.cfg"/>
</file-list>

</iwutild>

The iwutild.cfg file uses the port-ssl option to set the port number to be used for the
iwutild service. The default value is 6689. This value can be changed during the
TeamSite installation.

If you change the port number in iwutild.cfg after installation, you need to update the
cssdk.cfg file and set the following option in iw.cfg so that iwserver can find the
iwutild service.
[iwserver]
utild_ext_tasks_portnum=portnumber

The iwutild.cfg file allows you to select which commands or scripts use
impersonation and which are to run as System. The iwptcompiler is one of these
commands. Disable impersonation for a command by specifying impersonate="false"
for the command.

The iwutildreset CLT can force iwutild to re-read the iwutild.cfg file. The
iwutildstat CLT provides status information for the iwutild server. Refer to the
TeamSite Command-Line Tools for information on these CLTs.

Starting/Stopping the iwutild Server


The iwutild service is a separate service that is automatically started and stopped.

Interwoven, Inc. 50
Chapter 3: Configuring the TeamSite Server

Enabling the Event Subsystem


The Event Subsystem is packaged and installed with TeamSite and can be used to
deliver messages (events) to and from Search or ReportCenter with TeamSite as an
event publisher and Search and ReportCenter as subscribers. To do this, the Event
Subsystem stores and queues events.

The Event Subsystem uses a JMS (Java Message Service)-compliant model of message
delivery, which is based on three concepts:
„ Events – Synonymous with message. Events are the result of changes, end-user
actions, or occurrences in a Publisher program. For example, TeamSite server
events include (but are not limited to):
‰ CreateBranch
‰ Submit

‰ TaskActivate

Events have names and properties, such as user, role, and timestamp, that are
represented in the Event Subsystem as attribute/value pairs.
A subscriber can be set up to perform functions after a TeamSite event occurs. For
example, an index can be updated after files are submitted.
„ Publishers. Applications that send events to the Event Subsystem. The Event
Subsystem then passes the events to Subscribers that have registered to receive
them.
„ Subscribers. Applications that register with the Event Subsystem to receive events.
Subscribers can filter events so that they receive only the ones they need.

Figure 6 illustrates how the Event Subsystem works.

Figure 6 How the Event Subsystem Works

Publishers Event Subsystem Subscribers

TeamSite Search
Server Proxy Servlet
ReportCenter

Message Service Interface

Message Service
Implementation

The Event Subsystem is configured by the TeamSite installer. Refer to the TeamSite
Installation Guide for information.

TeamSite Administration Guide 51


Chapter 3: Configuring the TeamSite Server

Configuring the Event Subsystem Manually


The Event Subsystem is normally enabled during the TeamSite installation. You can
verify that the Event Subsystem was enabled by checking the iw-home\etc\iw.cfg file.
Look for the following line in the [event_subsystem] section:
[event_subsystem]
ew_enable=true

If the line is not included, add it to the iw.cfg file. Save and close the file; issue the
iwreset CLT.

The default size of each default_log_location/iwevents/TeamsiteEvents.x log file


(before it rolls over) is 100 MB. This is specified in iw.cfg under the
[event_subsystem] section.
[event_subsystem]
ew_rollover_threshold=104587600

NOTE
The iw.cfg file may contain other commented-out settings in the [event_subsystem]
section; ignore these settings.

When you installed TeamSite, you were asked for information about your database
system. If that process was successful and no warning messages were issued, your
database system is active. If that information was not provided or if the database system
was not configured properly, perform the following steps to set up RDBMS-based event
persistence:
1. Make a copy of the following file:
iw-home\eventsubsystem\conf\jmsconfignew_rdbms.xml.example

and give the copied file the following name:


iw-home\eventsubsystem\conf\jmsconfignew.xml

2. Open the copied file using a text or XML editor.


3. Remove the comment tags from the RdbmsDatabaseConfiguration section that cor-
responds to the RDBMS to use. The RdbmsDatabaseConfiguration section is
located in the DatabaseConfiguration section of that file.
The following code sample shows the commented RdbmsDatabaseConfiguration
section for an Oracle database:
<!-- Oracle setup example
<RdbmsDatabaseConfiguration
driver="oracle.jdbc.driver.OracleDriver"
url="jdbc:oracle:thin:@myhost:1521:dbsid"
userName="user1"
password="password"
retries="5"
timeout="2000"/>
-->

Interwoven, Inc. 52
Chapter 3: Configuring the TeamSite Server

Change the values for the driver, url, username, and password attributes according
to your needs.
4. Copy the appropriate JDBC drivers into iw-home\eventsubsystem\lib.

Oracle classes12.2.zip (shipped with TeamSite Reporting)


DB2 db2jcc.jar
db2jcc_license_cu.jar
MsSQL mssqlserver.jar
msbase.jar
msutil.jar
MySQL MySQL Connector/J can be obtained from www.mysql.com.
5. Create and register database tables before you start the Event Subsystem. A number
of SQL scripts that let you create and register the tables are included with TeamSite
and reside in the following location:
iw-home\eventsubsystem\conf\ddl\create_dbvendor.sql

Run the script that corresponds with the database you use.

Oracle create_oracle.sql

DB2 create_db2.sql

MsSQL create_sqlserver.sql

MySQL create_mysql.sql

Derby create_derby.sql

You can execute the SQL script using a client utility supplied by the database
vendor. For example, if you are using an Oracle database, use SQL*Plus. If you are
using Microsoft SQL Server, use Query Analyzer.
If you are running this script for the first time, the Event Subsystem tables may not
be present and you will receive an error message. Ignore the error message and
continue executing the script.
6. Configure Event Subsystem logging by editing the log4j.xml file in
iw-home\eventsubsystem\conf. Only the location and name of the configuration
file need to be specified. The Event Subsystem uses log4j for logging. More infor-
mation about this can be found at www.apache.org/log4j/docs/.
7. Start the Event Subsystem by selecting Control Panel > Services.
8. Restart the Interwoven servlet engine to ensure that the Event Subsystem servlet is
started; this can be done by issuing an iwreset -ui command.

TeamSite Administration Guide 53


Chapter 3: Configuring the TeamSite Server

Using the Microsoft SQL Server


The deadlock in the Microsoft SQL server running with the Event Subsystem can be
prevented by running the table-rename and view-creation scripts that are part of the
MsSQL DDL (create_sqlserver.sql).

This has to be done manually and is required if MsSQL 2000 or 2005 is being used as
the event subsystem database.

Script for the workaround for MsSQL transactional deadlocks under load:
exec sp_rename @objname='messages',
@newname='messages_table', @objtype = 'OBJECT'
exec sp_rename @objname='message_handles',
@newname='message_handles_table', @objtype='OBJECT'

exec ('create view messages as select * from messages_table with(nolock)')


exec ('create view message_handles as select * from message_handles_table
with(nolock)')

If the database is to be created manually, run the entire create_sqlserver.sql script. If


the TeamSite installation program created the database or the database already exists,
run the section of the script that is marked for the deadlock prevention.

Configuring Microsoft SQL Server 2005 for Use with the Event Subsystem
NOTE
To use the Microsoft SQL Server 2005 with TeamSite Reporting, see “Configuring
Microsoft SQL Server 2005 for Use with TeamSite Report Center” on page 230.

To use the Microsoft SQL Server 2005 with the TeamSite Event Subsystem, install and
configure MSSQL Server 2005 manually as follows:
1. Stop the Interwoven Event Subsystem Service. Use the Services control panel.
2. Uninstall the Event Subsystem Service:
iw-home\iw-perl\bin\iwperl.exe iw-home\install\install_eventsubd.ipl -u
3. Obtain the MSSQLServer 2005 JDBC driver jar file sqljdbc.jar.
4. Copy the file into the iw-home\eventsubsystem\lib directory.
5. Back up the iw-home\eventsubsystem\conf\jmsconfignew.xml file.
6. Copy the iw-home\eventsubsystem\conf\jmsconfignew_rdbms.xml.example file
to iw-home\eventsubsystem\conf\jmsconfignew.xml.

Interwoven, Inc. 54
Chapter 3: Configuring the TeamSite Server

7. Edit the following element in iw-home\eventsubsystem\conf\jmsconfignew.xml:


<DatabaseConfiguration>
<RdbmsDatabaseConfiguration
driver="_JDBC_DRIVER_"
url="_JDBC_URL_"
user="_DB_USER_"
password="_DB_PASSWD_"
maxActive="10"
maxIdle="5"
minIdleTime="1800"
evictionInterval="3600" />
</DatabaseConfiguration>

So that it appears as follows:


<DatabaseConfiguration>
<RdbmsDatabaseConfiguration
driver="com.microsoft.sqlserver.jdbc.SQLServerDriver"
url="jdbc:sqlserver://<database server name>:<database listen
port>;databaseName=<database name>"
user="<database admin user name>"
password="<the above user password>"
maxActive="10"
maxIdle="5"
minIdleTime="1800"
evictionInterval="3600" />
</DatabaseConfiguration>
8. Configure the database on MSSQLServer 2005:
<iw-home\tools\java\jre\bin\java.exe
-Dopenjms.home="iw-home\eventsubsystem"
-classpath "iw-home/eventsubsystem/lib/openjms-0.7.6.1.jar";
"iw-home/eventsubsystem/lib/sqljdbc.jar"
org.exolab.jms.tools.db.DBTool
-create
-config "iw-home\eventsubsystem\conf\jmsconfignew.xml"
9. Rebuild the Interwoven Event Subsystem Service:
iw-home\iw-perl\bin\iwperl.exe iw-home\install\install_eventsubd.ipl -i
10. Use the Services control panel to start the Interwoven Event Subsystem service.

TeamSite Administration Guide 55


Chapter 3: Configuring the TeamSite Server

Deleting Expired Messages

The Event Subsystem clears all messages from the database once they reach a certain
age, regardless of their delivery status. This helps control the database size. The JMS
persistence can cause the database to grow significantly if subscribers such as Search or
Reporting are down. As the proxy servlet web application publishing to JMS server, the
expiry time is added in the iw_bridge_cfg.xml config file (refer to the TeamSite
Installation Guide for information on iw_bridge_cfg.xml):
iw-home\httpd\webapps\eventsubsystem\WEB-INF\iw_bridge_cfg.xml
For example:
<iwovJMS
classpath="C:/Interwoven/TeamSite/eventsubsystem/lib/openjms-client-0.7.6
.1.jar"

initialContextFactory="org.exolab.jms.jndi.InitialContextFactory"
url="tcp://localhost:3035/"
factoryName="JmsTopicConnectionFactory"
topic="Interwoven"
waitTime="300000"
expiryTimeInDays = "2">
</iwovJMS>

The expiryTimeInDays property in the iwovJMS tag can be used for setting up the expiry
time in days; specify whole positive numbers only. The default is 4 days. Specifying 0
or -ve value means the messages do not expire.

Enabling DAS Publishing

OpenDeploy and DataDeploy subscribe to a deprecated message topic called


TeamSite_User. Publishing to this topic is disabled by default. To enable this, perform
the following steps. Future releases of OpenDeploy use the new message topic
Interwoven.

If you are using DataDeploy, enable DAS by performing the following steps:
1. Stop the TeamSite services.
2. Make the following changes to the
iw-home\httpd\webapps\eventsubsystem\WEB-INF\iw_bridge_cfg.xml file.
‰ Add dasTopic="TeamSite_User" property to the iwovJMS tag.
For example:
<iwovJMS
classpath="_IW_HOME_/eventsubsystem/lib/openjms-client-0.7.6.1.jar"

initialContextFactory="org.exolab.jms.jndi.InitialContextFactory"
url="tcp://localhost:3035/"
factoryName="JmsTopicConnectionFactory"
topic="Interwoven"
dasTopic="TeamSite_User"
expiryTimeInDays="4"
waitTime="300000">
</iwovJMS>

Interwoven, Inc. 56
Chapter 3: Configuring the TeamSite Server

‰ Uncomment logFile tags with the name property value of "TeamSiteDASLog"


and "TeamSiteClientDASLog".
For example:
<logFile name="TeamSiteClientDASLog"

baseLogName="_IW_LOG_DIR_/iwui/iwevents/TeamSiteClientEvents"

stateFileName="_IW_HOME_/servletd/logs/iwclientDASproxy.properties"
waitTime="30000"
isDAS="true" />

<logFile name="TeamSiteDASLog"
baseLogName="_IW_LOG_DIR_/iwevents/TeamsiteEvents"

stateFileName="_IW_HOME_/servletd/logs/iwDASproxy.properties"
waitTime="30000"
isDAS="true" />
3. Restart the TeamSite services.
4. The DAS enabling can be verified by looking into the messages_handles database
table for the messages published for the DAS.
example: Pseudo Query:
Select * from message_handles where destinationId in
(Select destinationId from destinations where name ='TeamSite_User')

Configuring Server Performance


The following sections describe the configuration settings that enable you to maximize
the performance of TeamSite relative to your unique environment.

Cache Size
To set the TeamSite cache size, edit the cachesize line in the [iwserver] section of
iw.cfg. If a comment symbol (#) begins the line, remove it. If this line does not appear
in your iw.cfg file, add it as shown below. The initial cache size setting should be
approximately three times the number of files and directories on the largest branch.

For example, if the largest branch contains 15,000 files and directories, you should set
cache size to 45000 as follows:
[iwserver]
cachesize=45000

Minimum cache size is 1000; maximum is 400,000 entries. Each cache line takes a
maximum of 1KB of physical memory. Recommended physical memory is cache size
times 1KB plus an additional 25% as a safety margin. In the example shown below,
physical memory would be (45,000 * 1KB) + 11MB = 56MB. If you encounter a great
deal of memory swapping, you should either reduce the cache size or install more
memory.

TeamSite Administration Guide 57


Chapter 3: Configuring the TeamSite Server

NOTE
The value of cachesize is not the amount of memory that is used, but the number of
objects kept in the cache.

You must restart the TeamSite server for this change to take effect.

External Task Impersonation


When the disable_ext_task_impersonation option in the iw.cfg file is set to true,
workflow external tasks run without impersonation (that is, as System).
[authentication]
disable_ext_task_impersonation=true|false

External tasks run as the task owner and are restricted to the permissions associated with
the task owner. If the impersonate_without_password option in the iw.cfg file is set to
false, the behavior from earlier TeamSite versions in which the iwauth cookie carries
the password is in effect. This applies only to iwptcompile and CGIs and has no effect
if impersonation is turned off for a given command in the iwutild.cfg file.
[authentication]
impersonate_without_password=true|false

Throughput Monitors
Throughput monitors can be used in conjunction with the iwstat CLT to monitor
system status and performance. By default, the throughput monitoring is set to off. To
turn on throughput monitoring edit the thruputmonitoring line in the [iwserver]
section of iw.cfg as follows:
[iwserver]
thruputmonitoring=on

After turning monitoring on, the five default throughput monitors are activated. They
return system statistics over the previous minute, 15 minutes, hour, eight hours, 24
hours, and for the entire time that the system has been running.

You can deactivate any of the default monitors by adding a comment mark (#) to the
beginning of the line. The last two throughput monitors can be configured with custom
time intervals.
[iwserver]
thruputmonitoring=on
thruputmonitor1=1 # 1 minute
thruputmonitor2=15 # 15 minutes
thruputmonitor3=60 # 1 hour
thruputmonitor4=480 # 8 hours

Interwoven, Inc. 58
Chapter 3: Configuring the TeamSite Server

thruputmonitor5=1440 # 24 hours
thruputmonitor6=-1 # forever
thruputmonitor7
thruputmonitor8

Detecting Low Disk Space


TeamSite is configured to freeze the Content Store when it detects that free disk space is
low. The Content Store remains frozen until sufficient disk space is restored, at which
point the server returns to its normal running state. This feature helps prevent possible
corruption of the Content Store. While the Content Store is frozen, users cannot write to
the TeamSite Content Store. Users can still perform read-only operations. The CLT
iwfreeze can be used to manually freeze the Content Store.

The disklow lines in the [iwserver] section of iw.cfg control the behavior of disk low
detection. They are shown here with their default settings:
[iwserver]
disklow_mbytes=50
disklowpercent=10
„ disklow_mbytes—Defines the freeze threshold in MB for the TeamSite server. The
TeamSite server does not allow any write operations if the disk space falls below
this setting.
„ disklowpercent—Defines the percentage of free disk space that is considered low.

NOTE
If the server detects a low-disk state based on the threshold set in iw.cfg, it does not
allow you to manually unfreeze the Content Store with the iwfreeze command.The
TeamSite server does not allow disklowpercent to go below 2 percent. To change these
settings, edit the setting on any of these lines.

Configuring the TeamSite Server Locale


The iw.cfg file contains a server_locale entry in the [iwserver] section. The entry
specifies the locale in which current execution of the TeamSite server (iwserver) runs.
For example:
[iwserver]
server_locale=English_UnitedStates.MS1252@Binary;

This setting is automatically created in the iw.cfg file when iwserver is started. The
system locale is determined by reading the System Locale setting in the Regional
Settings control panel. Once the server_locale setting exists in the iw.cfg file, it is
used to determine the TeamSite server’s system locale at every invocation of iwserver.
If this setting is not present, iwserver determines its locale from the System Locale
setting in the Regional Settings control panel.

TeamSite Administration Guide 59


Chapter 3: Configuring the TeamSite Server

NOTE
While this setting can be user-modified, it is designed to serve as reference as to the
locale in which iwserver is currently running. If you have a situation where you want to
force iwserver to run in a particular locale (independent of the System Locale setting)
you can stop the TeamSite server, manually edit the server_locale line, then restart the
TeamSite server.

The locale in which the server operates (as defined by the server_locale entry),
effectively determines the locale of the TeamSite IFS. For example, if iwserver runs
under the Japanese_Japan.Shift_JIS@Binary locale, all file and directory names are
encoded in Shift_JIS encoding.

The server_locale setting in the iw.cfg file can contain any of the locales listed in the
following table (note that these settings are Interwoven naming conventions—the
operating system locales to which they map are also contained in the table):

Table 5 server_locale Settings


iw.cfg server_locale Setting Windows 2000 Locale
SimplifiedChinese_China.MS936@Binary Simplified Chinese 2000
Korean_Korea.MS949@Binary Korean 2000
Japanese_Japan.MS932@Binary Japanese 2000
German_Germany.MS1252@Default German 2000
English_UnitedStates.MS1252@Binary U.S. English 2000

Configuring FormsPublisher
The following sections describe how to configure FormsPublisher to provide an
example templating environment. After the initial setup is complete, you can:
„ Use the example templating environment to become familiar with the
FormsPublisher end-user features.
„ Customize the example environment to create your site-specific configuration.

Setting up the Example Environment


Perform the following steps to set up the example FormsPublisher environment. You
must copy these files and directories to locations that are specific to your site.
1. Decide which workarea you will use for the initial FormsPublisher setup.
Ideally, this workarea should be on a temporary test branch where you can submit
and publish without affecting the rest of your TeamSite installation. After
FormsPublisher is configured in a workarea on this test branch, you can copy the

Interwoven, Inc. 60
Chapter 3: Configuring the TeamSite Server

workarea to a permanent branch. You can then submit the workarea to the staging
area and use Get Latest to propagate the setup to other workareas on the branch.
2. Read the iw-home\examples\Templating\README file (and README files in the each
subdirectory) for details about directory contents and last-minute information that
might not be documented elsewhere.
3. Copy the contents of iw-home\examples\Templating\templatedata (including the
templatedata directory itself) to the workarea determined in step 1.

‰ Ensure all users have read and write permission for each file.
‰ Do not change any directory or file names.
‰ The end result should be workarea_name/templatedata/...
4. Edit the templating.cfg file to specify the branches where FormsPublisher is used.
5. Optionally, edit the available_templates.cfg file as described in the Workflow
Developer’s Guide.

FormsPublisher Settings in iw.cfg


You may need to configure the following FormsPublisher settings in your TeamSite
iw.cfg file:

Identifying the Templating Directory

To change the directory in your workareas where templating content will reside, modify
the /etc/iw.cfg file. The default directory is templatedata.
[teamsite_templating]
data_root=directory

Maintaining Preview Files

A manifest file is created at the top of the user’s workarea when a preview is performed.
Included in the manifest file is a list of files created during a preview. When a new
preview is requested, the manifest file is checked and the temporary files listed in it are
deleted. The manifest file is also deleted. The preview is then generated and a new
manifest file is created.

The preview_history_limit parameter in the iw.cfg file lets a user do multiple


previews and compare the results of previews without the preview files being deleted.
For example, if preview_history_limit=2, two temporary preview files would be
maintained. When the user does a third preview in the same workarea, the oldest set of
preview and manifest files are deleted and replaced with preview files that are created
by the current preview. As a result, a user's workarea always contains two manifest files
and the corresponding preview files. These files are marked private so they will not be
submitted to the staging area or shown in a TeamSite directory listing.
[teamsite_templating]
preview_history_limit=value

TeamSite Administration Guide 61


Chapter 3: Configuring the TeamSite Server

The preview_system_directory parameter in the iw.cfg file puts preview system files,
such as manifest files, in a directory other than data_root (templatedata).
[teamsite_templating]
preview_system_directory=directory

Controlling Printing of Data Records

Data records are normally written so that all content appears on a single line. You have
the option to print so that each new XML element in a data record starts on a new line,
indented. To enable this type of printing, include the following line in the /etc/iw.cfg
file.
[teamsite_templating]
pretty_print_dcrs=true

TeamSite Embedded Failsafe


The TeamSite Failsafe functionality has been automated to improve the ability to protect
your assets against unexpected server outages. Unlike previous versions of TeamSite,
there is no need to modify your iw.cfg file to benefit from what is now known as
Embedded Failsafe.

Embedded Failsafe improves reliability by automatically flushing the cache at clean


flush points, thereby reducing the possibility of on-disc metadata inconsistencies caused
by abnormal server termination.

Interwoven, Inc. 62
Chapter 4

Managing the TeamSite


Server

This chapter describes configuration settings and procedures that can be used to manage
and enhance your server performance. While there are many variables that contribute to
your TeamSite server performance, the information contained in this section should
prove useful to most TeamSite administrators. The following topics are discussed:
„ Verifying Server Operation
„ Starting and Stopping the TeamSite Server
„ Checking Request Handling
„ Verifying the Server Mount
„ Locating the Installation Directory
„ Reviewing TeamSite Log Files
„ Monitoring the Server Load
„ Reconfiguring iwwebd to Recognize a New IP Address
„ Managing Disk Space
„ Monitoring Disk Space Usage

TeamSite Administration Guide 63


Chapter 4: Managing the TeamSite Server

Verifying Server Operation


To verify that the TeamSite server is running, complete the following procedure:
1. Press Alt + Ctrl + Delete and select Task Manager to open the Windows Task
Manager.
2. Click the Processes tab.
Figure 7 Windows Task Manager, Processes dialog box

3. Ensure that one iwserver.exe is running.


If there is no iwserver.exe listed:
a. Open the Control Panel (Start > Settings > Control Panel) and select
Administrative Tools.
b. Double-click Services.
c. Ensure that Interwoven TeamSite is listed in the Name column, and that it is
listed as Started in the Status column (Interwoven TeamSite in the Services
window is the equivalent of iwserver.exe in the Task Manager).
4. Optionally, check the Mem Usage column of the Task Manager to see how much
memory iwserver.exe is using.
For details about analyzing and changing the amount of memory it is using, and the
relationship between cache size and memory usage, see “Cache Size” on page 57.

Interwoven, Inc. 64
Chapter 4: Managing the TeamSite Server

Starting and Stopping the TeamSite Server


To manually stop the TeamSite server:
1. Log in to Windows with Administrator permissions.
2. Select Start > Settings > Control Panel.
3. Double-click Administrative Tools.
4. Double-click Component Services.
The Component Services Control Panel displays.
Figure 8 Component Services Control Panel

5. Select Interwoven TeamSite from the list of services, and click Stop.
6. Select Interwoven Proxy from the list of services, and click Stop.
7. If you are using OpenDeploy, select Interwoven OpenDeploy from the list of ser-
vices, and click Stop.
8. To restart TeamSite, you must reboot the server host machine.
Do not attempt to restart the Interwoven TeamSite service from the Services control
panel. By default, TeamSite is configured to start automatically on reboot.

NOTE
If you stop the TeamSite server while there are open handles (for example, someone has
a file from the Content Store open, or is exploring it, or it is remotely mounted), either
of the following entries may be written to iwtrace.log:

ERROR: DrvUnMountDevice - Lock volume failed Access Denied


or:
Trying to delete non-existent vnode 0xXXXXXXXX

These messages can be ignored.

TeamSite Administration Guide 65


Chapter 4: Managing the TeamSite Server

Checking Request Handling


To ensure that the TeamSite server is answering requests correctly, type the following
command:
>iw-home\bin\iwversion

If the TeamSite server is responding, you will see a response similar to this:
iwserver: 6.7.0 Build 61235 Interwoven 20060328

If the server does not respond or stops, then the server is not handling requests correctly.
Restart the server as described on page 65.

Verifying the Server Mount


Use Windows Explorer to verify that the Y: (default) drive is mounted as a file system
volume as shown in the following graphic. Note that the directory tree is fully expanded
to show the default directory structure:

Figure 9 Default Directory Structure

If you did not use the default installation location, check the iwmount line in the
[locations] section of iw-home\etc\iw.cfg to find out what drive letter was used.
Use Windows Explorer to verify that the drive is mounted as an IFS volume. If it is not,
reboot the server.

NOTE
If you are using IIS, the Microsoft Management Console may show an error flag next to
the IFS volume when you reboot the Windows server. This does not necessarily indicate
an error. Because IIS starts before TeamSite, it cannot find the IFS volume when it first
starts, and it does not remove the error even after TeamSite starts and the IFS volume
appears. Once the TeamSite server does start, you can navigate to the IFS volume and
see your content files in your backing store.

Interwoven, Inc. 66
Chapter 4: Managing the TeamSite Server

Locating the Installation Directory


To locate the TeamSite installation directory, use the iwgethome.exe CLT:
1. Select Start > Run.
2. Type cmd in the Open field and click OK.
The command window displays.
3. Type iwgethome at the command prompt and press Enter.
TeamSite displays the installation directory:
>iwgethome
C:Program Files\Interwoven\TeamSite

For detailed information about iwgethome and all TeamSite CLTs, refer to the TeamSite
Command-Line Tools manual for your platform.

Reviewing TeamSite Log Files


TeamSite records events in various TeamSite log files and also in the Windows Event
Viewer. These files, their contents, and default locations are described in the following
sections.

NOTE
The default locations of files is iw-home\local\logs.

Configuration Log
The configuration log records the ports assigned to TeamSite during the installation
procedure, the host IP address, and whether auto-configuration of IIS is enabled. The
file is called config_summary.log and, by default, is located in iw-home\install\.

Server Log
The server log records the state of TeamSite over time—including, but not limited
to—when the TeamSite server is started, stopped, and mounted. The file is called
iwserver.log and, by default, is located in iw-home\local\logs. If the file is not in the
default location, you can locate it using the CLT iwgetelog.

Master users can also view the server log from the Administration tab by selecting
TeamSite Admin > Logs > Server Log.

TeamSite Administration Guide 67


Chapter 4: Managing the TeamSite Server

Trace Log
The trace log records any irregularities on the TeamSite server. It is primarily used by
Interwoven Consulting Services to diagnose system performance issues. The file is
called iwtrace.log and, by default, is located in iw-home\local\logs. If the file is not
in the default location, you can locate it using the CLT iwgettrace.exe.

Master users can also view the trace log from the Administration tab by selecting
TeamSite Admin > Logs > Trace Log.

Events Log
The iwevents.log records TeamSite activities—including, but not limited to—file
submits, edition, branch and workarea creation, and DiskLow, Freeze, ShutDown,
StartUp and Thaw events. It is used with certain TeamSite triggering scripts. By default,
the file is located in iw-home\local\logs. If the file is not in the default location, you
can locate it using the CLT iwgetelog.exe. The entries in your iwevents.log file will
be similar to these:

timestamp domain\user role event

[Thu Aug 23 15:43:27 2007] SYSTEM master StartUp


[Thu Aug 23 15:44:11 2007] INTERWOVEN\bgunn _ ModifyEntity
[Thu Aug 23 15:44:14 2007] INTERWOVEN\bgunn _ ModifyEntity
[Thu Aug 23 15:44:16 2007] INTERWOVEN\bgunn _ ModifyEntity
[Thu Aug 23 15:44:20 2007] INTERWOVEN\bgunn _ ModifyEntity
[Fri Aug 24 11:47:47
2007] INTERWOVEN\tom editor TaskGroupTaken CPE
Workflow 0x3ffcf Editor Review 0x3ffd8 tom

event-specific information
(the example line wrapped)

The last sample line states that on Friday August 24, 2007, the user tom, who is logged
in with the role of editor, took ownership of task 0x3ffd8 (or 262104). The task is
labeled Editor Review in job 0x3ffcf (or 262095) and is part of a workflow named CPE
Workflow. The user tom assigned ownership to the task to tom (himself).

Master users can also view the event log from the Administration tab by selecting
TeamSite Admin > Logs > Event Log.

Interwoven, Inc. 68
Chapter 4: Managing the TeamSite Server

Workflow Log
The workflow log records the output from workflow runtime diagnostics. The file is
called iwjoberrors.log and, by default, is located in iw-home\local\logs. The log file
contains entries when the following events occur:
„ When the TeamSite server encounters an error compiling a workflow, including:
‰ a task’s named owner has insufficient privileges to its areavpath
‰ an areavpath does not exist
This does not include every workflow specification that has errors—some errors
occur on the client.
„ When externaltasks have trouble forking.
„ When the workflow engine has problems while running tasks in a job, including:
‰ attempting to create a task variable that already exists.
‰ attempting to add a file to a task that is already in its file list.

Windows Event Viewer


You can configure TeamSite to log and display any of the following events in the
Windows Event Viewer:
„ DiskLow
„ Freeze
„ ShutDown
„ StartUp
„ Thaw

Configuration is controlled by the [iwserver] section in the iw.cfg file. See the
Windows Event Viewer documentation provided by its manufacturer for usage details.

Monitoring the Server Load


The TeamSite CLT iwstat.exe returns a list of all current TeamSite processes, for
example:
„ While the TeamSite server is not running (as the result of iwfreeze), iwstat
returns:
*** SERVER FROZEN: 55 SECONDS REMAINING ***
ID Thread User Duration Operation
0x9d 0xf root 0.000 GetArchiveStatus

TeamSite Administration Guide 69


Chapter 4: Managing the TeamSite Server

„ While the TeamSite server is running, iwstat returns:


Status: Server running
ID Thread User Duration Operation
0x3f4e 0x17 mroot 0.000 GetArchiveStatus
Minutes Thruput Avg op Load
1 27 0.0189 0.51
15 14 0.0219 0.30
29 9 0.0233 0.20

See TeamSite Command-Line Tools for details about iwstat.exe usage and output.

Reconfiguring iwwebd to Recognize a New IP


Address
If you change the IP address of the server hosting TeamSite, complete the following
procedure to reconfigure iwwebd to recognize the new address.
1. Go to the iwwebd.bin folder.
2. Run iwwebd_conf.ipl from the command line.
3. Restart iwwebd.

Managing Disk Space


The following sections describe procedures you can use to manage disk space on the
TeamSite server.

Interwoven, Inc. 70
Chapter 4: Managing the TeamSite Server

File Locations
The [locations] section of iw.cfg must be updated if you change the locations of
certain TeamSite files and directories from their default locations. To change the
location of one of the following files, remove the comment (#) marks from its line and
edit the line to point to the new location (ensure that the [locations] line is not also
commented out). After restarting, TeamSite looks for the specified file or directory in
the new location.
[locations]
iwbin=C:\Program Files\Interwoven\TeamSite\bin
iwmount=Y:
iwcgimount=Y:
iwroles=C:\Program Files\Interwoven\TeamSite\local\config\roles
iwstore=C:\iw-store
iwsubmitconfig=C:\Program Files\Interwoven\TeamSite\local\config\submit.cfg
iwautoprivate=C:\Program
Files\Interwoven\TeamSite\local\config\autoprivate.cfg
iwlogs=C:\Program Files\Interwoven\TeamSite\local\logs
iwconfigs=C:\Program Files\Interwoven\TeamSite\local\config
iweventlog=C:\Program Files\Interwoven\TeamSite\local\logs\iwevents.log
iwtracelog=C:\Program Files\Interwoven\TeamSite\local\logs\iwtrace.log
iwdeploylog=C:\Program Files\Interwoven\TeamSite\local\logs\iwdeploy.log

where:

Table 6 Types of files controlled by [location]


iwbin Specifies the location of TeamSite binaries (by default
iw-home\bin).
iwmount Specifies the location of the TeamSite mount point.
iwcgimount Specifies the location of the non-attribute caching TeamSite mount
point.
iwroles Specifies the directory containing the TeamSite roles files.
iwstore Specifies the location of the TeamSite Content Store (this setting can
be overridden by the Registry key).
iwsubmitconfig Specifies the location of the Submit Filtering configuration file.
iwautoprivate Specifies the location of the Autoprivate configuration file.
iwlogs Specifies the directory containing TeamSite logs.
iwconfigs Specifies the default configuration file directory.
iweventlog Specifies the location of the TeamSite event log.
iwtracelog Specifies the location of the TeamSite trace log.
iwdeploylog Specifies the location of the deployment log.

NOTES
„ The TeamSite shared drive location can be configured to any drive letter (for
example, to change the shared drive to X:, edit the [locations] section to contain
the line iwmount=X:). If you change the shared drive location, you must update the

TeamSite Administration Guide 71


Chapter 4: Managing the TeamSite Server

webserver alias (iw-mount) accordingly. After changing shared drive locations, you
must reboot the server for the changes to take effect.
„ If you change the location of one of the logs and no file with the specified name is
present in the new location, a new file is created.
„ To change the location of the TeamSite Content Store, you must edit the Registry.
Figure 10Registry Editor window

Enhancing File System Performance on the TeamSite Server


On the TeamSite server, browsing the TeamSite shared drive using Windows Explorer
can be slow. If you are working on the system that hosts the TeamSite server, you can
improve performance by completing the following procedure:
1. Open Windows Explorer or My Computer.
2. Select Tools > Map Network Drive.
The Map Network Drive window displays.
3. Click Browse.
The Browse For Folder window displays.
4. Locate the system that hosts the TeamSite server.
5. Click the plus sign (+) to expand the directory tree of your TeamSite server.
The following graphic shows this for a TeamSite server called Bgunn.
Figure 11Expanding the directory tree of the TeamSite server

6. Select IWServer, then click OK.

Interwoven, Inc. 72
Chapter 4: Managing the TeamSite Server

7. In the Map Network Drive window, click Finish.


The new drive is assigned a drive letter (M: in this example) and has access to the
same files, but without sharing.
Figure 12Viewing a shared access drive

Local access only, no sharing, but


much faster access

Shared access (over a network), but


slower local access

When you browse the contents using the new mounted drive, you will notice
improved performance. Users accessing the TeamSite file system interface remotely
(over a network) are not affected.

Monitoring Disk Space Usage


You have two options for checking the amount of disk space used by the files being
managed by TeamSite, either:
„ The size of the Content Store. Actual disk space being used.
„ The size of the mount point. Contains many virtual copies of files in workareas,
staging areas, and editions.

To check the amount of disk space used by files managed by TeamSite:


1. Open Windows Explorer or My Computer on the TeamSite server host.
2. Navigate to, and highlight either the content store (C:\iw-store by default) or the
mount point (IFS Volume Y: by default).

NOTE
You can determine their locations by issuing the iwstore or iwmount CLTs.

The amount of disk usage for your selection is shown in the bottom of the window:

TeamSite Administration Guide 73


Chapter 4: Managing the TeamSite Server

Figure 13 Viewing the size of the iw-store

Size of C:\iw-store

Deleting Editions
To reclaim some disk space, you can delete old editions, which also deletes all files
contained in that edition and all intermediate submissions between publication of
editions. You should be aware that if a file is contained in more than one edition and not
all of these editions are deleted, the file is not deleted; only the pointer to the file in the
deleted edition is deleted. Therefore, you may not save as much space as you anticipate.

To delete an edition using the ContentCenter Professional interface:


1. In the branch view, click the check box next to the edition you want to delete.
2. Select File > Delete.
A confirmation window displays.
3. Type YES in the confirmation field and then click Delete.
The edition and all versions of the files contained within that edition are deleted.
Additionally, all Submit Log entries are transferred to the next most recent edition.
If the edition you have deleted is the newest one, the Submit Log entries are
transferred to the staging area.

NOTE
You can also delete editions using the iwrmed CLT as described in the TeamSite
Command-Line Tools.

Metadata Forking
Metadata forking conserves disk space by reducing the number of files whose content is
duplicated throughout the TeamSite Content Store. That is, if you have an old version of
a file in one branch, and an identical version on another branch, the same data may
appear twice in the Content Store. Metadata forking is accomplished by running the
iwfsshrink CLT and results in no user-visible changes to the TeamSite virtual file
system (for example, file histories are not changed).

Interwoven, Inc. 74
Chapter 4: Managing the TeamSite Server

The iwfsshrink utility must be run while the TeamSite server is running; however,
TeamSite may experience some performance degradation while it is running. Also,
iwfsshrink may not remove all duplicates (for example, it does not remove any
duplicates created by TeamSite users while the utility is running). The iwfsshrink
utility should be run every few months.
1. Start the iwfsshrink utility from the command line:
>iwfsshrink run storename

The utility may take several hours to run.


2. Issue the command again using the status option to view the current status:
>iwfsshrink status storename

when iwfsshrink finishes running, it returns a message similar to:


Not currently running.
Last started Mon Jun 26 15:47:53 2002
Last completed Tue Jun 27 00:40:04 2002
Files examined: 317974
Bytes examined: 75936814830
Files found to be duplicates: 233430
Files converted: 198352
Bytes removed: 23455046531

3. Optionally, you can pause the operation with the pause option, then restart it with
the run option.

For more details about the iwfsshrink utility, see the TeamSite Command-Line Tools.

Moving the Content Store and Removing Old Versions


If you are running out of disk space and iwfsshrink does not recover enough extra
space, you may need to move the TeamSite Content Store. The TeamSite Content Store
must reside on a single logical volume, for example, a single disk or an array of disks.

Alternatively, if you have unused branches in TeamSite, you can delete these branches
to recover disk space. Over time, individual branches take up an increasing amount disk
space, as the number of versions and files on the branch grows. If you do not need any
of your old version history, you can create a new (empty) branch, create a workarea,
copy all the old content into the workarea, then delete the old branch. Exercise extreme
caution when doing this, as all version and metadata information will be irrevocably
lost.

TeamSite Administration Guide 75


Chapter 4: Managing the TeamSite Server

Interwoven, Inc. 76
Chapter 5

Defining Users and Roles

TeamSite provides configurable roles that allow companies to define their own user
roles that map more closely to their corporate structure or to modify the out-of-the-box
roles. Additionally, permissions to manage branches can be delegated to users in
specific roles. This allows users other than TeamSite administrators to manage other
users working on a branch. Information discussed in this chapter includes:
„ User Roles
„ Configuring Roles
„ Managing TeamSite Users
„ Working with TeamSite Groups
„ Working with Branches

Scenario

The following scenario demonstrates how roles might be allocated among users and
some of the functionality available to each role:

Ajuba Corporation, a fictional conglomerate, uses the Interwoven platform to manage


business-critical content across its many subsidiaries. This example focuses on four
Ajuba employees—Andre, Chris, Pat, and Eric—and their roles in maintaining the
partner portal for the subsidiary Ajuba Financial.

Andre, a member of Ajuba Corp.’s Information Technology (IT) group, is responsible


for installing, setting up, and maintaining theTeamSite Content Server. Once Andre has
installed and configured TeamSite, he can set up content stores and TeamSite users and
groups. Andre creates the content stores using the iwstoreadm CLT.

As a Master, Andre has access to the Administration tab in ContentCenter Professional.


Andre creates TeamSite users using the Manage Users section of the Administration tab
in ContentCenter Professional. He can search the OS users by user ID or by name and
can add them as TeamSite users. He can also search the LDAP database for LDAP users
and add users from external databases. He can specify the ContentCenter interface for
each user. This means users can be set up to use either ContentCenter Standard or
ContentCenter Professional or can switch between the two interfaces.

He creates new TeamSite groups using the Manage Groups section of the
Administration tab. He also assigns users to groups and specifies the manager or

TeamSite Administration Guide 77


Chapter 5: Defining Users and Roles

managers of the group. The group manager may or may not be a member of the group
they are managing.

Andre creates new TeamSite roles or modifies existing roles using the Manage Roles
section of the Administration tab. When Andre determines that a new role is needed, he
analyzes the operations to be performed by that role. He then creates a new role by
building from an existing role and adding or removing operations as appropriate. If
necessary, he can also modify existing roles to more accurately reflect the business
needs at Ajuba.

Andre can also stop the server to perform maintenance, and can restart the TeamSite
server. Andre maintains the server’s configuration files and works with the server
through command-line tools, a variety of APIs, or the Administration tab in
ContentCenter Professional.

Chris, a manager in Ajuba’s Partner Marketing Group, is responsible for the partner
portal. Andre creates a branch called Research_Reports and assigns Chris the
Administrator role because Chris is responsible for managing the users and groups and
their roles on the branch and for creating editions when content is ready to be published.
He is automatically assigned the Administrator role if he is made owner of the branch.

The Research_Reports branch is where content for the Financial Research section of
the portal is developed. The initial workarea was created by Andre and the group for
sharing was assigned to a TeamSite group that consists of Research Analysts in the
Marketing Department. Chris has also been made the manager of the TeamSite group by
Andre. He can then add other members in his marketing team to the group and to the
branch (provided the users have already been added to the system as TeamSite users by
Andre).

Chris creates subbranches on the Research_Reports branch that correspond to the


categories of reports published in the Financial Research section: Food_and_Beverage,
Technology, Manufacturing, and so on. Chris adds Pat, a Senior Financial Analyst, to
the system as an Editor because Chris has assigned Pat to review and submit content
developed in the Technology branch. He also adds Eric as a user with the Author role.

Chris uses ContentCenter frequently throughout the week to monitor the progress of
jobs and check the readiness of content in the staging areas of the branches he owns.

Pat uses ContentCenter daily to assign tasks to Authors, review content-in-progress, and
submit files to the staging area. Pat assigns Eric, a Financial Analyst who covers the
wireless sector of the technology industry, a task to update a report.

Eric is an expert with the tools he uses for analyzing a business, but does not need to
know the details of the content management system he uses. As an Author, Eric uses
ContentCenter to manage his tasks and access his content-in-progress. Typically, Eric
responds to automated email messages that notify him of new tasks and requests for
revision.

Interwoven, Inc. 78
Chapter 5: Defining Users and Roles

User Roles
TeamSite provides the following out-of-the-box user roles, each with varying levels of
access to TeamSite:
„ Author
„ Reviewer
„ Editor
„ Administrator
„ Master
„ WorkflowUser
„ WorkflowAdmin

To determine which role a user should have, consult the following lists of tasks and find
the role that best fits the user’s work. If these roles do not meet your needs, you can
configure your own roles as described in “Configuring Roles” on page 82.

Reviewer

A TeamSite user with the Reviewer role performs the following tasks:
„ Search for content.
„ Compare files.
„ Preview files.
„ Preview form output.
„ Create new jobs, transition tasks, attach and remove files from tasks, view task
details and properties.

Author

A TeamSite user with the Author role performs the following tasks:
„ Create, edit, import, move, rename, copy, and delete folders and files.
„ Merge, lock, tag, revert, submit, and preview, and compare files.
„ Mark files private, search for content, and submit content.
„ Edit file properties.
„ Create forms, preview, and generate form output.
„ Update workarea.
„ View files in context of all content in staging area.
„ Create new jobs, and work with tasks assigned to them.

TeamSite Administration Guide 79


Chapter 5: Defining Users and Roles

Editor

A TeamSite user with the Editor role performs all the tasks that an Author can perform
and also does the following tasks:
„ Download files, perform a copy to area operation.
„ View all jobs and assign tasks.
„ View and modify job properties and file permissions.
„ Approve and reject content.

Administrator

A TeamSite user with the Administrator role performs all the tasks that an Editor can
perform and also does the following tasks:
„ Create and delete branches and edit their properties.
„ Create and delete workareas and edit their properties.
„ Create and delete editions and edit their properties.
„ Add users to the branch and specify their role.
„ Add, remove, or modify TeamSite users and groups.
„ Delegate administration of the branch or subbranches.
„ Change job and task attributes.

Master

A TeamSite user with the Master role performs all the tasks that any other user can
perform and also does the following tasks:
„ Add, delete content stores and edit their properties.
„ Freeze and thaw the Content Stores.
„ Add TeamSite users.
„ Create/modify roles.
„ Create/delete TeamSite groups.
„ Delegate administrative authority.

A Master user can work anywhere in TeamSite. This role is not configurable.

NOTE
Most installations only need to assign a few Master users, who will then delegate
administrative authority to other users.

Interwoven, Inc. 80
Chapter 5: Defining Users and Roles

WorkflowUser

By default, all TeamSite users should be able to use workflow models. To achieve this,
the workflowModels branch of the iwadmin store is shared for iwEveryone with role as
WorkflowUser.

This role has the minimum privileges required to instantiate a workflow. Users with the
WorkflowUser role can perform the following tasks in TeamSite:

„ Create, copy, and delete files and folders.


„ Edit files.
„ Lock and unlock files.
„ Modify file extended attributes.
„ Submit files and update the workarea.

NOTE
The iwEveryone group is automatically added to the workflowModels branch with the
WorkflowUser role. You do not have to add it manually.

WorkflowAdmin

Not all TeamSite users are allowed to create, subscribe, and configure workflow models.
Normally, users who can perform these operations include workflow developers or
TeamSite administrators.

The WorkflowAdmin role has privileges to design workflows using Interwoven


Workflow Modeler and upload them to TeamSite. They have privileges to manage,
configure, and debug the workflow models.

Users with the WorkflowAdmin role can perform the following tasks in TeamSite:
„ Crete, copy, move, and delete files and folders.
„ Download and import files.
„ Preview and edit files.
„ Lock and unlock files.
„ View file history.
„ Modify file extended attributes.
„ Submit files and update workarea.
„ Manage workflow models.
„ Configure workflow models.
„ Publish workflow models.
„ Webview workflow model.

TeamSite Administration Guide 81


Chapter 5: Defining Users and Roles

NOTE
Add users to this role manually. This role should not normally be given to the
iwEveryone group.

Users with the WorkflowAdmin role can perform four new operations in TeamSite, in
addition to the existing operations mentioned in this section. Refer to the Workflow
Modeler User’s Guide for more information on these operations.

The four new operations have been included under the Workflow category (select
Administration > Roles and Permissions > Manage Roles > Edit). They are as
follows:
„ Manage Workflow Model. Users can add or remove workflows allowed for a
branch or vpath. They can specify the users who can instantiate these workflows.
They have access to the Manage Workflows link.
„ Publish Workflow Model. Users can use Interwoven Workflow Modeler to publish
workflows to TeamSite. Without this permission, users can only save the workflow
in the draft state to the iw-wa workarea. They cannot publish it (that is, submit it to
the staging area).
„ Configure Workflow Model. Users can configure or customize the workflows for
different branches. They can provide default values or make certain fields hidden or
visible during instantiation.
„ Webview Workflow Model. Users can view the workflow in a browser. They can
check the values of the properties for each task and track the workflow after
instantiation.

Configuring Roles
TeamSite provides the out-of-the-box roles described in “User Roles” on page 79.
TeamSite provides a method for Master users to modify these out-of-the-box roles as
well as create new roles.

TeamSite defines all the operations that can be performed by users in the out-of-the-box
roles. These operations display on the Edit Roles screen. If your site has created
additional operations, these are described in the custom_userops.xml file and will also
display on the Edit Roles screen; refer to the TeamSite User Interface Customization
Guide for information on this file.

The roles.xml file contains the descriptions of each role. This file is modified by
changes made through the Manage Roles option on the Administration tab.

NOTE
The iwroleadm CLT can also be used to manage roles.

Interwoven, Inc. 82
Chapter 5: Defining Users and Roles

Recommendations:
„ When creating a new role, start with an existing role that is similar to the role you
want to create. Make changes as appropriate.
„ When creating roles, define all the business user roles (non-administrative roles)
first and then create the administrative roles later (administrative roles are not
limited to the Administrator role but refer to the general category of roles that can
administer TeamSite functions). The non-administrative roles need to exist so that
you can add them as delegable roles in your administrative roles. (For example, if
you create new roles such as Contributor and Approver first, these new roles are
available to select as delegable roles when you create or edit your branch
administrator role.) New customer-defined roles are not automatically added as
delegable roles, so defining the non-administrative roles first saves you from going
back to the Administrative role to add new roles as delegable roles.
„ Avoid using spaces in role names.

Managing Roles
The Roles screen shows the names and description of each TeamSite role. TeamSite
ships with four out-of-the box roles (see “User Roles” on page 79) that can be configured
plus the Master role that cannot be configured (so it is not listed on this screen).

Figure 14 Roles screen

Each role has a link to edit it or to remove it.

The New Role link lets you create new roles. It is recommended that new roles be
created from existing roles with changes to meet your specific configuration.

TeamSite Administration Guide 83


Chapter 5: Defining Users and Roles

Creating New Roles


Click the New Role link to display the New Role screen, which contains the following
fields:
„ Create from. Select from the list of existing roles to use as a starting point as you
create your new role. Select a role that provides similar functionality to the role you
are creating. For example, if you want to add functionality to an Editor role, select
Editor. If you select (no role), the Edit Role screen will not have any operations in
any categories checked. Selecting (no role) is not recommended.
„ Name. Enter the name of your new role. The role name is set to the name specified
in this field and cannot be changed once the role is created even though the display
name may change. A role name may need to be specified in the iw.cfg file or when
designing workflows.
„ Description. Enter a description of your new role.

Click Next to move to the Edit Role screen where you can specify the attributes of your
new role.

Figure 15 New Role screen

Interwoven, Inc. 84
Chapter 5: Defining Users and Roles

Editing Roles
The Edit Role screen is used to make changes to the operations performed by users in
this role. This screen displays when you click Next from the Add Role screen or Edit
next to a role.

Figure 16 Edit Role screen

The Display Name and Description fields show the name of the role and the
description. If you are creating a new role, these are the values that you entered in the
Add Role screen. These fields can be modified. However, the role name was set to the
name specified in the New Roles screen and will not change even though the display
name may change. A role name may need to be specified in the iw.cfg file or when
designing workflows.

TeamSite Administration Guide 85


Chapter 5: Defining Users and Roles

The Roles that role can delegate field is used to specify role delegation
permissions.When a user is granted permission to delegate, that user can assign roles to
other users on that store or branch. For example, if a user has a role such as
Administrator that allows delegation of Editors, the Administrator can assign users the
Editor role on that branch. To allow delegation, move the role from the Available to the
Selected field by highlighting the role and clicking the arrow. If you have delegation on
a branch, you normally also have it on any subbranches.

The Locking model field lets you select the type of locking that occurs when users in
this role work on files. The choices are:
„ Submit Lock
„ Optional Write Lock
„ Mandatory Write Lock
„ None

Refer to “Setting Locking Models” on page 44 for information on locking models.

The categories area of the form shows the More Detail and Less Detail links. More
Detail opens all the categories and shows all the check boxes that can be selected. Less
Detail closes all categories.

Each category includes a title, a brief summary and the links More Detail and Less
Detail. These links show or close the available check boxes for that category only.
When a category shows details, the Select All and Clear All links control whether all or
none of the check boxes are selected.

You can change the attributes for a role in the following categories:
„ Branch Administration. Lets you give users authorization to create, delete, and
rename branches, modify branch properties, delete and rename editions, and
delegate roles.
„ ContentCenter Professional Operations. Enables the Reporting tab in
ContentCenter Professional. Refer to Appendix A, “Configuring TeamSite
ReportCenter,” for information on the ReportCenter.
„ Content Management. Controls whether users can compare files, publish an
edition, submit content, and update workareas (that is, do Get Latest and Copy to
Area operations).
„ Custom User Operations. Lists items that have been specifically set up for your
organization. This functionality is contained in the custom_userops.xml file; refer
to the TeamSite User Interface Customization Guide.
„ External Triggers. Controls whether the users in this role can modify the iwat CLT
triggers. Refer to the TeamSite Command-Line Tools.
„ Files, Forms, and Folders. Controls the actions that users may perform with files
and forms. These include editing, previewing downloading, and merging files;
copying deleting, moving, and renaming files and folders; previewing and
generating forms; searching for file content; locking and unlocking files; reverting

Interwoven, Inc. 86
Chapter 5: Defining Users and Roles

to an earlier version of a file; undoing changes; marking files private; changing file
extended attributes and permissions; and viewing the file history.
„ New and Imported Content. Controls whether users can create files, folders, and
forms and import content.
„ Store Administration. Indicates whether users in this role can freeze and thaw the
content store.
„ User Administration. Controls whether users can create and delete TeamSite users
and create TeamSite groups.
„ Workarea Administration. Indicates whether users can create, rename, and delete
workareas, and modify workarea properties.
„ Workflow. Controls all aspects of jobs and tasks. These operations include:
‰ Tasks. Attach a file, add a comment, assign a task, detach a file from a task, and
read or modify task properties.
‰ Jobs. Create and end a job, and read and modify job properties.
‰ Ownership. Take or return ownership of a group task, retry a task, and take a
task back.
‰ View. View all jobs and tasks, the user’s jobs and task, and job details.
‰ Manage Workflow Model. Add or remove workflows allowed for a branch or
vpath. Specify the users who can instantiate these workflows using the Manage
Workflows link.
‰ Publish Workflow Model. Use Interwoven Workflow Modeler to publish
workflows to TeamSite. Without this permission, users can only save the
workflow in the draft state to the iw-wa workarea. They cannot publish it (that
is, submit it to the staging area).
‰ Configure Workflow Model. Configure or customize the workflows for
different branches. Provide default values or make certain fields hidden or
visible during instantiation.
‰ Webview Workflow Model. View the workflow in a browser. Check the values
of the properties for each task and track the workflow after instantiation.

At the bottom of the Edit Role screen is the Permission Overrides section. These
options lets users in this specific role:
„ Modify tasks and jobs that they do not own.
„ View and modify files in workareas where they are not a member of the group for
sharing.

Providing these permissions in a role allows users with that role to perform actions such
as cleaning up files or deleting jobs even though they may not own the job or have
permission to work on the files.

TeamSite Administration Guide 87


Chapter 5: Defining Users and Roles

NOTE
Users with permission overrides can perform operations through ContentCenter.
However, if these users access files through the file system (Y: drive), traditional file
system permissions govern file access. Permission overrides should be used carefully.

Deleting Roles
Clicking the Delete link opposite a role name in the Roles screen displays a message
asking you to verify deletion of the role. If you click Delete, the role will no longer be
available in TeamSite. TeamSite users in the deleted role can view public branches and
workareas and file contents but cannot perform TeamSite operations unless they have
access through another role.

Managing TeamSite Users


You can view TeamSite users, add users, and delete users from the Manage Users link
in the Administration tab.

TeamSite users may have operating system access (referred to as OS users) or they may
be users who do not have operating system (OS) access (referred to as non-OS users).
Non-OS users can be assigned roles so they have the same TeamSite access as any other
TeamSite user. Non-OS users can only be added to non-OS groups. TeamSite Master
users can add non-OS users to TeamSite without waiting for the IT department to add
these users to the operating system.

TeamSite can configured to use LDAP or Active Directory for user authorization. You
can maintain multiple LDAP databases. These must be identified to TeamSite in the
user_databases.xml file (refer to “Storing TeamSite Users” on page 123). An LDAP
database may contain either OS users or non-OS users, but OS and non-OS users cannot
be mixed in an LDAP database.

NOTE
Depending on how your LDAP database is identified in the user_databases.xml file,
the users may be synchronized with TeamSite users automatically. This process is
described in “Synchronizing LDAP Users” on page 127.

Information about TeamSite users is stored in the iw-home\conf\roles\tsusers.xml


file. This file is maintained by adding users, deleting users, or editing user information
through the Manage Users link in the TeamSite Administration tab, with the
iwuseradm CLT, or through the synchronization process. Do not modify the
tsusers.xml file manually.

Interwoven, Inc. 88
Chapter 5: Defining Users and Roles

The iwuseradm CLT can also be used to maintain the information in the tsusers.xml
file; refer to the TeamSite Command-Line Tools for information.

Adding TeamSite Users


To add users to TeamSite, you must be a Master user. Select the Administration tab in
ContentCenter Professional. Navigate to Roles and Permissions > Manage Users. Click
the Add User link. The Add User screen lets you select users to add as TeamSite users.
You can enter an user name, search for a user, or browse the LDAP databases. From the
results of the Search/Browse, select users to be added as a TeamSite user.

Figure 17 Add Users screen

In the Email field, enter the user’s email address.

In the Preferred ContentCenter field, select one of these options to specify the
ContentCenter interface for each user:
„ Professional. ContentCenter Professional displays when the user logs in. A link at
the top of the screen allows them to move between ContentCenter Professional and
ContentCenter Standard. When logging in later, the user returns to the interface they
were using when they logged out.
„ Professional only. ContentCenter Professional displays. The user cannot switch to
ContentCenter Standard.
„ Standard. ContentCenter Standard displays when the user logs in. A link at the top
of the screen allows them to move between ContentCenter Standard and
ContentCenter Professional. When logging in later, the user returns to the interface
they were using when they logged out.
„ Standard only. ContentCenter Standard displays. The user cannot switch to
ContentCenter Professional.

TeamSite Administration Guide 89


Chapter 5: Defining Users and Roles

You can specify that this user has the Master role by selecting the This user is a
TeamSite Master check box.

After a TeamSite user is added, you may, optionally, create a workarea for the user on
the subbranch where he or she will be working (see the ContentCenter Professional
online help).

When creating a workarea, you must include the user’s domain name in the Name field
of the New Workarea window (for example, MYDOMAIN\andre); use the Find option to
select this information. However, for a non-OS user, just enter the user id.

Search or Browse for Users

When you click the Search/Browse button on the Add Users screen, the form that
displays allows you to search for users or browse LDAP databases.

Figure 18 Search tab to search for users

In the Search tab, select the database you want to search. Enter a name or partial name
in the Name field. Click Search. Users satisfying the search criteria display. Highlight
the users you wish to add (hold down the Ctrl key while clicking on the user names to
select multiple users). Click Select User.

The users you selected display in the Selected Users area of the screen. You can do
multiple searches by changing the database and the name. The users you select from the
new search are added to the Selected Users area. You can select and remove individual
users and all users from this list with the Remove and Remove All buttons.

When you complete your search, click OK to add the selected users to TeamSite.

Interwoven, Inc. 90
Chapter 5: Defining Users and Roles

In the LDAP Browse tab, you can browse through the list of LDAP databases. Highlight
the users you wish to add (hold down the Ctrl key while clicking on the user names to
select multiple users). Click Add Selected Users.

Figure 19 LDAP Browse tab

The users you selected display in the Selected Users area of the screen. You can add
users from different databases. The users you select from the new database are added to
the Selected Users area. You can select and remove individual users and all users from
this list with the Remove and Remove All buttons.

When you complete browsing the databases, click OK to add the selected users to
TeamSite.

TeamSite Administration Guide 91


Chapter 5: Defining Users and Roles

Add Multiple Users

When you select multiple users to add to TeamSite as a result of the search or browse
processes, the Add Multiple Users screen displays.

Figure 20 Add Multiple Users screen

This screen offers two choices:


„ You can add all the selected users to TeamSite with the same ContentCenter
interface. You can also indicate whether all the users are to be TeamSite Masters.
„ You can individually review and edit each users, but you specify the starting
ContentCenter interface and Master status.

When you add all the selected users at the same time by clicking Add, the users display
in the list of users. If you wish to individually review each other, when you click Add
the Add Multiple Users Individually screen displays.

Interwoven, Inc. 92
Chapter 5: Defining Users and Roles

Add Multiple Users Individually

When you select multiple users and indicate that you want to add the individually, the
Add Multiple Users Individually screen displays.

Figure 21 Add Multiple Users Individually

Each user is listed separately. The user name, database where the user information is
stored, and email address display. You can change the ContentCenter interface and
specify whether the user is to be a TeamSite Master.

After you have specified the information for each user, click Add.

Editing TeamSite Users


To edit the information about a TeamSite user, click on Edit opposite the user name.

The User Details screen provides information about the user and lets you modify
existing user information.

The user ID, name, and email address display as specified when the user was added to
TeamSite. The groups of which this user is a member are shown. The workareas and the
role the user has in each of those workareas is also shown.

You can change the value in the Preferred ContentCenter field and change whether the
user is a TeamSite Master. If the user is an OS user, you can also modify the email
address.

TeamSite Administration Guide 93


Chapter 5: Defining Users and Roles

Deleting TeamSite Users


To remove a TeamSite user, click on Delete opposite the user name to remove the user
from TeamSite. A verification message displays; click Delete to remove the user or
Cancel to retain this TeamSite user. TeamSite is no longer accessible to a deleted user.
You can optionally use the iwuseradm CLT to delete a user.

Recommendation: Remove the user from any groups, workareas, or branches that refer
to that user before deleting the user.

If your installation uses the LDAP synchronization process to obtain user information,
delete the user from the LDAP database or delete all LDAP roles for the LDAP user
entry. The next time the iwldapsync CLT is run, the user will be removed from
TeamSite. If the user needs to be removed immediately, you can manually run the
iwldapsync CLT.

Use the following CLT to remove the user from the TeamSite entity database:

>iwuser -d DOMAIN\username

where DOMAIN\username is the username of the user you want to remove.

If you do not perform this step, you will not be able to create another user with the same
name.

To remove the user’s Windows account from the TeamSite server, use the Windows
Computer Manager or, if Microsoft Active Directory is installed, use the Active
Directory Users and Computers administrative tool:
1. Remove the user from any groups the user belongs to.
2. Remove the user account itself.

Working with TeamSite Groups


TeamSite provides managed groups of users (referred to as TeamSite groups) to
complement the groups managed through the Windows operating system (referred to as
OS groups) that TeamSite uses as groups for accessing branches and sharing workareas.
This feature allows groups other than the OS groups to be specified for sharing. When a
branch is created, the TeamSite group can be entered in the Add Group field. When a
workarea is created and Group is selected for the Sharing field, the TeamSite group can
be entered. TeamSite groups can also be used in branch access entries.

Interwoven, Inc. 94
Chapter 5: Defining Users and Roles

When using TeamSite groups, one OS group is used for file system representation; the
default iwglobal group is created when TeamSite is installed. This is the name of the
OS group that displays in the file system interface for assets that are shared by non-OS
users. The name of the default group is configurable using iwglobal_group in the
iw.cfg file. You must restart TeamSite for this change to take effect.
[iwserver]
iwglobal_group=group_name

TeamSite uses the iw-home\conf\tsgroups.xml file to store information about


TeamSite groups. The tsgroups.xml file is created and maintained through the Manage
Groups link in the Administration tab or by the iwgroup CLT. While the file can be
modified by administrators, it is recommended that modifications to the file be made
through the Administration tab or the CLT. The TeamSite server reads this file into
memory and allows branches and workareas created with group for sharing options to
use these groups.

Managing Groups
When you select Manage Groups, the Groups screen shows a list of TeamSite groups.
The listing can be modified by clicking All to show all the groups or by clicking
Managed by: to show the groups managed by the logged-in user.

NOTE
TeamSite ships with the out-of-the-box TeamSite group iwEveryone. This is a group of
all TeamSite users; it cannot be deleted.

Figure 22 Groups screen

TeamSite Administration Guide 95


Chapter 5: Defining Users and Roles

Click New Group to display the New Group screen. In this screen, you can enter the
name of the new TeamSite group and a description of the group.The group name must
contain at least one non-numeric ASCII character.

Figure 23 New Group Screen

For each group, you can click on links to obtain more information about that group:
„ Members. Displays the Group Membership screen to show a list of all the members
in that group.
„ Managers. Displays the Group Managers screen to show a list of the managers of
that group. A manager does not need to be a member of the group.
„ Properties. Displays the Group Properties screen to allow you to modify the
properties.
„ Delete. Deletes the group after requesting verification that you do want to delete the
group.

Interwoven, Inc. 96
Chapter 5: Defining Users and Roles

Working with Group Properties


The Group Properties screen is accessed from the Properties link in the Group
Membership screen or from the Group List screen. You can change the description. The
group name cannot be modified. Click Save to make your change.

Figure 24 Group Properties screen

Click on Members to go the Group Membership screen to modify the members of the
group.

Group Membership
The Group Members screen shows all the members of the group. You can control the
display using the following links:
„ Collapsed. The collapsed view shows the names of group members and the names
of the subgroups within the group.
„ Expanded. The expanded view shows the names of group members and expands the
subgroups so all members of the subgroups are listed.

TeamSite Administration Guide 97


Chapter 5: Defining Users and Roles

Figure 25 Group Membership screen

You have links to work with the group as follows:


„ Add Members. Displays the Users and Groups window so you can enter search
criteria to locate TeamSite users or existing groups to add to the group.
„ Properties. Displays the Group Properties screen so you can modify the description
of the group.
„ Managers. Displays the Users window so you can select individuals to manage the
group; multiple managers may be specified. A group manager does not need to be a
member of the group.
„ For each member of the group, you can select the links:
‰ Add as Manager. Clicking this link results in this individual being added as a
manager of the group. To remove this individual as a manager, go to the Group
Manager screen.
‰ Remove. Remove this user from the group.

Viewing Group Managers


The Group Manager screen shows all managers of the group. A group manager does not
need to be a member of the group. A group manager can use the Actions > Manage
Groups menu item to modify the group members, managers, or properties.

Interwoven, Inc. 98
Chapter 5: Defining Users and Roles

Deleting Groups
Clicking the Delete link opposite a group name in the Group screen displays a message
asking for you to verify deletion of the group. If you click Delete, the group will no
longer be available in TeamSite.

TeamSite users in the deleted group may still have access to TeamSite branches if they
are members of other groups that have a role on a branch or if they directly have a role
on a branch. Minimally, without being in any group or having any role, users can still
navigate into public branches and public workareas and see folders for which they have
read permissions.

Recommendation: Care should be taken to ensure that no assets are held by the group to
be deleted. You may want to just empty users from the group but leave the group. A
TeamSite administrator can later use the iwidmap CLT and reassign assets to another
group.

The iwgroup CLT


The iwgroup CLT manipulates Interwoven group information. Refer to the TeamSite
Command-Line Tools for usage information on the iwgroup CLT.

NOTE
Be careful not to add an OS group that has a name that is the same as an existing
TeamSite group name; doing so may prevent TeamSite access.

Working with Branches


Branches represent paths of content development. Branches contain exactly one staging
area, one or more editions, and one or more workareas. Newly created branches are
based on an edition of the parent branch. A staging area and an INITIAL edition are
created automatically when a new branch is added; workareas must be created manually.

Content can be shared among branches. See “Integrating Content From Different
Branches” on page 102.

A locking model is one of the properties set when a branch is created. Locking models
specify locking behavior for all workareas on the branch and determine whether users
can edit files in different workareas at the same time. The role the user has on a branch
also sets locking behavior. The locking behavior for both the branch and the role are
combined to determine the locking behavior for a user in a branch. See “Setting Locking
Models” on page 44.

All users can view public branches and their properties, but only users with a role on the
branch can view private branches. Only users in roles who have authorization can

TeamSite Administration Guide 99


Chapter 5: Defining Users and Roles

reassign a branch to a new owner and update the branch properties. Only some
properties are editable after the branch is created.

Deleting branches removes them and their contents, including the version history, from
the system. Use caution when deleting branches.

To access branches:
1. Select the Content tab.
2. Navigate to the store that contains the branches you want.
3. Open the main branch. If subbranches exist, navigate through them to the branch
you want.

Controlling Branch Ownership and Administration


You can specify the owner and group of the main branch of a new Content Store by
editing the main_owner and main_group lines in the [iwserver] section of iw.cfg.
When TeamSite is first installed, it uses the default option of Administrator for main
branch ownership as follows.
[iwserver]
main_owner=Administrator
main_group=Administrators

To change this setting on an existing main branch, you must use the Windows File
Properties to take ownership, or the command-line tool iwchgrp to change the group of
the root directory of the main branch. However, if you edit the main_owner and
main_group lines and then create a new Content Store, the new settings take effect on
the new Content Store. For information about creating a new Content Store, see the
TeamSite Installation Guide.

You can specify the role that the owner of a branch has in the iw.cfg file. This role will
be added for the person who is the branch owner. This will be in effect whenever a new
branch is created. If nothing is specified, the Administrator role is used.
[iwserver]
branch_owner_role=role_name

You can specify the role or roles that can administer branches (have access to the
Actions > Manage Branches menu item) with the following iw.cfg option:
[iwserver]
admin_roles=role_name, role_name

If a user has one of the roles specified in the admin_roles setting in the branch being
viewed, the Manage Branches menu item is enabled. This setting controls whether the
user sees the menu item; it does not give users in the roles any additional privileges,
such as adding users to a role on a branch. For that, you still need to modify the role to
have Delegate permission.

Interwoven, Inc. 100


Chapter 5: Defining Users and Roles

You can specify a secondary master user other the local administrator with the following
iw.cfg option:
[iwserver]
secondary_admin_account=domain\user

Creating Branches
Users with appropriate permissions can create subbranches within branches.

Figure 26 New Branch screen

To create a branch:
1. Select the Content tab.
2. Navigate to the branch under which you want to create the new branch.
3. Click New Branch in the view pane title bar.
4. Enter a name for the branch.
5. Enter a general description of the branch (for example, if content for a product cata-
log is to be developed on the branch, you might enter “Branch established for the
development of product catalog content.”).
6. Your user name is displayed in the Owner field by default. Enter a different user
name if you want to assign the branch to another person. By default, this user will
have the Administrator role on the branch (unless a different role has been config-
ured using the branch_owner_role option in the iw.cfg file).
7. Select a locking option. See “Setting Locking Models” on page 44 for information
about those options.
8. Enter the name of the edition you want to use as a starting point. The edition must
be from the parent branch.

TeamSite Administration Guide 101


Chapter 5: Defining Users and Roles

9. Specify whether you want to you want the branch to inherit access from the parent
branch.Turn on Inherit from Parent to indicate that the users and their roles should
initially be identical to those on the parent branch. You can add additional users
later. This is the recommended setting. If this setting is not turned on, you select the
users and groups for this branch separate from the parent branch. It is recommended
that individual users be added to a TeamSite group rather than being added individ-
ually to a branch.
10. Select Restrict Access to set up this branch so it only displays for users or the
groups that have permission to work in the branch. By default, a restricted branch is
shown in general listings of all branches, but users without a role on that branch
cannot go into that branch. (The branch_security option in iw.cfg controls
whether the name of restricted branches can be seen.)
11. Click OK.
The branch is created and contains no workareas, one edition named INITIAL, and
a staging area. The staging area and INITIAL edition contain a copy of the content
from the edition you chose as a starting point.

After a branch is created you can create workareas and base them on the branch’s
INITIAL edition, or any other editions you create on the branch.

Integrating Content From Different Branches


You can integrate content from different branches manually, or through automated
workflow processes. This section describes the manual process; see the TeamSite
Workflow Developer’s Guide for information about automated workflow processes.

The staging area and INTIAL edition in newly created branches contain a copy of the
content in the parent branch’s edition on which they are based. Newly created workareas
contain a copy of the content in the branch’s edition on which they are based. Therefore,
if you want to create subbranches with workareas that contain content similar to that in
the parent branch, create an edition for the parent branch that contains the content you
want, and base your subbranches on that edition. You can then base the workareas on the
INITIAL edition in each subbranch.

To manually integrate content from one branch to another:


1. Select the Content tab.
2. Navigate to the branch that contains an edition of the content that you want to prop-
agate.
3. Click Editions.
The view pane displays the Editions view. The Editions view lists the staging area
(top) and editions (most recent first).
4. Select the edition that contains the content you want, or navigate into the edition and
select the items you want to propagate if only a subset of the edition’s content is
desired.

Interwoven, Inc. 102


Chapter 5: Defining Users and Roles

5. Select a workarea.
6. Select an overwrite option.
7. Click OK.
The content is copied to the selected workarea.

After the content is copied to the workarea on the target branch, you can submit the
content and create new editions to meet your needs.

Managing Branches
If your role allows you to manage branches, you can use the Actions > Manage
Branches menu item from the Content tab to display the Manage Branches screen. This
screen lists the branches you can manage, along with your role or roles in each branch.
From this screen, you can delete or rename the branch. Each branch also has a
Properties link so you can modify the branch properties. Click on the name of the
branch to find the users and their roles.

Figure 27 Manage Branches screen from the Actions menu

TeamSite Administration Guide 103


Chapter 5: Defining Users and Roles

Working with Branch Properties


When you click the Properties link that corresponds to a branch, the Branch Properties
screen displays.

Figure 28 Branch Properties screen

It contains the following information:


„ Name. The name of the branch.
„ Location. The path to the branch.
„ Description. The text entered to describe the branch. You can modify this field if
you have permission to manage branches.
„ Created on. The date the branch was originally created.
„ Locking. The locking model that was selected when the branch was created.
„ Based on. The edition that was used to provide content for this branch.
„ Owner. The owner of the branch. You can modify this field if you have permission
to manage branches. You can use the Find link to search for the user who will own
the branch.
„ Users and Roles. The Inherit from Parent check box controls whether users and their
roles should initially be identical to those on the parent branch. Additional users can
be added later. If this setting is not turned on, the users and groups for this branch
are selected separate from the parent branch.
„ Private. The Restrict access check box determines whether the branch is visible only
for users with access to this branch or whether it can be viewed by all TeamSite
users.

Interwoven, Inc. 104


Chapter 5: Defining Users and Roles

If you make changes to the branch properties, click Save to save and close the Branch
Properties screen.

You can click Users and Groups to see the list of users and groups with access to this
branch and the role they have for this branch.

Viewing Branch Users and Roles


The Branch Users and Roles screen shows a list of users and groups who have roles on
that branch.

Figure 29 Branch Users and Roles screen

Users and groups may be specifically assigned for that branch, as shown in the top
section of the screen, or they may be inherited from the parent branch, as shown in the
bottom part of the screen.

Recommendation: Rather than adding individual users to a branch, it is recommended


that you create groups of users. You can assign a group of users a role on a branch. If
additional users need to access the branch, they can be added to the group.

Options from this screen allow you to:


„ Edit. Change the role that user or group has in that branch.
„ Delete. Remove the user or group from accessing that branch.
„ From the Users and Groups screen, add a new user or group to the branch and
specify the role the user or group has in that branch.
„ Search Users and Roles. Enter a user name and search for all the roles that user has
in the branch.

TeamSite Administration Guide 105


Chapter 5: Defining Users and Roles

Editing Users and Their Roles


When you click the Edit link opposite a user in Branch Users and Roles screen, the Edit
Users and Roles screen displays. This allows you to change the role for that user or
group. The name fields is already filled in and cannot be changed.

After you set or change the role for that user, click Save to save the change and return to
the Branch Users and Roles screen.

Searching by Name
From the Branch Users and Roles screen, click Search Users and Groups. In the Search
Users and Groups screen, enter a user name and click Get Roles. If you enter a partial
user name, all user names containing that string are included in the results.

The results lists all users satisfying the search criteria and the roles they have in the
branch. Both the user id and the user name are searched.

Choosing Users or Groups


This screen lets you choose users or groups. It displays in different forms from multiple
places. You can use the * wildcard or leave the Name field blank; then click Find.
„ Users and Groups. This format lets you choose whether you want to find users or
groups. It displays from:
‰ The Branch view when you click Add Users as Role.
‰ The Manage Groups link; from the Group Members screen, click Add
Members.
„ Groups. This format lets you select a group. It displays:
‰ When creating a new workarea, select Groups for the Sharing field; click Find
opposite the Group field.
‰ When viewing file or folder properties, click Find opposite Group.
„ Users. This format lets you select a user. It displays:
‰ From the Manage Groups screen, select Add Managers.
‰ When creating a New Branch, click Find opposite the Owner field.
‰ When accessing Branch Properties, click Find opposite the Owner field.
‰ From the Manage Users screen, select Add User and click Find opposite the
Name field.
‰ When assigning a new job.
‰ When viewing file or folder properties, click Find opposite User.

Interwoven, Inc. 106


Chapter 6

Managing TeamSite Access

This chapter discusses various procedures for managing access to TeamSite, including
assigning user roles, user authentication, and filtering user submissions, as follows:
„ Access Considerations
„ Working with Permissions
„ Sharing TeamSite Assets using Windows Groups
„ Enabling the User/Group/Role Disk Cache
„ Operating System Group Membership
„ Authentication
„ Configuring Submit Filtering

Access Considerations
Access to TeamSite is governed by the following two factors:
„ Windows-related authentication permissions
„ TeamSite role-based access

Windows file permissions control who has access to individual files and directories.
Windows password authentication is used when logging in to TeamSite. However,
TeamSite access privileges govern the role a user has in various branches and
workareas. For example, to edit a file in a workarea, a user must both be able to access
that workarea (through TeamSite access privileges), and have permissions for that file
and its parent directory (through Windows permissions).

When adding a new user, you need to consider the following factors:
„ Whether the user will have access to the server.
„ The role the user will play in your TeamSite operations.
„ The content the user will be editing.

To decide what groups new users need to belong to and which workareas they need to
access, consider your existing groups and the content and workareas they can access.
Add new users to the groups that work on the same content that they need to edit, and
they will automatically have access to their workareas and to their content files. If the

TeamSite Administration Guide 107


Chapter 6: Managing TeamSite Access

new users need their own workarea, create a private or shared workarea, but make sure
that they own or have access to the files that they will be editing. To change ownership
or access to files, see page 122.

When creating a new workarea, you need to decide:


„ What the name of the workarea should be.
„ Who will need to access the workarea.
„ What content the workarea’s owner and group should and should not have access to.

Set permissions on your files according to the latter consideration. Remember that
permissions cannot be set differently for different workareas. If the permissions for
corresponding files are set differently in different workareas, you will encounter
conflicts when you submit files to the staging area.

NOTE
The TeamSite log-in screen accepts passwords of virtually any length. If you are using
multi-byte characters, the maximum length is 64 characters.

Working with Permissions


When users try to perform any action in TeamSite, the TeamSite server automatically
checks to see whether or not they have permission to perform that action. TeamSite
checks the following factors:
„ User roles. If you are attempting to perform any of these actions through
ContentCenter, you must be a user or member of a group associated with a role
authorized to perform the action on the branch.
„ Workarea permissions. A user has workarea permissions if he is either the primary
owner of a workarea or if he belongs to the group that has access to the workarea.
„ File permissions. File permissions are Windows Modify permissions (unless
otherwise specified) to a file.
„ Directory permissions. Directory permissions are Windows Change permissions
(unless otherwise specified) to a directory.
„ Permission overrides. Standard permissions are overridden for that role.

Not all of these factors apply to every action. TeamSite checks only the factors that
apply to the action being attempted. Generally, it checks as follows:
„ All the roles a user has on the branch are calculated. If any of these roles allow the
operation, permission is granted; otherwise the operation is not allowed for the user
on that object.

Interwoven, Inc. 108


Chapter 6: Managing TeamSite Access

„ For operations on files in workareas:


‰ The user must be the owner or a member of the owning group of the workarea.
‰ The user must have the appropriate Windows file directory permissions.
‰ The file must meet the appropriate locking constraints.
‰ The user must be the owner of the job or task (if applicable).

If the user has a role on the branch that has permission overrides set, these restrictions
may not apply.

Table 7 lists all of the operations that can be specified when roles are being created or
edited. It also shows the scope of each of the operations and the permissions that are
checked before a user can perform the function.

NOTE
TeamSite workflow tasks may require users to perform actions such as editing a file,
submitting it to the staging area, or taking ownership of a group task. To perform the
task, the user must have the ability to perform the action as specified in the table. For
example, if you assign a task that requires an Author to edit a file, the Author must have
workarea permissions, parent directory permissions, and file permissions for that file in
addition to the Edit operation in the role.

Table 7 Role operations and permission checking


Operation Object Affected Permissions Checked
Branch Administration
Create Branch branch
Delete Branch branch
Delete Edition edition
Modify Branch branch
Properties
Rename Branch branch
Rename Edition edition
ContentCenter Professional Operations
Show Reporting UI
Content Management
Compare workarea, staging • User/group has file read permission
area, edition, file, on source and destination areas.
folder, deleted file • Workarea is readable.
Publish Edition branch
Submit workarea, file, • User/group is member of workarea.
folder, deleted file
Update Workarea workarea, file, • User/group is member of workarea.
folder, deleted file

TeamSite Administration Guide 109


Chapter 6: Managing TeamSite Access

Table 7 Role operations and permission checking (Continued)


Operation Object Affected Permissions Checked
External Triggers
Create or Delete
External Triggers
Files, Forms, and Folders
Copy Files and file, folder • User/group has file read permission
Folders on source area.
• User/group is member of workarea.
• User/group has file write permission
on destination area.
Delete Files and file, folder • Has operating system permission to
Folders delete files.
• User/group is member of workarea.
• Satisfies branch and role locking
constraints.
• User is owner of task or job
requesting deletion.
Download file, folder • User/group has file read permission.
• Workarea is readable.
Edit file, folder • User/group has file write
permission.
• User/group is member of workarea.
• Satisfies branch and role locking
constraints.
• User is owner of task or job
requesting edit.
Generate Form file, folder • User/group has file write
permission.
• User/group is member of workarea.
• Satisfies branch and role locking
constraints.
• User is owner of task or job
requiring the form generation.
Lock File file, deleted file • File is not locked.
• User/group is member of workarea.
Mark Private file, folder • User/group is member of workarea.
Merge File file • User/group is member of workarea.
• User/group has file write
permission.

Interwoven, Inc. 110


Chapter 6: Managing TeamSite Access

Table 7 Role operations and permission checking (Continued)


Operation Object Affected Permissions Checked
Modify File and file, folder • User/group is member of workarea.
Folder Permissions • Has operating system permission to
change files.
• Satisfies branch and role locking
constraints.
• User is owner of task or job
requesting edit.
Modify File Extended file • User/group is member of workarea.
Attributes • User/group has file write
permission.
• Satisfies branch and role locking
constraints.
• User is owner of task or job
requesting modification.
Move Files and file, folder • User/group has file write
Folders permission.
• User/group is member of workarea.
• Has operating system permission to
rename files.
• Satisfies branch and role locking
constraints.
• User is owner of task or job
requiring the rename.
Preview File file, folder, branch, • User/group has file read permission.
edition, workarea, • Workarea is readable.
staging area
Preview Form file, folder, workarea • User/group has file read permission.
• Workarea is readable.
Rename Files and file, folder • User/group has file write
Folders permission.
• User/group is member of workarea.
• Has operating system permission to
rename files.
• Satisfies branch and role locking
constraints.
• User is owner of task or job
requiring the rename.
Revert File file, deleted file • User/group is member of workarea.
Search content store, • User/group has file read permission.
branch, workarea, • Workarea is readable.
staging area, edition,
file, folder, deleted
file

TeamSite Administration Guide 111


Chapter 6: Managing TeamSite Access

Table 7 Role operations and permission checking (Continued)


Operation Object Affected Permissions Checked
Undo Changes file, workarea • User/group has file write
permission.
• User/group is member of workarea.
• Satisfies branch and role locking
constraints.
• User is owner of task or job
requesting change.
Unlock File file, deleted file • File is locked.
• User/group is workarea owner or
locked the file.
Unmark Private file, folder • User/group is member of workarea.
View File History file, deleted file • User/group has file read permission.
• Workarea is readable.
New and Imported Content
Create File folder • User/group has file write
permission.
• User/group is member of workarea.
• Satisfies branch and role locking
constraints.
• User is owner of task or job
requesting file creation.
Create Folder folder • User/group has file write
permission.
• User/group is member of workarea.
• Satisfies branch and role locking
constraints.
• User is owner of task or job
requesting file creation.
Create Form file, folder • User/group is member of workarea.
• User is owner of task or job
requesting form creation.
Import file, folder • User/group has file write
permission.
• User/group is member of workarea.
• Satisfies branch and role locking
constraints.
• User is owner of task or job
requesting file import.
Store Administration
Freeze Store content store
Modify Store content store
Properties

Interwoven, Inc. 112


Chapter 6: Managing TeamSite Access

Table 7 Role operations and permission checking (Continued)


Operation Object Affected Permissions Checked
Thaw Store content store
User Administration
Create TS Group
Create TS User
Delete TS User
Workarea Administration
Create Workarea branch
Delete Workarea workarea
Modify Workarea workarea User/role is member of workarea.
Properties
Rename Workarea workarea
Workflow
Add Task Comment task User is owner of task or job.
Assign file, folder, deleted
file
Attach to Task task User is owner of task or job.
Change Task Owner task User is owner of task or job.
Configure Workflow workflow
Models
Detach From Task task User is owner of task or job.
End Job job User/group is owner of job.
Manage Workflow workflow
Models
Modify Job job User/group is owner of job.
Properties
Modify Task task User is owner of job.
Properties

Publish Workflow workflow


Models
New Job
Read Job Properties job
Read Task Properties task
Retry Task task User is owner of task or job.
Return Group Task task User is owner of task or job.
Take Back Task task User is owner of task or job.
Take Group Task task
View All Jobs
View All Tasks

TeamSite Administration Guide 113


Chapter 6: Managing TeamSite Access

Table 7 Role operations and permission checking (Continued)


Operation Object Affected Permissions Checked
View Job Details job
View My Jobs
View My Tasks
Webview Workflow workflow
Models

Workarea Access
By default, the workarea root file system permissions restrict any subdirectory access.
For example, the permissions on a subdirectory or a file specify that a user can modify
the subdirectory or file. However, permissions on the root directory do not grant write
permissions to the user. Therefore, TeamSite does not allow the user to modify the file
or subdirectory. To disable this check, set this option to no.
[iwserver]
mask_workarea_access=no

When set to no, permissions on the workarea root directory affect only this directory
rather than the entire tree.

Branch and Workarea Security


Branch and workarea security determines whether or not users can see (in
ContentCenter) the names of branches and workareas they do not have access to. By
default, the branch_security and workarea_security lines in the [iwserver] section
of iw.cfg are set to off. This means that all branch and workarea names are displayed
to users even if they do not have permission to access them (they see the name of the
branch or workarea, but they cannot click on it and [N/A] displays next to it).

You can configure TeamSite to not display the names of branches and workareas in the
ContentCenter if the user does not have read permissions by editing the
branch_security and workarea_security lines in the section of iw.cfg as follows:
[iwserver]
branch_security=on
workarea_security=on

Interwoven, Inc. 114


Chapter 6: Managing TeamSite Access

Default Permissions
You can control branch permissions on Windows by adding the branch_default_perm
parameter to the [iwserver] section of the iw.cfg file as follows:
[iwserver]
branch_default_perm=0

The default behavior creates all branches with read access for the group Everyone. If
you add branch_default_perm=0 as shown, the group Everyone is not added to the
ACL for new branches created after this configuration setting is added.

Viewing File Permissions


When you click the Permissions link on a File Properties screen, the Permissions screen
displays. It shows the permissions set for the file and the inherited permissions.

From this screen, you can perform the following operations:


„ Add Permissions. Click Add Permissions to display the Users and Groups dialog
box with the Permission field. Select the type of permission you are granting (Read
only, Full Control, Modify). Then search for and select users and groups. Click Add
or Add and Close when you finish.

NOTE
Permissions can only be changed in ContentCenter or with the iwaccess CLT and not
through a browser window. Use add-windows-permission option of the iwaccess CLT
to set permissions recursively for a folder and the files or folders below that folder.

„ Edit. Click Edit opposite a user to display the Edit Permissions screen. The Name
and User display. Select a Permission option and save the change.
„ Delete. Click Delete to remove the user from the permissions. You are prompted to
verify the deletion.
„ Remove Inherited Permissions. When you click Remove Inherited Permissions,
you are asked if you want to make a local copy of the inherited permissions.

TeamSite Administration Guide 115


Chapter 6: Managing TeamSite Access

Sharing TeamSite Assets using Windows Groups


Windows groups can be used to group users and to share TeamSite assets such as
branches and workareas. They may also be used, in conjunction with Windows Access
Control Lists (ACLs) to provide finer-grained access control for individual directories
and files. Over time, Windows has evolved, and the use of Windows groups has evolved
with it. Best practice for using groups with TeamSite depends on the Windows
Operating System version, and on the size and complexity of the network in which it
works. There are three basic scenarios:
„ A Windows 2000 environment using NTLM or Mixed Mode Active Directory.
„ A small-scale Windows 2000/2003 network using Native Mode Active Directory.
„ A large-scale Windows 2000/2003 network using Native Mode Active Directory.

NOTE
TeamSite groups are an alternative to Windows groups. The advantage of TeamSite
groups is that they are managed entirely within TeamSite whereas Windows groups
require management through the Windows operating system. The advantage of
Windows groups is that they interoperate with Windows and AD.

The following sections explain how Windows groups are typically used in each of these
environments, and describe in what circumstances the new Active Directory System
Interface (ADSI) and disk-caching code can be used to improve performance.

Group Usage with NTLM or Mixed Mode Active Directory


This is the classic Windows environment. With the increasing acceptance of Microsoft
Active Directory, it is no longer common for new Windows installations, but it is still
used in many existing networks.

Microsoft provides two kinds of groups in an NTLM or Mixed Mode Active Directory
environment: local groups and global groups. In a typical TeamSite installation in this
environment, global groups are used to group users, and local groups are used to share
TeamSite resources. The global groups contain lists of users, and these global groups are
in turn members of the local groups used for sharing.

No special steps are required to configure TeamSite for this environment. The
parameters use_adsi and domain_local_groups found in the [iwserver] section of
iw.cfg are not used. They should either be commented out or set to false.

Local groups are defined on the machine on which TeamSite runs, so they have some
disadvantages. If the TeamSite server is to be moved to a new machine, even if the new
machine is a member of the same domain, the local groups need to be re-created on the
new machine. For this reason, where practical, Interwoven recommends the use of
domain local groups and domain users rather than local users and groups. However,

Interwoven, Inc. 116


Chapter 6: Managing TeamSite Access

machine local groups and users are sometimes the best choice for TeamSite servers that
are used for demonstration or test purposes.

When TeamSite is used in a Mixed Mode Active Directory environment, it is necessary


to give the TeamSite server permission to read group information from any Active
Directory domains specified in the domain_list parameter in the iwserver section of
iw.cfg. If your network is not already configured to allow this, the necessary
permissions can be added using the Windows Active Directory Users and Computers
tool. The following procedure is performed for each domain that contains TeamSite
users and groups:
1. Start the Active Directory Users And Computers tool. This tool is found in the
Windows Start menu under Programs > Administrative Tools on the computer that
is used to administer the Active Directory domain.
2. Right click on the domain name that the TeamSite users belong to and select Dele-
gate Control. This starts the Delegation Wizard.
3. Add the name of the computer that the TeamSite server is running on when it asks
you to add users and groups.
4. Check the Create a custom task field when it asks which tasks to delegate.
5. Select User Objects from the list when it asks you to select an object type.
6. Select Property Specific when it asks what permissions to show.
7. Check ReadGroupMembershipSAM and ReadGroupMembership. Newer systems
(Windows 2003) may not include the ReadGroupMembership option; in this case,
only check ReadGroupmembershipSAM.

Group Usage with Native Mode Active Directory


When a Mixed Mode Active Directory installation is converted to Native Mode
operation, the local groups on the Primary Domain Controller become domain local
groups. This type of group is not available in an NTLM or Mixed Mode AD
environment.

The advantage of domain local groups is that they are known to all machines in the
domain in which they are defined. If domain local groups are used to share TeamSite
resources, the TeamSite server may run on any machine in the domain, and moving the
TeamSite server software to a different machine in the domain does not require any
changes to the group structure. In a Mixed Mode environment, where the groups for
sharing are tied to a particular machine rather than to the domain, it is more difficult to
swap out failed hardware or to move the TeamSite server to a different machine.

In this environment, use domain local groups for sharing rather than traditional local
groups. To enable the use of domain local groups as groups for sharing, use the
following setting in iw.cfg:
[iwserver]
domain_local_groups=yes

TeamSite Administration Guide 117


Chapter 6: Managing TeamSite Access

TeamSite may be configured to use traditional Windows APIs to collect group


information, or it may be configured to use the Active Directory System Interface
(ADSI) supported by Windows 2000 and later systems. Use of the newer ADSI code
may improve performance if users and groups come from multiple domains and there
are larger numbers of users and groups. The groups for sharing must be domain local
groups rather than (machine) local groups. To select the ADSI code, specify the
following two lines in the iw.cfg file:
[iwserver]
use_adsi=yes
domain_local_groups=yes

For larger installations, TeamSite may be configured to use cached user and group
information to significantly reduce the server's startup time. This feature may be used
with or without enabling the ADSI code. See “Enabling the User/Group/Role Disk
Cache” on page 120.

Group Usage for Larger AD Networks


TeamSite is often installed on a machine that is part of a large, complex Windows
network. Such a network may contain many different domains, and each domain may
contain resources that must be shared across domains. In this scenario, recommended
practice is to use universal groups rather than global groups to group users. Universal
groups are known across all domains, and they may contain users from any domain.
(Global groups, by contrast, may only contain users from their own domain). Like
domain local groups, universal groups are only available in domains that have been
promoted to run Native Mode Active Directory.

In this environment, where users are grouped in universal groups, and resources are
shared using domain local groups, the new ADSI code must be enabled in iw.cfg:
[iwserver]
use_adsi=yes
domain_local_groups=yes

When TeamSite users are in tsusers.xml, the TeamSite server may take several
minutes to start up as it collects user and group information. This startup time can be
significantly reduced when the server is configured to use cached user and group
information at startup time (this is on by default). See “Enabling the User/Group/Role
Disk Cache” and information later in this section.

In networks that are spread over large geographic areas and where TeamSite users are
spread among different domains, network response times may encounter unusual delays
when the TeamSite service is first started. The TeamSite service is usually configured to
start automatically after a Windows reboot. At startup, TeamSite reads a variety of user
and group information from the Active Directory. This process may take several
minutes. In extreme cases, the time required to start the server may result in a system
timeout, which occurs when the server requires more than 10 minutes to start. These are
possible solutions for this problem:

Interwoven, Inc. 118


Chapter 6: Managing TeamSite Access

„ Increase the timeout period from the default value of 600, which denotes 600
seconds (10 minutes), to a larger value. The timeout period may be set to a different
value by changing a parameter in the Windows Registry. The key to be changed is
found in the Registry at HKEY_LOCAL_MACHINE\SYSTEM\
CurrentControlSet\Services\iwserver\Parameters\Start Timeout. Its value is
the number of seconds that Windows should wait for the server to start.
„ If the server startup time is unacceptably long, consider limiting the number of
inquiries that TeamSite must make to remote AD controllers. This is done by
limiting the number of domains that TeamSite is required to search using the
domain_list parameter in the iwserver section of iw.cfg. If it is not practical to
limit the number of domains, the need to query remote AD controllers for group
membership information can be reduced or eliminated completely by careful choice
of Windows group type for various uses. These possible changes may improve
performance:
‰ Use universal groups exclusively to group users. This is recommended practice
from Microsoft (although other group types may be used). To instruct TeamSite
to restrict its user search to universal groups, set the following parameter in
iw.cfg:
[iwserver]
windows_groups_for_users=UNIVERSAL
‰ If the groups used to share TeamSite resources are domain local groups only,
limit the TeamSite search for nested groups to groups nested in domain local
groups. This is done with the following iw.cfg setting:
[iwserver]
windows_groups_for_sharing=LOCAL
‰ Use universal groups exclusively to share TeamSite resources. Recommended
practice is usually to share resources using domain local groups, but in larger
systems, significant performance gains may be made if universal groups are
used instead. If universal groups only are used to share TeamSite resources, then
the TeamSite server can use the Active Directory Global Catalog for all its
inquiries about groups for sharing. To configure the server to restrict its groups
for sharing to universal groups, include the following settings in the iw.cfg file:
[iwserver]
windows_groups_for_sharing=UNIVERSAL

Managing Windows Groups for Best Performance


System response times are dependent on several factors:
„ The number of groups in the system.
„ The extent of group nesting.
„ The size of groups.
„ The number of TeamSite users.
„ The number of domains to be searched for users and groups.
„ The performance of the corporate network.

TeamSite Administration Guide 119


Chapter 6: Managing TeamSite Access

While some of these factors may be outside your control, response times can usually be
improved by trying some of the following:
„ Where practical, limit the number and size of groups used for sharing TeamSite
assets. Create dedicated groups, composed solely of TeamSite users, instead of
using large existing groups. This is especially helpful if the existing operating
system groups contain many members that are not TeamSite users.
„ Limit the number of domains that contain TeamSite users and Windows groups used
for sharing. The domain_list parameter in the [iwserver] section of iw.cfg
should be set to include only domains that contain TeamSite users and groups; see
“Domains to Use for Group Authentication” on page 131. A short list of domains can
be searched faster than a long one.
„ If possible, use universal groups exclusively to group TeamSite users. Set
windows_groups_for_users=UNIVERSAL in iw.cfg. This is recommended for most
TeamSite installations.
„ Consider using universal groups instead of domain local or global groups to share
TeamSite resources. Set windows_groups_for_sharing=UNIVERSAL in iw.cfg. This
restriction is not necessary for most TeamSite installations.
„ Where TeamSite users are in tsusers.xml and there are a lot of users, groups or
domains, leave the user/group/role disk cache enabled (the default setting). This is a
good practice for most large TeamSite installations.
„ In installations that do not include nested groups in the groups used for sharing
TeamSite assets, disable the nested group handling functions (see “Disabling Group
Nesting” on page 121). This option is not frequently used, but is sometimes chosen
to improve response times where there are very large numbers of TeamSite users.

Enabling the User/Group/Role Disk Cache


When the user/group/role disk caching code is enabled, TeamSite saves a copy of the
in-memory user, group, and role cache to disk every time the in-memory cache is
refreshed. This disk image of the cache is used the next time the TeamSite server is
started to improve the server startup performance. Server startup time is faster.In the
case of Windows, particularly where TeamSite must search multiple domains and
process large amounts of user and group information, this feature also improves the
usability of the server during its first few minutes of operation. This improved usability
is due to the fact that the server does not have to wait until all of the access information
is collected from Windows before it allows access to particular TeamSite resources.

The disk cache is enabled by default. To disable this feature in iw.cfg, set:
[iwserver]
enable_user_group_disk_cache=false

Interwoven, Inc. 120


Chapter 6: Managing TeamSite Access

Disabling Group Nesting


In some TeamSite installations, the Windows groups used for sharing TeamSite assets
do not contain any nested groups. In this case, server operation can be sped up by
disabling the code within TeamSite that handles nested groups.

Group nesting is enabled by default. To disable TeamSite's handling of nested groups in


iw.cfg, set:
[iwserver]
include_nested_groups=false

Enabling the ADSI Debug Flag


To examine the TeamSite group information in detail, use the debugging flag to examine
the cache of nested groups that TeamSite builds on startup. Enabling this flag causes
TeamSite to write the contents of the ADSI group cache to the iwtrace log.

This flag is disabled by default. To enable the group debugging flag in iw.cfg, set:
[iwserver]
debug_adsi=true

Additional Tools for Debugging


Several software tools can be used to examine the group memberships of TeamSite
users.
„ The iwdebug command-line tool can be used to display the contents of the TeamSite
internal cache at any time the server is running. The output from iwdebug
commands is written to the iwtrace log. The -g option lists group information, and
the -u option lists each user in the cache and the groups of which that user is a
member. The two options can be used together, if desired: iwdebug -g -u.
„ The iwldapsearch command-line tool can be used to search an Active Directory or
an LDAP directory for user or group information. It uses syntax similar to the ldap
search utilities that accompany most LDAP server installations. However, unlike the
generic LDAP search tools, it knows about any LDAP configuration information
found in iw.cfg. For example, if TeamSite roles are kept in an LDAP attribute
called description, the following command can be used to retrieve the names of all
the TeamSite Authors in the system: iwldapsearch "description=author" dn.
The iwldapsearch utility may be used even if there is no LDAP or Active Directory
configuration information in iw.cfg. In this case, the server (host) name and search
base need to be specified. The following command lists all of the Windows groups
on an Active Directory server called qa.qadomain.com:
ldapsearch -h qa.qadomain.com -b "cn=users,dc=qadomain,dc=com"
"objectclass=group" name

TeamSite Administration Guide 121


Chapter 6: Managing TeamSite Access

Operating System Group Membership


TeamSite supports two types of groups for user management: those managed through
standard Windows functions (referred to as operating system groups) and those
managed through TeamSite (referred to as TeamSite groups). Workareas can be shared
by either type of group. For users to have access to a particular workarea, they must
either be the owner of the workarea or a member of the workarea’s group. TeamSite uses
Windows groups for access control; it also uses TeamSite groups as described on
“Working with TeamSite Groups” on page 94.

To add a user to a Windows group:


1. Select Start > Programs > Administrative Tools > Computer Management. The
Computer Manager displays.
2. In the Computer Manager, select Local Users and Groups > Groups.
3. Double-click the group that has access to the workarea to which you want to add the
user.
The Properties window for the selected group displays.
4. Click Add.
5. Select the user you want to add from the list or type the user name, then click OK.
If the user is an Administrator and you want that user to have Administrator
privileges for a branch, add the user to the group of Administrators for that branch.
You can add any number of users to a group.

Changing Group Ownership of Workareas


To change which group has access to a workarea:
1. From the Command Prompt, navigate into the directory containing the workarea.
2. Use the iwchgrp.exe command (see TeamSite Command-Line Tools) to change the
workarea’s group. You can change either the OS group or the TeamSite group. The
chgrp command can only be used to change the OS group.

TeamSite only checks the primary group owner of a workarea and does not rely on
ACLs to determine workarea ownership.

You can also change ownership of workareas through ContentCenter Professional in the
Workarea Properties screen.

Interwoven, Inc. 122


Chapter 6: Managing TeamSite Access

Web Server Group


The web server group setting should be set to any group that allows the web server to
see the web content as an outside viewer would see it, in order for users to be able to
preview the Web site like any external user would. To change the web server group
setting, edit the webserver_group line in the [iwserver] section of iw.cfg. If iw.cfg
does not contain this line, add it as shown:
[iwserver]
webserver_group=IWGROUP

This sets a group of users, all of whom have full file system access. If this line does not
exist, the group Everyone is used.

Authentication
Authentication involves determining whether users can access TeamSite resources. The
tsusers.xml file maintains information on TeamSite users. Operating system users are
usually identified as TeamSite users and added to this file through the Manage Users
option in the ContentCenter Professional Administration tab that is available to Master
users (refer to “Managing TeamSite Users” on page 88).

OS and non-OS users can be identified in LDAP or an external source.

The LDAP files can be set up in one of two ways:


„ Users in the LDAP file display in the Administration tab and can be added through
the Manage Users screen or with the iwuseradm CLT (refer to “Managing TeamSite
Users” on page 88).
„ Users in the LDAP file are added as TeamSite users through a synchronization
process that reads the LDAP files; they cannot be added through the
Administration tab or using the CLT (refer to “Synchronizing LDAP Users” on
page 127).

Storing TeamSite Users


Potential TeamSite users must be identified in a database or must have operating system
access. This database may be an LDAP file or an external database. These databases are
identified in the user_databases.xml file. An LDAP database can contain either OS
users or non-OS users; they cannot be mixed.

TeamSite Administration Guide 123


Chapter 6: Managing TeamSite Access

The user_databases.xml File


TeamSite reads information on user databases from the user_databases.xml file. You
must edit this file manually. The file is stored in iw-home\conf\roles directory; an
empty file ships with TeamSite. Databases identified in the file are used to authenticate
TeamSite users. Only configurations for LDAP databases and external databases are
supported. Define as many LDAP or external databases as are required for your site.

NOTE
LDAP files that contain users that are to be added through synchronization include the
attr_sync attribute described in “Synchronizing LDAP Users” on page 127.

The following code is an example of the user_databases.xml file that defines two
LDAP databases and two external databases. Databases set up using these formats are
used to add TeamSite users through the iwuseradm CLT or the Administration tab.
<iwuser_databases>
<iwldap id="ldap_1" display_name="my ldap_1" os="t">
<server value="ishuffle-sol.amer.interwoven.com" />
<port value="389" />
<search_key value="uid" />
<ssl_port value="0" />
<CAFile value="" />
<dnBase value="marketing.interwoven.com" />
<account value="admin" />
<password value="52616e646f6d4956c82bafa0f007
0585907d439c34792e66c55ade1fd1e21fc4" />
<attr_email value="mail" />
<attr_display_name value="cn" />
</iwldap>

<iwldap id="ldap_2" display_name="my ldap_2" os="f">


<server value="ishuffle-sol.amer.interwoven.com" />
<port value="389" />
<search_key value="uid" />
<ssl_port value="0" />
<CAFile value="" />
<dnBase value="sales.interwoven.com" />
<account value="admin" />
<password value="52616e646f6d4956c82bafa0f007
0585907d439c34792e66c55ade1fd1e21fc4" />
</iwldap>

<external-source id="ext_src_1" display_name="my ext_src_1">


<authentication_source value="http://localhost/iw/my_prog1"/>
<param_username value="username"/>
<param_password value="password"/>
<timeout value="500"/>
</external-source>

Interwoven, Inc. 124


Chapter 6: Managing TeamSite Access

<external-source id="ext_src_2" display_name="my ext_src_2">


<authentication_source
value="https://host:443/iw-bin/sample_extsrc.cgi"/>
<CAFile value="c:\iw-home\iw-webd\conf\client\cacert.pem"/>
<timeout value="500"/>
</external-source>
</iwuser_databases>

Table 8 describes each of the attributes in the user_databases.xml file.

Table 8 Attributes for user_databases.xml file


Attribute or Element Description
id Unique id that identifies a particular LDAP server or
external source.
display_name Identifies the LDAP server or external source in the
ContentCenter Professional Administration tab. If it
is not defined, the id attribute is used.
os Boolean value that indicates whether the users from
this LDAP server are OS users (t) or non-OS users (f).
The default value is f. Each LDAP configuration can
contain either OS users or non-OS users, but not both.
server Name or IP address of the LDAP server.
port Port for the LDAP server (default is 389).
search_key Name of the LDAP attribute that holds the user
account names (default is uid).
ssl_port Port that the LDAP server uses to communicate when
SSL is in use. This is assumed to be port 636.
CAFile Location of your CA certificate database file. This file
is expected to be in Netscape “cert7” format. A default
“cert7.db file” that contains the certifications for a
variety of Certification Authorities is found in the
TeamSite installation in the directory
iw-home\tools\db\netscape\cert7.db.
dnBase Specification of the DN base location according to
LDAP search syntax.
account Specifies the Distinguished Name of the Active
Directory user account to be used for Active Directory
searches. This is not a simple account name, but a
complete Distinguished Name (DN) for a user.
password Encrypted version of the password (refer to “The
Password Attribute” on page 126).
attr_email Used to query the LDAP server for email addresses.
The default is mail. If the value is specified with an
empty string, LDAP will not be queried for this
attribute.

TeamSite Administration Guide 125


Chapter 6: Managing TeamSite Access

Table 8 Attributes for user_databases.xml file (Continued)


Attribute or Element Description
attr_display_name Used to query the LDAP server for user display names
or common names. The default is cn. If the value is
specified with an empty string, LDAP will not be
queried for this attribute.
authentication_url A URL that TeamSite uses to authenticate a user from
the external source. Username and password are
included as URL parameters and the command is
posted to the external source server. Both HTTP and
HTTPS protocols are supported. If HTTPS protocol is
used, the filepath for the Certificate Authority file
must be specified using the CAFile attribute.
param_username Used with param_password to construct the URL for
authentication. The default is username.
param_password Used with param_username to construct the URL for
authentication. The default is password.
timeout_value Specifies how long (in ms) to wait for the HTTP
response; default is 500 ms.

The Password Attribute

The password value stored in user_databases.xml is an encrypted version of the


password. Blowfish encryption software is used to encrypt/decrypt the password.

Since the user_databases.xml file has to be maintained manually, you need to


manually encrypt the password and save the encrypted password in
user_databases.xml.

To encrypt a LDAP login password:


1. Define IWCLT_PASSWORD environment variable as the actual password.
2. Run the following CLT to generate the encrypted password:
iwuseradm encrypt-userdatabase-pwd
The CLT outputs a 64-bit password like the one shown below:
52616e646f6d4956c82bafa0f0070585907d439c34792e66c55ade1fd1e21fc4
3. Copy the 64-bit encrypted password to the corresponding LDAP server configura-
tion in user_databases.xml file.

To verify whether an encryption is correct:


1. Define IWCLT_PASSWORD environment variable as the actual password.
2. Run the following CLT to verify an encryption:
iwuseradm encrypt-userdatabase-pwd -v
52616e646f6d4956c82bafa0f0070585907d439c34792e66c55ade1fd1e21fc4

The CLT outputs YES if the encrypted password matches the original password.

Interwoven, Inc. 126


Chapter 6: Managing TeamSite Access

When you use the ContentCenter Professional Administration tab to manage users, you
can search for users in these databases (“Managing TeamSite Users” on page 88).

Synchronizing LDAP Users


The LDAP synchronization process (iwldapsync) reads the LDAP databases to
synchronize the users contained in the databases with TeamSite users. It adds new users,
deletes obsolete users, and updates user attributes, such as email addresses, based on
changes made to the LDAP databases.

Identifying LDAP Synchronization Files

The description of a LDAP file in user_databases.xml must contain the attr_sync


attribute to allow users in that LDAP file to be automatically created as TeamSite users.
The synchronization process updates attributes of LDAP users in TeamSite or removes
TeamSite users that are no longer in LDAP.

When attr_sync is defined, TeamSite users from the LDAP file can only be created by
the synchronization process; TeamSite users from this LDAP file cannot be added or
deleted through the Administration tab or using the iwuseradm CLT.

The following section of code is used in user_databases.xml to describe an LDAP file


from which the users will be synchronized. The attr_sync name is the name of the
LDAP attribute that identifies TeamSite users (in this example it is named
description). The attr_sync value contains possible values in that field that provide
TeamSite user information.
<iwldap id="ldap_1" display_name="my ldap_1" os="f">
<server value="ishuffle-sol.amer.interwoven.com" />
<port value="389" />
<search_key value="uid" />
<ssl_port value="0" />
<CAFile value="" />
<dnBase value="marketing.interwoven.com" />
<account value="admin" />
<password value="52616e646f6d4956c82bafa0f0070585907
d439c34792e66c55ade1fd1e21fc4" />
<attr_email value="mail" />
<attr_display_name value="cn" />
<attr_sync name="description"
value="master,tsuser,ccpro,ccstd,ccpro_only,ccstd_only" />
</iwldap>

NOTE
If attr_sync attribute is not defined, LDAP users are added to TeamSite through the
ContentCenter Professional Administration tab or the iwuseradm CLT.

TeamSite Administration Guide 127


Chapter 6: Managing TeamSite Access

Modifying LDAP Schemas to Store TeamSite User Interface Information

If you do not have an existing attribute in your LDAP schema where you can store
TeamSite user interface information, add a new attribute to your LDAP schema as
described in this section. If you already have an attribute where you can store TeamSite
interface information, start the procedure with step 3.
1. Add an auxiliary class to an existing object in the schema.
2. Add a new attribute to that object that will contain the TeamSite information. This
attribute is the name specified for attr_sync.
3. Your LDAP administrator can now assign TeamSite interface information to users
configured in your LDAP server using the server’s administration tools. The infor-
mation for this attribute indicates whether the user is a TeamSite user or a TeamSite
Master user and the ContentCenter interface the user can access.
The following are the valid values (they are case-sensitive):
‰ master. This user is a TeamSite Master user.
‰ tsuser. This user is a TeamSite user. In releases prior to TeamSite 6.7, the
values of admin, editor, and author could be specified for this attribute. Those
values are now converted to tsuser.
‰ ccpro. ContentCenter Professional displays when the user logs in. A link at the
top of the screen allows them to move between ContentCenter Professional and
ContentCenter Standard. When logging in later, the user returns to the interface
they were using when they logged out.
‰ ccpro-only. ContentCenter Professional displays. The user cannot switch to
ContentCenter Standard.
‰ ccstd. ContentCenter Standard displays when the user logs in. A link at the top
of the screen allows them to move between ContentCenter Standard and
ContentCenter Professional. When logging in later, the user returns to the
interface they were using when they logged out.
‰ ccstd-only.ContentCenter Standard displays. The user cannot switch to
ContentCenter Professional.

Configuring TeamSite and Active Directory to Work Without an Anonymous


Bind
In some installations, anonymous binds to Active Directory are not permitted for
security reasons. If you cannot use an anonymous bind to Active Directory to read user
names, you can establish a dedicated Active Directory user account to use for user
authentication. All searches for users’ Distinguished Names are done using this account
instead of an anonymous bind.

Interwoven, Inc. 128


Chapter 6: Managing TeamSite Access

DistinguishedName specifies the Distinguished Name of the Active Directory user


account to be used for Active Directory searches. This is not a simple account name, but
a complete Distinguished Name (DN) for a user. For example:
account=cn=TeamSite,cn=Users,dc=myCompany,dc=com.

The password specifies the encrypted password of the Active Directory user account
that matches account.

This information is included in the user_databases.xml file using the account and
password attributes.

LDAP Synchronization
Synchronization is done with the iwldapsync CLT (refer to the TeamSite
Command-Line Tools for options on this CLT). This CLT is normally launched when
TeamSite starts up and is run periodically as defined by ldapcache_thread_delay in
the iw.cfg file. The default is every 24 hours. The CLT can also be run manually.

You can enable logging of the LDAP synchronization process using the log_ldap_sync
option in the iw.cfg file; logging is on by default. The ldap_sync_retry_count is used
to specify the number of retries to connect to the TeamSite server when the LDAP
synchronization process runs. By default, the retry count is 12, which means that
TeamSite waits about 60 seconds to start responding to client requests.

Set these options in the [authentication] section as:


[authentication]
ldapcache_thread_delay=1440
log_ldap_sync=yes
ldap_sync_retry=12

TeamSite automatically synchronizes TeamSite users up to the search limit set by the
LDAP server for each LDAP configuration. If the LDAP server is configured to limit
the number of records returned by a search query to a number that is less than the
number of TeamSite users in the LDAP database, no LDAP users will be found during
the synchronization. Try the following options to address the issue when using LDAP
synchronization:
„ Divide the users under different LDAP subtrees (under different base DNs) and
define multiple LDAP databases in TeamSite such that the number of TeamSite
users under each LDAP database configuration is no more than the LDAP search
limit.
„ Increase you LDAP search limit to the number of TeamSite users configured in
LDAP.

The other option is to add LDAP users to TeamSite using either the Administration tab
or the iwuseradm CLT instead of using the LDAP synchronization procedure.

TeamSite Administration Guide 129


Chapter 6: Managing TeamSite Access

Impact of Using Non-OS Users in TeamSite


Enabling non-OS users in TeamSite impacts the way TeamSite operates in some areas.
You should be aware of the following:
„ The file system interface is not available for contents that belong to non-OS users.
An OS user, with the exception of the TeamSite global OS user (iwguser), will not
be able to view TeamSite content properties that belong to a non-OS user through
the file system interface.
„ File permissions cannot be set for multiple non-OS users or non-OS groups on a
single asset because non-OS users or groups are mapped to a single OS user or
group.
„ Non-OS user functionality is only available from sciface, CSSDK, and the
ContentCenter interfaces. There is no file system support for Non-OS users. From
the file system, all non-OS users appear as iwguser.
„ Non-OS users can only be added to non-OS groups.
„ While LaunchPad works for non-OS users, the Direct Edit feature that uses the file
system interface will not be available on content belonging to non-OS users.
„ Non-OS users cannot use the Perl compiler to compile presentation templates. The
XSLT PT compiler must be used.
„ Non-OS users cannot be the owners of external tasks since OS impersonation is not
possible; use an URL external task. If a non-OS user attempts to execute an external
task, the task is not launched and an error displays in the iwjoberrors.log file.
„ TeamSite does not manage LDAP user passwords (such as expiration information).
You need to manage LDAP user passwords.

Every LDAP directory has a schema that describes the objects and attributes that are
found in the directory. For example, you could have an object called user and an
attribute postaladdress. To configure TeamSite to perform user authentication, you can
either modify an existing attribute to represent TeamSite users or create a new one; this
procedure is described in “Modifying LDAP Schemas to Store TeamSite User Interface
Information” on page 128.

Interwoven, Inc. 130


Chapter 6: Managing TeamSite Access

Domains to Use for Group Authentication


To configure which domains are used for group authentication, configure the
domain_list line in the [iwserver] section of iw.cfg. This setting can be used to
reduce the startup time for TeamSite, by limiting the number of domains it tries to
authenticate against.

By default, TeamSite authenticates against all domains. To limit the number of domains
used for group authentication, add the following line to the [iwserver] section of
iw.cfg:
[iwserver]
domain_list=domain1,domain2,domain3

You can include any number of domains in this list.

You can explicitly specify the domain controller that should be used for a particular
domain. This option should not be used if the use_adsi parameter is enabled.
[iwserver]
domain_list=domain1, domain2:domain_controllerA, domain3

In this example, the primary domain controller would be used for first and third
domains, while domain_controllerA would be used for the second domain.

NOTE
Do not confuse this line with the domain_list line in the [iwcgi] section.

Logging Users and Groups


TeamSite can be configured to record in its log files every authenticated user and all
groups with which each user is associated. To activate this feature, add the following
line to the [iwserver] section of iw.cfg:
[iwserver]
show_user_list=true

Once this feature is activated, each time TeamSite is restarted, it logs all users in the
roles files and their associated groups in iw-home\local\logs\iwtrace.log. Log files
use the following format:

user: username [associated groups]

NOTE
If this feature is left on for too long, your log files will grow extremely large.

TeamSite Administration Guide 131


Chapter 6: Managing TeamSite Access

Configuring Submit Filtering


The TeamSite server enables you to automatically change file attributes, including
owner, group, and ACLs, at the time that you submit a file. This functionality enables
you to automate the task of defining the permissions associated with each file stored in
TeamSite. The submit filter performs the specified operation on files immediately
before they are submitted, so that changes are made to the files in the workarea, which
are then submitted.

The submit.cfg File


On startup, the TeamSite server reads a configuration file named submit.cfg in the
iw-home\local\config\ directory (unless the location of this file is otherwise specified
in the [locations] section of iw.cfg). The submit.cfg file contains rules to match file
and workarea patterns to specific actions to perform when files and directories are
submitted.

NOTE
This file is not present by default; you need to create the file in the location specified.

The submit.cfg file uses the following format:


case-sensitive = [yes|no]
rules
{
workarea1_pattern
{
file_pattern1 { action1 action2 ... }
file_pattern2 { action3 action4 ...
...
}
workarea2_pattern
{
file_pattern3 { action5 action6 ... }
file_pattern4 { action7 action8 ... }
...
}
...
}

where:
„ The case-sensitive statement specifies whether or not the rules matching should
ignore the case of the path names. If case-sensitive is not specified, the value is
assumed to be no.
„ workarea#_pattern is used to match a workarea to the set of file rules to apply
when a submit is done from that workarea. Each pattern can only be specified once,
and the first match is used. The syntax of the pattern is regex(5) (extended syntax).

Interwoven, Inc. 132


Chapter 6: Managing TeamSite Access

For more information on regular expressions, consult a reference manual such as


Mastering Regular Expressions, by Jeffrey Friedl.
The match is done against the path name of the workarea, starting with
\default\main.

„ file_pattern# is used to match a file or directory to the set of actions to perform


on it when it is submitted. Each file or directory pattern can only be specified once,
and the first match is used. The syntax of the pattern is regex(5) (extended syntax).
The match is done against the path name of the file or directory relative to the
workarea.
„ action# is one of:
owner = name (changes the owner of the file or directory)
group = name (changes the group of the file or directory)
setaccess = ACL (replaces the access control list for the file or directory)
changeaccess = ACL (modifies the access control list so that the specified users
have only the specified rights)
‰ where name is one of:
username
groupname
domainname\username
domainname\groupname

‰ and where ACL (Access Control List) contains one or more Access Control
Entries (ACE), as follows:
name:perms (a single ACE, to specify a single user or group)
{ name:perms, name:perms, ... } (multiple ACEs, to specify multiple users or
groups)
where perms specifies the permissions granted to the specified user or group and
is either any sequence made of the characters:
R (read)
W (write)
X (execute)
D (delete)
P (change permissions)
O (take ownership)
or one of the preset combinations:
ALL (RWXDPO)
NONE (none)
READ (RX)
WRITE (W)
CHANGE (RWXD)

For example:
setaccess={ andre:ALL, marketing\pat:RX }

would remove the existing ACL and grant andre full access and pat (in the
marketing domain) read and execute access to the specified files.

TeamSite Administration Guide 133


Chapter 6: Managing TeamSite Access

changeaccess={ chris:CHANGE, everyone:RX }

would remove any existing ACEs for the user chris and the group everyone,
and grant chris change access and the group everyone read access to the
specified files. Any other existing ACEs would remain unchanged.

Submit Filtering Sequence


When you submit files or directories, the following sequence is initiated:
1. The server determines what files and directories have changed and need to be
submitted. It also verifies that none of them are in conflict with the staging area or
locked in other workareas.
2. The path name of the workarea from which the submit is being done is matched
against the workarea patterns in the submit.cfg file.
3. If the workarea matches one of the workarea patterns, then, for each file and direc-
tory that needs to be submitted (as determined in step 1), the file’s path name is
matched against the file patterns in the matching workarea’s section.
4. If a match is found, the server performs the specified set of actions (defined in
submit.cfg) to the file or directory in the workarea.

5. The server submits the transformed files and directories to the staging area.

Sample submit.cfg file


CASE-SENSITIVE = NO

RULES
{
. # any workarea
{
/a/b/.*\.html$ # files ending in .html under /a/b
{
owner=DOMAIN\andre
group="DOMAIN\\web editors"
setaccess = {everyone:Read, domain\andre:ALL}
}
[^/]$ # all other files
{
group="DOMAIN\\web editors"
setaccess = {users:rx, "domain\\webeditors:change"}
}
/$ # all directories
{
group="DOMAIN\\web editors"
setaccess = {everyone:rwx/rx, "domain\\webeditors:change"}
}
}
}

Interwoven, Inc. 134


Chapter 6: Managing TeamSite Access

NOTES
„ Only the first match is applied. That is, the first match is used if multiple rules
match the file or directory. The submit.cfg file should be ordered so that the most
specific workarea patterns are closer to the top and the most specific file patterns are
earlier in each section. You may need to duplicate some actions for them to apply to
multiple rules.
„ For purposes of matching, the path name of a directory must end in a slash (/).
„ Single or double quotes around patterns are optional, but they must be used around
workarea and file patterns that contain spaces or the following special characters:
#, {, }, =, or ,.

Backslashes (\) are special characters when used within patterns surrounded by
quotes; a backslash followed by any character is replaced by the single character.
For example, to embed a single quote, double quote, or backslash in a pattern,
precede the character with a backslash (\', \", or \\). Backslashes are not special
characters in patterns that are not quoted.
For example, the following three specifications are equivalent:
owner = DOMAIN\andre
owner = 'DOMAIN\\andre'
owner = "DOMAIN\\andre"

You can use backslashes (\) or forward slashes (/) as the path delimiter in regular
expressions, but using forward slashes is more readable. This is because the
backslash is treated as a special character in regex(5) syntax, and it is also treated
as a special character by the configuration file parser when the expression is
enclosed in quotes or double quotes. Therefore, when an expression using
backslashes is contained in quotes or double quotes, the backslashes must be
escaped twice, for a total of four backslashes.
For example, the following are equivalent expressions for matching any file whose
name ends in .html in the \a\b directory:
^/a/b/.*\.html$
'^/a/b/.*\\.html$'
"^/a/b/.*\\.html$"
^\\a\\b\\.*\.html$
'^\\\\a\\\\b\\\\.*\\.html$'
"^\\\\a\\\\b\\\\.*\\.html$"

„ Do not specify duplicate workarea patterns multiple times, duplicate file patterns
multiple times within a workarea section, or the same action multiple times within a
file rule.
„ Changes to submit.cfg do not take effect until the server is restarted or until you
use iwreset.
„ File permissions could be overwritten with submit.cfg options. If submit.cfg and
file permissions are not designed properly, the end user could be confused.

TeamSite Administration Guide 135


Chapter 6: Managing TeamSite Access

Testing and Debugging Submit Filtering


The iwtestcfg CLT can be used to determine which workarea and file patterns are
applied to a file at the time of submission. For example:
>iwtestcfg /default/main/WORKAREA/andre/cgi/test.sh

would return:
Matched area pattern "^/default/main/WORKAREA/.*$"
Matched file pattern ".*\.sh$"
Actions to do are:
owner = andre

Matched area pattern and Matched file pattern are the case-insensitive regular
expressions found in submit.cfg that match the workarea and file. Actions to do are
the actions (specified in submit.cfg) that will be applied to the file.

Refer to the TeamSite Command-Line Tools manual for more information about this
CLT.

You can also get debugging information on the submit handling configuration printed to
iwtrace.log by adding the following line to the [iwserver] section of iw.cfg:
[iwserver]
debug_event_handler=yes

This configures the TeamSite server to print:


„ A configuration map of submit.cfg.
„ Which actions are performed as files are submitted.

Interwoven, Inc. 136


Chapter 7

Configuring Interwoven
Search

The Interwoven Search function allows users to search common document types and
data records from TeamSite. Users can search for text within a file or for values
specified by metadata. Users enter search criteria using the search user interface from
ContentCenter. ContentCenter users may also save their search queries so the queries
can be reused or modified; refer to the online help for details. CLTs are also available for
system administrators to perform queries and to set up index and search functionality;
refer to the TeamSite Command-Line Tools.

The following topics are discussed in this chapter:


„ Search Overview
„ Working with Branches
„ Configuring the Index and Search Managers
„ Field Mapping Configuration
„ Types of Files Being Indexed
„ Using CLTs
„ Search Examples
„ Troubleshooting

Search Overview
The primary uses for Interwoven search are to:
„ Find files for viewing, editing, copying, and tagging.
„ Find outdated files for removal.
„ Find files for reuse.
„ Find files for reporting purposes (regulation and auditing compliance).
„ Find files for recovery purposes (restore older versions of deleted files).

The Interwoven Search function is made up of two parts—the index manager and the
search manager. The index manager controls the indexing of content. The search

TeamSite Administration Guide 137


Chapter 7: Configuring Interwoven Search

manager performs queries on indices and returns the results to the user. Both the index
manager and the search manager use agents, which are processes that access the search
engine for either indexing or querying documents. The index manager also uses a
document cracker that cracks a file or a data record and provides metadata and
full-search content on the document. TeamSite CLTs are used to issue commands to
either the index manager or the search manager. The ContentCenter interfaces
communicate with the search manager to request searches and to view the search results.

NOTE
Within configuration or log files associated with the Interwoven Search function, the
term index server is sometimes used to refer to the index manager and the terms search
service or search server may be used to refer to the search manager.

Figure 30 High-level design of search system

TeamSite

Search Index
Manager Manager

Query Query Index ... Index Document


Agent ... Agent Agent Agent Cracker

Working with Branches


The indexing of content and searching for content based on specified input constraints is
done on a branch-by-branch basis. This section explains how to index and search on
branches.

Indexing Branches
When a new TeamSite branch is to be indexed, the branch can be indexed in two ways.
„ The branch may be specified in the iwsearch-home\etc\branches.cfg file and
then the index manager may be started. The index manager picks up the branch
name during startup time and indexes the branch. If non-English characters are used
in this file, save the file in UTF-8 encoding.
„ The branch can be specified in the iwndxaddbr CLT that tells the index manager the
relevant branch that is to be indexed.

Interwoven, Inc. 138


Chapter 7: Configuring Interwoven Search

Whenever a branch that is specified to the index manager to be indexed has been
successfully indexed, the index manager creates a collection of data and indices about
the documents in the branch that is optimized for subsequent searching.

In addition to indexing an entire branch, the index manager also has a listener that
listens to any submit event on a previously indexed branch. When a user submits a set of
files through TeamSite, the index manager recognizes that a submission has occurred
and instructs the indexing to occur on that set of files. Indexing can be tuned based on a
set of parameters in the iwsearch-home\etc\search.properties file.

When an index manager is shut down, relevant information about all the branches that it
has indexed is stored in a file. When the index manager subsequently comes back up, it
sets the appropriate context by reading the information from this file.

Searching Branches
A ContentCenter user issues a search query. This query is sent to the search server.
Results are returned to the ContentCenter screen, arranged in relevancy order
determined by the search engine.

A CLT can also be used to issue a query. Queries are written in XML format and may be
saved in a file. The name of the file is provided with a CLT flag. Refer to the TeamSite
Command-Line Tools for details on using CLTs for queries.

Using the ContentServices API, you can search across multiple branches. Search across
multiple branches is not supported through ContentCenter or CLTs.

Deleting Branches
When a TeamSite branch has to be deleted, you need to issue the appropriate index
server CLTs so that the collections maintained by the index server for that branch are
handled correctly.

To purge the branch’s collection from the index manager and from the disk, issue the
iwndxpurgebr CLT for that branch. Otherwise, issue the iwndxrmbr CLT to remove the
collection from the index manager. Refer to the TeamSite Command-Line Tools for an
explanation of the differences between the two CLTs.

After issuing one of these CLTs, you can delete the branch from TeamSite. Refer to
page 167 for troubleshooting information if collections or branches are not deleted
correctly.

TeamSite Administration Guide 139


Chapter 7: Configuring Interwoven Search

Configuring the Index and Search Managers


The iwsearch-home\etc\search.properties file is used to configure the index
manager and the search server. This file is used to set parameters in the following areas:
„ Generic configuration
„ Generic agent configuration
„ Index manager configuration
„ Index agent configuration
„ Search manager configuration
„ Query agent configuration
„ Logging information

This section shows the configuration parameters in each area and describes the
information that can be modified.

The search.properties file cannot contain non-English characters.

NOTE
The iwsearch-home\etc\search.private.properties file contains settings you do
not normally need to adjust. Do not modify this file unless specifically instructed to do
so by an Interwoven representative.

Generic Configuration
This section identifies the TeamSite server. It is normally set by the installation
program. However, if your TeamSite server changes, you need to modify this section.
You also need to specify the locale of the index manager and search manager. This value
should typically refer to the same language or country as specified for the locale of the
TeamSite server.

######################################################################
# Generic configuration items (common for index server and search)
######################################################################

# TeamSite host
iw.teamsite.server.host=_IW_TS_HOST_NAME_

# Locale of index/search server. The values should be one of


# English_UnitedStates, French_France, Korean_Korea, Japanese_Japan,
# SimplifiedChinese_China,
# TraditionalChinese_Taiwan and German_Germany. Else, it will default
# to English_UnitedStates.
iw.server.locale=English_UnitedStates

Interwoven, Inc. 140


Chapter 7: Configuring Interwoven Search

Generic Agent Configuration


This section specifies the maximum times to wait for agent response and initialization.
If timeouts are occurring because of a loaded system or a slow machine, you may want
to increase these numbers.

When an agent fails to respond to a command from its server, the server automatically
restarts it. However, if the agent has a persistent problem, it can go through rapid
restarts, which can slow the system down. To limit this behavior, you can specify the
number of times the server is allowed to restart its agent within a specific time period. If
the restart limit is exceeded, the server takes the agent out of operation, which is called
taking the agent offline. Once an agent has been taken offline, the only way to start it is
to restart the server.

The iw.agent.windows.systemroot item in this section is used for Windows servers to


identify where the Windows operating system is located. If your Windows operating
system is in a different location, change the value.

The iw.agent.logs.agentlogs.enable item and the iw.agent.logs.toserverlogs control


whether agent logs are logged to separate files or to the logs of the server that started the
agent.
####################################
# Generic agent configuration items
####################################

# The maximum time (ms) to wait for agent response


iw.agent.timeout=1000000

# The maximum time (ms) to wait for agent initialization


iw.agent.init.timeout=20000

# If agent restarts more than iw.agent.restart.limit times during an


# iw.agent.restart.interval (ms), it is taken offline.
iw.agent.restart.limit=2
iw.agent.restart.interval=1000

iw.agent.windows.systemroot=_SYSTEM_ROOT_

# If iw.agent.logs.toserverlogs is true, the agents logs are logged to the


# log file of the server that started them.
iw.agent.logs.toserverlogs=false

# The iw.agent.logs.toserverlogs determines whether agents logs are


# logged to the log file of the server that started them. This property
# determines whether agents logs should go to their separate log files.
# The agent log files are in agentlogs subdir of the log directory and are
# named agent_<agent_pid>.log.
iw.agent.logs.agentlogs.enable=false

TeamSite Administration Guide 141


Chapter 7: Configuring Interwoven Search

Index Manager Configuration


This section is used to configure the index manager.

Change the value for iw.index.server.port to reflect your actual TCP port. This is the
TCP port that the index manager monitors for API requests, such as requests from CLTs
and the user interface. Also specify the value for the java.naming.provider.url.

The iw.index.markpartial.duration parameter specifies how old (in hours) an index


can be before it is considered to be a partial (or out-of-date) index. Search compares the
last indexed edition with the current edition; if they are not the same, this value is used
to determine whether the index is partial.

The iw.index.maxbifsize parameter controls how many files are optimally submitted
to be indexed at a time. Once the value is exceeded, an index job starts. BIF refers to
Bulk Insert File; BIFs are generated per branch so this refers to the optimal number of
changes per branch to be processed at one time.

The session pooling parameters control the number of connections open to TeamSite.
The iw.index.scipool.max parameter specifies the maximum number of connections
that can be opened. The iw.index.scipool.warm parameter specifies the number of
connections that are always open, whether or not they are used.

The iw.index.binaryextension parameter is used to indicate types of files that will


not have the content indexed. For example, graphics files do not have content that can
be indexed. Any metadata set for these files will, however, be indexed. See page 157 for
more details.

The iw.index.maxfilesizetoindex parameter indicates the maximum size of the file


in megabytes that will be indexed by the index manager. If the size of the file is larger
than the value specified by this parameter, then the contents of this file will not be
indexed.

The iw.index.events.enable parameter indicates whether the index should be updated


whenever a file is submitted. A value of true indicates that the index should be updated
when a file is submitted; otherwise, set it to false.

You can control the number of times the index manager attempts to listen to the
TeamSite Event Subsystem before giving up using the
iw.index.events.listen.attempts parameter; this value must be a positive number.
You can also specify the number of seconds the index manager waits between attempts
to listen to the TeamSite Event Subsystem using the iw.index.events.listen.wait
parameter.

You can control the number of times the index manager attempts to connect to the
TeamSite server before giving up by using the iw.index.iwserver.connect.attempts
parameter. You can also specify the number of seconds the index manager waits
between attempts to connect to the TeamSite server using the
iw.index.iwserver.connect.wait parameter.

Interwoven, Inc. 142


Chapter 7: Configuring Interwoven Search

When the iw.index.events.enable parameter the setting is set to true, the


iw.index.optimalWaitMins parameter indicates that events should be queued before
being indexed and specifies the number of minutes to wait before starting the index job.
Using this feature allows grouping the submits so multiple files are indexed at once. If a
lot of updates are occurring, you may want to set a higher value to get maximum
performance; however, your index may become slightly out-of-date.

The iw.index.wamodifications.enable parameter controls at a global level whether


indexing of and searching across modifications in workareas of indexed branches is
turned on. A value of true indicates that this feature is turned on; a value of false
indicates that this feature is turned off.

The iw.index.wamodifications.branchcreation.default parameter controls


whether indexing the modifications of all the workareas of an indexed branch should
begin when that indexed branch is loaded in the index server memory. This could
happen the first time the branch is indexed or when the index server is restarted and the
indexing information for that branch is read from the relevant branch collection. The
only permissible values for this parameter are all or none. A value of all indicates that
all the workareas of the relevant indexed branch will be indexed. A value of none
indicates that none of the workareas of the relevant indexed branch will be indexed.
This feature is useful if you need to either index all of the workareas of the indexed
branches or none of the workareas of the indexed branches at one time. The
iwdxwamodifications CLT provides the ability to control indexing of the modifications
in workareas on a per-branch level.

The iw.index.wamodifications.frequency parameter controls how often (in minutes)


the workarea indexer module inside the index server goes through all the relevant
workareas of the indexed branches and indexes the modified files. After the workarea
indexer module has completed one cycle, it waits for the remainder of the time specified
by this parameter before it repeats its cycle. However, if the amount of time taken by the
workarea indexer module to complete one cycle is greater than the time specified by this
parameter, the next cycle of indexing begins immediately.

The iw.index.wamodifications.deleteindexes parameter controls how often (in


hours) the workarea indexer module inside the index server deletes all previous
collections created for workarea modifications and re-indexes all the modified files for
the relevant workareas of the branches into a persistent collection. This step is useful to
delete old collections of workarea modifications that may have grown over time. This
property is checked by the index server at startup only.
######################################################################
# Index server configuration
######################################################################

# Server configuration
iw.index.server.port=_IW_INDEX_PORT_

# TeamSite JMS producer side details


java.naming.provider.url=tcp://_IW_TS_HOST_NAME_:_IW_EVENT_PORT_/

# How old (hours) the index needs to be (relative to current edition)

TeamSite Administration Guide 143


Chapter 7: Configuring Interwoven Search

# for it to be considered partial


iw.index.markpartial.duration=24

# Max number of files for BIF


iw.index.maxbifsize=4000

# TeamSite session pooling


iw.index.scipool.max=10
iw.index.scipool.warm=1

# Binary extensions. The content in these files will not be indexed,


although metadata will be.
iw.index.binaryextensions=exe,jpg,gif,psd,tif,tiff,au,wav,bmp,rif

# Maximum size of the file (in megabytes) to be indexed.


iw.index.maxfilesizetoindex=20

# Event-based updates are enabled


iw.index.events.enable=_IW_INCR_UPDATES_ENABLED_

# Number of times Index server attempts to listen to


# TeamSite event system before giving up
iw.index.events.listen.attempts=10

# Number of seconds Index server waits between attempts to listen to


# TeamSite event system
iw.index.events.listen.wait=12

# Number of times Index server attempts to connect to


# TeamSite server before giving up
iw.index.iwserver.connect.attempts=10

# Number of seconds Index server waits between attempts to connect to


# TeamSite server
iw.index.iwserver.connect.wait=12

# Optimal wait time before received events are processed (in minutes)
iw.index.optimalWaitMins=1

# Indexing workarea modifications


# Control whether indexing of and searching across modifications in
# workareas of indexed branches is turned on or not.
iw.index.wamodifications.enable=false
# Control whether indexing the modifications of ALL the workareas of a
# branch at the time the branch is first indexed should be turned on or
off
# (permissible values are none and all).
iw.index.wamodifications.branchcreation.default=none
# Control how often (in minutes) an attempt is made to index the modified
# files in the relevant workareas of all the relevant indexed branches.

Interwoven, Inc. 144


Chapter 7: Configuring Interwoven Search

iw.index.wamodifications.frequency=2
# Control after how much time (in hours) the collections of workarea
# modifications for a branch are considered too old and hence deleted
# and then re-indexed. Checked during index server startup only.
iw.index.wamodifications.deleteindexes=72

Index Agent Configuration


This section is used to configure the index agent.

The iw.index.agent.mainport parameter specifies the TCP port number on which the
index manager listens to its agent. This connection is used by the index manager to
dispatch commands to its agents. The iw.index.agent.callbackport parameter
specifies the TCP port on which the index manager listens to its agents for a callback
connection. The callback connection is used by the agents to send their log messages to
the server.

The iw.index.agent.idxdir parameter sets the directory on the index manager server
that holds the indexes for all branches. For example:
iw.index.agent.idxdir=C:/Interwoven/Index

NOTE
If workarea indexing is turned on, the directory on the index manager server that holds
the indexes for all workarea-modified files will be a subdirectory named WORKAREAINDX
under the path you specified. In a scenario where the index server is on machine 1 and
the search server is on machine 2, the collection directories that both the index and
search server point to have to be same. If the index collection is on C:\collection on
machine 1 and pointed to by iw.index.agent.idxdir, it has to be mapped using a
network drive such that it is accessible by the search server from machine 2. So
iw.search.agent.idxdir could be x:\coll-dir on machine 2 although both of them
finally point to the same set of bytes.

######################################################################
# Index agent configuration
######################################################################

# Port number on which index server listens for connections from its
agents
iw.index.agent.mainport=_IW_INDEX_AGENT_MAIN_PORT_

# Port number on which index server listens for callbacks from its agents
iw.index.agent.callbackport=_IW_INDEX_AGENT_CALLBACK_PORT_

# Collections directory for index agents


iw.index.agent.idxdir=_IW_INDEX_SHARED_FILESYSTEM_

TeamSite Administration Guide 145


Chapter 7: Configuring Interwoven Search

Search Manager Configuration


This section contains parameters that control the search manager.

Change the value for iw.search.server.port to reflect your actual TCP port. This is
the TCP port that the search manager monitors for API requests, such as requests from
CLTs and the user interface.

The search manager uses a pool of worker threads for servicing client requests. Each
client connection, whether from a CLT or the user interface, is served by its own worker
thread. When the search manager starts, it creates threads specified by the value of the
iw.search.server.threadpool.warmthreads parameter. If a new client connection is
made and none of these threads is available to service the connection, a new thread is
created, thus growing the thread pool.

The thread pool growth is capped by the value of the


iw.search.server.threadpool.maxthreads parameter. This value determines the
maximum number of simultaneous client connections that can be serviced by the server.

When a thread has been idle for longer than the millisecond time out specified by the
value of the iw.search.server.threadpool.keepalivetime parameter, it is
terminated by the server to conserve resources. If
iw.search.server.threadpool.keepalivetime is set to a value of -1, the threads are
never reclaimed.

The iw.search.query.maxOpenQueriesPerUser parameter indicates the maximum


number of queries an individual user can have open. If they exceed that number of
queries, the earliest ones are no longer valid.

The iw.search.query.defaultQueryLocale parameter provides a default locale to use


to process queries when the query locale is not specified.

Change the value for the iw.index.server.host parameter if the index manager is on a
different host computer than the search manager.

You can modify the cache configuration. The raw cache contains the results of a query
as they are retrieved. Post-processing filters the results from the raw cache and writes
the results to the processed cache until enough results are found to return the first page
of results. The values for iw.search.cache.raw.entries.capacity and
iw.search.cache.raw.entries.grace are used to control the total number of queries
kept in the system and the extra capacity that can be used when managing the number of
queries. For example, the default settings indicate 100 queries are kept in the system,
but that number can go to 110 (10 grace queries) and then 10 queries would be deleted at
one time to return to the 100-query capacity. This is more efficient than deleting one
extra query at a time. The iw.search.cache.processed.size parameter specifies the
size of the processed cache.

The session pooling parameters control the number of connections open to TeamSite.
The iw.search.scipool.max parameter specifies the maximum number of connections
that can be opened. The iw.search.scipool.warm parameter specifies the number of

Interwoven, Inc. 146


Chapter 7: Configuring Interwoven Search

connections that are open, whether they are used or not. The value for
iw.search.scipool.max should be less than half the value of
iw.search.server.threadpool.maxthreads, but should not generally exceed 25 for the best
performance.
######################################################################
# Search server configuration
######################################################################
iw.search.server.port=_IW_SEARCH_PORT_
iw.search.server.threadpool.maxthreads=50
iw.search.server.threadpool.warmthreads=10
iw.search.server.threadpool.keepalivetime=60000

iw.search.query.maxOpenQueriesPerUser=2

iw.search.query.defaultQueryLocale=en

# change this if the index server is on a different host than the


# search server
iw.index.server.host=_IW_SEARCH_HOST_

#Cache configuration

#Raw cache
iw.search.cache.raw.entries.capacity=100
iw.search.cache.raw.entries.grace=10
iw.search.cache.raw.validity.mins=240

#Processed cache
iw.search.cache.processed.size=100

# TeamSite session pooling. Note that the optimal behavior is to have


# the same max number of connections as there are agents.
iw.search.scipool.max=10
iw.search.scipool.warm=1

Search Agent Configuration


This section is used to configure the search agent.

The iw.search.agent.mainport parameter specifies the TCP port on which the search
manager listens to its agents. This connection is used by the search manager to dispatch
commands to its agents. The iw.search.agent.callbackport parameter specifies the
TCP port on which the search manager listens to its agents for a callback connection.
The callback connection is used by the agents to send their log messages to the server.

The iw.search.agent.idxdir parameter sets the directory on the search manager that
holds the indexes for all branches.

TeamSite Administration Guide 147


Chapter 7: Configuring Interwoven Search

NOTE
If workarea indexing is turned on, the directory on the search manager server that holds
the indexes for all workarea-modified files will be a subdirectory named WORKAREAINDX
under the path you specified.

######################################################################
# Search Agent configuration
######################################################################

# Port number on which search server listens for connections from its
# agents
iw.search.agent.mainport=_IW_SEARCH_AGENT_MAIN_PORT_

# Port number on which search server listens for callbacks from its agents
iw.search.agent.callbackport=_IW_SEARCH_AGENT_CALLBACK_PORT_

# Collections directory for search agents


iw.search.agent.idxdir=_IW_SEARCH_SHARED_FILESYSTEM_

Logging Configuration
The logging configuration refers to both the index manager and the search manager. The
first part of the value for the log4j.logger.com.interwoven parameter specifies the
log level for the server. The set of possible log levels are in increasing order of verbosity
are FATAL, ERROR, WARN, INFO, and DEBUG. Normally, the server should be run with the
log level of INFO. You can control the maximum log file size using
log4j.appender.mainLogger.MaxFileSize and specify the number of archived or
backup log files using log4j.appender.mainLogger.MaxBackupIndex.

#######################################################
# Logging configuration
#######################################################
log4j.logger.com.interwoven=INFO, mainLogger
log4j.appender.mainLogger.MaxFileSize=5000KB
log4j.appender.mainLogger.MaxBackupIndex=3

Field Mapping Configuration


The field mapping configuration file:
„ Defines the extended attributes that will be indexed by the index manager.
„ Defines the templating attributes for the specified template type that will be indexed
by the index manager.

Interwoven, Inc. 148


Chapter 7: Configuring Interwoven Search

If you make changes such as adding another attribute to the FieldMapping.xml file, you
need to force the index manager to re-index all the files. Use the iwndxpurgebr CLT to
remove the collection; then add the branch to the index again.

The FieldMapping schema (in iwsearch-home\etc\FieldMapping.xsd) provides the


schema for creating the iwsearch-home\etc\FieldMapping.xml configuration file.

In addition to these extended and templating attributes that are defined in the field
mapping configuration file, there are a set of attributes and file properties that will
always be indexed. These are defined in an internal standard field mapping
configuration file. The StandardFields schema (as described on page 155) defines these
fields and they cannot be changed.

In the field mapping configuration file, the globalFields element contains


extendedAttributeFields that contain the fieldSpecification element for each field
that will be indexed.

The templates element contains a template element for each FormsPublisher template
used. The template element includes a templateType element that identifies the
FormsPublisher template (or form). The fields within the form that will be indexed are
identified in the templatingFields element, which contains one or more
templatingField elements. Each templatingField element contains a xpath element
and a fieldSpecification element. The templatingField element defines a mapping
from the xpath of a templating entry to the field definition that is used to store it.

A fieldSpecification element has the following elements:


„ A fieldName element: Any typical name can be chosen for this element. This name
is used for building queries that are submitted to the search manager. This name
should be unique across all fieldName entries in the FieldMapping.xml and
StandardFields.xml files. The fieldName must be in the same language as it is in
the datacapture.cfg file in order for indexing to occur.
„ A fieldType element: The possible values are string, int, float, and date.
„ An optional formatString element: This element is relevant and required only if
the fieldType element has a value of date. This element specifies the date-time
format for the relevant EA in one of the JDK-defined standard forms. For example it
could be, yyyy-mm-dd (see “Configuring Date Fields”).
„ A fieldStorage element:
‰ If the fieldType element is a string, then this element needs to be of the form
zone:variable-name. The variable-name specified here should be unique
across all fieldStorage entries in the FieldMapping.xml and
StandardFields.xml files.

‰ If the fieldType element is an int, float, or date, then the fieldStorage


element should respectively be one of CustomInt1 through CustomInt5,
CustomFloat1 through CustomFloat5, or CustomDate1 through CustomDate5.
This entry should be unique across all fieldStorage entries in the
FieldMapping.xml and StandardFields.xml files.

TeamSite Administration Guide 149


Chapter 7: Configuring Interwoven Search

NOTE
The fieldName and fieldStorage elements defined in globalFields must be unique.
The fieldName and fieldStorage elements defined for a single template type may be
reused in other template types. This means two different templates could have fields that
share names or storage; however, these cannot conflict with a global field.

The value for a zone name must be a valid XML name; it cannot have spaces. Names are
character insensitive. They can consist of all alphabetic characters (upper and lower
case), numeric characters, the dash (-), the underscore character (_), or the number
sign (#).

Configuring Date Fields


If a custom field is of type date, the formatString corresponding to the field must be
configured in FieldMapping.xml. The formatString tells the index manager how to
parse dates during the indexing process. The index manager and search manager will not
start without formatString for date fields. As shown in this example, the value of
formatString specifies the pattern of the data and time strings.
<fieldSpecification>
<fieldName>TeamSite/Metadata/Launch Date</fieldName>
<fieldType>date</fieldType>
<formatString>yyyy-MM-dd</formatString>
<fieldStorage>CustomDate1</fieldStorage>
</fieldSpecification>

Explanation of pattern letters:

y year
M Month (in numeric form)
d Day in month
a|p AM or PM marker
h Hour
m Minute

The following examples show how Index Manager interprets the date and time patterns.

Table 9 Interpretation of Time and Date Patterns


Pattern Date Interpretation
MM/dd/yyyy 08/30/2004 30 Aug 2004
yyyy-MM-dd hh:mm a 2004-08-30 06:30 AM 30 Aug 2004 06:30 AM
yyyy-MM-dd hh:mm a 2004-08-30 30 Aug 2004 12:00 AM

Interwoven, Inc. 150


Chapter 7: Configuring Interwoven Search

Example of FieldMapping File


The following code is an example of a FieldMapping.xml file. It includes some of the
default FormsPublisher forms that ship with TeamSite. This file is located at
iwsearch-home\etc\FieldMapping.xml.example. If desired, you can use snippets of
this file to create your FieldMapping.xml file.

TeamSite Administration Guide 151


Chapter 7: Configuring Interwoven Search

<?xml version="1.0" encoding="UTF-8"?>


<searchFieldMapping xmlns="http://www.interwoven.com/products/teamsite
/search/config/FieldMapping.xsd" xmlns:xsi="http://www.w3.org/2001
/XMLSchema-instance" xsi:schemaLocation="http://www.interwoven.com
/products/teamsite/search/config/FieldMapping.xsd
Schema location
FieldMapping.xsd">
<globalFields>
<!-- These metadata fields are tagged through TeamSite
Metadata capture form -->
globalFields section <extendedAttributeFields>
that lists
ExtendedAttributeFields
that contain one or more <!-- Examples of configuring string fields -->
fieldSpecification
elements. <fieldSpecification>
<fieldName>TeamSite/Metadata/Description</fieldName>
<fieldType>string</fieldType>
<fieldStorage>zone:Description</fieldStorage>
</fieldSpecification>
<fieldSpecification>
<fieldName>TeamSite/Metadata/Business Unit</fieldName>
<fieldType>string</fieldType>
<fieldStorage>zone:Business Unit</fieldStorage>
</fieldSpecification>

<!-- Examples of configuring date fields -->


<fieldSpecification>
<fieldName>TeamSite/Metadata/Expiration Date</fieldName>
<fieldType>date</fieldType>
<formatString>yyyy-MM-dd</formatString>
<fieldStorage>CustomDate2</fieldStorage>
</fieldSpecification>
</extendedAttributeFields>
</globalFields>

<templates>
<!-- Examples of configuring 'iwov' style templates -->
The templates section <template>
begins by defining
intranet/weather. <templateType>intranet/weather</templateType>
<templatingFields>
<templatingField>
<xpath>/Announcement</xpath>
<fieldSpecification>
<fieldName>Announcement</fieldName>
<fieldType>string</fieldType>
<fieldStorage>zone:WeatherAnnouncement</fieldStorage>
</fieldSpecification>
</templatingField>
</templatingFields>
</template>

Interwoven, Inc. 152


Chapter 7: Configuring Interwoven Search

<template>
This section defines <templateType>internet/yacht</templateType>
internet/yacht.
<templatingFields>
<!-- An Example of configuring int fields -->
<templatingField>
<xpath>/General Info/Length</xpath>
<fieldSpecification>
<fieldName>YachtLength</fieldName>
<fieldType>int</fieldType>
<fieldStorage>CustomInt1</fieldStorage>
</fieldSpecification>
</templatingField>
</templatingFields>
</template>

<template>
Another template
category and type. <templateType>internet/auction</templateType>
It defines <templatingFields>
internet/auction.
<!-- An Example of configuring float fields -->
<templatingField>
<xpath>/Minimum Bid Amount</xpath>
<fieldSpecification>
<fieldName>MinBidAmount</fieldName>
<fieldType>float</fieldType>
<fieldStorage>CustomFloat1</fieldStorage>
</fieldSpecification>
</templatingField>
</templatingFields>
</template>

<template>
This element defines <!-- An example of configuring all instances of replicants -->
internet/careers.
<templateType>internet/careers</templateType>
<templatingFields>
<templatingField>
<xpath>/Responsibilities List</xpath>
<fieldSpecification>
<fieldName>Responsibilities</fieldName>
<fieldType>string</fieldType>
<fieldStorage>zone:Responsibilities</fieldStorage>
</fieldSpecification>
</templatingField>
</templatingFields>
</template>

TeamSite Administration Guide 153


Chapter 7: Configuring Interwoven Search

<template>
This section defines <!-- An example of configuring a particular replicant instance -->
internet/pr. <templateType>internet/pr</templateType>
<templatingFields>
<templatingField>
<xpath>/Story[1]/Section Paragraphs[1]/Paragraphs</xpath>
<fieldSpecification>
<fieldName>FirstStoryParagraph</fieldName>
<fieldType>string</fieldType>
<fieldStorage>zone:FirstStoryParagraph</fieldStorage>
</fieldSpecification>
</templatingField>
</templatingFields>
</template>

<!-- Examples of configuring 'xml' style templates -->


This section defines
xml/press-release. <template>
<templateType>xml/press-release</templateType>
<templatingFields>
<templatingField>
<xpath>/press-release/head/byline/@author</xpath>
<fieldSpecification>
<fieldName>PR_Author</fieldName>
<fieldType>string</fieldType>
<fieldStorage>zone:PR_Author</fieldStorage>
</fieldSpecification>
</templatingField>
<templatingField>
<xpath>/press-release/body/section/subheading</xpath>
<fieldSpecification>
<fieldName>Subheading</fieldName>
<fieldType>string</fieldType>
<fieldStorage>zone:PR_Subheading</fieldStorage>
</fieldSpecification>
</templatingField>
</templatingFields>
</template>
</templates>
</searchFieldMapping>

Interwoven, Inc. 154


Chapter 7: Configuring Interwoven Search

The standardFields.xml File


The standardFields.xml file is based on the standardFields.xsd schema and defines
fields for extendedAttributes and fileAttributes elements. This file cannot be
edited. You cannot redefine the fields in FieldMapping.xml that are defined in
standardFields.xml. The entries in bold in the StandardFields.xml are the relevant
extended attributes and file attributes that a search query may be issued against. The
other entries are indexed but are for Interwoven internal use only.

<?xml version="1.0" encoding="UTF-8"?>


<standardFields
xmlns="http://www.interwoven.com/products/teamsite/search/config/Standar
dFields.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.interwoven.com/products/teamsite/search/c
onfig/StandardFields.xsd StandardFields.xsd">
<extendedAttributes>
<field>
<fieldName>TeamSite/Templating/PrimaryDCR</fieldName>
<fieldType>string</fieldType>
<fieldStorage>zone:IWTemplatingPrimaryDCR</fieldStorage>
</field>
<field>
<fieldName>TeamSite/Templating/PrimaryDocumentType</fieldName>
<fieldType>string</fieldType>
<fieldStorage>zone:IWTemplatingPrimaryDocuemntType</fieldStorage>
</field>
<field>
<fieldName>TeamSite/Templating/DCR/Type</fieldName>
<fieldType>string</fieldType>
<fieldStorage>ContentType</fieldStorage>
</field>
</extendedAttributes>
<fileAttributes>
<field>
<fieldName>Creator</fieldName>
<fieldType>string</fieldType>
<fieldStorage>zone:Creator</fieldStorage>
</field>
<field>
<fieldName>CreateDate</fieldName>
<fieldType>date</fieldType>
<fieldStorage>CreateDate</fieldStorage>
</field>
<field>
<fieldName>AreaRelativePath</fieldName>
<fieldType>string</fieldType>
<fieldStorage>AreaRelativePath</fieldStorage>

TeamSite Administration Guide 155


Chapter 7: Configuring Interwoven Search

<field>
<fieldName>BranchId</fieldName>
<fieldType>long</fieldType>
<fieldStorage>BranchId</fieldStorage>
</field>
<field>
<fieldName>OwningAreaId</fieldName>
<fieldType>long</fieldType>
<fieldStorage>OwningAreaId</fieldStorage>
</field>
<field>
<fieldName>LastModifier</fieldName>
<fieldType>string</fieldType>
<fieldStorage>zone:LastModifier</fieldStorage>
</field>
<field>
<fieldName>LastModifiedDate</fieldName>
<fieldType>date</fieldType>
<fieldStorage>LastModifiedDate</fieldStorage>
</field>
<field>
<fieldName>Indexed</fieldName>
<fieldType>int</fieldType>
<fieldStorage>Indexed</fieldStorage>
</field>
<field>
<fieldName>IndexedDate</fieldName>
<fieldType>date</fieldType>
<fieldStorage>IndexedDate</fieldStorage>
</field>
<field>
<fieldName>Size</fieldName>
<fieldType>int</fieldType>
<fieldStorage>FileSize</fieldStorage>
</field>
<!-- Fields returned by Verity -->
<field>
<fieldName>Title</fieldName>
<fieldType>string</fieldType>
<fieldStorage>zone:DocMetadataTitle</fieldStorage>
</field>
<field>
<fieldName>Author</fieldName>
<fieldType>string</fieldType>
<fieldStorage>zone:DocMetadataAuthor</fieldStorage>
</field>
<field>
<fieldName>Keywords</fieldName>

Interwoven, Inc. 156


Chapter 7: Configuring Interwoven Search

Types of Files Being Indexed


Content is extracted only from documents belonging to these general classifications:
„ Word processor documents
„ Spreadsheet documents
„ Presentation documents

Only TeamSite EAs (if there are any) and file properties are extracted from most other
types of documents, such as:
„ Raster image documents
„ Vector graphic documents
„ Executable files
„ Encapsulation formats
„ Sound file formats
„ Planning/outline formats
„ Scheduling/planning formats
„ Movie files
„ Animation files

You can specify other types of files for which content is not extracted using the
iw.index.binaryextensions parameter in the search.properties file (see page 142).

Using CLTs
CLTs have been created to manage the index and search servers. Refer to the
Command-Line Tools Reference for details on usage.

Table 10 Search CLTs


CLT Description
iwsrchgethome Displays the location of the TeamSite Search home
directory.
iwndxmgrfreeze Freezes and unfreezes the index manager.
iwndxmgrstatus Determines the current status of the index manager (active
or frozen).
iwndxmgrstop Shuts down the index manager.
iwndxstatus Displays the index status for branches.
iwndxlistbr Lists all the indexed branches.
iwdxpurgebr Removes the index collection associated with the branch.

TeamSite Administration Guide 157


Chapter 7: Configuring Interwoven Search

Table 10 Search CLTs (Continued)


CLT Description
iwndxaddbr Adds a branch to be indexed by the index manager.
iwndxrmbr Removes a branch so it is no longer indexed by the index
manager.
iwndxfreezebr Freezes or unfreezes a branch that is being indexed by the
index manager.
iwndxrefreshbr Reindex the branch using either the bulk or incremental
queue.
iwndxwamodificationsbr Enables or disables indexing of workarea modifications for
the specified index branch.
iwsrchndxstatus Displays the index status for branches from the search
server.
iwsrchquery Returns the first page of the query output in XML format.
iwsrchgetpage Displays a page of results from a previously performed
query.
iwsrchmgrstop Shuts down the search server.
iwsrchmgrping Pings the search server.
iwsrchndxstatuschg Notifies the search server of changes in the index manager
status.
iwsrchattrib Displays a list of field specifications for indexed attributes.

Search Examples
This section contains examples of searches based on a set of input constraints. Each
search example contains:
„ a brief description,
„ the code for using Interwoven Query Schema to define the query (required when
issuing the query with iwsrchquery),
„ a code fragment showing how to issue the query using the ContentServices API.

NOTE
The searches described in this chapter will work only after TeamSite Search is installed
and configured.

Interwoven, Inc. 158


Chapter 7: Configuring Interwoven Search

Example 1
Find all content in English that has either:
„ An attribute called LaunchDate that is equal to Oct 14, 2005, or
„ An attribute called TeamSite/Metadata/Description that contains the phrase This
file discusses the weather pattern.

Query in Interwoven Query Schema

Construct the query as follows to issue it with the iwsrchquery CLT:

<predicate xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="TeamSiteSearch.xsd">
<queryLocale>en</queryLocale>
<or>

<attributeComparison><name>LaunchDate</name><operator>EQ</operator>
<value><![CDATA[14 Oct 2005]]></value></attributeComparison>
<fulltext-attribute>
<name>TeamSite/Metadata/Description</name>
<fulltext-phrase>
<term>This file discusses the weather pattern</term>
</fulltext-phrase>
</fulltext-attribute>
</or>
</predicate>

Code Fragment Using ContentServices API

Construct the query as follows to issue it with the ContentServices API:

CSConstraint query1 = new CSOrConstraint(new CSConstraint[] {


new CSFieldConstraint("LaunchDate", CSOperator.EQUALS,
new Date(2005-1900, 9/*October, not September*/, 14)),
new CSFieldConstraint("TeamSite/Metadata/Description",
new CSPhraseConstraint("This file discusses the weather pattern"))
});

TeamSite Administration Guide 159


Chapter 7: Configuring Interwoven Search

Example 2
Find all content in English that has either:
„ A file size greater than 20KB, or
„ File names that start with b and end with txt.

Query in Interwoven Query Schema

Construct the query as follows to issue it with the iwsrchquery CLT:


<predicate xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="TeamSiteSearch.xsd">
<queryLocale>en</queryLocale>
<or>

<attributeComparison><name>Size</name><operator>GT</operator><value><![
CDATA[20000]]></value></attributeComparison>
<areaRelativePath>
<wildcard>
b*.txt
</wildcard>
</areaRelativePath>
</or>
</predicate>

Code Fragment Using ContentServices API

Construct the query as follows to issue it with the ContentServices API:


CSConstraint query2 = new CSOrConstraint(new CSConstraint[] {
new CSFieldConstraint("Size", CSOperator.GREATER_THAN, "20000"),
new CSPathConstraint("b*.txt")
});

Example 3
Find all FormsPublisher (Templating) content in English that:
„ Belongs to the template category/type of internet/yacht, and
„ Has both:
‰ A templating attribute called GeneralInfoLength (this maps to the xpath
/General Info/Length as specified in FieldMapping.xml) whose value is
greater than 200, and
‰ A templating attribute called Details (this maps to the xpath /Details as
specified in FieldMapping.xml) that contains the full-text phrase example of a
boat that I would like.

Interwoven, Inc. 160


Chapter 7: Configuring Interwoven Search

Query in Interwoven Query Schema

Construct the query as follows to issue it with the iwsrchquery CLT:


<predicate xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance
"xsi:noNamespaceSchemaLocation="TeamSiteSearch.xsd">
<queryLocale>en</queryLocale>
<and>
<templatingAttribute>
<templateType>internet/yacht</templateType>

<attributeComparison><name>GeneralInfoLength</name><operator>GT
</operator><value><![CDATA[200]]></value></attributeComparison>
</templatingAttribute>
<templatingAttribute>
<templateType>internet/yacht</templateType>
<fulltext-attribute>
<name>Details</name>
<fulltext-phrase>
<term>example of a boat that I would like</term>
</fulltext-phrase>
</fulltext-attribute>
</templatingAttribute>
</and>
</predicate>

Code Fragment Using ContentServices API

Construct the query as follows to issue it with the ContentServices API:

CSConstraint query3 = new CSAndConstraint(new CSConstraint[] {


new CSScopedConstraint("internet/yacht",
new CSFieldConstraint("GeneralInfoLength",
CSOperator.GREATER_THAN, "200")),
new CSScopedConstraint("internet/yacht",
new CSFieldConstraint("Details",
new CSPhraseConstraint("example of a boat that I would like")))
});

TeamSite Administration Guide 161


Chapter 7: Configuring Interwoven Search

Example 4
Find all content in English that has either:
„ Both the full-text terms hello and world, or
„ At least one full-text term beginning with environ.

Query in Interwoven Query Schema

Construct the query as follows to issue it with the iwsrchquery CLT:

<predicate xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="TeamSiteSearch.xsd">
<queryLocale>en</queryLocale>
<or>
<fulltext-all>
<term>hello</term>
<term>world</term>
</fulltext-all>
<fulltext-wildcard>
<term>environ*</term>
</fulltext-wildcard>
</or>
</predicate>

Code Fragment Using ContentServices API

Construct the query as follows to issue it with the ContentServices API:

CSConstraint query4 = new CSOrConstraint(new CSConstraint[] {


new CSContainsAllConstraint(new String[] {"hello", "world"}),
new CSWildCardConstraint("environ*")
});

Interwoven, Inc. 162


Chapter 7: Configuring Interwoven Search

Example 5
Find all content in English that has either:
„ An attribute called Description that contains both the terms weather and
patterns, or

„ The full-text terms Scotland and Yard next to each other.

Query in Interwoven Query Schema

Construct the query as follows to issue it with the iwsrchquery CLT:

<predicate xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="TeamSiteSearch.xsd">
<queryLocale>en</queryLocale>
<or>
<fulltext-attribute>
<name>Description</name>
<fulltext-all>
<term>weather</term>
<term>patterns</term>
</fulltext-all>
</fulltext-attribute>
<fulltext-near>
<ordered>true</ordered>
<proximity>1</proximity>
<term>Scotland</term>
<term>Yard</term>
</fulltext-near>
</or>
</predicate>

Code Fragment Using ContentServices API

Construct the query as follows to issue it with the ContentServices API:

CSConstraint query5 = new CSOrConstraint(new CSConstraint[] {


new CSFieldConstraint("Description",
new CSContainsAllConstraint(new String[] {"weather", "patterns"})),
new CSNearConstraint(true, 1, new String[] {"Scotland", "Yard"})
});

TeamSite Administration Guide 163


Chapter 7: Configuring Interwoven Search

Example 6

Find all content in Japanese that contains the full-text term .

Query in Interwoven Query Schema

Construct the query as follows to issue it with the iwsrchquery CLT:

<predicate xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="TeamSiteSearch.xsd">
<queryLocale>ja</queryLocale>
<or>
<fulltext-all>

<term> </term>
</fulltext-all>
</or>
</predicate>

Code Fragment Using ContentServices API

Construct the query as follows to issue it with the ContentServices API:

String japaneseString = readStringFromFile("japanese.txt");


CSConstraint query6 = new CSOrConstraint(new CSConstraint[] {
new CSContainsAllConstraint(new String[] {japaneseString})
});

NOTE
In this example, the Japanese strings are obtained from the file japanese.txt, where
they are stored in UTF-8 format.

Interwoven, Inc. 164


Chapter 7: Configuring Interwoven Search

Troubleshooting
The following topics provide additional information you may need regarding index and
search functionality.

Files Not Found


If you are having trouble finding what you are looking for, consider the following:
„ Ensure that search terms are spelled correctly.
„ The user may have indicated a particular capitalization that is not indexed. If the
user enters text in all upper-case characters or all lower-case characters, Search will
find the word in any combination of characters. However, if the user enters text with
a particular combination of upper- and lower-case characters, only exact matches
will be found. For example, the user enters “teamsite” and gets results containing
TeamSite, teamsite, and TEAMSITE. If the user enters “TeamSite,” the results will
be an exact match and will not contain teamsite or TEAMSITE. This also applies
when the user is searching file attributes, such as the file owner in the form
domain\\user. Specifying Domain\\User would result in a case-sensitive search
being attempted.
„ The search subsystem relies on a search index. Recently modified or submitted
content might not be indexed immediately.For example, a user’s search result
includes a specific file. If the user then modifies the file and does the search again,
the file may not be included because it has not yet been indexed. If workarea
indexing is enabled and a file is modified, its previous index is invalid until the file
is re-indexed.
„ Some forms contain menus, such as drop-down menus. Menus can be configured so
that a value different from the displayed text is what is actually saved. For example,
the form contains a drop-down menu with a list of states: California, Florida,
Washington. The drop-down menu is configured so that the abbreviation for the
selected state is saved, not the full name. So, if a user selects California and saves
the form, the value “CA” is what is actually saved. Under those conditions, a search
for “California” will not return the form; a search for “CA” would.
„ When search subsystem indexes content, it attempts to identify the languages in
which the content is written. If some content does not contain enough
natural-language text for the indexing engine to determine its language, then it is not
indexed. This can be a problem for forms, which often contain non-natural-language
text, such as part numbers.
For example, a form that has only two fields: Item number and Minimum bid
amount. The user enters 123 for the item number and 20.00 for the minimum bid
amount. The search subsystem attempts to index it. Because the form entries do not
contain any natural-language text, the indexing engine cannot determine the
language in which the form is written and fails to index it. A search for “123” or
“20.00” might yield results, but this form will not be included among them. As a
best practice, ContentCenter administrators should ensure that forms contain some
natural-language text.

TeamSite Administration Guide 165


Chapter 7: Configuring Interwoven Search

„ Content in text (.txt) documents (including files with .cpp, .c, or .html
extensions) must be saved in UTF-8 encoding to be properly indexed and
searchable.
„ Searching on standard Author, Keyword, and Title metadata is possible only for
Microsoft Word documents.
„ When a non-Microsoft Office file (such as a .txt or .pdf file) that has “Document
Summary Info” is copied to a workarea, either through the Local File Manager or
through the file system, the “Document Summary Info” is not preserved so that
information is not indexed and cannot be searched.
„ If there is a comment in a file (<!-- and -->), then the last word in the file fails to
be indexed. Add a blank space after the last word to remedy this situation.
„ Comments (between <!-- and -->) in a .xml file are not indexed.
„ Search stemming is not supported.

Deleted Edition
If you delete the initial edition of a branch or the last indexed edition of a branch,
indexing of further assets on the branch cannot be done. You may obtain the last
indexed edition of a branch by using one of the Index Manager CLTs that provides the
detailed branch status.

If you delete the last edition of a branch before the index server has started indexing it,
you need to create a new edition; doing so ensures that the indexing of assets on the
branch work when the index server starts indexing it.

Using the CustomDate Extended Attribute


When attempting to search on the CustomDate extended attribute, a document may not
be found. This problem occurs when the date format specified in FieldMapping.xml is
not consistent with the format in which the EA is stored in TeamSite. The
fieldSpecification element in FieldMapping.xml may contain an optional
formatString element that can specify the date format. If this specified format is
consistent with the way the EA is stored in TeamSite, the indexing and searching should
work fine. If no formatString element is specified in the fieldSpecification element
in FieldMapping.xml, then the default format of dd-MMM-yyyy hh:mm a is used.

Interwoven, Inc. 166


Chapter 7: Configuring Interwoven Search

Deleted Branches
If a TeamSite branch was deleted without issuing the iwndxpurgebr CLT or the
iwndxrmbr CLT on that branch (see page 139), perform the following steps to clean the
state of the index server and search server for that branch:
1. Issue the iwndxstatus -a CLT to list information about all the branches the index
server knows about, including the deleted branch. From this list find the vpath of the
deleted branch exactly as it appears.
2. To purge the collection for the deleted branch from disk, issue the iwndxpurgebr
CLT and provide the branch vpath exactly as it appeared in the iwndxstatus output.
Alternately, issue the iwndxrmbr CLT and provide the branch vpath exactly as it
appeared in the iwndxstatus output.
These CLTs may issue an error message indicating that the specified branch does
not exist in TeamSite, but they will clean the state of the index server.

Changes to Content Store IDs


If a store ID changes because a Content Store is deactivated and activated (using the
iwstoreadm CLT), the search indexes for all branches in that store need to be purged.
Then the branch indexes should be rebuilt.

Bringing Down Servers


If the index manager and search manager are restarted or brought down, you need to
keep them synchronized. If the index manager is brought down or restarted, restart the
search manager after restarting the index manager. If the search manager is brought
down or restarted, it is not necessary to restart the index manager.

To manually stop the index manager and search manager:


1. Log in to Windows with Administrator permissions.
2. Select Start > Settings > Control Panel.
3. Double-click Administrative Tools.
4. Double-click Component Services.
5. In the Component Services Control Panel, select Search Manager from the list of
services, and click Stop. Then select Index Manager from the list of services, and
click Stop.

TeamSite Administration Guide 167


Chapter 7: Configuring Interwoven Search

Running on Different Hosts


If the index manager and search manager are running on different hosts, they may not be
able to access the other’s resources. To work around this:
1. Always run search manager and index manager under the same account.
2. If the search manager is on a different host than TeamSite, the account must belong
to the TeamSite domain group and must also be a privileged user on the search host.
3. Change the iw.search.agent.idxdir parameter in the search.properties file to
use the UNC path (for example, \\newlywed\Search\Index).
4. The index directory must be shared with full permissions given to the same account.

Configuration Issues
„ A incorrect entry in the FieldMapping.xml file may result in the index server not
coming up. Typically, an appropriate error message displays in the log. However,
sometimes based on the type of incorrect entry specified in the FieldMapping.xml
file, the index server may not come up and an appropriate error message may not be
entered in the log. In these cases, please double check your FieldMapping.xml file
for syntactic and semantic correctness.

Using CLTs
„ When configuring and administrating Search, do not run any Search administration
CLTs while the index server is starting up, until the event subsystem is available. If
you see an error message similar to: ERROR - DFsyEOFException: Unexpected end
of stream, wait several minutes and then run the CLT again.

„ The iwndxpurgebr CLT results in a 10002 error because indexed collection writers
(indexer, workarea indexer, purge branch) need to coordinate access to avoid
collection corruption. In this purge command, the index manager tries to remove the
collection directory. It could not remove everything because the collection is opened
in the search agent. Since it removed some of the unlocked files, the collection was
corrupted.
‰ Use the iwndxrmbr CLT instead. This simply removes the branch from the index
manager but does not purge the collection. It is a safe operation.
‰ Before using the iwndxpurgebr CLT, stop the search server so all current
connections to the collection are closed. Make sure that the indexing for the
branch (including workarea indexing) is not active. The branch must be frozen
first and indexer should be allowed time to finish the current jobs for this
branch. One can look into indexer logs for any active indexing jobs being
carried out for that branch.

Interwoven, Inc. 168


Chapter 7: Configuring Interwoven Search

Error Messages
This section provides index manager and server manager error codes and messages.

Table 11 Index Manager Error Messages


Error Number Error Message
10000 The relevant branch br-vpath does not exist.
10001 The relevant branch br-vpath has not been indexed.
10002 The collection for branch br-vpath could not be purged
10003 Incorrect parameters were supplied to the command.
10004 Unknown command [command-name].
10005 The branch br-vpath cannot be refreshed because it is frozen.
10006 The branch br-vpath either does not exist or has not been indexed.
10007 Indexing of workarea modifications has not been enabled.
-1 Unexpected error in the index server.

Table 12 Search Manager Error Messages


Error Number Error Message
20000 Generic query processing exception.
20001 Query is malformed.
20002 The query specified with id=query-id does not exist in the system.
20003 The query cannot be issued because the relevant branches were
unindexed.
20004 A very high load on the system prevents the query from being
processed.
20005 Incorrect parameters were supplied to the command.
20006 Unknown command [command-name].
20007 The search manager is unable to contact the index manager.
20008 The branch br-vpath does not exist.
20009 One or more of the areas specified in area-list do not exist.
20010 The user userid does not exist in the system.
20011 The number of query results returned on each page is specified
incorrectly.
20012 The index of the first query result to be returned cannot be less than
zero.
-1 Unexpected error in the search server.

TeamSite Administration Guide 169


Chapter 7: Configuring Interwoven Search

Interwoven, Inc. 170


Chapter 8

Configuring Metadata Capture

TeamSite metadata capture enables TeamSite users to add metadata information to files.
Metadata is a structured way to describe data in your files allowing you to organize and
manage it.

The ContentCenter Standard and ContentCenter Professional interfaces include a


default data capture form known as the Tagger GUI.

This chapter provides information on the following topics:


„ Introducing the Tagger GUI
„ Metadata Capture Overview
„ Configuring Metadata Capture
„ Modifying the Tagger GUI
„ Metadata Capture and TeamSite Workflow

Introducing the Tagger GUI


TeamSite uses the following default ContentCenter form, known as the Tagger GUI.
This form, with two tabs, enables your TeamSite end-users (using either ContentCenter
Standard or ContentCenter Professional) to add metadata information to the content files
they create or edit.

TeamSite Administration Guide 171


Chapter 8: Configuring Metadata Capture

Figure 31 Tagger GUI screens

End users can access a field description by clicking on the question mark next to the
field name.

In addition to the convenience of having a default metadata capture form, the form is
easy to modify to reflect the categorization of metadata in your organization.

Metadata Capture Overview


Metadata capture is a file-specific feature. That is, you must explicitly select the files on
which you intend to set metadata. You cannot globally set metadata for an entire area or
branch. For example, to set metadata on all files in a workarea, you must select each file
in that workarea (by clicking Select All or by clicking the check box next to each file)
and then initiate a metadata capture session. The form that displays for multiple files is
different than the one for a single file. See the online help for more information.

Interwoven, Inc. 172


Chapter 8: Configuring Metadata Capture

Metadata capture can be initiated in the following ways:


„ From the Tag menu item in ContentCenter.
„ Submitting a file that is part of a Solutions workflow (as described in the TeamSite
Workflow Developer’s Guide).
„ Clicking the Tag link any time you view a file’s properties or differences. These
links might be deactivated (grayed out) depending on access controls including user
role and file ownership.
„ Clicking More > Tag in the VisualPreview screen.
„ Importing a file into TeamSite.
„ Through a job as part of a <cgitask> element (as described in “Initiating Metadata
Capture from a Job Specification File” on page 192).

Metadata Capture Components


Regardless of how metadata capture is initiated, it uses the following components:
„ datacapture.cfg. Configuration file that defines rule sets for capturing data. By
default, it is located in the iw-home\local\config directory.
„ metadata-rules.cfg. Configuration file that maps vpaths to the data capture rules
defined in datacapture.cfg. By default, it is located in the iw-home\local\config
directory.
„ iwmetadata.cgi. Metadata capture CGI that interprets data from end-users and
rules in datacapture.cfg and metadata-rules.cfg, produces browser graphics
and prompts, and acts as an interface with workflow configuration files (if metadata
capture is running as part of a job).
„ Tagger GUI. Browser-based form for end-user input.
„ Metadata capture subsystem (part of the TeamSite Content Server) processes the
data entered in the Tagger GUI and stores it in the TeamSite Content Store as
extended attributes.

The two configuration files (metadata-rules.cfg and datacapture.cfg) enable you to


configure the following on a per-user or per-vpath basis:
„ The metadata item name that displays in the metadata entry form.
„ The interface element through which the end-user enters input (for example, a check
box or a data field).
„ The type of data that is acceptable or unacceptable in any given field.
„ Whether input is required for any given field.

TeamSite Administration Guide 173


Chapter 8: Configuring Metadata Capture

The following diagram shows how these components work together. Sections following
the diagram explain each diagram step and component in detail.

Figure 32 Metadata Capture components

metadata-rules.cfg datacapture.cfg

References Defines rule sets for


capturing data
datacapture.cfg
Maps vpaths to rule sets
(Server Side) (Server Side)

2 2
5 5

iwmetadata.cgi Job Specification


Browser 1
(1) File
„ Reads configuration
Displays Tagger files
Can run metadata
GUI metadata 3 „ Generates forms capture using
entry form
„ Checks validity of <cgitask>
end-user data via rule element
sets
(Client Side)
4 „ Follows rules to add (7) (Server Side)
metadata to specific
files

iw-store

Files saved with new


metadata

Diagram Key
1. The metadata CGI receives a list containing the names of the files that can have
metadata added to them. The list can come from an instantiated job (if metadata
capture is initiated from a job) or from the browser (if initiated from a TeamSite user
interface).
2. The metadata CGI reads both configuration files (metadata-rules.cfg and
datacapture.cfg) to determine what information it should display in the Tagger
GUI. It makes this determination on a per-file basis, so that the entry form can con-
tain different prompts and actions for different files.
3. The metadata CGI displays the Tagger GUI on the client system.
4. An end-user enters and submits the data using the metadata entry form and the meta-
data CGI.

Interwoven, Inc. 174


Chapter 8: Configuring Metadata Capture

5. The metadata CGI consults the rules in both configuration files to verify the validity
of the data entered by the user. If the data does not meet all necessary criteria, noti-
fication is sent to the user so that data can be re-entered.
6. If the data meets all necessary criteria, the metadata CGI adds the new metadata (in
the form of TeamSite extended attributes) to the specified files. The metadata CGI
interfaces directly with the Content Store to update the files with the new metadata.
7. If metadata capture was initiated from a job, the metadata CGI notifies the workflow
subsystem, which starts successor task 0 (zero) as defined in the job specification
file.

Metadata Capture and Extended Attributes


When end-users set metadata on files (that is, tag them), the metadata is added to files as
TeamSite extended attributes and stored in the TeamSite Content Store. The metadata
can be viewed in the following ways:
„ By displaying the Tagger GUI for a file by clicking:
‰ File > Tag in the file browser screen for any file managed in TeamSite.
‰ The Tag link when viewing a file’s properties or differences.
‰ More > Tag in the VisualPreview screen.
The metadata that has already been set for a file prepopulates the fields in the
Tagger GUI.
„ Using the iwextattr CLT as described in the TeamSite Command-Line Tools
manual. You can use this CLT to get a specific value, or all a list of all the attributes
for the file.

You can deploy these extended attributes to a database using Interwoven DataDeploy.
The deployment can be manual, or automatic using Database Auto-Synchronization
(DAS). See the Database Deployment for OpenDeploy Administration Guide for more
information.

Configuring Metadata Capture


You must perform two main activities to configure metadata capture:
„ Create a metadata-rules.cfg file in iw-home\local\config for your site.
„ Create a datacapture.cfg file in iw-home\local\config for your site.

The following sections describe these steps in detail.

TeamSite Administration Guide 175


Chapter 8: Configuring Metadata Capture

The metadata-rules.cfg File


The metadata-rules.cfg file maps vpaths to data capture rules that are defined in
datacapture.cfg. The metadata-rules.cfg file consists of a series of <cond>
(conditional) elements. A <cond> element can contain <rule> elements and other
<cond> elements. Each vpath is run through metadata-rules.cfg, resulting in a
one-to-many mapping from vpaths to named rules. Whenever a list of <cond> elements
is found, the first to match the current vpath takes effect, and the rest of the elements in
the list are discarded.

The TeamSite installation program installs the metadata-rules.cfg in the


iw-home\local\config\ directory. The metadata-rules.cfg file uses the following
DTD:
<!ELEMENT metadata-rules (cond)*>
<!ELEMENT cond (cond|rule)*>
<!ATTLIST cond
vpath-regex CDATA #REQUIRED
>
<!ELEMENT rule EMPTY>
<!ATTLIST rule
name CDATA #REQUIRED
>

The contents of the metadata-rules.cfg file are as follows:


<?xml version="1.0" encoding="UTF-8" ?> International Encoding

<metadata-rules>
<cond vpath-regex="."> Vpath Identifier
<rule name="Default Rule" /> Rule Identifier
</cond>

Notes:
„ International Encoding—UTF-8 is an encoding of Unicode, a standard for encoding
the character sets of international languages. All of your content should specify their
encoding as UTF-8. For details about encoding, see Appendix G,
“Internationalization.”
„ Vpath Identifier—Names the vpath (in this case, all directories) to which the rules
named in the following subelements are applied.
„ Rule Identifier—Names the rule that applies to the preceding vpath. The rule itself
is defined in the <ruleset> element in iw-home\local\config\datacapture.cfg.
In this example, the Default Rule rule defined in datacapture.cfg always applies
to all directories.

The following metadata-rules.cfg file illustrates a more sophisticated example:

Interwoven, Inc. 176


Chapter 8: Configuring Metadata Capture

<metadata-rules>
<cond vpath-regex="^/default/main/syndication"> Vpath Identifier 1

<rule name="Default" /> Rule Identifiers 2

<rule name="Syndication" />


<cond vpath-regex="\.pdf$"> Vpath Identifier 3

<rule name="PDF Files" /> Rule Identifier 4

</cond>
<cond vpath-regex="\.doc$"> Vpath Identifier 5

<rule name="MS Word Files" /> Rule Identifier 6

</cond>
</cond>

<cond vpath-regex="^/default/main/www"> Vpath Identifier 7

<rule name="Default" /> Rule Identifiers 8

<rule name="Web Content" />


<cond vpath-regex="\.html$"> Vpath Identifier 9

<rule name="HTML Files" /> Rule Identifier 10

<cond vpath-regex="/pr/"> Vpath Identifier 11

<rule name="PR" /> Rule Identifier 12

</cond>
<cond vpath-regex="/corp/"> Vpath Identifier 13

<rule name="Corporate" /> Rule Identifier 14

</cond>
</cond>
</cond>
</metadata-rules>

Notes:
„ Vpath Identifier . Files on the\syndication branch always receive the rules named
1

in the following subelements.


„ Rule Identifier . The Default and Syndication rules defined in datacapture.cfg
2

always apply to the \main\syndication branch.


„ Vpath Identifier . Files ending in .pdf on the \main\syndication branch receive
3

rules in addition to those defined by Default and Syndication.


„ Rule Identifier . The PDF Files rule defined in datacapture.cfg applies to files
4

ending in .pdf on the \main\syndication branch.


„ Vpath Identifier . Files ending in .doc on the \main\syndication branch receive
5

rules in addition to those defined by Default and Syndication.


„ Rule Identifier . The MS Word Files rule defined in datacapture.cfg applies to
6

files ending in .doc on the \main\syndication branch.


„ Vpath Identifier . The \main\www branch always receives the rules named in the
7

following subelements.
„ Rule Identifier . The Default and Web Content rules defined in datacapture.cfg
8

apply to the \main\www branch.

TeamSite Administration Guide 177


Chapter 8: Configuring Metadata Capture

„ Vpath Identifier . Files ending in .html on the \main\www branch receive rules in
9

addition to those defined by Default and Web Content.


„ Rule Identifies . The HTML Files rule defined in datacapture.cfg apply to files
10

ending in .html on the \main\www branch.


„ Vpath Identifier . Files ending in .html in the pr directory on the \main\www branch
11

receive rules in addition to those defined by Default and Web Content.


„ Rule Identifies . The PR rule defined in datacapture.cfg applies to files ending in
12

.html in the pr directory on the \main\www branch.

„ Vpath Identifier . Files ending in .html in the corp directory on the \main\www
13

branch receive rules in addition to those defined by Default and Web Content.
„ Rule Identifiers . The Corporate rule defined in datacapture.cfg applies to files
14

ending in .html in the corp directory on the \main\www branch.

Creating the datacapture.cfg File


The datacapture.cfg file defines rule sets for capturing data. Rules are referred to by
name in metadata-rules.cfg (see “The metadata-rules.cfg File” on page 176).

Rules contain items, where each item is a single set of data that is to be captured from
the end-user. An item consists of one or more instances. Each instance encapsulates how
to capture the data for the item, and each instance defines an ACL that determines which
(if any) instance a particular user is allowed to use to enter the data.

The metadata capture form is a data capture template (DCT) that is configured
specifically for metadata capture. The data capture subsystem that generates the
metadata capture form is similar to the subsystem that generates data capture templates
for FormsPublisher. A major difference between the two implementations is the location
of the datacapture.cfg file. FormsPublisher relies on multiple datacapture.cfg files
(one for each data type), while metadata capture relies on a single datacapture.cfg file
(in iw-home\local\config).

See “Setting Up Data Capture Templates” in the TeamSite FormsPublisher Developer’s


Guide for a complete explanation of datacapture.cfg files, including annotated
examples and explanations of elements and attributes. Even though the examples in the
TeamSite FormsPublisher Developer’s Guide are specific to FormsPublisher and not all
FormsPublisher data capture functionality is supported for metadata capture forms, they
are a useful reference for configuring datacapture.cfg for metadata capture.

The TeamSite installation program installs a sample file called


datacapture.cfg.example in the iw-home\local\config\ directory.You can copy,
rename, and edit the example file to create your actual datacapture.cfg file. Use the
following DTD and annotated examples as a reference to create your own site-specific
configuration.

Interwoven, Inc. 178


Chapter 8: Configuring Metadata Capture

The datacapture.cfg file uses the following DTD (it is also installed by the TeamSite
installation program in iw-home\local\config\). The datacapture.cfg files must
have been created using metadatacapture6.0.dtd.
<!-- metadatacapture6.0.dtd Version 1.1 2/12/04 -->
<!-- Start with some basic parameter entities. -->
<!ENTITY % data-capture-requirements-contentspec "(ruleset+)*">
<!ENTITY % items "container|view-container|view|item">
<!ENTITY % chooser-options "option|inline">
<!ELEMENT data-capture-requirements
(%data-capture-requirements-contentspec;)>
<!ATTLIST data-capture-requirements
name CDATA #IMPLIED
type (metadata) #REQUIRED
dtd-system-identifier CDATA #IMPLIED
>
<!-- The ’dtd-system-identifier’ attribute is a URI indicating the
DTD from whence a particular data-capture-requirements was
derived, if any.
-->

<!ELEMENT ruleset (label?, description?, (%items;)*)>


<!ATTLIST ruleset
name CDATA #REQUIRED
>

<!ELEMENT container (label?, description?, (%items;)*)>


<!ATTLIST container
name CDATA #REQUIRED
>

<!ELEMENT item (label?, description?, database?, (checkbox | radio | text


| textarea | select | replicant | browser | readonly | hidden)+)>
<!ATTLIST item
name CDATA #REQUIRED
>

<!ELEMENT label (#PCDATA)>

<!ELEMENT description (#PCDATA)>

<!ELEMENT text (allowed?,cgi-callout?,default?) >


<!ATTLIST text
required (t | f) "f"
maxlength CDATA "0"
size CDATA "0"
validation-regex CDATA #IMPLIED
>
<!-- validation-regex is a regex for validating this element -->

TeamSite Administration Guide 179


Chapter 8: Configuring Metadata Capture

<!ELEMENT textarea (allowed?,cgi-callout?,default?) >


<!ATTLIST textarea
required (t | f) "f"
rows CDATA "0"
cols CDATA "0"
wrap (off | virtual | physical) "off"
validation-regex CDATA #IMPLIED
>
<!-- validation-regex is a regex for validating this element -->
<!ELEMENT browser (allowed?,cgi-callout?)>
<!ATTLIST browser
required (t | f) "f"
initial-dir CDATA #IMPLIED
extns CDATA #IMPLIED
>
<!ELEMENT readonly (allowed?,cgi-callout?)>

<!ELEMENT hidden (allowed?,cgi-callout?)>


<!ATTLIST hidden
required (t | f) "f"
>

<!ELEMENT checkbox (allowed?, cgi-callout?, (%chooser-options;)+)>


<!ATTLIST checkbox
required (t | f) "f"
>

<!ELEMENT radio (allowed?, cgi-callout?, (%chooser-options;)+)>


<!ATTLIST radio
required (t | f) "f"
>

<!ELEMENT select (allowed?, cgi-callout?, (%chooser-options;)+)>


<!ATTLIST select
required (t | f) "f"
size CDATA "0"
multiple (t | f) "f"
>

<!ELEMENT option EMPTY>


<!ATTLIST option
selected (t | f) "f"
value CDATA #IMPLIED
label CDATA #REQUIRED
>

<!ELEMENT replicant (allowed?, (%items;)*)>


<!ATTLIST replicant
min CDATA "0"
max CDATA "1"

Interwoven, Inc. 180


Chapter 8: Configuring Metadata Capture

default CDATA "1"


>

<!ELEMENT allowed (cred | and | or | not)>

<!ELEMENT cred EMPTY>


<!ATTLIST cred
role CDATA #IMPLIED
user CDATA #IMPLIED
>

<!ELEMENT and ((cred | and | or | not)+)>


<!ELEMENT or ((cred | and | or | not)+)>
<!ELEMENT not (cred | and | or | not)>

<!ELEMENT default (#PCDATA)>

<!--The form of this element is exactly the same as that for the callout
element in datacapture.4.0.dtd. -->
<!ELEMENT cgi-callout EMPTY>
<!ATTLIST cgi-callout
label CDATA #REQUIRED
url CDATA #REQUIRED
window-features CDATA #IMPLIED
>

<!ELEMENT database EMPTY>


<!ATTLIST database
deploy-column (t | f) "t"
searchable (t | f) "t"
data-type CDATA "VARCHAR(255)"
data-format CDATA #IMPLIED
>
<!-- An ’inline’ element should have a ’command’ attribute. e.g.:
<inline command="/bin/cat /tmp/a /tmp/b"/>

The callout program should return a well-formed XML document.


The document’s outermost element should be a "substitution"
element. It should contain any XML that is valid according
to this DTD.

That "substitution" element’s contents will replace the


"inline" element in the datacapture.cfg file.

So, if this DCT snippet:

<select>
<inline command="command name" />
</select>

TeamSite Administration Guide 181


Chapter 8: Configuring Metadata Capture

runs the "blah" callout program, and that program returns this text:

<substitution>
<option label="ABC" />
<option label="123" />
<option label="Jackson 5" />
</substitution>

then the DCT snippet will, after callout execution and inline
substitution, look like:

<select>
<option label="ABC" />
<option label="123" />
<option label="Jackson 5" />
</select>
-->
<!ELEMENT inline EMPTY>
<!ATTLIST inline
command CDATA #REQUIRED
>

The contents of the datacapture.cfg.example are as follows; the section immediately


following the file explains the callouts.

Interwoven, Inc. 182


Chapter 8: Configuring Metadata Capture

International Encoding
<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE data-capture-requirements SYSTEM "metadatacapture6.0.dtd">

<!-- A <data-capture-requirements> element with type="metadata"


can contain multiple <ruleset> elements.

Rules contain "items"; one item is a single (set of) data that is
to be captured from the end user. An item consists of one or more
"instances". Each instance encapsulates how to capture the data
for the item, and each instance defines an ACL that determines which
(if any) instance a particular user is allowed to use to enter the
data. Instances are text, textarea, radio, checkbox, select, and
replicant.

Replicants are very special kinds of instances; they are repeatable.


Replicants contain _items_ instead of just an ACL like the other
types of instances.

Note: The <database> elements have no effect on the metadata


capture process. These optional elements are used to help integrate
metadata capture with Data Deploy. Data Deploy configuration
files can be automatically generated from datacapture.cfg files.
The <database> tags ensure the database tables are built using
the appropriate datatype.
-->

<data-capture-requirements type="metadata"> Metadata Identifier


<ruleset name="Default Rule"> Rule Identifier
<description>
This rule applies to all files on all branches.
</description>

<view-container name="Asset metadata"> View-container Element

<view name="Description"> View Element


<description>
Metadata that describes the topic of the asset.
</description>
<item name="Title">
<database data-type="VARCHAR(100)" /> Database Element
<text required="f" size="32" maxlength="60" />
</item> Instance (text)

TeamSite Administration Guide 183


Chapter 8: Configuring Metadata Capture

<item name="Keywords">
<description>
Keywords can include terms that are not in the asset itself.
</description>
<database data-type="VARCHAR(100)" />
<text required="f" size="32" maxlength="60" />
</item>

<item name="Description">
<description> Description Elemen
A brief summary of 250 characters or less.
</description>
<database data-type="VARCHAR(100)" />
<textarea required="f" rows="5" cols="72" wrap="virtual"
maxlength="250" />
</item>
</view>

<view name="Details"> View Element


<description>
Metadata that records attributes of the asset.
</description>
<item name="Business Unit">
<description>
Unit that is responsible for the asset.
</description>
<database data-type="VARCHAR(100)" />
<select>
<option label="Administration" value="Admin" />
<option label="Facilities" value="Facilities" />
<option label="Finance" value="Finance" />
<option label="Human Resources" value="HR" />
<option label="Legal" value="Marketing" />
<option label="Marketing" value="Legal" />
<option label="Sales" value="Sales" />
<option label="Systems" value="Systems" />
</select>
</item>

Interwoven, Inc. 184


Chapter 8: Configuring Metadata Capture

<item name="Creation Date">


<description>
The date the asset was created, in the YYYY-MM-DD format.
</description>
<database data-type="DATE" data-format="yyyy-MM-dd" />
<text required="f" maxlength="10" size="32"
validation-regex=
"^[0-9][0-9][0-9][0-9]-[0-1][0-9]-[0-3][0-9]$">
</text>
</item>

<item name="Expiration Date">


<description>
The date the asset should be retired, in the YYYY-MM-DD
format. DATE element
</description>
<database data-type="DATE" data-format="yyyy-MM-dd" />
<text required="f" maxlength="10" size="32"
validation-regex=
"^[0-9][0-9][0-9][0-9]-[0-1][0-9]-[0-3][0-9]$">
</text> validation-regex
</item>
</view>
</view-container>
</ruleset>
</data-capture-requirements>

Notes:
„ International Encoding—UTF-8 is an encoding of Unicode, a standard for encoding
the character sets of international languages. All web assets should specify their
encoding as UTF-8. For details about encoding, see Appendix G,
“Internationalization.”
„ Metadata Identifier. When configuring datacapture.cfg for metadata capture, you
must specify "type=metadata" in the <data-capture-requirements> element as
shown here.
„ Rule Identifier. The <ruleset> element contains all of the items that make up the
rule set defining the appearance and behavior of the data capture form. A
datacapture.cfg file that is configured for metadata capture can contain any
number of <ruleset> elements (as opposed to FormsPublisher datacapture.cfg
files, which can contain just one <ruleset> element). This example file happens to
contain just one <ruleset> element; it could contain more if necessary. The rule
defined here is named Default Rule and is referenced by the metadata-rules.cfg
file shown on page 176. The name attribute is required and its value appears in the
TeamSite user interfaces as the name of the data capture form. Optional subelements

TeamSite Administration Guide 185


Chapter 8: Configuring Metadata Capture

include <label>, <description>, <item>, and <itemref>. The <label> subelement


is used to provide a label on the data capture form. The <itemref> subelement
requires the name attribute and is used as a stand-in for the <item> subelement in a
<symbol-table> element.

„ View-container Element. The <view-container> element specifies that the form


has multiple screens that are accessed by selecting the tabs at the top of the form.
„ View Element. The <view> element encloses the fields that are on each screen of the
form. It also provides the text on the tabs. In this form, there are two screens: the
first is named Description and contains the Title, Keyword, and Description fields,
and the second is named Details and contains the Business Unit, Creation Date, and
Expiration Date fields.
„ database Element. The optional <database> element facilitates the use of the
appropriate data type in DataDeploy and is used only for generation of the
mdc_dd.cfg file. It does not control any aspects of the metadata capture form. The
<data-type> and <searchable> information in the <database> element are passed
on to mdc_dd.cfg, which in turn uses that information to control how metadata is
deployed to a database by DAS. The <database> element has four attributes.
Because attribute order in XML documents is important; these attributes should
occur in the following order:
‰ deploy-column can be either "t" (true, the default) or "f" (false) and
determines whether or not data entered for the item is deployed to a database
column.
‰ searchable can be either "t" (default) or "f" and determines whether or not
users can search against this item.
‰ data-type is required and is any JDBC database type. If you do not set the
data-type attribute, a default datatype of VARCHAR (255) is set in mdc_dd.cfg.
‰ data-format describes the format if date or time is specified for the data-type
attribute (see the DATE datatype description that follows). If a value for
data-format is specified, the instance should contain a validation regex to force
a valid entry in the field (see the validation-regex description that follows).
In this example, deploy-column would be the first attribute if it were set. Seeing as
it is not, all input for this item is deployed to a database column. Next, the
searchable attribute is specified as "t"; however, because this is the default
value for the attribute, searchable does not need to be included. Following
searchable is data-type, here specifying the input to be stored as a string. If date
or time is set as the value for the data-type, a data-format attribute should end the
element.
„ Instance (text). The optional <text> element controls the length of text entry fields
in metadata capture and search forms. It also controls whether an end-user is
required to enter text in a field. If the datatype is date or time and a format has been
specified, it is best to include a validation-regex to force users to input data in the
correct format (see the validation-regex description that follows). In this example
the user is required enter a string between one and 60 characters in the text field.
The data entered for this item is stored in the database as VARCHAR and is searchable.

Interwoven, Inc. 186


Chapter 8: Configuring Metadata Capture

„ Description. The <description> element is used to provide the information that


displays when a user clicks on the question mark next to a field on a form.
„ DATE datatype. If the datatype is set to date or time, you should specify a
data-format and include a validation. Because there are many formats for date and
time, specifying a format forces the user to enter data in that format and reduces the
chance of user error. The value for data-format can be any valid Java format for a
date or time.
„ validation-regex. The user can be forced to enter a date or time in the format you
specify by including a validation regex. The value for the validation-regex
attribute must match the format specified in for data-format. The regex in this
example specifies the range of digits that can be entered for yyyy-mm-dd and that
dashes must separate year, month and day. The following table shows validation
regex examples for several supported datatypes.
The <database> and <text> elements shown in the table are subelements of the
<item> element. Some regex lines are wrapped due to page constraints. You should
enter them all on one line in your configuration file.

Table 13 Datatypes
Datatype Description and Example
DATE If data-type is DATE, the data-format must be a format string that is
valid for the Java simple date format class. Formats do not have to be
year-month-day, any valid format will work.
<database data-type="DATE" data- format="yyyy-mm-dd" />
<text maxlength="10"
validation-regex="^[0-9][0-9][0-9][0-9]-[0-1] [0-9]-[0-3]
[0-9]$" />
INT Allows any integer up to 7 digits. This example assumes that you want
to store data as integers, not dollars and cents.
<database data-type="INT" />
<text maxlength="7"
validation-regex="^[0-9]\{0,\}$" />
REAL Allows any decimal up to 8 digits (including decimal). The regex
allows 0 or more digits, followed by a decimal point, followed by zero
or more digits.
<database data-type="REAL" />
<text required="t" maxlength="8"
validation-regex="^[0-9]\{0,\}\.[0-9]\{0,\}$" />

If users encounter an error with the Tagger GUI, an error message tells them to contact
their system administrator. The system administrator should check the servletd log file
for more information on the configuration problem.

TeamSite Administration Guide 187


Chapter 8: Configuring Metadata Capture

Troubleshooting
The following issues with metadata capture have resulted in the changes to the metadata
capture feature:
„ Standard name-value pairs from a datacapture.cfg file for metadata capture are
not posted to the resulting callout CGI.
„ Callouts from MetaTagger CGI do not support showing file names.
„ The area_path variable does not show the full path with the file name.

The path of a file being tagged is passed as form data in MetaTagger callouts.
Previously, this information was passed as path_indexnumber.

In the MetaTagger UI for single files, the path_0 value is posted with the file system
path to the file being tagged. For example, the form data would contain something
similar to:
y:/default/main/br1/WORKAREA/wa1/file.txt now

In the MetaTagger UI for multiple files, path_0, path_1, path_2... path_n values are
posted to provide all the files that are being tagged. A new form variable called
iw_callback_path contains the path_X string indicating which file a callout
corresponds to. For example:
Form data
---------
Callout prop30247927
Callout prop1682317
Callout prop6972548
iw_callback_path path_0 <====== this tells you that it's for the file
"atestfile.txt"
path_0 Y:/default/main/StressTestA/WORKAREA/test_wa1/atestfile.txt
path_1 Y:/default/main/StressTestA/WORKAREA/test_wa1/atag.txt
path_2 Y:/default/main/StressTestA/WORKAREA/test_wa1/11223344.txt
prop1682317 callout for path_0
prop30247927 callout for path_1
prop6972548 callout for path_2

Field access and validation is now done from the cgi called by the callout. However, the
field names have changed from being the actual field name (such as Title and Author)
to propXXXXXXXX. This format supports multi-file tagging where the UI layout shows
only one specific field corresponding to all the files. With this format, you see all the
Title fields for file 1, 2, 3, etc. on one page. You do not see any of the other fields in
conjunction.

Interwoven, Inc. 188


Chapter 8: Configuring Metadata Capture

In the MetaTagger UI for a single file, to determine what propXXXXXXXX means in terms
of actual field names, a mapping from the actual field name to the propXXXXXXXX names
is now posted. For example:
Form data
---------
Callout prop33462681
Description prop32955489
Keywords prop4078723
Title prop24746526
path_0 Y:/default/main/StressTestA/WORKAREA/test_wa1/atag.txt
prop24746526 search project
prop32955489 project for search
prop33462681
prop4078723 search verity

Here you can see that if you need to access the value of the Title field, you have one
extra step to get to the value:
Title > prop24746526 >search project

In the MetaTagger UI for a multiple files, callouts were not designed for this case so
their usefulness is somewhat limited. For example, the form data would appear as
follows:
Form data
---------
Callout prop30247927
Callout prop1682317
Callout prop6972548
iw_callback_path path_0
path_0 Y:/default/main/StressTestA/WORKAREA/test_wa1/atestfile.txt
path_1 Y:/default/main/StressTestA/WORKAREA/test_wa1/atag.txt
path_2 Y:/default/main/StressTestA/WORKAREA/test_wa1/11223344.txt
prop1682317 callout for path_0
prop30247927 callout for path_1
prop6972548 callout for path_2

The mapping from actual field name to the propXXXXXXXX field names is again present,
but it is only for one field per page. In this case it is for the Callout fields corresponding
to all the files being tagged. The array of Callout values is ordered the same as the file
indices, hence it is easy to determine which Callout field goes with which file. It is not
recommended that callouts be used in the multi-file case for traditional cross field
validation as it cannot be done. To mimic cross-field validation in this scenario, run an
external script to access the file determined by the iw_callback_path variable and read
the extended attributes outside of the MetaTagger UI context.

TeamSite Administration Guide 189


Chapter 8: Configuring Metadata Capture

Modifying the Tagger GUI


You may wish to use the data capture form provided with the TeamSite installation but
you need other fields or additional fields for the Business Unit drop-down list. Open the
datacapture.cfg file and find the section identifying the Business Unit item. The name
shown in quotation marks following label= is the name that displays in the Business
Unit list. The name shown following value= is the value stored in the TeamSite Content
Store as an extended attribute. Simply change these values or add additional <option>
elements to modify this section of the form.
<item name=Business Unit">
<description>Unit that is responsible for the asset.</description>
<database data-type="VARCHAR(100)" />
<select>
<option label="Administration" value="Admin" />
<option label="Facilities" value="Facilities" />
<option label="Finance" value="Finance" />
<option label="Human Resources" value="HR" />
<option label="Legal" value="Marketing" />
<option label="Marketing" value="Legal" />
<option label="Sales" value="Sales" />
<option label="Systems" value="Systems" />
</select>
</item>

You could also modify the item names or view names to modify these forms for your
use.

For more extensive form design, refer to the TeamSite FormsPublisher Developer’s
Guide for guidance.

Localizing the Tagger GUI


To display a localized version of the Tagger GUI (when applicable), perform the
following steps:
1. In the iw-home\local\config directory, locate the following Tagger GUI
configuration files for localization:
‰ datacapture.cfg.example.de (German)
‰ datacapture.cfg.example.fr (French)
‰ datacapture.cfg.example.ja (Japanese)
‰ datacapture.cfg.example.ko (Korean)
‰ datacapture.cfg.example.zh (Simplified Chinese)
2. Depending on the localized system, rename the appropriate file to
datacapture.cfg.

The localized version of the Tagger GUI will be enabled.

Interwoven, Inc. 190


Chapter 8: Configuring Metadata Capture

Using the datacapture.cfg.example2 File


The TeamSite Installation program also installs another example data capture file that
can be used if it better fits the needs of your organization. The file is called
datacapture.cfg.example2 and is installed in the iw-home\local\config directory.
The data capture form generated by this file is as follows:

Figure 33 Alternate Tagger GUI form

To replace the default datacapture.cfg file with the datacapture.cfg.example2,


complete the following procedure:

1. Go to the iw-home\local\config directory.


2. Rename (or move) the datacapture.cfg file, for example rename it
original_datacapture.cfg. Even if you choose to move the file, it is a good idea
to rename it to avoid possible confusion.
3. Rename the datacapture.cfg.example2 file to datacapture.cfg.

Metadata Capture and TeamSite Workflow


The following sections describe key interactions between metadata capture and
TeamSite workflow.

Specifying Files in Workflow Tasks


Metadata capture includes the ability to self-filter a list of files on which to capture
metadata. For example, a user task or a job task can name a set of files upon which
metadata will be set. All symlinks, directories, and deleted files that are part of the file
set will be filtered out and ignored. Only actual files will have metadata set.

TeamSite Administration Guide 191


Chapter 8: Configuring Metadata Capture

Initiating Metadata Capture from a Job Specification File


The following sample <cgitask> section from a job specification file shows the syntax
necessary to initiate a typical metadata capture process from within a job. The task
owner in this example is jk. The task in this example is associated with the area shown
in areavpath. See the TeamSite Workflow Developer’s Guide for information about the
<cgitask> DTD and other general information.
<cgitask name="metadata" owner="jk">
<description>apply metadata.</description>
<areavpath v="\default\main\test\WORKAREA\jk" immediate="+"/>
<successors>
successorset description="set">
<succ v="confirm" />
</successorset>
</successors>
<command v="iwmetadata.cgi" />
<activation>
<or>
<pred v="start" />
</or>
</activation>
</cgitask>

Interwoven, Inc. 192


Chapter 9

Configuring the TeamSite Web


Daemon and Proxy Server

The following sections describe the configuration settings for the TeamSite web daemon
and the TeamSite proxy server. They begin with an overview of each of these features,
and then are followed by sections on specific configuration settings.
„ About the TeamSite Web Daemon
„ About the Proxy Server
„ Configuring TeamSite Web Daemon and Proxy Server Operation
„ Resolving Fully Qualified URLs
„ Redirecting Fully Qualified URLs
„ Redirecting TeamSite Views to Different Areas
„ Configuring TeamSite to Use Different Web Servers
„ Configuring External Remappings
„ Host Header Remappings
„ Enabling iwproxy Access Control
„ Configuring SSI Remapping
„ Configuring Proxy Failover
„ Debugging Your Proxy Server Configuration

TeamSite Administration Guide 193


Chapter 9: Configuring the TeamSite Web Daemon and Proxy Server

About the TeamSite Web Daemon


TeamSite uses a web daemon, iwwebd.exe, to provide a single HTTP interface to the
TeamSite ContentCenter interfaces.

Figure 34 Browser access to iwwebd


optional
fire wall

Browser iwwebd

iwproxy servletd

Customer TeamSite
Web server File System

Remote contributors can use TeamSite securely without having to establish a Virtual
Private Network (VPN). The iwwebd web daemon also serves the non-servlet-based
parts of TeamSite ContentCenter. For an illustration of how requests are processed, see
Figure 4 on page 28.

About the Proxy Server


TeamSite uses a proxy server to perform the following functions:
„ Resolve relative and absolute URL names in TeamSite areas in order to present
users with a virtualized view of the Web site contained within an area (see
page 196).
„ Redirect fully qualified URLs into TeamSite areas (see page 200).
„ Redirect browsing in one branch or workarea into another area (see page 202).
„ Redirect individual workareas to use different Web servers (see page 204).
„ Remap links to external Web servers (see page 205).
„ Modify Host: headers (see page 206).
„ Remap SSI requests (see page 207).

Each time a request is made through the TeamSite proxy server, the following sections
of iw.cfg are processed as shown in the following graphic. More than one rule may be
applied to a request. When a rule matches a URL—depending on the section in which
the rule was specified—either an HTTP redirect is sent back to the browser to indicate

Interwoven, Inc. 194


Chapter 9: Configuring the TeamSite Web Daemon and Proxy Server

the new location or the URL is rewritten and passed to the new section. The first rule
that matches in any section prevails; no other rules in that section are applied.

Figure 35 Processing proxy requests through the iw.cfg file


See Configuring the Proxy Server
iwproxy_fullproxy_redirect to Redirect Fully Qualified URLs.
Applies only if the browser’s proxy
has been set to the TeamSite proxy
iwproxy_remap server.
See Document Roots.

iwproxy_external_remap See Configuring External


Remappings. Applies only if none
of the preceding rules has matched.
iwproxy_preconnect_redirect See Redirecting TeamSite Views to
iwproxy_preconnect_remap Different Areas.

See Host Header Remappings.


iwproxy_hostheader_remap

iwproxy_smartcontextedit_allowed See Enabling and Disabling


VisualPreview.

No
Can the rewritten path iwproxy_failover_remap
be found?
See Configuring Proxy Failover.
Yes Sends the rewritten path to be
reprocessed.

The specified page is returned.

Applying Changes to Proxy Configuration


If you change any of the iwproxy mappings in iw.cfg, you must use the iwreset -a
CLT to ensure that TeamSite recognizes the changes.

NOTE
iwreset -a does not apply changes to the [iwproxy_remap] or
[iwproxy_plugin_remap] sections of iw.cfg if you are using Web server plug-ins. If
you make changes to these sections and you are using Web server plug-ins, you must
restart the Apache Web server (not the Apache Tomcat, IBM WebSphere, or BEA
WebLogic web application server) to apply the changes.

TeamSite Administration Guide 195


Chapter 9: Configuring the TeamSite Web Daemon and Proxy Server

Configuring TeamSite Web Daemon and Proxy


Server Operation
The [iwproxy] section of iw.cfg is used to configure the operation of the TeamSite
proxy server. By default, your [iwproxy] section reads as follows:

[iwproxy]
customer_webserver_host=hostname or IP_address
iwproxy_host=proxy_hostname
iwproxy_port=1080
customer_webserver_port=81

where:
„ customer_webserver_host is the host name of the content Web server. The value
must be set to the host name of the Web server that serves the content of your Web
sites.
„ iwproxy_host specifies the host where the TeamSite proxy daemon runs. Usually
this is the TeamSite server.
„ iwproxy_port is the port on which the TeamSite proxy server operates. It should be
set to an open port value. This port need only be open to the TeamSite proxy server.
It may be blocked from end-user clients for added security.
„ customer_webserver_port is the port through which the TeamSite proxy server
communicates with the Web server. It must be set to the value of the port used by the
Web server.

The settings in the [iwproxy] section are set during the TeamSite installation. They can
be manually edited if necessary.

Resolving Relative and Absolute Paths


Relative paths specify file locations relative to the referencing file’s directory location.
Absolute paths specify file locations relative to the Web site’s document root directory.

For example, the file whose directory path (rooted in a TeamSite area) is
/main/index.html might contain a link to the file /images/banner.gif. This link can
be specified as either a relative or an absolute path as follows:
„ As a relative path:
../images/banner.gif

„ As an absolute path:
/images/banner.gif

Interwoven, Inc. 196


Chapter 9: Configuring the TeamSite Web Daemon and Proxy Server

NOTE
The proxy server does not allow you to remap the document root directory for Content
Store branches other than the default Content Store.

Links in HTML documents are often specified with relative or absolute path names. For
example, in a link to an image, the file name might appear as:

/images/miles.gif

On a typical Web server, this link reference would be mapped by the Web server to its
document root, for example:

/images/miles.gif D:\inetpub\wwwroot\images\miles.gif

All users that attempt to access the file using the absolute path name are mapped to the
same file location on the Web server.

However, TeamSite supports a system of private workareas, giving each user access to
the Web site’s files from within their own personal, virtual version of the Web site.
TeamSite uses a proxy server to manage mapping of files to workareas with relative and
absolute path references. Using the previous example, the TeamSite proxy server
enables all users attempting to access /images/miles.gif from within TeamSite to be
mapped to the copy of miles.gif in their own workareas. The redirected mapping
would look like:

/images/pic.gif Y:\default\main\branchpath\WORKAREA\workareaname\im
ages\miles.gif

Document Roots
TeamSite maps the initial Web server directory structure (the document root) of
workareas to the top level of the workarea directory by default. You may, however, want
to move the document root, or group types of files together for improved clarity,
convenience, or efficiency. On a branch-by-branch basis, the TeamSite proxy server
allows you to remap the document root anywhere within the workarea directory. It also
allows you to define mappings directly to subdirectories within workareas.

NOTE
The proxy server does not allow you to remap the document root directory for Content
Store branches other than the default Content Store.

Document roots are defined in the [iwproxy_remap] section of iw.cfg. The default
setting is as follows:

[iwproxy_remap]
global_default_map=/

TeamSite Administration Guide 197


Chapter 9: Configuring the TeamSite Web Daemon and Proxy Server

NOTE
The iw.cfg file also contains a section called [global_default_map]. There must be a
corresponding section for each parameter defined in the [iwproxy_remap] section.

To configure document roots for individual branches:


1. For each branch that you want to configure, add a line to the [iwproxy_remap]
section of iw.cfg as follows:
[iwproxy_remap]
configSectionName=vpath

where configSectionName is the name of the section of the configuration file that
defines the branch remappings, and vpath is the vpath to the branch you are
configuring.
2. For each line that you added to [iwproxy_remap] section, create a section in iw.cfg
named [configSectionName].
3. Add a line to this new section that defines the document root:
_docroot=dirpath

where dirpath is a directory path rooted in a workarea.


You can also add lines that bypass the document root, as follows:
path=path

For example, if you added the following lines to [iwproxy_remap]:


[iwproxy_remap]
branchrewrite_1=/main
branchrewrite_2=/main/training

The first line tells TeamSite to use the section [branchrewrite_1] to set the document
root configuration for the /main branch. The second line tells TeamSite to use the
[branchrewrite_2] section to set the document root configuration for the
/main/training branch.

You would then create two new sections in iw.cfg corresponding to the lines in
[iwproxy_remap]:
[branchrewrite_1]
_docroot=/htdocs
/pictures/=/pictures/
/html/=/html/

[branchrewrite_2]
_docroot=/htdocs
/images/=/images/

Note that the first line of both the new sections contains _docroot=/htdocs. This
defines a special directive that sets the mapping of the document root. Any requests

Interwoven, Inc. 198


Chapter 9: Configuring the TeamSite Web Daemon and Proxy Server

from workareas on the main branch or the main/training branch to the root level
directory (/) now start at:

.../workareaname/htdocs/

Thus, the request for file /miles.gif will now be mapped to:
.../workareaname/htdocs/miles.gif

newly defined docroot file

The two docroot configuration sections also contain lines similar to the following:

/pictures/=/pictures/

This line maps file requests directly to the listed directory /pictures/, bypassing the
document root defined in the first line. Thus, a request for the file
/pictures/mingus.gif gets mapped to:

.../workareaname/pictures/mingus.gif

not:

.../workareaname/htdocs/pictures/mingus.gif

The TeamSite proxy server operates using literal string matches and substitutions in
path names. To avoid inadvertently rewriting names, always use trailing slashes in your
remap definitions.

NOTE
Do not use trailing slashes in your remap definitions for _docroot directories.

Resolving Fully Qualified URLs


The proxy server can also be configured to resolve fully qualified paths. For example, a
link to the main page of a Web site might appear as: http://www.name.com.

If such a link appears in an HTML file in a TeamSite workarea, and you follow that link
while performing in-context QA, you will be taken out of the workarea and to the actual
referenced Web site.

Therefore, if you use fully qualified URLs to reference pages within your own Web site,
clicking on these links will take you out of the in-context view of the current workarea,
staging area, or edition and into your own currently deployed Web site. To solve this
problem, TeamSite enables you to configure your proxy server to redirect fully qualified

TeamSite Administration Guide 199


Chapter 9: Configuring the TeamSite Web Daemon and Proxy Server

links within your Web site, then pass them to the regular proxy server to ensure the
integrity of the in-context view in a workarea, staging area, or edition.

NOTE
Only configure this setting if your Web site uses fully qualified URLs that you need to
view in-context. This setting requires you to manually configure your browser, so that
you cannot view the actual Web site without reconfiguring your browser. This also
slows the TeamSite server by sending every request through iwwebd and iwproxy.

Redirecting Fully Qualified URLs


There are two major steps you must complete to configure TeamSite to redirect fully
qualified URLs:
„ Configure your proxy server by editing the [iwproxy_fullproxy_redirect]
section of iw.cfg.
„ Configure your Web browser’s proxy to use the TeamSite Web daemon (iwwebd).

These procedures are described in detail in the next two sections.

Configuring the Proxy Server to Redirect Fully Qualified URLs


This feature allows fully qualified URLs in a Web page to be redirected back into
workarea-virtualized paths if users set their browser’s proxy to iwproxy. This feature
must be specifically enabled (enabled=yes) to prevent it from being abused. If you
enable this feature, be sure you understand the security implications and properly secure
the HTTP and HTTPS ports of your TeamSite server using a firewall and VPN where
needed.

Edit the [iwproxy_fullproxy_redirect] section of iw.cfg. to include any number of


_regex lines as follows:
_regex=source_regex=dest_ex

where source_regex is a case-insensitive regular expression specifying a fully qualified


URL that might appear in a page, and dest_ex is an expression specifying the path that
the link will be redirected to. This expression should always be the path to the file
specified in source_regex, but rooted in a TeamSite area. For example:
[iwproxy_fullproxy_redirect]
enabled=yes
_regex=http://www(\.example\.com)?/(.*)=/$2

enables the feature and redirects links that specify http://www.example.com in the
URL and sends them to the corresponding location in the current TeamSite area.

Interwoven, Inc. 200


Chapter 9: Configuring the TeamSite Web Daemon and Proxy Server

NOTE
If your iw.cfg file’s [iwwebd] section defines the host as host=hostname.domain, and
your browser's proxy server is set to hostname.domain:port, when you start TeamSite,
you must enter http://hostname.domain/iw/ in your browser rather than
http://hostname/iw/.

Continue the configuration by completing the procedures described in the next sections.

The TeamSite web daemon can be used as a proxy server to connect to any outside
address and access content. You can create a regex in the
[iwproxy_fullproxy_redirect] section of iw.cfg to disable this functionality. Refer
to the [iwproxy_fullproxy_redirect] section of iw.cfg.example for details.

Configuring your Web browsers to Use the TeamSite Web Daemon


You must modify your Web browser to use the TeamSite proxy server as described here
for Internet Explorer.
1. In Internet Explorer, select Tools > Internet Options.
The Internet Options window displays.
2. Select the Connections tab.
3. Click LAN Settings.
The Local Area Network (LAN) Settings window displays.
Figure 36Local Area Network settings dialog box

4. Click the Use a proxy server check box.


5. Type the name of your TeamSite server (for example, teamsite1.example.com) in
the Address section.
6. Type the http-port specified in the [iwwebd] section of iw.cfg (for example, 80)
in the Port section.
7. Click OK.

TeamSite Administration Guide 201


Chapter 9: Configuring the TeamSite Web Daemon and Proxy Server

To configure Internet Explorer to not use the TeamSite proxy server:


1. In Internet Explorer, select Tools > Internet Options.
The Internet Options window displays.
2. Select the Connections tab.
3. Click LAN Settings.
The Local Area Network (LAN) Settings window displays.
4. Either:
‰ Clear the Use a proxy server check box, and click OK.
‰ Click Advanced. The Proxy Settings window displays. Continue with step 5.
5. In the Exceptions field, enter the URLs that you want to access without using the
proxy server.
6. Click OK.

Redirecting TeamSite Views to Different Areas


The proxy server enables web teams to work on branches of development that are
populated only with the portion of the content that they are developing, but still
maintain a full in-context view of the entire content collection by referencing the staging
area or a known edition on another branch of development.

This feature is very flexible in that it can be configured on a per-branch or per-workarea


basis, and the redirected view can be configured to take the user to any TeamSite area on
any branch. Redirection can occur in one of two ways:
„ Through [iwproxy_preconnect_remap], which retains your original area as the
current working area and directs files there from another area. In this scenario,
docroot is based on the original area’s parent branch.

„ Through [iwproxy_preconnect_redirect], which causes the area you redirect into


to become the current working area (and that area’s parent branch becomes the basis
of docroot).

Using iwproxy_preconnect_remap
To configure TeamSite to redirect workarea views and retain your original area as the
current working area (as described in the first bullet), edit the
[iwproxy_preconnect_remap] section of iw.cfg as follows:
[iwproxy_preconnect_remap]
_regex=source_regex=dest_ex

where source_regex is a case-insensitive regular expression describing the area to be


mapped from, and dest_ex is an expression describing the area to be mapped to. These
areas are most commonly workareas or staging areas, but you can map to and from any

Interwoven, Inc. 202


Chapter 9: Configuring the TeamSite Web Daemon and Proxy Server

workarea, staging area, or edition. You can add any number of _regex lines to this
section.

For example:
_regex=(.*)/branch1/WORKAREA/[^/]+/products/(.*)=$1/branch2/
STAGING/products/$2

tells the proxy server to remap the products directory of any workarea on any branch
named branch1 to the products directory of the staging area on its sister branch,
branch2.

In the source regular expression, (.*) is used to specify an arbitrary path, and $1 in the
destination expression means that it must follow the same path (and therefore branch1
can be anywhere in the branch structure, but branch2 is a sister branch of branch1).
Also in the source regular expression, [^/]+ is used to specify a single directory level,
of any name (which in this case would be the workarea name, and therefore all
workareas on branch1 are specified). Finally, the source regular expression uses (.*) to
specify another arbitrary path, and $2 in the destination expression tells it to follow the
same path.

You can also specify the exact location of the areas you want to remap:
_regex=^/
iw-mount/default/main/branch1/WORKAREA/[^/]+/products/(.*)=/
iw-mount/default/main/branch2/STAGING/products/$1

Or, you can specify an individual workarea to remap:


_regex=^/
iw-mount/default/main/dev/branch1/WORKAREA/andre/coolstuff/(.*)=/
iw-mount/default/main/branch2/STAGING/coolstuff/$1

The TeamSite proxy server applies the first match it finds, so you can exclude a
particular area from a more general rule by creating a separate rule for that area and
placing it before the more general rule. For example:
_regex=(.*)/branch1/WORKAREA/chris/products/(.*)=$1/branch1/
STAGING/products/$2
_regex=(.*)/branch1/WORKAREA/[^/]+/products/(.*)=$1/branch2/
STAGING/products/$2

remaps the products directory in all workareas on branch1 except for Chris’s to the
staging area of branch2.

See “Configuring Proxy Failover” on page 207 for more details about configuration rule
precedence.

TeamSite Administration Guide 203


Chapter 9: Configuring the TeamSite Web Daemon and Proxy Server

Using iwproxy_preconnect_redirect
To configure TeamSite to redirect workarea views and cause the area you redirect into to
become the current working area (as described in the second bullet on page 202), edit
the [iwproxy_preconnect_redirect] section of iw.cfg:
[iwproxy_preconnect_redirect]
_regex=source_regex=dest_ex

where source_regex and dest_ex are as described in “Using


iwproxy_preconnect_remap” on page 205. If you set [iwproxy_preconnect_redirect]
and then click on a link defined by an absolute path name, the docroot of that link is
based on the branch you redirected into (as opposed to the branch of the area you
redirected from, which would be the behavior if you had set
[iwproxy_preconnect_remap]). See “Configuring Proxy Failover” on page 207 for a
details about configuration rule precedence.

Configuring TeamSite to Use Different Web


Servers
You can configure TeamSite to use different Web servers for different workareas or
different types of content. For example, Andre might want to make all
under-development CGIs in his workarea on branch1 be served by
test1.example.com:1234. This would let Andre test different Web server
configurations for his CGIs on branch1 without disturbing anyone else.

To configure TeamSite to use different Web servers, edit the


[iwproxy_preconnect_remap] section of iw.cfg:
[iwproxy_preconnect_remap]
_regex=source_regex=dest_ex

where source_regex is a case-insensitive regular expression describing the area and


files to be served by the other Web server, and dest_ex is an expression describing the
area and files on the other Web server. This expression must include the port number.

For this to work properly, the other Web server must have the appropriate TeamSite
directory mounts and privileges. The Web server alias used by httpd on port 1234 of
test1.example.com must be configured with the TeamSite alias as well (/iw-mount/).

The following example would allow Andre to test all CGIs in his workarea on
test1.example.com, as previously described:
[iwproxy_preconnect_remap]
_regex=^/iw-mount/default/main/branch1/WORKAREA/andre/(.*)\.cgi
(\?.*)?$=http://test1.example.com:1234/iw-mount/default/main/branch1/
WORKAREA/andre/$1.cgi$2

Interwoven, Inc. 204


Chapter 9: Configuring the TeamSite Web Daemon and Proxy Server

Configuring External Remappings


The TeamSite proxy server enables you to define mappings to directories outside of the
TeamSite system or on different computers altogether. You can define these mappings
using either of the following methods:
„ [iwproxy_preconnect_remap]
„ [iwproxy_external_remap]

If you use [iwproxy_preconnect_remap], the mappings follow normal


[iwproxy_preconnect_remap] precedence rules. However,
[iwproxy_external_remap] mappings apply only if no other remapping rule has been
applied.

Using iwproxy_preconnect_remap
To configure TeamSite to redirect workarea views to external Web servers, edit the
[iwproxy_preconnect_remap] section of iw.cfg as follows:
[iwproxy_preconnect_remap]
_regex=source_regex=dest_ex

where source_regex is a case-insensitive regular expression describing the area to be


mapped from, and dest_ex is an expression describing the area to be mapped to. These
areas are most commonly workareas or staging areas, but you can map to and from any
workarea, staging area, or edition. For example:
_regex=(.*)/branch1/WORKAREA/[^/]+/logos/(.*)=http://corporateidserver
.example.com/logos/$2

sends all requests for files in the /logos directory in all workareas on branch1 to
another server, corporateidserver.example.com.

Using iwproxy_external_remap
You can also use [iwproxy_external_remap] rules for external remappings, although
[iwproxy_preconnect_remap] is the preferred methodology.

For example, if all your corporate logo files reside on a separate server, you can use
[iwproxy_external_remap] to create a mapping to the directory where they reside:
[iwproxy_external_remap]
/logos/=http://corporateidserver.example.com/logos/

This remapping sends all requests for /logos/ to a directory on another server,
corporateidserver.example.com/logos/. You can also create associations using
case-insensitive regular expression mapping.

The [iwproxy_external_remap] section is read after the [iwproxy_remap] section, and


is only applied if none of the [iwproxy_remap] rules were invoked. For example, if you

TeamSite Administration Guide 205


Chapter 9: Configuring the TeamSite Web Daemon and Proxy Server

create a mapping for /logos/ in one of the [branchrewrite] sections, all requests on
that branch for files in the /logos/ directory will use that mapping instead of the
external mapping. Requests on other branches will still be sent to the
corporateidserver.

Host Header Remappings


If your Web server manipulates Host: headers (for example, virtual domains), you can
configure TeamSite to replicate that behavior. To configure Host: header remapping,
edit the [iwproxy_hostheader_remap] section of iw.cfg.
[iwproxy_hostheader_remap]
_regex=source_regex=dest_ex

where source_regex is a case-insensitive regular expression describing the area to be


mapped from, and dest_ex is an expression describing the new Host: header. For
example:

_regex=^/iw-mount/default/main/branch1/WORKAREA/.*=example.com:1234

will change the Host: header that the source server gets from the TeamSite proxy server
to read:

Host: example.com:1234

whenever content in a workarea on branch1 is accessed.

Enabling iwproxy Access Control


By default, iwproxy allows any authenticated TeamSite user to view any file in
TeamSite. To configure iwproxy to verify the users’ ability to read certain files in the
file system, add an [iwproxy_access_control_enabled] section to your iw.cfg file based on the
example that follows.

This example implements the following policy:


„ All users should be able to read any document on the intranet, except for files in the
/hr/ directory, which require specific read access.

„ All users should be able to read any document on the internet site.

Interwoven, Inc. 206


Chapter 9: Configuring the TeamSite Web Daemon and Proxy Server

„ For all other branches, iwproxy should check to ensure the current user has read
access.
[iwproxy_access_control_enabled]
_default=yes
_regex=^/iw-mount/dc/main/intranet/(((WORKAREA|EDITION)/[^/)]+)|ST
AGING)/hr/=yes
_regex=^/iw-mount/dc/main/intranet/(((WORKAREA|EDITION)/[^/]+)|STA
GING)/=no
_regex=^/iw-mount/dc/main/www%20external/(((WORKAREA|EDITION)/[^/]
+)|STAGING)/=no

Configuring SSI Remapping


The TeamSite Web server plug-in supports the ability to both remap and virtualize SSI
requests. To enable SSI request virtualization, you must install the necessary redirector
module (iwproxy_nsapi.dll or iwproxy_isapi.dll) in addition to the Web server
plug-in.

After installing the necessary redirector module as described on as described in the


TeamSite Installation Guide, you can configure TeamSite to remap SSI requests by
adding or modifying the [iwproxy_plugin_remap] section of iw.cfg. In the following
example, any SSI request containing the string /forms/ is mapped to
/iw-mount/default/main/Branch2/STAGING/forms instead of being referred to the
root of the user’s workarea:
[iwproxy_plugin_remap]
_regex=(.*)/forms/(.*)=/iw-mount/default/main/Branch2/STAGING/forms/$2

If you want to debug regular expressions, set the value for _debug in the
[iwproxy_plugin_remap] section to true. On NES, debugging information is stored in
the Web server error log file. On IIS, this information is stored in
C:\temp\iw_isapi.log. This log file can grow extremely large over time.

Configuring Proxy Failover


If a requested page does not exist, the [iwproxy_failover_remap] section of iw.cfg
can be used to specify an alternate location. This section enables you to specify both
alternate locations and the number of times to process an URL in an attempt to find a
valid location. The figure below illustrates the process by which proxy failover remaps
URLs.

TeamSite Administration Guide 207


Chapter 9: Configuring the TeamSite Web Daemon and Proxy Server

Figure 37 Proxy failover remap diagram


The proxy server rewrites the URL according to
rules specified in iwproxy_fullproxy_redirect,
iwproxy_remap, iwproxy_external_remap
iwproxy_preconnect_redirect

Can the rewritten Yes


path be found?

No

iwproxy_preconnect_remap

iwproxy_hostheader_remap

iwproxy_smartcontextedit_allowed

Can the rewritten No iwproxy_failover_remap


path be found? remaps the rewritten URL and
Has maxfail been increments maxfail.
reached?

Yes

The specified page is returned, if found.


If it is not found, the proxy server returns a
File not found message.

The [iwproxy_failover_remap] section has the following structure:


[iwproxy_failover_remap]
_maxfail=#
_regex=source_regex=dest_ex
_regex=source_regex=dest_ex

To specify the number of times to try to remap a URL, edit the _maxfail line of the
[iwproxy_failover_remap] section of iw.cfg. The default value of this line is
_maxfail=0, which turns off proxy failover. Note that proxy failover is seldom needed
because files are almost always in locations that can be specified using static,
case-insensitive regular expressions during configuration. If you need to enable proxy
failover, it is recommended that you do not set _maxfail to more than 1 or 2 due to the
impact on system performance.

Interwoven, Inc. 208


Chapter 9: Configuring the TeamSite Web Daemon and Proxy Server

To specify expressions to remap, add _regex lines to [iwproxy_failover_remap].


These lines specify an incoming pattern to match, and an expression that they should be
mapped to. The proxy server will take the first match it finds, remap it as specified, then
try to locate the page. If it cannot find the new location, it will try to match the
remapped expression to a regular expression specified in [iwproxy_failover_remap].
This process will continue until a match is found or the number of iterations specified by
the _maxfail line is reached.

_regex lines in the [iwproxy_failover_remap] section follow the same syntax as


_regex lines specified in the [iwproxy_preconnect_remap] section of iw.cfg, where
source_regex is a case-insensitive regular expression describing the area to be mapped
from, and dest_ex is an expression describing the area to be mapped to. For examples
of _regex syntax, see “Resolving Relative and Absolute Paths” on page 196.

Debugging Your Proxy Server Configuration


If your proxy server does not seem to be configured correctly, use the iwproxy.exe
CLT’s debug option to list all the translations being made by the proxy server:

iwproxy [-d|-x]

-d Debug mode (outputs client & server headers)


-x Extended (verbose) debug mode (outputs client body text as well)

iwproxy returns debug output which you can redirect to a file. Note that the iwproxy
debug mode is single-threaded; it therefore slows the TeamSite server down
significantly. Use the debug mode for diagnostic purposes only.

One common source of proxy configuration problems is the inclusion of any character
or blank space past the end of a branch name in any line in any [iwproxy*] section in
iw.cfg. For example, the following line in the [iwproxy_remap] section is illegal
because it contains blank spaces and characters after the branch name:
[iwproxy_remap]
tag_engspecs=/main/engspecs #This is the engineering spec site

NOTE
iwproxy.exe needs to run as local Administrator or a user with the following access
privileges: Act as Part of Operating System, Log on Locally, Increase Quotas, and
Replace a Process Level Token.

TeamSite Administration Guide 209


Chapter 9: Configuring the TeamSite Web Daemon and Proxy Server

Interwoven, Inc. 210


Chapter 10

Backing Up TeamSite

Your TeamSite Content Stores represent a tremendous investment in resources and are a
valuable corporate asset. As such, they should be backed up daily, or even more
frequently, to minimize the possibility of damaged or lost data. Any third-party backup
solution that can guarantee exact time and state directory content recovery can be used.

This chapter discusses:


„ Integrating with Third-Party Backup Solutions
„ Suggested Strategies for Incremental Backups

Integrating with Third-Party Backup Solutions


Interwoven recommends using a high-quality third-party backup solution for protecting
the Content Store data. When evaluating a backup solution, the following criteria are
essential:
„ The backup method must provide a way to perform an iwfreeze operation prior to
performing the backup. This must be done to assure that the Content Store does not
change during the backup. The backup method must then perform an iwfreeze --
operation to allow writes to the Content Store when the backup is finished.
„ The backup method must be fast enough to perform a full or incremental backup of
the Content Store within a reasonable length of time. The maximum allowable
length of time depends on the requirements of the particular installation, but should
probably be less than 12 hours.
„ The restore method must provide a way to do a complete state-restore of a directory
as of a given time. This means that when a directory is recovered, the contents must
match exactly what was in the directory at the time the backup was performed. Only
files that were present at the time of the backup must be present in the restore. That
is, if a file was deleted from the original directory between backups, it should not be
present in the restore. For example, take a backup, delete a file, take another backup;
a restore from the second backup should not contain the deleted file. Some backup
and restore products regard all backed-up files to be “sticky,” that is, as long as a file
ever existed, it is present in the restoration regardless of whether it was deleted prior
to the last backup.

TeamSite Administration Guide 211


Chapter 10: Backing Up TeamSite

Additional criteria to consider are:


„ An automated backup execution facility capable of performing full backups
followed by level (preferred) or incremental backups to provide a customizable
backup strategy.
„ Automated backup media management and manipulation (for example, a tape
jukebox or silo).
„ The ability to make copies of completed backups for off-site storage.

If the available backup method is efficient and inexpensive (compared to the value of
the data being protected), the TeamSite workareas can also be backed up to allow users
to recover individual files or directories from their workareas, rather than having to
recover the entire Content Store. This is a very convenient feature for users, but can
come at a relatively high price in terms of extra time and space needed for these
redundant backups. Although the virtual files which comprise much of theTeamSite file
system mount (Y:) take up no extra space on the TeamSite server, if the actual TeamSite
workareas are backed up, the virtual files in the workareas will be treated as actual files
and will take up space in the backup media.

NOTE
Workarea backup must be done through the Y: drive.

You must freeze the TeamSite Content Store (with the iwfreeze command) while you
are backing up your Content Store or workareas. Failure to freeze the Content Store
while you are backing up can result in possible data loss and corruption. For details
about the iwfreeze CLT, refer to TeamSite Command-Line Tools for your platform.

NOTE
If you are using multiple Content Stores, you can back up each store independently. The
iw-store directory should be backed up if you have in-progress workflows or batch
jobs that you do not want to lose. Because workflows can span all stores, a full frozen
backup of all stores and the workflow store is needed. You can freeze and unfreeze the
workflow store just like any other store, but you cannot move it outside of iw-store.

Backing up workareas alone is not a substitute for backing up the TeamSite Content
Store. If you only back up the files that appear in the TeamSite file system mount, you
will lose important metadata such as version histories and file status. Always back up
the actual TeamSite Content Store whether or not you back up individual workareas.

Interwoven, Inc. 212


Chapter 10: Backing Up TeamSite

Suggested Strategies for Incremental Backups


It is possible to implement a “level-oriented” backup if a sufficiently sophisticated
backup solution is available. For example, a full backup can be performed on the first
Saturday of the month, then incremental backups that build on each other can be
performed for the rest of the week. On the second Saturday of the month, a
“super-incremental” backup based on the original full backup done on the first Saturday
is performed. The super-incremental backup supersedes all of the previous incremental
backups. Only the first full backup and super-incremental are needed to completely
recover the Content Store. For the subsequent week, incremental backups are again
performed based on the super-incremental backup done on the second Saturday. The
following Saturday, another super-incremental backup based on the previous
super-incremental file is performed, again eliminating the need for the previous week’s
incrementals to recreate the Content Store. To perform a recovery at this point, restore
the original full backup, then each super-incremental in sequence, and finally the
balance (if any) of the current week’s incrementals.

This tiered, or level-oriented backup can be repeated on a monthly basis to produce a


week-by-week record of the Content Store. To reproduce the Content Store as of any
particular Saturday, recover the full backup from the beginning of the month, then apply
each Saturday backup in turn until the desired Saturday is reached.

To determine your optimal backup strategy, you must analyze the trade-offs of
convenience and speed in backing up versus simplicity and speed of restoration, and
decide what best suits your needs. A strategy using a single full backup and an indefinite
string of incrementals is optimized for backup speed, but the amount of time required to
perform a full recover of the Content Store grows with each passing day as a new
incremental is added to the list. Every backup must be preserved to be able to recover
the Content Store. One benefit of this method is that a complete daily record of the
Content Store will be preserved.

The opposite extreme is to perform a full backup every day. Each backup will take the
maximum amount of time to perform, but only one recover needs to be done to
completely recreate the Content Store. If you only preserve the previous day’s backup,
no history of the Content Store will be retained, but the amount of storage space used by
the backups is minimized.

TeamSite Administration Guide 213


Chapter 10: Backing Up TeamSite

Interwoven, Inc. 214


Appendix A

Configuring TeamSite
ReportCenter

The TeamSite ReportCenter integrates with Crystal Enterprise to allow you to run
standard reports and to create additional reports. When TeamSite ReportCenter is
installed, authorized users of ContentCenter Professional have a Reporting tab that
provides access to available reports and displays the results of requested reports.

This chapter discusses the following ReportCenter topics:


„ Installing TeamSite ReportCenter
„ ReportCenter Overview
„ ReportCenter Configuration File
„ Archived Events
„ Database Schema
„ Crystal Enterprise Configuration
„ Troubleshooting

Installing TeamSite ReportCenter


The TeamSite ReportCenter module is an add-on module that is available for TeamSite.
It has a separate installation program and requires a license key. You can install
ReportCenter during the TeamSite installation or add it to an existing TeamSite
installation. The installer module for TeamSite ReportCenter does the following:
„ Sets up the database schema.
„ Sets up the UI configuration file.
„ Configures the TeamSite Reporting Server.

Refer to the TeamSite Installation Guide for details on installing TeamSite


ReportCenter.

NOTES
„ If Crystal Reports conflicts with TeamSite on Port 81, create the Crystal Reports
web site on a different port.

TeamSite Administration Guide 215


Appendix A: Configuring TeamSite ReportCenter

„ You might find KB article 59533 (from https://support.interwoven.com) helpful


if you are installing TeamSite and ReportCenter on the same computer.

ReportCenter Overview
TeamSite ReportCenter obtains information from the Event Subsystem (page 51).
Information is stored in a relational database and can be read by Crystal Enterprise
software to obtain reporting information.

Figure 38 ReportCenter System Overview

Event
TeamSite subsystem

Report
Module
TSReport
RDBMS

Reporting
Messaging UI RDBMS
library

Event Crystal
Proxy Enterprise

The reporting service infrastructure consists of the following modules:


„ A new messaging library. This library is used by the TeamSite server to publish
events.
„ A new proxy service that subscribes to the messages published by TeamSite and
publishes them to the Interwoven Event Subsystem. The proxy service referred to
here is not related to iwproxy in any way.
„ Interwoven Event Subsystem.
„ A report module that subscribes to the Interwoven Event Subsystem for TeamSite
events and archives the data into a reporting database.
„ The Reporting UI that queries Crystal Enterprise and displays Crystal Enterprise
reports.

The new messaging library provides TeamSite with a reliable method of publishing
events. This library exports a write/read interface, which can be used by event

Interwoven, Inc. 216


Appendix A: Configuring TeamSite ReportCenter

publishers and subscribers. The TeamSite server uses the message library to write events
and the new proxy service reads such events and propagates them to the Interwoven
Event Subsystem.

The TeamSite report server subscribes to events published by the TeamSite core server
engine, the workflow engine, and the templating engine. On receiving events from the
Interwoven Event Subsystem, the report server archives these events into the reporting
database. In some cases, the report server will query the engine that generated the event
for additional information. Some examples of this are:
„ Query the core server for all files submitted as part of a submit event.
„ Query the workflow engine for all files associated with a task.

To query on workflow events, modify the iw.cfg file so jobs are not deleted from the
content store when they complete, as follows:
[workflow]
delete_jobs_on_completion=false

The TeamSite report server archives the event-related information into a relational
database provided by the customer. The report server adheres to the JDBC standard
while accessing and modifying a database. The reporting service supports the following
databases: Oracle 8i, Oracle 9i, MS SQL Server 2000 and IBM DB2 8.1. The database
schema should be created prior to starting the TeamSite report server. The necessary
DDL scripts will be provided with the reporting server package.

ReportCenter Configuration File


The iw-home\tsreport\conf\tsreport.xml file is used to configure reporting.

This section shows the complete file and then describes the configuration parameters in
each area and specifies the information to be modified. Most of the information in this
file is entered during the installation. You should generally make changes to this file
using the iwconfigtsreport CLT.
<?xml version="1.0" encoding="UTF-8" ?>

<configuration>
<License key="_LICENSE_KEY_"/>
<!-- ********************** Logging ******************************** -->
<Logging>
<!-- See org.apache.log4j.xml.DOMConfigurator for more details -->
<log4j:configuration xmlns:log4j="http://jakarta.apache.org/log4j/">
<appender name="tsreport" class="org.apache.log4j.FileAppender">
<param name="File" value="_IWLOGDIR_/tsreport.log" />
<layout class="org.apache.log4j.PatternLayout">
<param name="ConversionPattern"
value="%d{HH:mm:ss.SSS} %-5p [%t] - %m\n"/>
</layout>
</appender>

TeamSite Administration Guide 217


Appendix A: Configuring TeamSite ReportCenter

<root>
<priority value="ERROR"/>
<appender-ref ref="tsreport"/>
</root>

<category name="com.interwoven">
<priority value="INFO"/>
<appender-ref ref="tsreport"/>
</category>
</log4j:configuration>
</Logging>

<!-- ******************** Database *************************** -->


<Database
poolsize="1"
driver="_JDBC_DRIVER_NAME_"
url="_JDBC_CONNECT_STRING_"
user="_DB_USER_" />

<!-- ********************* CSSDK connection configuration ****** -->


<Cssdk
poolsize="1"
server="localhost"
configfile="_CSSDK_CFGFILE_"
locale="en" />

<!-- **************** Product ********************************* -->


<!-- Product Node must appear before the Receiver node. -->
<!-- possible values: teamsite, opendeploy, datadeploy, openapi,
workflow, iwevents -->

<Product>
<param name="type" value="teamsite" />
<param name="name" value="Product : TeamSite" />
<param name="ref-id" value="1" />
<param name="database-id" value="42" />
</Product>

<!-- ********************** Receiver ***************************** -->


<Receiver>
<EventServer> <!-- JmsReceiver.configure -->
<param name="java.naming.factory.initial"
value="org.exolab.jms.jndi.InitialContextFactory"/>
<param name="java.naming.provider.url"
value="tcp://localhost:_JNDI_PORT_/"/>
<param name="TopicConnectionFactory"
value="JmsTopicConnectionFactory"/>

<!-- JmsReceiver.addListenerFromXML -->

Interwoven, Inc. 218


Appendix A: Configuring TeamSite ReportCenter

<Listener class="com.interwoven.tsreport.server.TeamsiteListener"
topic="Interwoven" product-ref="1">
<param name="Reportable Extended Attributes">
<value name="key"/>
<value name="key1"/>
<value name="key2"/>
</param>
<JobVariables>
<variable name="" />
<variable name="" />
<variable name="" />
</JobVariables>
</Listener>
</EventServer>
</Receiver>
</configuration>

License key
The license key is added to this file during installation. If you do not have the license
key when you install TeamSite, rerun the reporting installation module.

Logging
The <param> element describes where the log file is written; the directory where the file
is located may be changed during installation.

The <priority> element within the <category> element can be changed to reflect the
level of debugging. The levels of debugging are ERROR, WARN, INFO, and DEBUG. Refer to
http://logging.apache.org/log4j/docs/ for details.

Database
The installation software enters this information into this file.
„ The <poolsize> element describes the number of threads to connect to the database;
leave this at one.
„ The <driver> element refers to the database driver required.
„ The <URL> element is the URL connect string.
„ The <user> element refers to the database user. During installation, you are also
asked for this user’s password; it is stored in a different file.

TeamSite Administration Guide 219


Appendix A: Configuring TeamSite ReportCenter

The appropriate JDBC drivers are:

Oracle classes12.2.zip (shipped with TeamSite Reporting)


DB2 db2jcc.jar
db2jcc_license_cu.jar
MsSQL mssqlserver.jar
msbase.jar
msutil.jar
MySQL MySQL Connector/J can be obtained from www.mysql.com.

NOTE
For DB2, the pagesize of the user tablespace should be 16K for the database where
the Report Center schema will be created.

CSSDK
If the report server is being run under an account other than SYSTEM, you must also
add the user and role. The user account under which the reporting server is running must
be a TeamSite user in a role with sufficient privileges.
„ The <poolsize> element describes the number of threads to connect to the database;
leave this at one.
„ The <server> element identifies the server where TeamSite is running.
„ The <configfile> element provides the location of the configuration file.
„ The <locale> element identifies the language of the server.

Product
This section is currently a placeholder for future release; you do not need to make
changes.

Receiver
This section should be manually edited.

You need to specify values for the <param> element named Reportable Extended
Attributes at the end of the file. Replace key, key1, and key2 with the names of
extended attributes to be reported on. Add additional value elements as needed. If the
EAs in metadata.cfg are to be reported on, the full name should be specified, such as
TeamSite/Metadata/EAName.

The jobvariables section captures workflow and task variables. Job variables are
captured on WorkflowActivate events, and task variables are captured on
TaskInactivate events.

Interwoven, Inc. 220


Appendix A: Configuring TeamSite ReportCenter

You must restart the report server after making these changes in order for them to take
effect.

Archived Events
The following server events are archived in the reporting database.

Table 14 Archived Server Events


Event Name Attribute Names
ResetConfig timestamp | user | role
ShutDown timestamp | user | role
StartUp timestamp | user | role
ThawAll timestamp | user | role
Thaw timestamp | user | role | archive
FreezeAll timestamp | user | role | seconds
Freeze timestamp | user | role | seconds | archive
DiskLow timestamp | user | role | directory | message
DiskFail timestamp | user | role | directory | message
BlockBatchJobs timestamp | user | role | seconds | archive
UnblockBatchJobs timestamp | user | role | archive

TeamSite Administration Guide 221


Appendix A: Configuring TeamSite ReportCenter

The following user events are archived in the reporting database. The events SetEA
through DestroyFSE are only available when turned on by iwat scripts as described in
TeamSite Command-Line Tools.

Table 15 Archived User Events


Event Name Attribute Names
ModifyEntity timestamp | user | role
Update timestamp | user | role | area | objectId
Submit timestamp | user | role | area | objectId
Lock timestamp | user | role | area | path | objectId |
owner | comments
Unlock timestamp | user | role | area | path | objectId |
owner | comments
DestroyWorkarea timestamp | user | role | area
CreateWorkarea timestamp | user | role | area
PublishStagingArea timestamp | user | role | edition | area
DestroyEdition timestamp | user | role | edition
DestroyBranch timestamp | user | role | branch
CreateBranch timestamp | user | role | branch
SetEA timestamp | user | role | area | path | eaKey
DeleteEA timestamp | user | role | area | path | eaKey
SyncModify timestamp | user | role | area | path | fseType
SyncDestroy timestamp | user | role | area | path | fseType
SyncRevert timestamp | user | role | area | path | fseType |
revertType
RenameFSE timestamp | user | role | area | path1 | path2
CreateFSE timestamp | user | role | area | path
ModifyFSE timestamp | user | role | area | path
DestroyFSE timestamp | user | role | area | path

Interwoven, Inc. 222


Appendix A: Configuring TeamSite ReportCenter

The following workflow events are archived in the reporting database:

Table 16 Archived Workflow Events


Event Name Attribute Names
WorkflowActivate timestamp | user | role | type ("workflow") | wfName
| workflowId
WorkflowInactivate timestamp | user | role | type ("workflow") |
wfName| workflowId
ChooseTransition timestamp | user | role | wfName | workflowId | task
| taskId | choice
TaskTimedOut timestamp | user | role | wfName | workflowId | task
| taskId
TaskUndoChoice timestamp | user | role | wfName | workflowId | task
| taskId | choice
TaskActivate timestamp | user | role | wfName | workflowId | task
| taskId | other | otherId
TaskInactivate timestamp | user | role | wfName | workflowId | task
| taskId
TaskGoActive timestamp | user | role | wfName | workflowId | task
| taskId
TaskInvokeExternal timestamp | user | role | wfName | workflowId | task
| taskId
TaskCalledBack timestamp | user | role | wfName | workflowId |
taskId | returnCode
TaskAddFile timestamp | user | role | wfName | workflowId | task
| taskId | path
TaskRemoveFile timestamp | user | role | wfName | workflowId | task
| taskId | path
TaskDeleteFile timestamp | user | role | wfName | workflowId | task
| taskId | path
TaskGroupTaken timestamp | user | role | wfName | workflowId | task
| taskId | taker
TaskMoveFile timestamp | user | role | wfName | workflowId | task
| taskId | path1 | path2

The following events are published by FormsPublisher or the Tagger GUI:

Table 17 Archived FormsPublisher or Tagger GUI Events


Event Name Attribute Name Notes
SyncCreate user | role | area | Generated when a new or existing data record
path |dcrType is saved
SyncCreate user | role | area | Generated when metadata of this rule set
path (with these attributes) is applied to a file for
the first time
SyncModify user | role | area | Generated when metadata of this rule set
path (with these attributes) is applied to a file with
existing metadata
Note: path is a area-relative path

TeamSite Administration Guide 223


Appendix A: Configuring TeamSite ReportCenter

Database Schema
The iw-home\tsreport\conf\ddl\tables.xml schema lists the available tables in
Reporting.
<?xml version="1.0"?>
<!--A reference xml file listing all tables involved in the reporting
module -->

<database>
<schema name="teamsite_report_schema">
<table name="EventsSummary"/>
<table name="WFEventsSummary"/>
<table name="Files"/>
<table name="FileVersions"/>
<table name="WFTaskEventComments"/>
<table name="ExtendedAttributes"/>
<table name="VersionedFileEAs"/>
<table name="DataCaptureTemplates"/>
<table name="report5_view"/>
<table name="report6_view"/>
</schema>
</database>

Every table has a schema that describes the columns. Most of the columns are
self-explanatory and use basic data types as described in the schema. All tables in the
reporting database schema have an ID column. This column is used to uniquely identify
a row in each table. This ID is globally unique across the entire schema. The ID column
is also the primary key in each case.

For example, the following code from a schema describes the FileVersions table. Each
row in this table represents a particular version of a file or directory in TeamSite. Each
time a submit event is generated, each file associated with the submit is entered as one
row in this table.
- <table name="FileVersions">
<attribute name="ID" type="char(40)" not_null="true" />
<attribute name="EventID" type="char(40)" not_null="true" />
<attribute name="SubmitType" type="varchar(32)" not_null="true" />
<attribute name="FileID" type="char(40)" not_null="true" />
<attribute name="FileType" type="varchar(32)" not_null="true" />
<attribute name="LastModifier" type="varchar(32)" not_null="true" />
<attribute name="ContentModificationTime" type="datetime"
not_null="true" />
<attribute name="AttributeModificationTime" type="datetime"
not_null="true" />
<attribute name="Comments" type="blob" not_null="false" />
<attribute name="Version" type="varchar(255)" not_null="true" />
<attribute name="DctId" type="char(40)" not_null="false" />
<attribute name="DcrId" type="char(40)" not_null="false" />
</table>

Interwoven, Inc. 224


Appendix A: Configuring TeamSite ReportCenter

This table has four columns that serve as foreign keys indexing into the other reporting
tables (as illustrated in Figure 39):
1. EventID: This column maps to the ID columns in WFEventsSummary table and
EventsSummary table. Since the ID column is a globally unique identifier, it is safe
to use one column to map to two separate tables. This column identifies the event
associated with this file version.
d. FileID: This column maps to the ID column in the Files table. This provides the
file name and path information for this particular file version.
e. DctID: This column maps to the ID column in the DataCaptureTemplates table
and provides the category and type information of the data capture template
used to create this data record. If a particular file version is not a data record,
then this column has a null value.
f. DcrID: This column maps to the ID column in the FileVersions table itself. This
column identifies the particular version of the data record used to generate the
applicable output file.

Each database type has its own schema. The schemas are located in the
iw-home\tsreport\conf\ddl directory and are named: db2_schema.xml,
mssql_schema.xml, mysql_schema.xml, and oracle_schema.xml. Except for the
attributes and values for the <jdbc> element and the datatypes of the columns, the files
are identical.

The other reports defined in the tables.xml schema are described here and the mapping
relationships are illustrated in Figure 39:
„ EventsSummary. Every TeamSite event, with the exception of workflow-related
events, is archived in this table. Each event is persisted as a separate row in this
table.
„ WFEventsSummary. All events generated by the TeamSite workflow engine are
archived in this table.
„ Files. This table contains all files in the TeamSite repository that are either
versioned or were at any time part of a workflow task. The entries in this table are
vpaths and do not by themselves provide any version information.
„ ExtendedAttributes. This table contains a list of all extended attribute key/value
pairs. Each row in the table is a unique extended attribute name and value.
„ DataCaptureTemplates. This table contains all the category and type information
for all the templates defined in TeamSite. Each row in the table uniquely represents
a particular category and type.
„ WFTaskEventComments. This table contains all comments associated with a
particular task or job event. Any job or task transition to a particular state generates
an event, which could potentially have comments associated with it. All these
comments are archived in this table. The table has a column EventID that serves as a
foreign key and maps to the ID column in the WFEventsSummary table.
„ VersionedFileEAs. This table establishes a many-to-many relationship between the
FileVersions table and the ExtendedAttributes table. In TeamSite, one file can have

TeamSite Administration Guide 225


Appendix A: Configuring TeamSite ReportCenter

many extended attributes and a single key/value pair can be an extended attribute on
multiple files. The two main columns in this table are:
a. VersionedFileID: This foreign key maps to the ID column in the FileVersions
table and represents a particular file version.
b. EAID: This columns maps to the ID column in the ExtendedAttributes table
and represents one particular extended attribute.

Interwoven, Inc. 226


Appendix A: Configuring TeamSite ReportCenter

Figure 39 Relationship of Reporting database schemas

TeamSite Administration Guide 227


Appendix A: Configuring TeamSite ReportCenter

Crystal Enterprise Configuration


This section provides information on issues related to configuring Crystal Enterprise
software for use with TeamSite ReportCenter.

Running on a Windows Server


Crystal Enterprise and TeamSite do not run on the same computer when using Windows
operating systems. Crystal Enterprise 11 installs a version of libeay32.dll under the
SYSTEM32 directory which is incompatible with CSSDK. A workaround for this problem
is to move the offending dll from SYSTEM32 to the Crystal Enterprise executable
directory. By default, this directory is c:\Program Files\Crystal
Decisions\Enterprise 11\win32_x86.

Database Drivers
The Crystal Enterprise server must have the appropriate database client drivers installed
and configured. Because Crystal Enterprise accesses the TeamSite Events database
when rendering the TeamSite reports, the Crystal Enterprise server must be configured
appropriately to have access to this database. For example, it may be required to have an
ODBC System DSN entry referring to the TeamSite events database on a Crystal
Enterprise server. In the case of Oracle, it may be required to install an Oracle client
with the appropriate TNS setup on the Crystal Enterprise server. Please refer to the
Crystal Enterprise Administrative Guide and the appropriate database manuals for
details.

Displaying Reports in ContentCenter


The ContentCenter Reporting tab is designed to display only those reports residing
under a specified directory. The name of the directory is configured by the TeamSite
administrator in the TeamSite Reporting installer module. The administrator should
install the TeamSite reports under this directory on the Crystal Enterprise server. Please
refer to the Crystal Enterprise Administrative Guide for more details on creating
directories and deploying reports.

To create a folder under Crystal Enterprise:


1. Open the Admin Launchpad. From the Launchpad, open the Crystal Management
Console (CMC).
2. Log in as Administrator.
3. Select Organize > Folders.
4. Click New Folder. Enter the new folder name (for example, TeamSite Reports).

Interwoven, Inc. 228


Appendix A: Configuring TeamSite ReportCenter

To import reports under Crystal Enterprise:


1. Open the Admin Launchpad. From the Launchpad, open CMC.
2. Log in as Administrator.
3. Under Organize > Folders.
4. Select the folder and/or subfolder where the report is to reside. Repeat until the
desired location is reached.
5. Click New Object.
6. Browse for the report on the local system. Click OK.

Repeat steps 4-6 for all other reports.

Setting up Individual Users


Individual users need to be configured on Crystal Enterprise, since Crystal Enterprise
has its own authentication mechanisms. Please refer to the Crystal Enterprise
Administrative Guide for more details.

Although Crystal Enterprise natively supports NT login as an authentication method, the


ContentCenter Professional Reporting tab only supports login through the Crystal
Enterprise or LDAP authentication methods.

Reports on Crystal Enterprise have Crystal-proprietary ACLs associated with them. For
a user to view a TeamSite report, the users should have “View on Demand” rights
granted to them on the reports (or the folder that contains these reports).

To set the View On Demand ACL on the TeamSite Reports folder:


1. Open the Admin Launchpad. From the Launchpad, open CMC. Navigate to the
TeamSite reports root folder.
2. Click on the Rights tab.
3. Grant all relevant users and groups View On Demand access level.

Clicking the ContentCenter Logout link will also log the user out of Crystal Enterprise
if the user has logged into reporting during the TeamSite session. Only the session
created within ContentCenter is logged out. Crystal Enterprise sessions in other
windows, including those pointed to the Crystal Enterprise user interface, are not
affected.

Troubleshooting
This section contains troubleshooting issues related to Reporting.

TeamSite Administration Guide 229


Appendix A: Configuring TeamSite ReportCenter

Error Messages Displayed in ContentCenter

If generating a report from ContentCenter results in an error message from Crystal


Enterprise, the message displays in ContentCenter. Check the Crystal Enterprise
documentation and online knowledge base for details.

Large Number of Files

If you have a large number of files submitted, such that a report may return more than
20,000 files, you need to change the Crystal Enterprise configuration to allow the larger
number of files. Otherwise, ContentCenter users will see an error message. Refer to the
Crystal Enterprise online knowledge base.

Configuring Microsoft SQL Server 2005 for Use with TeamSite Report Center
NOTE
To configure the SQL Server 2005 for use with the Event Subsystem, refer to
“Configuring Microsoft SQL Server 2005 for Use with the Event Subsystem” on page 54.

To use the Microsoft SQL Server 2005 with the TeamSite Report Center, install and
configure MSSQL Server 2005 manually as follows:
1. Stop the Interwoven TeamSite Report Service. Use the Services control panel.
2. Uninstall the Interwoven TeamSite Report Service:
iw-home\tsreport\bin\tsreport.exe -uninstall iwtsreport

3. Obtain the MSSQLServer 2005 JDBC driver jar file sqljdbc.jar.


4. Copy the file into the iw-home\tsreport\lib directory.
5. Back up the iw-home\tsreport\conf\ddl\mssql_schema.xml file.
6. Edit the following element in iw-home\tsreport\conf\ddl\mssql_schema.xml:
<jdbc driver="com.microsoft.jdbc.sqlserver.SQLServerDriver"

url="jdbc:microsoft:sqlserver://_SERVERNAME_:_PORT_;databaseName=_DATA
BASE_;selectMethod=cursor;"/>
So that it appears as follows:
<jdbc driver="com.microsoft.sqlserver.jdbc.SQLServerDriver"

url="jdbc:sqlserver://_SERVERNAME_:_PORT_;databaseName=_DATABASE_"/>

NOTE
Do not substitute the tags with "_" (underbar) with the actual values.

Interwoven, Inc. 230


Appendix A: Configuring TeamSite ReportCenter

7. Configure the database on MSSQLServer 2005:


<iw-home>\tools\java\jre\bin\java.exe -Diw.home="<iw-home>"
-classpath "iw-home/cssdk/cssdkiface.jar";
"iw-home/cssdk/cssdkjni.jar";
"iw-home/cssdk/cssdkjni.jar";
"iw-home/eventsubsystem/lib/openjms-client-0.7.6.1.jar";
"iw-home/eventsubsystem/lib/log4j-1.2.7.jar";
"iw-home/eventsubsystem/lib/jndi-1.2.1.jar";
"iw-home/eventsubsystem/lib/xerces-2.3.0.jar";
"iw-home/eventsubsystem/lib/xml-apis-1.0.b2.jar";
"iw-home/tsreport/lib/message100.jar";
"iw-home/tsreport/lib/classes12.zip";
"iw-home/tsreport/lib/tsreport.jar";
"iw-home/tsreport/lib/serverutils100.jar";
"iw-home/tsreport/lib/sharedutils100.jar";
"iw-home/tsreport/lib/sqljdbc.jar"
com.interwoven.tsreport.tools.ConfigTool
-schema "iw-home\tsreport\conf\ddl\mssql_schema.xml"
-dbuser <database admin user name>
-dbpasswd <the above user password>
-dbserver <database server name>
-dbname <database name>
-dbport <database listen port>
-license <TeamSite Report Server license key>
-jndiport <TeamSite Event Subsystem JNDI server port number (default
is 3035)>
-iwhome iw-home
-iwlogs <logs directory (default is <iw-home>\local\logs)>

8. Rebuild the Interwoven TeamSite Report Service:


iw-home\tsreport\bin\tsreport.exe -install iwtsreport
iw-home\tools\java\jre\bin\server\jvm.dll
-Doracle.jdbc.V8Compatibility=true
-Djava.class.path="iw-home/cssdk/cssdkiface.jar";
"iw-home/cssdk/cssdkjni.jar";
"iw-home/cssdk/cssdkjni.jar";
"iw-home/eventsubsystem/lib/openjms-client-0.7.6.1.jar";
"iw-home/eventsubsystem/lib/log4j-1.2.7.jar";
"iw-home/eventsubsystem/lib/jndi-1.2.1.jar";
"iw-home/eventsubsystem/lib/xerces-2.3.0.jar";
"iw-home/eventsubsystem/lib/xml-apis-1.0.b2.jar";
"iw-home/tsreport/lib/message100.jar";
"iw-home/tsreport/lib/tsreport.jar";
"iw-home/tsreport/lib/sharedutils100.jar";
"iw-home/tsreport/lib/serverutils100.jar";
"iw-home/tsreport/lib/sqljdbc.jar";
"iw-home/tsreport/lib/classes12.zip";
"iw-home/tsreport/lib/xml100.jar"
-Djava.library.path="<iw-home>\lib";"iw-home\cssdk"

TeamSite Administration Guide 231


Appendix A: Configuring TeamSite ReportCenter

-start com.interwoven.tsreport.server.ReportServer
-params -startServer -config "iw-home\tsreport\conf\tsreport.xml"
-stop com.interwoven.tsreport.server.ReportServer
-params -stopServer -config "iw-home\tsreport\conf\tsreport.xml"
-out "<logs directory>\tsreport_out.log"
-err "<logs directory>\tsreport_err.log"
-current "iw-home\tsreport\bin"
-path "iw-home\tools\java\jre\bin"
-displayname "Interwoven TeamSite Report Service"
-startupmode automatic
9. Use the Services control panel to start the TeamSite Report Service.

Interwoven, Inc. 232


Appendix B

ECM Connector

This appendix describes the configuration and usage of the ECM Connector feature.
ECM Connector provides Web content developers seamless access to the business and
creative content managed in WorkSite MP and MediaBin repositories when using
TeamSite for performing Web content management tasks.

The following topics are described in this chapter:


„ Connector Configuration
„ FormsPublisher Configuration Files
„ Using ECM Connector
„ MetaData XML Record
„ WorkSite MP Configuration
„ MediaBin Configuration
„ Troubleshooting

Connector Configuration
Configuration of ECM Connector involves establishing connectors between the
TeamSite server and the WorkSite MP or MediaBin servers. Connectors can be
established using one of the following methods:
„ Trusted login. Connection is attempted using the TeamSite user’s personal
TeamSite login information. For trusted login to work correctly with WorkSite MP,
an account with the same user name as the TeamSite user must exist on the on the
WorkSite MP server. MediaBin trusted login is accomplished using LDAP
authentication. An entry matching the TeamSite user name must be present in the
LDAP.
Trusted login is not supported for root (UNIX) or Administrator (Windows)
accounts. It is intended only for end users.
See “WorkSite MP Configuration” on page 254 and “MediaBin Configuration” on
page 255 for more information.
„ Guest login. Connection is attempted using a “Guest” account established on the
WorkSite MP or MediaBin server for use with TeamSite. This account information
must be configured in TeamSite prior to the connection being attempted. This single
account applies to all TeamSite users. This method is also known as “proxy login.”

TeamSite Administration Guide 233


Appendix B: ECM Connector

When TeamSite connects to MediaBin or WorkSite MP, it does not use the identity
of the current TeamSite user. Instead, it impersonates a MediaBin or WorkSite MP
user. The credentials of these “proxy users” are stored in the TeamSite system and
are used by all TeamSite users. It is recommended that you not use the credentials of
a real person, but instead create dedicated user accounts in MediaBin and WorkSite
MP for use as TeamSite proxy users. The proxy users should be given read access to
those assets that are to be made available to TeamSite; they do not need any write
privileges.
„ Fail through. The initial connection is made using the TeamSite user’s personal
information. If that attempt fails, then the connection is reattempted using the Guest
account information.

Each server connector exists independently of the other. For example, you can configure
a trusted login connector between your TeamSite and the WorkSite MP servers, and a
guest login connector between your TeamSite and MediaBin servers.

Configuration of the connection to the MediaBin and WorkSite MP servers is performed


through the TeamSite Administration tab. When ECM Connector is installed, its
associated ECM Connector folder appears under the Configuration section. The ECM
Connector folder has links for configuring the connectors to WorkSite MP and
MediaBin.

WorkSite MP
Select the WorkSite MP link to display the WorkSite MP Properties screen (Figure 40).

Figure 40 WorkSite MP Properties Screen

Interwoven, Inc. 234


Appendix B: ECM Connector

Complete the following attributes in each of the following sections to configure your
WorkSite MP connector:
„ Cluster:
‰ Enter the cluster address of the WorkSite MP server. It is recommended that you
use a resolvable host name rather than an IP address.
‰ Check the associated box to enable a connection to the WorkSite MP server you
specified.
‰ Enter the process manager (PM) password (if one has been set) in the PM
Password field.

NOTE
In some cases, changing the cluster address or PM password values will require
resetting the TeamSite user interface. To reset the TeamSite user interface, run the
following command:
iw-home/bin/iwreset -ui

„ Authorization:
Select one of the following authorization options when connecting to WorkSite MP:
‰ Login as the TeamSite user. Login to the WorkSite MP server will be done
using the same user name that was used to login to the TeamSite server.
‰ Login with a WorkSite MP guest account. Login with the guest user account
you set up on the WorkSite MP server for use with your TeamSite server.
‰ Try to login as the TeamSite user, but use the WorkSite MP guest account if
unsuccessful. This option uses your TeamSite user login information first, but if
it is not successful, then it will try the WorkSite MP guest account
automatically.
„ TeamSite User:
Complete the following attribute if either the Login as the TeamSite user or Try to
login as the TeamSite user, but use the WorkSite MP guest account if
unsuccessful option was selected as your Authorization option:
‰ Enter the WorkSite MP domain of the TeamSite user in the Domain field under
TeamSite User. When logging in with the TeamSite user ID, all users must be in
the same WorkSite MP domain. For example, if the WorkSite MP domain is set
to mycompany.com and a user logs into TeamSite as one of the following:
Windows. MYCOMPANY\jdoe
The information used to log into WorkSite MP would be userid=jdoe and
domain=mycompany.com.

TeamSite Administration Guide 235


Appendix B: ECM Connector

„ Guest User:
Complete the following attributes if either the Login with a WorkSite MP guest
account or Try to login as the TeamSite user, but use the WorkSite MP guest
account if unsuccessful option was selected as your Authorization option:
‰ Enter the WorkSite MP user name of the account in the Name field.
‰ Enter the WorkSite MP domain (if necessary) in the Domain field.
‰ Enter the password associated with the user name in the Password field.
„ Destination:
‰ Enter the default directory within your TeamSite workarea under which any
files imported from the WorkSite MP server when using FormsPublisher are
written. Note that when you are importing WorkSite MP files using the Import
command, files are stored in your current working directory.

Click OK when you have completed the necessary attribute values. Your WorkSite MP
connector is now configured.

MediaBin
Select the MediaBin link to display the MediaBin Properties screen (Figure 41).

Figure 41 MediaBin Properties Screen

Interwoven, Inc. 236


Appendix B: ECM Connector

Complete the following attributes in each of the following sections to configure your
MediaBin connector:
„ Server:
‰ Enter the name of the MediaBin server hosting the Web services.
‰ Check the associated box to enable a connection to the MediaBin server you
specified.
‰ Enter the appropriate URL to point to the MediaBin web services in the WSDL
URL field. In most cases you can simply change the host name in the default
value.
„ Authorization:
Select one of the following authorization options:
‰ Login as the TeamSite user. Login to the MediaBin server will be done using
the same user name that was used to login to the TeamSite server. An entry for
this TeamSite user must be present in the LDAP used by MediaBin.
‰ Login with a MediaBin guest account. Login with the guest user account you
set up on the MediaBin server for use with your TeamSite server.
‰ Try to login as the TeamSite user, but use the MediaBin guest account if
unsuccessful. This option uses your TeamSite user login information first, but if
it is not successful, then it will try the MediaBin guest account automatically.
„ Trusted Client:
Complete the following attribute if either the Login as the TeamSite user or Try to
login as the TeamSite user, but use the MediaBin guest account if unsuccessful
option was selected as your Authorization option.
‰ Enter the hint required for trusted client access in the Hint field. This is the
same value as is used in the MediaBin web.config file’s TrustedClientHint
value.
„ Guest User:
Complete the following attributes if either the Login with a MediaBin guest
account or Try to login as the TeamSite user, but use the MediaBin guest account
if unsuccessful option was selected as your Authorization option:
‰ Enter the MediaBin user name of the account in the Name field.
‰ Enter the MediaBin domain (if necessary) in the Domain field.
‰ Enter the password associated with the user name in the Password field.
„ Destination:
‰ Enter the directory within your TeamSite workarea in which any files imported
from the MediaBin server when using FormsPublisher are written. Note that
when you are importing MediaBin assets using the Import command, files are
stored in your current working directory.

TeamSite Administration Guide 237


Appendix B: ECM Connector

„ Web Client:
‰ Enter the appropriate URL to point to the MediaBin server on which you can
edit assets selected within TeamSite. In most cases you can simply change the
host name in the default value.

Click OK when you have completed the necessary attribute values. Your MediaBin
connector is now configured.

FormsPublisher Configuration Files


The following FormsPublisher configuration files must be modified to use ECM
Connector:
„ datacapture.cfg. Defines rule sets for capturing data.
„ Presentation templates (.tpl files). Contains HTML code and FormsPublisher tags
to describe the output files.

Samples of these files are included in the following location:


„ iw-home/examples/Templating/templatedata/ecm/press-release
„ iw-home/examples/Templating/templatedata/ecm/press-release-immediate
„ iw-home/examples/Templating/templatedata/ecm/press-release-iwov

Refer to the README file residing at the following location for descriptions of each of
these samples:
iw-home/examples/Templating/templatedata

This chapter assumes the reader is familiar with creating FormsPublisher


datacapture.cfg files and presentation templates. Refer to the TeamSite
FormsPublisher Developer’s Guide for more information.

datacapture.cfg
You can incorporate WorkSite MP or MediaBin functionality in your FormsPublisher
form by including a dialog for either or both remote servers in your associated
datacapture.cfg file. In the datacapture.cfg file, dialogs are configured using the
dialog element. Each dialog has a set of named parameters that are used to connect the
FormsPublisher form fields to the dialog’s inputs and outputs.

Each parameter can have an input, an output, or both. An input parameter can have an
actual value, or it can reference an item whose value will be obtained when the dialog is
activated. An output parameter can only reference an item whose value will be set by the
dialog. Input and output parameters vary between WorkSite MP and MediaBin. Some
parameters are shared by both remote servers, while others are unique to one or the
other. The set of output parameters can also be different depending on whether the form

Interwoven, Inc. 238


Appendix B: ECM Connector

is configured to import files from the remote server immediately upon selection, or
whether to wait until the Web page is actually generated.

Dialog parameters reference items by name, not by path. When a dialog references an
item, it first looks for an item with that name in the same container as the dialog itself. If
it is not found, then it looks in the enclosing (parent) container, and so on up the
hierarchy.

You can configure the dialog element anywhere that an item element can appear. The
dialog element has the following attributes:

„ type. Specify one of the following values to indicate what type of remote server is
being represented:
‰ worksite
‰ mediabin

You must specify a value. There is no default value.


„ label. Specify the text that appears on the button, for example WorkSite or Browse
for Document.

The following configuration inserts a WorkSite MP field into the form, and gives the
associated button the label “WorkSite”:
<dialog type="worksite" label="WorkSite">
...
</dialog>

The dialog element can also include the optional rowcontinue and window-features
attributes, which are used elsewhere in the datacapture.cfg file. Refer to the
FormsPublisher documentation for more information.

Each parameter associated with the dialog is configured within the dialog element as a
separate dialog-param element. The type of parameter is specified by the
dialog-param element’s name attribute. For example:
<dialog type="worksite" label="WorkSite">
<dialog-param name="path">
...
</dialog-param>
...
</dialog>

Inputs and outputs are configured within each dialog-param element using the
dialog-input and dialog-output elements, respectively. Both these types of elements
include the field-ref sub-element, which associates the item reference to the input or
output.

In the following example, the parameter “path” includes both an input and an output,
while the parameter “label” includes only an output.
<dialog type="worksite" label="WorkSite">
<dialog-param name="path">
<dialog-input><field-ref name="path"/></dialog-input>

TeamSite Administration Guide 239


Appendix B: ECM Connector

<dialog-output><field-ref name="path"/></dialog-output>
</dialog-param>
<dialog-param name="label">
<dialog-output><field-ref name="label"/></dialog-output>
</dialog-param>

Here is a list of parameters used by WorkSite MP and MediaBin:


„ WorkSite MP:
‰ immediate. Indicate whether (true) or not (false) the selected WorkSite MP
document file is to be imported into TeamSite at the time it is selected within
FormsPublisher, or whether it will exist as a reference pointer until the Web
page is actually generated. Default value is false.
‰ asset-id. The WorkSite MP ID value for the selected document. The value can
later be used by the presentation template import tags to import the selected
asset. When you specify an input value, it indicates a previously-selected asset
that allows the browser to open up in the context of that asset.
‰ category-id. The default WorkSite MP ID for the container (category or
folder) in which the selected asset was found, or a user-defined container value.
Specifying an input value results in the WorkSite MP document being opened in
that category. This is option is provided because in a WorkSite MP knowledge
space, a single document may appear in more than one category.
‰ label. The default file name of the WorkSite MP document you selected, or a
user-define label value. The value you use will appear as the hyperlink text to
the WorkSite MP document in the generated Web page.
‰ path. Displays a path on the WorkSite MP server where the document file can
be accessed.
‰ arearelpath. Indicates the path to the imported WorkSite MP document
relative to the TeamSite workarea. This value only applies if immediate="true".
„ MediaBin:
‰ immediate. Indicate whether (true) or not (false) the selected MediaBin asset
file is to be imported into TeamSite at the time it is selected within
FormsPublisher, or whether it will exist as a reference pointer until the Web
page is actually generated. Default value is false.
‰ asset-id. The MediaBin ID value for the selected digital asset. The value can
later be used by the presentation template import tags to import the selected
asset. When you specify an input value, it indicates a previously-selected asset
that allows the browser to open up in the context of that asset.
‰ label. The default file name of the MediaBin asset you selected, or a
user-defined label value. The value you use will appear as the hyperlink text to
the WorkSite MP document in the generated Web page.
‰ path. Displays a path on the MediaBin server where the document file can be
accessed.
‰ arearelpath. Indicates the path to the imported MediaBin document relative to
the TeamSite workarea. This value only applies if immediate="true".

Interwoven, Inc. 240


Appendix B: ECM Connector

‰ format. The desired format for the asset rendition. Use of the following values:
• GIF

• JPG

• JPEG

‰ task. The name of the desired retrieval task.


‰ width (optional). The width in pixels of the asset.
‰ height (optional). The heght in pixels of the asset.
‰ ceilingDirectory (optional). The MediaBin container path that the user can
browse. The user can only browse assets and containers under this directory.The
leading slash is required; do not include a trailing slash.
Example: /Media Database/TestFolder
‰ destinationDirectory (optional). The path relative to the TeamSite workarea
where the selected MediaBin asset should be imported. This value only applies
if immediate=”true”. The MediaBin asset’s path in the MediaBin repository is
not re-created under this TeamSite directory.
Example: pressRelease/images
Use of the format parameter is not compatible with the task, width, and height
parameters. If you do not specify any of these parameters, then the asset is imported
in its existing state.
The original proportions of the asset will be maintained even if the specified width
and height do not conform to those original proportions. If you specify the width
and height parameter values as each being “0”, then the original dimensions of the
asset are used.

Presentation Template Files


ECM Connector makes the following tags available to the presentation templates:
„ iwov_import_mediabin. Creates a TeamSite file that is a copy or derivative of an
asset in MediaBin. It then emits a URL that points to the imported file. The URL
will be relative to the workarea of the data capture record.
„ iwov_import_worksite. Creates a TeamSite file that is a copy of a document in
WorkSite MP. It then emits a link (anchor tag) that points to the imported file. The
URL in that anchor will be relative to the workarea of the data capture record.
„ iwov_link_worksite. Emits a link (anchor tag) that points to a document in
WorkSite MP. If the user clicks on the link and is not already logged into WorkSite
MP, the WorkSite MP login page is displayed and a valid username and password
must be given in order to proceed. The normal WorkSite MP access control will be
enforced, so the user cannot view the document unless permission has been granted
to the user.

Refer to your sample presentation templates that were installed with ECM Connector to
get additional usage information.

TeamSite Administration Guide 241


Appendix B: ECM Connector

These tags require the IW_AUTH environment variable to be set to a valid value. This
variable will be set when the presentation template is invoked from the user interface or
a workflow external task. If you want to test the presentation template from the
command line, you must set this variable before calling the iwpt_compile CLT.

When these tags are used in a presentation template, the template may not function if it
is applied from the command line (for example, using iwgen or iwregen) or in a
nonstandard execution environment. These tags require access to a valid TeamSite
session string. The session string is provided by ContentCenter when the Preview or
Generate commands are performed and is provided by the workflow engine if the
template is applied in an external task.This IW_AUTH environment variable can be set to a
valid session string if one is not already available

You can also run the perldoc program to get more information on these tags. To run this
program, navigate to the following location:
iw-home/iw-perl/bin

and enter the following command at the prompt:


„ Windows. perldoc.bat tagname
„ UNIX. perldoc tagname

where tagname is one of the ECM Connector tags listed at the beginning of this section,
for example:
perdoc.bat TeamSite::PT::iwov_import_mediabin

Using ECM Connector


This section describes how to use ECM Connector within TeamSite. You can use ECM
Connector in the following methods:
„ FormsPublisher. Import MediaBin digital assets and links to WorkSite MP
documents into your Web page using the FormsPublisher user interface.
When ECM Connector is installed and configured, additional controls are present in
the FormsPublisher user interface where you can browse and search the associated
WorkSite MP or MediaBin server for the items you want to include.
„ File import. Import MediaBin digital assets and WorkSite MP documents into your
workarea.

FormsPublisher
This section assumes that you are familiar with the use of FormsPublisher, including
generating and previewing Web pages. Refer to your TeamSite FormsPublisher
Developer’s Guide documentation for general information on FormsPublisher. This
section describes how to use ECM Connector in the FormsPublisher context.

Interwoven, Inc. 242


Appendix B: ECM Connector

Names for items in the FormsPublisher user interface, such as for fields and buttons, are
user-defined. Terms that appear in the following sections are only examples.

When ECM Connector is installed and configured, additional controls are present in the
FormsPublisher user interface where you can browse and search the associated
WorkSite MP or MediaBin server for the items you want to include.

WorkSite MP
You can insert links to WorkSite MP documents into FormsPublisher. Depending on
your presentation template, this link is subsequently represented as a hyperlink in the
generated Web page.

Figure 42 shows an example of the WorkSite MP field in FormsPublisher.

Figure 42 WorkSite MP Field in FormsPublisher

Click the WorkSite button to display the WorkSite MP Browser screen appears
(Figure 43), which shows files that reside on the WorkSite MP server.

Figure 43 WorkSite MP Browser

You can navigate through the different workspaces on the server until you find the
document file you want. You can also click Find to search the current directory for files
based on their file names, or specify files by type. This feature searches the working
repository or container, such as a workspace, directory, or category, as well as any
sub-repositories contained within the working one.

TeamSite Administration Guide 243


Appendix B: ECM Connector

Select the document file you want and click OK. In this example, we have navigated to
the following WorkSite MP location:
Employee Personal Workspaces/Analyst Day - internal/
ANALYST DAY MATERIALS

and have selected the file Anaylist Day Feedback.doc (Figure 44):

Figure 44 WorkSite MP Browser with Selected File

When the WorkSite MP browser displays files, it provides the option of viewing
additional information on any given file. Click Properties to display the Document
Properties screen, which lists a variety of properties associated with the file (Figure 45).

Figure 45 Document Properties Screen

You can open the file through the WorkSite MP user interface by clicking Open in
WorkSite. Otherwise, click Close to return to the WorkSite MP Browser.

Interwoven, Inc. 244


Appendix B: ECM Connector

Click OK to select the highlighted document. Otherwise, click Cancel to return to


FormsPublisher without a document selection. The FormsPublisher screen returns, with
the path to the file contained in the Source field, and by default, the file name contained
in the Link Label field (Figure 46).

Figure 46 WorkSite MP Field with Document File Information

You can modify the Link Label value to another term if you want. The text contained in
the Link Label field value will be the hyperlink text in the outputted Web page
(Figure 47).

Figure 47 WorkSite MP Hyperlink in Outputted Web Page

MediaBin
Figure 48 shows an example of the MediaBin field in FormsPublisher.

Figure 48 MediaBin Field in FormsPublisher

To insert a digital asset that resides on the MediaBin server into your Web page, click
the MediaBin button. The MediaBin browser appears (Figure 49), which represents the
file system on the MediaBin server.

TeamSite Administration Guide 245


Appendix B: ECM Connector

Figure 49 MediaBin Browser Screen

Directories appear as folder icons in the MediaBin browser, while files appear in
thumbnail form.

You can navigate through the different folders on the server until you find the digital
asset file you want. You can also click Find to search the current directory for files
based on their file names.

Select the document file you want and click OK. In this example, we have navigated to
the following MediaBin directory:
Photography/Stock/Corel_PSDs/AutoRacing

and have selected the file 21003.PSD (Figure 44):

Figure 50 MediaBin Browser with Selected File

Click Properties to display the Asset Properties screen, which lists a variety of
properties associated with the file (Figure 45).

Interwoven, Inc. 246


Appendix B: ECM Connector

Figure 51 Asset Properties Screen

You can view an enlarged version of the selected file by clicking on its thumbnail image.

You can open the file through the MediaBin user interface by clicking Open in
MediaBin. Otherwise, click Close to return to the MediaBin Browser.

From the MediaBin browser, when you select an item, you can also click Find Similar
to locate all assets that are similar to the selected image. The results are ordered by how
closely they resemble the original. This does not apply to non-image assets. You can
also add metadata criteria to similar image searches to refine your results even further.
Refer to your MediaBin documentation for more information on this feature.

Click OK when you are finished. The FormsPublisher screen returns, with the path to
the file contained in the File field, and by default, the file name contained in the Label
field (Figure 46).

Figure 52 MediaBin Field With Asset File Information

You can modify the Link Label value to another term if you want. The text contained in
the Label field value will be the Alt text (the text label that appears when you place the
cursor over the object) that accompanies your digital asset in the outputted Web page
(Figure 53).

TeamSite Administration Guide 247


Appendix B: ECM Connector

Figure 53 MediaBin Asset with Alt Value in Outputted Web Page

TeamSite Workarea
This section assumes that you are familiar with the use of the Import feature in the
TeamSite. Refer to the ContentCenter Professional User’s Guide for general information
on the Import feature. This section describes how to use ECM Connector in the context
of importing files to your TeamSite workarea.

When ECM Connector is installed and configured, the existing TeamSite Import feature
is enhanced to allow you to import document and digital asset files from the connected
WorkSite MP and MediaBin servers to your workarea.

Selecting the File > Import command displays the Import to: screen (Figure 54), where
you can select from where you want to import content.

Figure 54 Import to: Screen

Select one of the following options:


„ Import from your local host (this is the legacy functionality of the Import
command).
„ Import from the connected WorkSite MP server.
„ Import from the connected MediaBin server.

Selecting either the WorkSite MP or MediaBin options displays the WorkSite MP


Browser or MediaBin Browser screens, respectively. The screens function in the same
manner as is described in “FormsPublisher” on page 242, except the Import feature has
an additional selection for the retrieval task

When you select the document or digital asset file you want to import and click OK, the
file you selected is imported into your working directory within your TeamSite
workarea. After the file is successfully imported, you can perform the same functions on
that file that you can any other imported file.

Interwoven, Inc. 248


Appendix B: ECM Connector

Editing Imported Files


You can edit files imported from WorkSite MP and MediaBin in the same manner as any
other file contained in your TeamSite workarea. However, when you select an imported
item and click Edit, you are advised that it is preferable that you edit the file from the
WorkSite MP or MediaBin server on which it originated, rather than from TeamSite.

You can access the originating WorkSite MP or MediaBin server by clicking the Open
in WorkSite or Open in MediaBin button that appears in the same window. After
logging in to the appropriate server, you can make the desired modifications, save the
file, and then re-import it into TeamSite.

If it is necessary to open the imported file in TeamSite, you can click the Edit in
TeamSite button, and proceed with your editing. However, note that if a file is imported
to TeamSite and then edited within TeamSite, it is not given any special protection. If
that same image is re-imported to the same location in TeamSite, the file will be
replaced (within the workarea) and the edits may be lost.

Using MediaBin Search in ECM Connector


The text-based search feature used by ECM Connector is equivalent to performing a
search from the MediaBin using the following parameters (Figure 55):

Figure 55 MediaBin Search

MetaData XML Record


WorkSite MP and MediaBin assets have associated metadata. This metadata contains
information about an asset such as the creation date, author name, and description. It can
also contain product-specific information such as a a WorkSite MP document id, and a
MediaBin repository path. For a full list of metadata for both WorkSite MP and
MediaBin assets, refer to the documentation for these products.

TeamSite Administration Guide 249


Appendix B: ECM Connector

In ECM Connector, the metadata associated with an imported WorkSite MP or


MediaBin asset is also imported into TeamSite. The imported metadata is represented as
an XML record, and this XML record is written to a TeamSite extended attribute (EA)
of the imported asset. The EA names are:
„ WorkSite/Metadata. Metadata EA name for a WorkSite MP imported asset.
„ MediaBin/Metadata. Metadata EA name for a MediaBin imported asset;

The format of the metadata XML record is the same for both WorkSite MP and
MediaBin imported assets. The basic structure is a document-level metadata element
that contains namespace attributes, and zero or more attribute metadata child elements
and Dublin Core metadata elements. The following is an example of a partial metadata
XML record for a MediaBin file.
<metadata xmlns:dc="http://purl.org/dc/elements/1.1/"
xmlns:xs="http://www.w3.org/2001/XMLSchema">
<dc:type>JPEG</dc:type>
<attribute>
<name>Asset Type</name>
<value type="xs:string">JPEG</value>
</attribute>
<attribute>
<name>Dimensions (pixels)</name>
<value type="xs:int">300</value>
<value type="xs:int">300</value>
</attribute>
<dc:date.created>2004-10-19T09:50:00</dc:date.created>
...
</metadata>

attribute Metadata Elements


WorkSite MP and MediaBin metadata is represented in the XML record within
attribute elements. The metadata name and value is unaltered from the original asset’s
metadata. An attribute element contains one name child element and zero or more
child elements. The following shows a MediaBin attribute element with a single
value.
<attribute>
<name>Asset Type</name>
<value type="xs:string">JPEG</value>
</attribute>

This example shows a MediaBin attribute element with multiple values.


<attribute>
<name>Dimensions (pixels)</name>
<value type="xs:int">300</value>
<value type="xs:int">300</value>
</attribute>

Interwoven, Inc. 250


Appendix B: ECM Connector

MediaBin metadata comprises both system metadata, such as insertion time, modified
time, and dimensions, and file format specific metadata for formats such as JPEG,
PhotoShop, and MS Office. All this metadata is represented for a single asset. For an
imported MediaBin asset, the metadata concerns the asset in MediaBin, not the
rendition. For example, if a TIFF file is retrieved as a GIF, the attributes regarding the
format, size and dimensions of the asset will be appropriate for the TIFF file.

WorkSite MP metadata is available for the base asset and for versions of that asset, so
differentiation of the metadata’s origin is required.

WorkSite MP attribute Metadata Elements


WorkSite MP assets have metadata for the base asset and versions of that asset. There is
some intersection of this metadata, for example, “description” metadata is given for
both the base asset and versions of that asset.

For WorkSite MP assets, both the base and version metadata is downloaded. For
WorkSite MP metadata XML records only, the attribute element contains a scope
attribute with a value of either document or version. The scope attribute indicates
whether the metadata is for the base asset (document) or for a version of that asset
(version). This example is for WorkSite MP version metadata with a single value.
<attribute scope="version">
<name>BASE::VERSION_NUMBER</name>
<value type="xs:int">2</value>
</attribute>

This example is for WorkSite MP document metadata that has multiple values.
<attribute scope="document">
<name>APP::LABEL_RSID</name>
<value type="xs:string">business</value>
<value type="xs:string">document processing</value>
<value type="xs:string">Interwoven, Inc.</value>
</attribute>

Representation of Data Types


The metadata value element contains a type attribute. This attribute gives the data type
of the metadata value. The W3 standard namespace for data types is used with the
namespace prefix xs. The namespace URI is an attribute of the metadata element. It is
located at the following URL:
http://www.w3.org/2001/XMLSchema

The following data types are represented:


„ boolean
„ dateTime
„ double

TeamSite Administration Guide 251


Appendix B: ECM Connector

„ float
„ int
„ long
„ string

Dublin Core Metadata Elements


The standard Dublin Core metadata element set is used to represent corresponding
WorkSite MP and MediaBin metadata. Dublin Core metadata elements are qualified by
the Dublin Core namespace with the namespace prefix dc. The namespace URI is an
attribute of the metadata element. It is located at the following URL:
http://purl.org/dc/elements/1.1/

The Dublin Core standard permits omitted or repeated metadata elements. The Dublin
Core element set comprises the following elements:
„ Title
„ Creator
„ Subject
„ Description
„ Publisher
„ Contributor
„ Content
„ Date
„ Type
„ Format
„ Identifier
„ Source
„ Language
„ Relation
„ Coverage
„ Rights

For the Dublin Core Date metadata element there are two qualifiers applied:
„ Created
„ Modified

WorkSite MP and MediaBin metadata elements that correspond to Dublin Core


metadata elements are represented in the metadata XML record as the following:
„ A Dublin Core metadata element
„ A proprietary metadata element

Interwoven, Inc. 252


Appendix B: ECM Connector

This example shows the two elements representing MediaBin’s “Asset Type” metadata:
a Dublin Core dc:type element and an attribute element.
<dc:type>JPEG</dc:type>
<attribute>
<name>Asset Type</name>
<value type="xs:string">JPEG</value>
</attribute>

The following table lists WorkSite MP metadata elements that correspond to Dublin
Core metadata elements:

Table 18 WorkSite MP metadata elements


WorkSite MP Dublin Core
Owner Creator
Number Identifier
Name Title
Description Description
Created Date Date Created
Modified Date Date Modified

The following table lists MediaBin metadata elements that correspond to Dublin Core
metadata elements:

Table 19 MediaBin metadata elements


MediaBin Dublin Core
Name Title
Asset Type Type
Check In User Creator
Insertion Time Date Created
Modified Time Date Modified

Custom Metadata
Both WorkSite MP and MediaBin support the generation of custom metadata.
WorkSite MP custom metadata allows the generation of multi-level metadata. Currently,
only the first level of metadata is captured. MediaBin custom metadata associated with
an asset is captured along with the system and file format specific metadata.

TeamSite Administration Guide 253


Appendix B: ECM Connector

WorkSite MP Configuration
This section contains instructions for configuring your WorkSite MP server for use with
ECM Connector 2.0. The instructions contained here are supplemental to the WorkSite
MP product documentation.

Configuring WorkSite MP with the User Interface Location


If you want ContentCenter to contain links back to the WorkSite MP user interface, or if
you want to use FormsPublisher to create web pages with links back to the WorkSite MP
server, then WorkSite MP must be configured with the location of the user interface.
This is set as the “URL site prefix” in the configuration of the notification service. Refer
to your WorkSite MP documentation for more information.

Configuring WorkSite MP Trusted Login


You must perform the tasks described in this section to enable the WorkSite MP trusted
login feature.

Enabling External Authentication for Libraries

The ability to allow external authentication for enterprise users must be enabled for the
authentication library. From the Configuration Manager, navigate to the Edit
Cluster:CMS Settings window, select the authentication library, and check the Allow
external authentication for enterprise users option. Save and close the window.

Enabling Authenticated Login

Follow the instructions for enabling authenticated login in section 2.1.1 of the WorkSite
MP HFB7 release notes.

Allowing Invocation of Authenticated Login

The ability to allow invocation of an authenticated login for an enterprise session must
be enabled. From the Library Manager, navigate to the appropriate cluster and library,
and select the Systems Configurations command. Set the value of the Allows the
invocation of a authenticated logon for an enterprise row to True.

Interwoven, Inc. 254


Appendix B: ECM Connector

Setting the PM Password


To set the process manager (PM) password on your WorkSite MP server, follow these
steps”
1. Navigate to the following location:
worksitemp4/mpserver/bin/platform

2. Run the impmpassword application.


3. Enter and verify your PM password in the dialog box that is displayed.

MediaBin Configuration
This section contains instructions for configuring your MediaBin server for use with
ECM Connector 2.0. The instructions here are supplemental to the MediaBin product
documentation.

The MediaBin Web Service README file contains information on configuring


MediaBin. This file is named readme.txt and resides in the following location:
c:\InetPub\www\MediaBinWebService

Setting Anonymous Access


The MediaBin Web Service depends on anonymous access. To configure this correctly,
follow these steps:
1. For the MediaBinWebService virtual directory, go to the Authentication Methods
screen and turn on the Enable anonymous access check box.
2. For the folder in the MediaBinWebService directory that is used for transferring
files, verify that the Enable anonymous access check box is turned on.
3. Verify that the anonymous user has read and write access to the temporary directory
specified in the TempPath setting in the MediaBin web.config file.

Configuring MediaBin Trusted Client and LDAP Authentication


Refer to the LDAP Support and Trusted Client Support sections in the README file
for the appropriate information.

Additional information is available in the section on configuring the MediaBin Web


service for LDAP support in the MediaBin Asset Server Administration Guide.

TeamSite Administration Guide 255


Appendix B: ECM Connector

Troubleshooting
This information may provide information on issues related to ECM Connector.

Running ECM 1.1 and ECM 2.0 Toolkits Simultaneously


The ECM Connector 1.1 and 2.0 toolkits have not been tested together in the same
ContentCenter Web application. If you are upgrading from a system that uses ECM
Connector 1.x, the recommended best practice is to remove the ECM Connector 1.x
toolkit from ContentCenter and migrate existing datacapture templates and presentation
templates to the ECM Connector 2.0 solution.

If you want to run both the ECM Connector 1.1 and 2.0 toolkits in the same
ContentCenter instance, follow these steps:
1. Back up the following files:
‰ k3.jar
‰ MediaBinServer.jar

from their home location:


iw-home/local/config/lib/content_center/sample_connector_src/lib
into a backup directory.
2. Extract the following files (using tools such as WinZip or Gnu Zip):
‰ wom.jar
‰ MediaBinServer.jar

from the ecmconnector.tk.war file, which resides in the following location:


iw-home/private/lib/content_center

3. Copy the wom.jar and MediaBinServer.jar files to the location referenced in


step 1.
4. Rebuild the ECM Connector 1.1 toolkit. Refer to the instructions included with the
toolkit for more information.

Import from MediaBin Requires Anonymous Access to the Transfer


Directory
The ability to import digital assets from the MediaBin server requires that IIS be
configured to allow anonymous access to the MediaBin transfer directory. By default,
anonymous access to the transfer directory is not enabled. Refer to your MediaBin
documentation for more information on configuring anonymous access.

Interwoven, Inc. 256


Appendix B: ECM Connector

Using IP Address for WorkSite MP Cluster Prevents Trusted Login


If you change the WorkSite MP cluster address from a resolvable host name to an IP
address, the trusted login feature is not supported. It is recommended that you use
resolvable host names rather than IP addresses

Patch Required When Using Microsoft Internet Explorer 6.0 SP1


If you are using Microsoft Internet Explorer 6.0 SP1 as your browser, you must install
the following patch:
Cumulative Security Update for Internet Explorer 6 Service Pack 1 for
Corporations - Windows XP and Windows 2000 (873377)

You can obtain this patch from the following Microsoft Web site:
http://www.microsoft.com/downloads/details.aspx?amp;amp;amp;amp;displayla
ng=en&familyid=8C6560FC-297C-4982-8BA5-DE7949043B17&displaylang=en

NOTE
This link could change at any time.

TeamSite Administration Guide 257


Appendix B: ECM Connector

Interwoven, Inc. 258


Appendix C

Content Transformation
Services

Content Transformation Services Powered by CambridgeDocs provides a method for


TeamSite users to convert Microsoft Word documents to PDF or HTML output. If the
content transformation engine is installed, the Convert menu item is added to
ContentCenter menus (see “Using Content Transformation Services” on page 264).
Additionally, two URL Commands are provided (see “URL Commands” on page 262).

The following topics are described in this chapter:


„ Overview
„ Installation
„ URL Commands
„ Removing or Modifying Menu Items
„ Using Content Transformation Services

Overview
This section provides a Content Transformation Services overview. Refer to Figure 56
for an illustration.

With Content Transformation Services, Microsoft Word content is transformed into PDF
or HTML through an intermediate step that saves the content in reusable, sequentially
formatted ppXML. This format exposes the internal structure of the source document,
and can in turn be transformed into a customer-defined schema prior to style sheet
application. The rules for ppXML transformation are built by administrators or
developers using the Developer Workbench GUI.

From the TeamSite end-user perspective, all transformations are initiated through the
ContentCenter user interfaces. The typical end user of the system, using a browser,
communicates exclusively with the TeamSite server. When a document is to be
converted, the TeamSite server fetches the source document from the content store and
sends it, using an HTTP request, to the content transformation engine (the XDoc server
from CambridgeDocs). The content transformation engine writes the file into a
temporary upload directory, writes the converted versions into that directory, and then

TeamSite Administration Guide 259


Appendix C: Content Transformation Services

responds to the request. The response includes a .zip file with all of output files. When
TeamSite receives the response, it unzips the response into its own temporary directory,
reads the results from that directory, and writes the appropriate files to the content store.

For security reasons, the content transformation engine does not have direct access to
the TeamSite content store. If a restricted, confidential document is maintained in
TeamSite and converted by this system, it may be exposed to others in the temporary
directories on the two systems. Normally, the document only exists there for a short time
and is deleted after it has been converted. However, it may remain if an error occurs or
the system is being debugged.

Because all document conversions are initiated by a user action, the content store is
accessed through the ContentServices API using the credentials of the current user. The
user needs read access to the source document and write access to the workarea that
contains it. The user who initiated the conversion owns any files that are created.

If a source document is modified by a user after it has been converted into PDF or
HTML format, the system does not automatically regenerate the output. It does not
report that output is obsolete. The user must regenerate output.

To customize the way the output is shown (such as adding headers or footers or mapping
styles), the templates and configuration on the content transformation engine must be
modified. Refer to the content transformation engine documentation to do this.

Installation
This section describes the recommended installation of Content Transformation
Services for TeamSite on two servers (Figure 56). One server (Server A) hosts
Interwoven TeamSite, and the other server (Server B) hosts the content transformation
engine.

Figure 56 Installation on Two Servers

User’s
Browser

ContentCenter Request
Content
TeamSite Transformation
Response Engine
Server A Server B

Temporary Upload
Directory Directory

Interwoven, Inc. 260


Appendix C: Content Transformation Services

The first server (Server A) has:


„ TeamSite.
„ A new configuration file (transform.cfg).
„ A temporary directory that is accessible to ContentCenter.

The second server (Server B) has:


„ The content transformation engine.
„ A temporary directory that is accessible to the content transformation engine.

Installation Procedure
1. Install TeamSite on Server A. Refer to the TeamSite Installation Guide for
instructions.
2. Install the content transformation engine on Server B. Refer to the documentation
provided with the content transformation engine.
3. Set the TeamSite configuration:
a. Create a directory on Server A and give full control to the owner of the
Interwoven Servlet Engine process. This is usually SYSTEM.
b. Edit the iw-home/local/config/transform.cfg file (see “Editing the
transform.cfg File” on page 262):
• Set the value of <transfer-dir-local> to the path of the directory created
in step 3a.
• Set the value of <url> so that it points to the installation of content
transformation engine.
• Set <conversion> to active="true".
• In the <debugging> section, specify the roles that have the debugging option
in ContentCenter Professional. By default, this option is set to the
Administrator and Master roles. Setting this option places a Show
debugging information checkbox on the Conversion Selection screen. If
the user turns on this feature, the Conversion Results screen contains a link
to a log file. These temporary log files are not removed from the temporary
directory when the debugging feature is activated.
c. Restart the Interwoven Servlet Engine (using iwreset -ui). Restart the Servlet
Engine anytime the configuration file is modified so that the system picks up the
changes.

TeamSite Administration Guide 261


Appendix C: Content Transformation Services

Editing the transform.cfg File


The following code shows the default transform.cfg file. Modify the <debugging>,
<url>, and <transfer-dir-local> sections as directed in the previous section.

<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>

<conversion active="false">
<source-files>
<source extension="doc">
<output-format extension="xml"
implied="true" />
<output-format extension="html"
default-selection="false"
required="false" />
<output-format extension="pdf"
default-selection="false"
required="false" />
</source>
</source-files>
<!-- Roles that will be shown the debugging option -->
<debugging>
<role>master</role>
<role>admin</role>
</debugging>
<service>
<!-- The URL used to invoke the transformation engine.
Replace "localhost" with the name of the server on which
the transformation engine has been installed.
If the instance of Tomcat on that server is not listening to port
8080 (the default), then replace "8080" with the correct port
number.
-->
<url>http://localhost:8080/MultiFormat/MultiFormatServlet</url>
<!-- The path to a temporary directory on the local (TeamSite)
server -->
<transfer-dir-local>C:\WINNT\temp\transform</transfer-dir-local>
</service>
</conversion>

URL Commands
Two URL commands are available for use in connection with Content Transformation
Services. The /iw-cc/convert URL Command initiates the Convert functionality. The
/iw-cc/converttask URL is used as a CGI task within a workflow. These URL tasks
are discussed briefly in this chapter. For additional information on URL Commands,
refer to the TeamSite User Interface Customization Guide.

Interwoven, Inc. 262


Appendix C: Content Transformation Services

The convert URL Command


You can initiate the Convert function using the /iw-cc/convert URL Command. This
URL Command accepts two standard parameters:
„ vpath (required) specifies at least one document to be converted. When used with
ContentCenter Standard, only one vpath is permitted. When used with
ContentCenter Professional, multiple vpaths are permitted, but all of the referenced
files must be in the same workarea.
„ done_page (optional) provides the URL of the page to go to after the convert
operation completes.

As with most URL Commands, this URL Command invokes the appropriate
ContentCenter screen that provides this operation.

The converttask URL Command


You can set up a Convert workflow task. This is a CGI task that can be added as a step in
existing workflows, or you can create new workflows that employ this task. Document
conversion can be made a part of any TeamSite workflow by adding a CGI task where
the <command> is /iw-cc/converttask and the readonly flag is "f". When it is
activated, the task prompts the user to select the desired output formats.

When the Convert task is initiated, it shows the user all of the Word documents that are
attached to the task. The user can select the desired output formats (HTML, PDF, or
both) for each document. ContentCenter then displays the results of the conversion and
includes links to the generated HTML or PDF files if the conversion is successful. The
generated files are automatically attached to the task, and the user can then transition to
the next task.

Demonstrating the Workflow CGI Task


A file named cgi_task_test.wft in iw-home/local/config/wft/examples can be
used to test a workflow CGI program. The workflow has two tasks. The first task is a
CGI task that can transition either to the end of the workflow or to the second task. The
second task is a user task that transitions back to the first task (to re-run the CGI).

This workflow can be modified to use the Convert CGI task by performing the
following steps:
1. Make of copy of the WFT with a different name.
2. Edit the new file.
a. Change the $cgi_command to /iw-cc/converttask (line 31).
b. Change the readonly flag on the CGI task from "t" to "f" (line 117).
c. Optionally, change the description of the CGI task to something like Convert
Attached Documents (line 114).

TeamSite Administration Guide 263


Appendix C: Content Transformation Services

3. Add this workflow to iw-home/local/config/wft/available_templates.cfg for


the desired command, branches, etc. For example:
<template_file name='Convert Files' path='local/convert_files.wft'>
<command_list>
<command value='new_job' />
</command_list>
</template_file>

Alternatively, this task can be added into an existing workflow by simply adding a CGI
task with the command /iw-cc/converttask and readonly="f". For example:
<cgitask name="Convert"
description="Convert Attached Documents"
owner="__TAG__('iw_user');"
immediate="t"
readonly="f">
<areavpath v="__TAG__('iw_workarea');"/>
<successors>
<successorset description="NEXT TASK">
<succ v="Done"/>
</successorset>
</successors>
<command v='/iw-cc/converttask'/>
</cgitask>

Removing or Modifying Menu Items


To modify or move the Convert menu items, refer to the TeamSite User Interface
Customization Guide.

Using Content Transformation Services


Content Transformation Services for TeamSite adds the Convert menu option to
ContentCenter that allows users to convert Microsoft Word documents to PDF and
HTML formats. Refer to the online help or a ContentCenter user’s guide for usage
information.

NOTES
„ While users can edit the HTML or PDF output using an appropriate editor, the edits
will be lost if the Word document is converted again. Change the Word document to
get the needed output.
„ If a source document is modified after it has been converted into PDF or HTML
format, the system does not automatically regenerate the output or report that the
output is obsolete. The user must regenerate the output.

Interwoven, Inc. 264


Appendix C: Content Transformation Services

The Content Transformation Services transformation engine does not support


conversion of the following MS Word features:
„ Text boxes and frames
„ Absolutely positioned images
„ Word shapes and shape groups
„ Continuous section breaks
„ Mixing multiple columns and single columns on the same page
„ Paragraph borders and shading
„ Non-standard tables
„ Unequal column widths in a multiple column page
„ Non-standard text direction
„ Revision tracking
„ Comments
„ Custom picture bullets
„ Double borders

TeamSite Administration Guide 265


Appendix C: Content Transformation Services

Interwoven, Inc. 266


Appendix D

Next Generation Tagger GUI

This TeamSite release supports the next generation Tagger GUI for tagging files (that is,
adding metadata to them). The original Tagger GUI used in TeamSite 6.7.1 and earlier
releases is also supported. Which Tagger GUI is invoked depends on what type of
tagging activity is initiated by an user:
„ The next generation Tagger GUI is invoked whenever a user selects a single file to
tag through ContentCenter Standard or Professional. To ensure backward
compatibility, the next generation Tagger GUI is capable of displaying rulesets
based on the schemas used by both the original and next generation Tagger GUIs.
The default behavior for this TeamSite release is for the next generation Tagger GUI
to implement rulesets based on the original-style schema.
„ The original Tagger GUI is invoked whenever a user selects more than one file to tag
through ContentCenter Standard or Professional.

The next generation Tagger GUI differs from the original Tagger GUI in several key
areas (see “Tagger GUI New Features and Differences” on page 268 for details). The
original Tagger GUI still performs as described in the Chapter 8, “Configuring Metadata
Capture.”

NOTES
„ While the next generation Tagger GUI supports the original Tagger GUI schema, the
opposite is not true. That is, the original Tagger GUI does not support the next
generation Tagger GUI schema.
„ In future TeamSite releases, the next generation Tagger GUI will support tagging
more than one file at a time. When that ability is supported, the next generation
Tagger GUI will be the default Tagger GUI for all tagging activities initiated in
ContentCenter Standard and Professional.

The rest of this appendix contains the following topics:


„ Tagger GUI New Features and Differences
„ Sequence of Events
„ Compatibility and Default Behavior
„ Configuring the Next Generation Tagger GUI
„ Integrating MetaTagger
„ DTDs

FormsPublisher Developer’s Guide 267


Appendix D: Next Generation Tagger GUI

Tagger GUI New Features and Differences


Table 20 summarizes the new features supported by the next generation Tagger GUI.
Table 21 summarizes the differences between the original and next generation Tagger
GUIs.

Table 20 Next generation Tagger GUI new features


Feature Description
Scripting through FormAPI You can use FormAPI and the <script> element in
datacapture.cfg to create dynamic Tagger GUI input
forms. See the TeamSite FormsPublisher: FormAPI
Developer’s Guide for details about using FormAPI.See
the TeamSite FormsPublisher Developer’s Guide for
details about using the datacapture.cfg <script>
element.
Rich text editor support You can configure data forms to use rich text editors
such as TinyMCE and VisualFormat for data entry.
Additional replicant and You can configure data forms using combination=”or”
container support for replicants and containers.
Additional <browser> You can use ceiling-dir and other new attributes with
attribute support the <browser> element.
Support for next generation If Metatagger is installed, you can map individual data
MetaTagger integration form items to specific Metatagger projects so that
dialogs Metatagger is invoked when a user tags a file through
those data form items.

NOTE
For this release, the next generation Tagger GUI only supports tagging a single file at a
time. Therefore, the features shown in Table 20 are available only for single-file tagging
at this time.

The differences between the original and next generation Tagger GUIs are as follows.

Table 21 Tagger GUI differences


Feature Original Tagger GUI Next Generation Tagger GUI
Rendering engine and Rendering engine is unique Same rendering engine is shared by
CGI environment to Tagger GUI. FormsPublisher, Tagger GUI, and Workflow
Modeler. This new CGI environment is
enabled by default, but the original CGI
environment can be re-enabled separately from
Tagger GUI for backward compatibility (that
is, a system can run the original CGI
environment and next generation Tagger GUI
at the same time).
See “Reverting to the Original CGI
Environment” on page 277 for more
information.

Interwoven, Inc. 268


Appendix D: Next Generation Tagger GUI

Table 21 Tagger GUI differences (Continued)


Feature Original Tagger GUI Next Generation Tagger GUI
Overall Tagger GUI iw-home\local\config\data iw-home\local\config\tagui\rulesets60\any
configuration file capture.cfg filename.cfg
iw-home\local\config\datacapture.cfg
(supported for backward compatibility)
DTD iw-home\local\config\meta iw-home\local\config\datacapture6.0.dtd
datacapture6.0.dtd (to (DTD formerly unique to FormsPublisher;
validate overall Tagger GUI now updated for use by FormsPublisher,
configuration file Tagger GUI, and Workflow Modeler.)
datacapture.cfg) Validates, amongst other things, overall Tagger
GUI configuration files in
iw-home\local\config\tagui\rulesets60.
This is the same format used by
FormsPublisher for XML-style (but not
Interwoven-style) templates and data forms.
iw-home\local\config\metadatacapture6.0.
dtd (original Tagger GUI DTD to validate
datacapture.cfg; supported by next
generation Tagger GUI for backward
compatibility)
Tagger GUI iw-home\local\config\meta iw-home\local\config\metadata-rules.cfg
configuration file for a data-rules.cfg (same file used with original Tagger GUI)
specific file vpath and
to specify a ruleset
Data capture template iw-home\local\config iw-home\local\config\tagui\rulesets60
location iw-home\local\config (supported for
backward compatibility)
Supported data capture IWOV data record style XML data record style (conforming to
template format (conforming to datacapture6.0.dtd)
metadatacapture6.0.dtd) IWOV data record style (conforming to
metadatacapture6.0.dtd; supported for
backward compatibility)
Support for single-file Yes Yes
tagging?
Support for Yes No
multiple-file tagging?
Tagging scenario that Multiple file. Single file.
triggers launch of
Tagger GUI
Interaction with Original MetaTagger dialog Next generation MetaTagger dialog window.
MetaTagger (if window.
installed)

FormsPublisher Developer’s Guide 269


Appendix D: Next Generation Tagger GUI

Table 21 Tagger GUI differences (Continued)


Feature Original Tagger GUI Next Generation Tagger GUI
<ruleset> element Any number of <ruleset> If using next generation Tagger GUI ruleset
elements allowed in schema: Only one <ruleset> element allowed
iw-home\local\config\data per
capture.cfg configuration iw-home\local\config\tagui\rulesets60\any
file. filename.cfg configuration file; any number
of configuration files allowed. (Rulesets are
split into multiple files for improved
performance.)
If using original Tagger GUI ruleset schema
(supported for backward compatibility): Any
number of <ruleset> elements allowed in
iw-home\local\config\datacapture.cfg
configuration file.
<root-container> Not supported. Required if using next generation Tagger GUI
element ruleset schema (datacapture6.0.dtd).
Not supported if using original Tagger GUI
ruleset schema (metadatacapture6.0.dtd).
<replicant> element Supported. Not supported if using next generation Tagger
GUI ruleset schema (datacapture6.0.dtd).
Instead use:
<container min=" " max=" " default=" ">
or
<item min=" " max=" " default=" ">
Supported if using original Tagger GUI ruleset
schema (metadatacapture6.0.dtd).
<item> element No pathid attribute. Required pathid attribute if using next
generation Tagger GUI ruleset schema
(datacapture6.0.dtd). pathid must be
simple (not using relative, attribute, #PCData,
non-located, or any combination of these
forms). Examples of simple pathid: 1) setting
pathid the same as the item name, or 2)
setting pathid without using xpath syntax
such as /itemName (requires putting all
elements in the root node of the data record
under the <itemName> element, or using
@attrName if a parent container exists and
pathid is an attribute of that container
<container attrName="...">), or 3) using a
unique pathid across the entire data capture
template (recommended). See the TeamSite
FormsPublisher Developer’s Guide for
information on using the pathid attribute.
No pathid attribute if using original Tagger
GUI ruleset schema
(metadatacapture6.0.dtd).

Interwoven, Inc. 270


Appendix D: Next Generation Tagger GUI

Table 21 Tagger GUI differences (Continued)


Feature Original Tagger GUI Next Generation Tagger GUI
<container> element No location attribute. Optional location attribute if using next
generation Tagger GUI ruleset schema
(datacapture6.0.dtd). Conforms to the same
rules as pathid. See the TeamSite
FormsPublisher Developer’s Guide for
information on using the pathid attribute.
No location attribute if using original Tagger
GUI ruleset schema
(metadatacapture6.0.dtd).
<view-container> Supported. Not supported if using next generation Tagger
<view> element GUI ruleset schema (datacapture6.0.dtd).
Replaced with <root-container><tab>.
Supported if using original Tagger GUI ruleset
schema (metadatacapture6.0.dtd).
<cgi-callout> element Supported. Not supported if using next generation Tagger
GUI ruleset schema (datacapture6.0.dtd).
Replaced with <callout>.
Supported if using original Tagger GUI ruleset
schema (metadatacapture6.0.dtd).
Dynamic addition of Not supported. Supported; may require migrating extended
select box entries. attribute data to next generation format. See
“Dynamic Addition of Select Box Entries” on
page 277 for more information.

NOTES
„ The original Tagger GUI does not support the next generation Tagger GUI schema.
„ For the original Tagger GUI, the overall Tagger GUI configuration file
iw-home\local\config\datacapture.cfg must conform to the DTD defined in
iw-home\local\config\metadatacapture6.0.dtd.This behavior is documented in
Chapter 8, “Configuring Metadata Capture.”
„ For the next generation Tagger GUI, the overall Tagger GUI configuration file does
not need to be named datacapture.cfg, and the schema that it must conform to is
defined in iw-home\local\config\datacapture6.0.dtd. The only naming
requirement for the overall next generation Tagger GUI configuration file is that it
end in .cfg (anyfilename.cfg). This convention is possible because each next
generation Tagger GUI overall configuration file may contain just one <ruleset>
element. This change was made to improve performance. Thus, to enable the next
generation Tagger GUI to support multiple rulesets, you must create multiple
configuration files in iw-home\local\config\tagui\rulesets60, each with a unique
file name and a uniquely named ruleset defined in the <ruleset> element. See
“DTDs” on page 280 for DTD details.
„ Because the next generation Tagger GUI overall configuration file can have any file
name ending in .cfg, it is possible for it to be named datacapture.cfg.This is the
same file name used by the original Tagger GUI configuration file. When both files
are named datacapture.cfg, the location of datacapture.cfg determines which
XML tags are used by the next generation Tagger GUI. If datacapture.cfg is in
iw-home\local\config, the next generation Tagger GUI uses the tags defined by

FormsPublisher Developer’s Guide 271


Appendix D: Next Generation Tagger GUI

metadatacapture6.0.dtd. If datacapture.cfg is in
iw-home\local\config\tagui\rulesets60, the next generation Tagger GUI uses the
tags defined by datacapture6.0.dtd (and only then can take advantage of all next
generation Tagger GUI features).

Sequence of Events
The following sections describe what happens when a user invokes the Tagger GUI
through ContentCenter Standard or Professional.

Tagging a Single File (Next Generation Tagger GUI)


When a user selects a single file to tag in ContentCenter Standard or Professional:
1. FormsPublisher checks application.xml to determine whether to use the original
or next generation Tagger GUI for single-file tagging.
2. The next generation Tagger GUI engine is invoked. This is the same rendering
engine used by FormsPublisher and Workflow Modeler.
3. The Tagger GUI reads the file iw-home\local\config\metadata-rules.cfg to
determine which ruleset to use. (The ruleset is specified by name in the <ruleset>
element. See “The metadata-rules.cfg File” on page 176.)
4. The Tagger GUI searches for the specified ruleset.
a. First the Tagger GUI searches for the ruleset in the files located in the
iw-home\local\config\tagui\rulesets60 directory. This directory is only
searched by the next generation Tagger GUI. It is not searched when the original
Tagger GUI is invoked (such as when multiple files are tagged as described in
the next section). All of the files in this directory must conform to the schema
for the next generation Tagger GUI as defined by
iw-home\local\config\datacapture6.0.dtd.

b. If the specified ruleset is not found in any of the files in


iw-home\local\config\tagui\rulesets60, the Tagger GUI searches for the
ruleset in the iw-home\local\config\datacapture.cfg file. This file must
conform to the schema for the original Tagger GUI as defined by
iw-home\local\config\metadatacapture6.0.dtd.

5. When the ruleset is found, the rules defining Tagger GUI appearance and behavior
are executed, the Tagger GUI is displayed, and the user can complete the process of
tagging the file originally selected.

Interwoven, Inc. 272


Appendix D: Next Generation Tagger GUI

Tagging Multiple Files (Original Tagger GUI)


The following is the default sequence of events for this TeamSite release. Future
releases will support the use of the next generation Tagger GUI and rulesets for tagging
multiple files.

When a user selects multiple files to tag in ContentCenter Standard or Professional:


1. The original Tagger GUI engine is invoked.
2. The Tagger GUI reads the file iw-home\local\config\metadata-rules.cfg to
determine which ruleset to use. (The ruleset is specified by name in the <ruleset>
element. See “DTDs” on page 280.)
3. The Tagger GUI searches for the specified ruleset in the
iw-home\local\config\datacapture.cfg file. This file must conform to the
schema for the original Tagger GUI (as defined by
iw-home\local\config\metadatacapture6.0.dtd), not the schema for the next
generation Tagger GUI (as defined by
iw-home\local\config\datacapture6.0.dtd).

4. When the ruleset is found, the rules defining Tagger GUI appearance and behavior
are executed, the Tagger GUI is displayed, and the user can complete the process of
tagging the files originally selected.

Compatibility and Default Behavior


The following table shows which Tagger GUI schemas are supported by the original and
next generation Tagger GUIs.

Table 22 Tagger GUI schema support


Original Tagger GUI Next Generation Tagger GUI
Tagger GUI Schema
(Multi-File Tagging) (Single-File Tagging)
Original Supported Supported
(metadatacapture6.0.dtd)
Next generation Not supported Supported
(datacapture6.0.dtd)

The original Tagger GUI shipped with this release is configured to use one or more
rulesets located in the iw-home\local\config\datacapture.cfg configuration file.
(These rulesets are named in iw-home\local\config\metadata-rules.cfg as the
rulesets to search for when the Tagger GUI is invoked, but are defined in
iw-home\local\config\datacapture.cfg). As shown in the preceding table, the
original Tagger GUI only supports the original Tagger GUI schema for rulesets.
Therefore, the datacapture.cfg file in iw-home\local\config\must conform to
metadatacapture6.0.dtd.

FormsPublisher Developer’s Guide 273


Appendix D: Next Generation Tagger GUI

The next generation Tagger GUI supports both the original (for backward compatibility)
and next generation Tagger GUI schemas. To ensure backward compatibility in this
release, the next generation Tagger GUI implements the original Tagger GUI ruleset and
configuration file (iw-home\local\config\datacapture.cfg). This occurs because no
configuration files containing next-generation rulesets are included in the
iw-home\local\config\tagui\rulesets60 directory for this release (see “Configuring
the Next Generation Tagger GUI” for information about adding such rulesets).

Therefore, when the Tagger GUI performs step 3a on page 272, it does not find a
next-generation ruleset having the name specified in metadata-rules.cfg. It then
performs step 3b, at which time it finds an original ruleset having the name specified in
metadata-rules.cfg.

NOTE
Future TeamSite releases will contain examples of next generation rulesets in the
iw-home\local\config\tagui\rulesets60 directory so that all of the features supported
by the next generation Tagger GUI will be available by default. For the current release,
if you choose to customize the Tagger GUI you should edit
iw-home\local\config\datacapture.cfg so that your changes are implemented no
matter which Tagger GUI (original or next generation) is invoked.

Implications of Configuring the Next Generation Tagger GUI


If you specify in metadata-rules.cfg that a next generation ruleset is used for all file
tagging sessions, no ruleset will not be found when a user tags multiple files. This
occurs because multi-file tagging invokes the original Tagger GUI, which does not
search in the iw-home\local\config\tagui\rulesets60 directory for rulesets.

Replicant Processing
Unlike the original Tagger GUI schema, the next generation Tagger GUI schema does
not support the <replicant> element. Instead, it provides equivalent support through
the <container> element. The New Tagger GUI <container> element supports the
same max, min, and default semantics of the <replicant> element. The <replicant>
element is still supported for backward compatibility in rulesets conforming to the old
schema, but the old schema does not provide support for new features such as FormAPI
script.

The original Tagger GUI schema distinguished between replicants and containers, and
whether an item used the <replicant> or <container> tag had an impact on the format
for the item when it was saved in the Content Store. This format may be important for
your downstream systems. In the next generation Tagger GUI’s new schema, the
replicant save format is preserved for backward compatibility for containers that can be
instantiated (those where neither min and max are not 1). To properly support containers
or replicants that implicitly or explicitly have both min and max equal to 1, a new

Interwoven, Inc. 274


Appendix D: Next Generation Tagger GUI

attribute eaSaveFormat for <container> elements allows you to explicitly define


whether you want to use the container or replicant save format in this otherwise
ambiguous case (see Table 21).

To implement a next generation UI using the next generation schema that mimics the
replicant element in UI behavior and backend save format, or if you have existing data
records that you would like to manually port into the next generation schema (to add
FormAPI script, for example), you need to add <container> elements in place of
<replicant> elements when using the next generation Tagger GUI schema. Since
<replicant> and <container> elements support the same attributes in the new schema,
you should be able to keep all attributes the same, unless the replicant explicitly or
implicitly uses min and max of 1.

A new eaSaveFormat attribute in the <container> element is provided to allow this


case:

min CDATA "1"


max CDATA "1"
default CDATA "1"
location CDATA #IMPLIED
refid CDATA #IMPLIED
eaSaveFormat (withInstanceNums | withoutInstanceNums) "withInstanceNums"
<!-- @eaSaveFormat: Tag UI specific for EA compatibility.
withoutInstanceNums only applies when min==max==1. -->

Since <replicant> elements were always saved in the Content Store using instance
numbers using the original Tagger GUI, you can specify
eaSaveFormat=”withInstanceNums” to mimic the save format of a replicant tag. Also,
since <container> elements were always saved in the Content Store without instance
numbers in the original Tagger GUI, you can specify
eaSaveFormat=”withoutInstanceNums” to get this behavior in the next generation
Tagger GUI (note: “withoutInstanceNums” only applies when min and max are both
equal to 1, since having an instantiable container would result in a save format that
includes instance numbers in the old Tagger GUI). Finally, the default for the
eaSaveForrmat in the next generation tagger GUI is “withInstanceNums”, so unless
otherwise specified, containers in the next generation Tag UI configurations would save
using instance numbers (to support the min and max elements allowed by next generation
<container> elements).

To migrate replicants and containers in which min==max==1, set


eaSaveForm="withoutInstanceNums".

FormsPublisher Developer’s Guide 275


Appendix D: Next Generation Tagger GUI

Example

In the original Tagger GUI schema, the following datacapture.cfg entry:

<container name="container"> <item name="item"> <text>

creates an extended attribute with container/item=user_input_value in the Content


Store.

And similarly, the following datacapture.cfg entry (also using the original Tagger
GUI schema):

<replicant name="replicant" min="1" max="1"> <item name="item"> <text>

creates an extended attribute such as


replicant/0/item=user_input_value_for_instance_0 in the Content Store. If max
was changed to allow two instances, a second instance would use /1/ in the extended
attribute name.

Because the next generation Tagger GUI must be compatible with the original Tagger
GUI, it also must support saving and loading the data shown above. When min==max==1,
the eaSaveForm attribute lets you specify whether the /#/ format should be included
when saving (or attempting to load) the data form.

Setting eaSaveForm="withInstanceNums" retains the instance numbers. Setting


eaSaveForm="withoutInstanceNums" does not.

NOTES
„ When min and max are not both 1, this is automatically a replicant type and instance
numbers must be used in the Content Store. If they are not, replicant instances 2
through N would overwrite the first instance in the Content Store. FormsPublisher
recognizes this case automatically, which is why withoutInstanceNums only
applies when min==max==1.
„ Even though the eaSaveFormat attribute only exists in the next generation Tagger
GUI schema, the original Tagger GUI schema files are transformed dynamically at
runtime into next generation schema files when the next generation Tagger GUI
renders them. Therefore, the dynamic migration code automatically adds
eaSaveFormat=withoutInstanceNums whenever migrating an original format
container into a next generation format container so that the next generation Tagger
GUI will automatically work with the original schema and be backwards compatible
with any pre-existing data.

Interwoven, Inc. 276


Appendix D: Next Generation Tagger GUI

Reverting to the Original CGI Environment


The next generation Tagger GUI CGI environment is enabled by default, but the original
CGI environment can be re-enabled separately from Tagger GUI and vice versa (that is,
a system can run the original CGI environment and next generation Tagger GUI at the
same time).

To revert to the original CGI environment for Tagger GUI, set the following in
application_custom.xml:

iw.tagui.CGIEnv="old"

To change back to the new CGI environment, set the following:

iw.tagui.CGIEnv="new"

Dynamic Addition of Select Box Entries


The next generation Tagger GUI supports dynamic addition of select box entries
through FormAPI. As a result, the next generation Tagger GUI must interpret unknown
saved select box values as dynamic entries from a previous session, and allow those
values into the drop-down list.

Because multi=t values are saved in a single string (for example, "value1, value2,
value3"), on changing a multi-valued list into a single-valued list, the next generation
Tagger GUI renders "value1, value2, value3" as a legal option in the select list. The
original Tagger GUI would have arbitrarily chosen one of the values.

If you anticipate this case (in which the meaning of a saved value could change), it is
recommended that you migrate the extended attribute data to the new format to achieve
whatever result your organization desires.

Configuring the Next Generation Tagger GUI


NOTE
The instructions in this section are intended to let you preview the features supported by
the next generation Tagger GUI prior to the next TeamSite release. In a future release,
these features will be available by default for both single- and multi-file tagging. You
should back up the iw-home\local\config\metadata-rules.cfg file before performing
these steps so that you can revert to the default Tagger GUI configuration if necessary.

FormsPublisher Developer’s Guide 277


Appendix D: Next Generation Tagger GUI

You can configure the next-generation Tagger GUI to use next generation rulesets
(rather than the default original Tagger GUI ruleset in datacapture.cfg). The general
steps are as follows.
1. Create one or more configuration files in the
iw-home\local\config\tagui\rulesets60 directory. Configuration file names must
end in .cfg, and the files must conform to the schema defined in
iw-home\local\config\datacapture6.0.dtd. Each configuration file can contain
only one ruleset.
2. In iw-home\local\config\metadata-rules.cfg, change the ruleset name specified
for use to the name of the new ruleset you created in the
iw-home\local\config\tagui\rulesets60 directory.

Integrating MetaTagger
If MetaTagger is installed on your system, you can configure the next generation Tagger
GUI to use Metatagger whenever the next generation Tagger GUI is invoked.
Configuration involves two main activities:
„ Creating a ruleset for the data form from which Metatagger will be invoked.
„ Creating a file that maps Metatagger projects to data form items defined in the
ruleset.

The following sections describe how to perform these tasks.

Creating a Ruleset
Use the example ruleset shown in this section as the basis for creating your own ruleset
for a data form that will invoke Metatagger. The file defining the ruleset must:
„ Reside in the iw-home\local\config\tagui\rulesets60 directory.
„ Have a file name ending in .cfg.
„ Contain the tagEngineConfig attribute, which points to the Metatagger mapping
file that you will create as described in the next section.
„ Conform to the next generation Tagger GUI schema defined in
datacapture6.0.dtd.

The following example shows a hypothetical ruleset file named defaultRule.cfg. It


defines a data form named “Asset_metadata.” This data form:
„ Collects input from a user in two data entry areas (“CustomMT” and “Keywords”).
„ Invokes Metatagger when the user chooses to add metadata, using the Metatagger
projects defined in MT_Rulefile (explained in “Creating a Mapping File”).
„ Saves the information in an XML-format data record having the root node
Asset_metadata.

Interwoven, Inc. 278


Appendix D: Next Generation Tagger GUI

<data-capture-requirements>
<ruleset name="Default Rule">
<root-container name="Asset_metadata" location="Asset_metadata">
<item name="CustomMT" pathid="CustomMT" tagEngineConfig="met
atagger://MT_Rulefile">
<label>CustomMT</label>
<description>Keywords can include terms that are not
in the asset itself.</description>
<database data-type="VARCHAR(100)"/>
<text required="f" size="32" maxlength="60"/>
</item>
<item name="Keywords" pathid="Keywords" tagEngineConfig="met
atagger://MT_Rulefile">
<label>Keywords</label>
<description>Keywords can include terms that are not
in the asset itself.</description>
<database data-type="VARCHAR(100)"/>
<text required="f" size="32" maxlength="60"/>
</item>
</root-container>
</ruleset>
</data-capture-requirements>

NOTE
Be sure that the maxlength attribute is set to a value that is high enough to display all
results for metadata suggestions returned by MetaTagger. If maxlength is too low, the
display field will truncate the returned result, and you will not be able to highlight
and/or edit the result.

Creating a Mapping File


Perform the following steps to create a file that maps Metatagger projects to data
capture template items.
1. Create a metataggerMappings directory in iw-home\local\config\tagui. All
Metatagger mapping files must reside in this directory.
2. In iw-home\local\config\metataggerMappings, create a file with a name of your
choice (referred to in this example as MT_Rulefile).
3. Edit MT_Rulefile so that it contains just the <tagUIConfig> element and its
associated subelements. The <tagUIConfig> element can contain multiple items
(one for each data entry area that will use Metatagger). Each item also contains one
or more parameter subelements mapping the data entry area for that item to a
Metatagger project. For example:

FormsPublisher Developer’s Guide 279


Appendix D: Next Generation Tagger GUI

<?xml version="1.0"?>
<tagUIConfig>
<item name="/Asset_metadata/CustomMT">
<parameter name="metataggerProjectName" value="summidx_en"/>
</item>
<item name="/Asset_metadata/Keywords">
<parameter name="metataggerProjectName" value="test_taxonomy"/>
<parameter name="metataggerBrowseInitialDir" value=""/>
</item>
<item name="/Asset_metadata/test_taxonomy">
<parameter name="metataggerProjectName" value="test_taxonomy"/>
<parameter name="metataggerBrowseInitialDir" value=""/>
</item>
</tagUIConfig>

NOTE
All item references are rooted in the node specified in the <root-container> element in
defaultRule.cfg. The syntax for item references is the same as the base FormAPI path
syntax. You do not need to specify indices in an item reference if the item/container is a
replicant.

The data entry areas of the “Asset_metadata” form are mapped to Metatagger
projects as follows:
‰ CustomMT (mapped to the summidx_en Metatagger project)
‰ Keywords (mapped to the test_taxonomy Metatagger project)

DTDs
The following sections show the DTDs used to define the original and next generation
Tagger GUI ruleset schemas.

metadata-rules.dtd
This DTD defines the schema used by the iw-home\local\config\metadata-rules.cfg
file, which is used by the original and next-generation Tagger GUIs.

NOTE
This DTD is documented in greater detail in Chapter 8, “Configuring Metadata Capture.”

Interwoven, Inc. 280


Appendix D: Next Generation Tagger GUI

<!ELEMENT metadata-rules (cond)*>


<!ELEMENT cond (cond|rule)*>
<!ATTLIST cond
vpath-regex CDATA #REQUIRED
>
<!ELEMENT rule EMPTY>
<!ATTLIST rule
name CDATA #REQUIRED
>

metadatacapture6.0.dtd
This DTD defines the schema used by the iw-home\local\config\datacapture.cfg
file, which is used by default by the original Tagger GUI. It is also supported by the
next-generation Tagger GUI for backward compatibility.

NOTE
This DTD is documented in greater detail in Chapter 8, “Configuring Metadata Capture.”

<!-- metadatacapture6.0.dtd Version 1.1 2/12/04 -->


<!-- Start with some basic parameter entities. -->
<!ENTITY % data-capture-requirements-contentspec "(ruleset+)*">
<!ENTITY % items "container|view-container|view|item">
<!ENTITY % chooser-options "option|inline">
<!ELEMENT data-capture-requirements
(%data-capture-requirements-contentspec;)>
<!ATTLIST data-capture-requirements
name CDATA #IMPLIED
type (metadata) #REQUIRED
dtd-system-identifier CDATA #IMPLIED
>
<!-- The 'dtd-system-identifier' attribute is a URI indicating the
DTD from whence a particular data-capture-requirements was
derived, if any.
-->

<!ELEMENT ruleset (label?, description?, (%items;)*)>


<!ATTLIST ruleset
name CDATA #REQUIRED
>
<!ELEMENT container (label?, description?, (%items;)*)>
<!ATTLIST container
name CDATA #REQUIRED
>

<!ELEMENT item (label?, description?, database?, (checkbox | radio | text


| textarea | select | replicant | browser | readonly | hidden)+)>
<!ATTLIST item

FormsPublisher Developer’s Guide 281


Appendix D: Next Generation Tagger GUI

name CDATA #REQUIRED


>

<!ELEMENT label (#PCDATA)>


<!ELEMENT description (#PCDATA)>
<!ELEMENT text (allowed?,cgi-callout?,default?) >
<!ATTLIST text
required (t | f) "f"
maxlength CDATA "0"
size CDATA "0"
validation-regex CDATA #IMPLIED
>
<!-- validation-regex is a regex for validating this element -->
<!ELEMENT textarea (allowed?,cgi-callout?,default?) >
<!ATTLIST textarea
required (t | f) "f"
rows CDATA "0"
cols CDATA "0"
wrap (off | virtual | physical) "off"
validation-regex CDATA #IMPLIED
>
<!-- validation-regex is a regex for validating this element -->
<!ELEMENT browser (allowed?,cgi-callout?)>
<!ATTLIST browser
required (t | f) "f"
initial-dir CDATA #IMPLIED
extns CDATA #IMPLIED
>
<!ELEMENT readonly (allowed?,cgi-callout?)>
<!ELEMENT hidden (allowed?,cgi-callout?)>
<!ATTLIST hidden
required (t | f) "f"
>
<!ELEMENT checkbox (allowed?, cgi-callout?, (%chooser-options;)+)>
<!ATTLIST checkbox
required (t | f) "f"
>
<!ELEMENT radio (allowed?, cgi-callout?, (%chooser-options;)+)>
<!ATTLIST radio
required (t | f) "f"
>
<!ELEMENT select (allowed?, cgi-callout?, (%chooser-options;)+)>
<!ATTLIST select
required (t | f) "f"
size CDATA "0"
multiple (t | f) "f"
>
<!ELEMENT option EMPTY>
<!ATTLIST option
selected (t | f) "f"

Interwoven, Inc. 282


Appendix D: Next Generation Tagger GUI

value CDATA #IMPLIED


label CDATA #REQUIRED
>
<!ELEMENT replicant (allowed?, (%items;)*)>
<!ATTLIST replicant
min CDATA "0"
max CDATA "1"
default CDATA "1"
>
<!ELEMENT allowed (cred | and | or | not)>
<!ELEMENT cred EMPTY>
<!ATTLIST cred
role CDATA #IMPLIED
user CDATA #IMPLIED
>
<!ELEMENT and ((cred | and | or | not)+)>
<!ELEMENT or ((cred | and | or | not)+)>
<!ELEMENT not (cred | and | or | not)>
<!ELEMENT default (#PCDATA)>

<!--The form of this element is exactly the same as that for the callout
element in datacapture.4.0.dtd. -->
<!ELEMENT cgi-callout EMPTY>
<!ATTLIST cgi-callout
label CDATA #REQUIRED
url CDATA #REQUIRED
window-featuresCDATA #IMPLIED
>

<!ELEMENT database EMPTY>


<!ATTLIST database
deploy-column (t | f) "t"
searchable (t | f) "t"
data-type CDATA "VARCHAR(255)"
data-format CDATA #IMPLIED
>
<!-- An 'inline' element should have a 'command' attribute. e.g.:
<inline command="/bin/cat /tmp/a /tmp/b"/>

The callout program should return a well-formed XML document.


The document's outermost element should be a "substitution"
element. It should contain any XML that is valid according
to this DTD.

That "substitution" element's contents will replace the


"inline" element in the datacapture.cfg file.

So, if this DCT snippet:

<select>

FormsPublisher Developer’s Guide 283


Appendix D: Next Generation Tagger GUI

<inline command="command name" />


</select>

runs the "blah" callout program, and that program returns this text:

<substitution>
<option label="ABC" />
<option label="123" />
<option label="Jackson 5" />
</substitution>

then the DCT snippet will, after callout execution and inline
substitution, look like:

<select>
<option label="ABC" />
<option label="123" />
<option label="Jackson 5" />
</select>
-->
<!ELEMENT inline EMPTY>
<!ATTLIST inline
command CDATA #REQUIRED
>

datacapture6.0.dtd
This DTD defines the schema used by the configuration files (anyfilename.cfg)
located in the iw-home\local\config\tagui\rulesets60 directory, which are used by
the next-generation Tagger GUI.

<!-- datacapture6.0.dtd -->

<!ELEMENT data-capture-requirements (ruleset)>


<!ATTLIST data-capture-requirements
name CDATA #IMPLIED
dtd-system-identifier CDATA #IMPLIED
dcr-validation (none | accept-invalid | reject-invalid) "none"
>
<!-- The 'dtd-system-identifier' attribute is a URI indicating the
DTD from whence a particular data-capture-requirements was
derived, if any.

In TeamSite Templating, the value of this attribute is used as


the system identifier of the document type declaration of a DCR
if and only if that DCR's type is "xml", as defined in
templating.cfg.
-->

Interwoven, Inc. 284


Appendix D: Next Generation Tagger GUI

<!ELEMENT ruleset (label?, description?, script*, root-container)>


<!ATTLIST ruleset
name CDATA #REQUIRED
>

<!ELEMENT root-container (label?, ((tab)+|(container|item


|choice|dialog)+))>
<!ATTLIST root-container
name CDATA #REQUIRED
combination (and | or) "and"
location CDATA #REQUIRED
>

<!ELEMENT script (#PCDATA)>


<!ATTLIST script
language CDATA "javascript"
location (webserver|template-type) "webserver"
src CDATA #IMPLIED
>

<!ELEMENT tab ( (container|item|choice|dialog)+)>


<!ATTLIST tab
name CDATA #REQUIRED
>

<!ELEMENT container (label?,


description?,(container|item|choice|dialog)*,itemref?)>
<!ATTLIST container
name CDATA #REQUIRED
combination (and | or) "and"
min CDATA "1"
max CDATA "1"
default CDATA "1"
location CDATA #IMPLIED
refid CDATA #IMPLIED
eaSaveFormat (withInstanceNums | withoutInstanceNums)"withInstanceNums"
<!-- @eaSaveFormat: Tag UI specific for EA compatibility.
withoutInstanceNums only applies when min==max==1. -->
>

<!ELEMENT choice (label?,description?,(container|item|dialog)+,itemref?)>


<!ATTLIST choice
name CDATA #REQUIRED
refid CDATA #IMPLIED
>

<!ELEMENT itemref EMPTY>


<!ATTLIST itemref
label CDATA #IMPLIED
refid CDATA #REQUIRED

FormsPublisher Developer’s Guide 285


Appendix D: Next Generation Tagger GUI

min CDATA "1"


max CDATA "1"
>

<!ELEMENT item (label?, description?, (checkbox | radio | text | textarea


| select | browser | readonly | hidden)+)>
<!ATTLIST item
name CDATA #REQUIRED
rowcontinue (t|f) "f"
min CDATA "1"
max CDATA "1"
default CDATA "1"
pathid CDATA #REQUIRED
isTitle (t|f) "f"
tagEngineConfig CDATA #IMPLIED
>
<!-- @tagEngineConfig: Tag UI specific. Enables MetaTagger
suggestions/taxonomies for this item. See Tag UI docs for usage. -->

<!ELEMENT label (#PCDATA)>


<!ELEMENT description (#PCDATA)>
<!ELEMENT text (allowed?,callout?,default?) >
<!ATTLIST text
required (t | f) "f"
maxlength CDATA "0"
size CDATA "0"
validation-regex CDATA #IMPLIED
>
<!-- validation-regex is a regex for validating this element -->
<!ELEMENT textarea (allowed?,callout?,default?) >
<!ATTLIST textarea
required (t | f) "f"
rows CDATA "0"
cols CDATA "0"
wrap (off | virtual) "off"
validation-regex CDATA #IMPLIED
external-editor CDATA #IMPLIED
external-editor-config CDATA #IMPLIED
external-editor-inline (t | f) "t"
>
<!-- validation-regex is a regex for validating this element -->
<!ELEMENT browser (allowed?, callout?)>
<!ATTLIST browser
required (t | f) "f"
maxlength CDATA "0"
size CDATA "0"
initial-dir CDATA #IMPLIED
ceiling-dir CDATA #IMPLIED
extns CDATA #IMPLIED
>

Interwoven, Inc. 286


Appendix D: Next Generation Tagger GUI

<!ELEMENT readonly (allowed?, callout?)>


<!ELEMENT hidden (allowed?, callout?)>
<!ATTLIST hidden
required (t | f) "f"
>
<!ELEMENT checkbox (allowed?, callout?, (option|inline)+)>
<!ATTLIST checkbox
required (t | f) "f"
delimiter CDATA ", "
>
<!ELEMENT radio (allowed?, callout?, (option|inline)+)>
<!ATTLIST radio
required (t | f) "f"
>
<!ELEMENT select (allowed?, callout?, (option|inline)+)>
<!ATTLIST select
required (t | f) "f"
size CDATA "0"
multiple (t | f) "f"
delimiter CDATA ", "
>
<!-- The delimiter attribute is for multiple=t only -->
<!ELEMENT option EMPTY>
<!ATTLIST option
selected (t | f) "f"
value CDATA #IMPLIED
label CDATA #REQUIRED
>

<!ELEMENT allowed (cred | and | or | not)>


<!ELEMENT cred EMPTY>
<!ATTLIST cred
role CDATA #IMPLIED
group CDATA #IMPLIED
user CDATA #IMPLIED
>
<!ELEMENT and ((cred | and | or | not)+)>
<!ELEMENT or ((cred | and | or | not)+)>
<!ELEMENT not (cred | and | or | not)>
<!ELEMENT default (#PCDATA)>

<!ELEMENT callout EMPTY>


<!ATTLIST callout
label CDATA #REQUIRED
url CDATA #IMPLIED
window-features CDATA #IMPLIED
>

FormsPublisher Developer’s Guide 287


Appendix D: Next Generation Tagger GUI

<!-- An 'inline' element should have a 'command' attribute. e.g.:


<inline command="/bin/cat /tmp/a /tmp/b"/>

The callout program should return a well-formed XML document.


The document's outermost element should be a "substitution"
element. It should contain any XML that is valid according
to this DTD.

That "substitution" element's contents will replace the


"inline" element in the datacapture.cfg file.

So, if this DCT snippet:

<select>
<inline command="command name" />
</select>

runs the "blah" callout program, and that program returns this text:

<substitution>
<option label="ABC" />
<option label="123" />
<option label="Jackson 5" />
</substitution>

then the DCT snippet will, after callout execution and inline
substitution, look like:

<select>
<option label="ABC" />
<option label="123" />
<option label="Jackson 5" />
</select>
-->
<!ELEMENT inline EMPTY>
<!ATTLIST inline
command CDATA #REQUIRED
>
<!-- window-features is ignored if dialog type is button. function and
function-param can only be used if
dialog type is a button. Function name should not contain braces and
arguments. -->

<!ELEMENT dialog (allowed?, dialog-param+ | function-param+ )>


<!ATTLIST dialog
type (worksite|mediabin|button) #REQUIRED
label CDATA #REQUIRED
rowcontinue (t|f) "f"
function CDATA
window-features CDATA #IMPLIED

Interwoven, Inc. 288


Appendix D: Next Generation Tagger GUI

>

<!-- An dialog-input can have an input, and output, or both -->


<!ELEMENT dialog-param (allowed?, (dialog-input | dialog-output |
(dialog-input, dialog-output)))>
<!ATTLIST dialog-param
name CDATA #REQUIRED
>

<!-- A function parameter is any information you want to pass as function


argument -->
<!ELEMENT function-param (#CDATA)>

<!-- A dialog-input can have either a literal value or an item reference


-->
<!ELEMENT dialog-input (#PCDATA | field-ref)*>

<!-- A dialog-output must have an item reference -->


<!ELEMENT dialog-output (field-ref)>

<!ELEMENT field-ref EMPTY>


<!ATTLIST field-ref
name CDATA #REQUIRED
>

<!--Deprecated. Use <callout> instead.


<!ELEMENT cgi-callout EMPTY>
<!ATTLIST cgi-callout
label CDATA #REQUIRED
url CDATA #IMPLIED
window-features CDATA #IMPLIED
>
-->

FormsPublisher Developer’s Guide 289


Appendix D: Next Generation Tagger GUI

Interwoven, Inc. 290


Appendix E

Using the Derby Database

The Apache Derby database ships with TeamSite and can be used for the Event
Subsystem if you are not using another database system. The Derby database was
installed with TeamSite. You need to configure it if you wish to use it.

NOTE
The Derby database is not supported as the Report Center database.

Creating the Derby Database


1. If it is running, stop the Derby server.
2. Use the ij command line tool located in the iw-home\derby\bin directory to create
a Derby database and make the SQL queries. Issue the following command to create
a database named testdb:
ij> connect 'jdbc:derby:testdb;create=true;user=usr';
3. Create a Derby database schema using the create_derby.sql file located in the
iw-home\eventsubsystem\conf\ddl directory and issuing the following command:
ij> run 'iw-home\eventsubsystem\conf\ddl\create_derby.sql';
Verify that the tables have been created properly as shown in these commands and
output:
ij> show tables;
TABLE_SCHEM |TABLE_NAME |REMARKS
-----------------------------------------------------------------
USR |CONSUMERS |
USR |DESTINATIONS |
USR |MESSAGES |
USR |MESSAGE_HANDLES |
USR |SEEDS |
USR |SYSTEM_DATA |
USR |USERS |

ij> exit;

<BookTitle> 291
Appendix E: Using the Derby Database

4. Start the Derby server.


From the Services window, select the Interwoven Derby Database Server service
and start the service.

NOTE
To start this service automatically when you reboot, set the service type to
automatic.

5. Stop the Event Subsystem. Copy the Derby JDBC jar (derbyclient.jar) from the
iw-home\derby\lib directory to the iw-home\eventsubsystem\lib directory.

6. Edit the registry key to include the path of the new JDBC driver jar file. The older
JDBC jars if any should be removed.
\\HKEY_LOCAL_MACHINE\SYSTEM\Current ControlSet\
Services\iweventsubd\Parameters\JVM Option Number 0
7. Delete the events.lock file if it is located in the iw-home\eventsubsystem
directory.
8. Point to the new database in the <DatabaseConfiguration> section of the
iw-home\eventsubsystem\conf\jmsconfignew.xml file:
<DatabaseConfiguration>
<RdbmsDatabaseConfiguration
driver="org.apache.derby.jdbc.ClientDriver"
url="jdbc:derby://localhost:1527/testdb" user="usr"
maxActive="10" maxIdle="5" minIdleTime="1800"
evictionInterval="3600" />
</DatabaseConfiguration>
9. Start the Event Subsystem by selecting Control Panel > Services.
10. Verify from the eventsubd.log that the Event Subsystem has started properly.

Setting User Information


To add the user usr with a password of hgaur, issue the command:
CALL SYSCS_UTIL.SYSCS_SET_DATABASE_PROPERTY('derby.user.usr','hgaur');

To remove the user mary by setting the password to null, issue the following command:
CALL SYSCS_UTIL.SYSCS_SET_DATABASE_PROPERTY('derby.user.mary', null)

To add Derby users and not users in LDAP or an external file, issue the following
command:
CALL SYSCS_UTIL.SYSCS_SET_DATABASE_PROPERTY
('derby.authentication.provider','BUILTIN');

To add the property required for authentication, issue the following command:
CALL SYSCS_UTIL.SYSCS_SET_DATABASE_PROPERTY
('derby.connection.requireAuthentication','true');

Interwoven, Inc. 292


Appendix E: Using the Derby Database

Testing Derby
You can test whether a valid user and password have been created. The first command
shows testing a user with an invalid password and receiving an error message, while the
second command shows using a valid password.
ij> connect 'jdbc:derby:testdb;create=false;user=usr;password=test';
ERROR 08004: Connection refused : Invalid authentication.
ij> connect 'jdbc:derby:testdb;create=false;user=usr;password=hgaur';

Managing the Derby Database


To remove the Derby database, stop Derby and then delete the database folder.

A Derby table or index (called a conglomerate) can contain unused space after large
amounts of data have been deleted or updated. This happens because, by default, Derby
does not return unused space to the operating system. After a page has been allocated to
a table or index, Derby does not automatically return the page to the operating system
until the table or index is dropped, even if the space is no longer needed. However,
Derby provides the following commands to reclaim unused space in tables and
associated indexes.
ij> call SYSCS_UTIL.SYSCS_COMPRESS_TABLE('USR', 'MESSAGES', 1);
0 rows inserted/updated/deleted
ij> call SYSCS_UTIL.SYSCS_COMPRESS_TABLE('USR', 'MESSAGE_HANDLES', 1);
0 rows inserted/updated/deleted

NOTE
See Derby documentation at http://db.apacheorg/derby/ for details on running and
managing a Derby database.

<BookTitle> 293
Appendix E: Using the Derby Database

Interwoven, Inc. 294


Appendix F

Specifying Content Encoding

TeamSite includes a configuration file called file_encoding.cfg that enables you to


create rules to determine the character encoding of the contents of files that do not
specify their encoding. The file_encoding.cfg file (located by default in
iw-home\local\config) uses an XML-based language called regex_map. The
regex_map format is designed to be structured enough for maintainability, and
extensible so that the same format may be used in future configuration files. This file
contains a <regex_map> element, which contains rules to map vpaths (directory paths)
to the character encoding specification of file contents.

For TeamSite to correctly interpret a text document, it is necessary to know the character
encoding in which its contents are represented. Unlike an HTML document that can
declare the encoding of its contents using an <HTTP META="Content-Type"
CONTENT="text/html; charset=charsetname"> tag, a plain text file has no mechanism
for storing this information. The encoding is required for certain TeamSite functionality
including VisualPreview and the Source Differencing and Interwoven Merge tools.

In previous releases, VisualPreview relied on the Content-Type header from the content
Web server to specify the encoding of plain text files. This required you to configure the
encoding at your content Web server which may limit flexibility and scalability. By
default, the Source Differencing and Interwoven Merge tools assumed that text files are
encoded in ISO-8859-1, which is not suitable for content in eastern Asian languages.

The following sections describe the regex_map language, and how it is used to specify
the character encodings of text files used by TeamSite:
„ regex_map Defined
„ The regex_map Format
„ Strategies for Effective regex_maps
„ Internationalization and regex_maps
„ VisualPreview and file_encoding.cfg
„ Source Differencing and Merging and file_encoding.cfg

TeamSite Administration Guide 295


Appendix F: Specifying Content Encoding

regex_map Defined
A regex_map is a filter that transforms a set of input variable values into a set of output
variable values through a set of rules written in XML using the following form:
Input Variables
var1 = "original value1"
var2 = "original value2"

regex_map

<regex_map>
<match .../>
<subst .../>
<subst .../>
<match .../>
</regex_map>

Output Variables

var1 = "transformed value1"


var2 = "transformed value2"
var3 = "new value3"

Simple regex_map Example


The following regex_map determines the character encoding of TeamSite files. Each
reg_vpath means that a match is to be performed on the vpath variable, and each
val_encoding assigns a result if the match succeeded.

Input Variable
vpath = path of a TeamSite file

regex_map

<regex_map>
<match reg_vpath= "/web/techsupport/jp/" val_encoding= "Shift_JIS"/>
<match reg_vpath= "\.txt$" val_encoding= "8859_1"/>
<match reg_vpath= ".*" val_encoding= "UTF8"/>
</regex_map>

Output Variable
encoding = character encoding
for the given vpath

Interwoven, Inc. 296


Appendix F: Specifying Content Encoding

In the preceding regex_map example:


„ If the input vpath variable is "/x/y/z.txt", the resulting encoding variable is set to
"8859_1" because "/x/y/z.txt" ends with ".txt".

„ All files in the /web/techsupport/jp branch are encoded in Shift-JIS, because their
vpath begins with "/web/techsupport/jp/".

„ If the input vpath variable does not contain "/web/techsupport/jp/", the output
encoding variable is set to "UTF8" because ".*" matches any string.

Each rule within <regex_map> is evaluated in order, the first <match> tag with a regular
expression that matches the input variable vpath is used, and subsequent rules are
ignored. Therefore, it is important for the <match reg_vpath= ".*" val_encoding=
"UTF8"/> rule to appear last.

The regex_map Format


A regex_map consists of a <regex_map> element that contains substitution and match
rules expressed by using <subst> and <match> tags. Substitution and match rules are
consulted in the order in which they are listed within the <regex_map> element. Each
rule may assign values to variables.

Rule Syntax
Every <subst> or <match> rule expresses the following logical operation:
„ If all the regular expressions within this rule match, then perform all of this rule’s
variable assignments; otherwise, ignore this rule and consult the next rule.

Execution terminates when the first <match> rule has been applied, or when there are no
more rules. A <subst> rule that has been satisfied does not terminate execution (unless
it is the last rule).

All attributes of rules use the form reg_varname or val_varname.


„ reg_varname attributevApplies a regular expression to varname.
„ val_varname attribute. Assigns a value to varname if all of the regular expressions
in the current rule are satisfied.

The following are some simple examples of rules.


„ If vpath starts with /default/main/ set the encoding to 8859_1 and continue
processing:
<subst reg_vpath="^/default/main/" val_encoding="8859_1"/>

„ The encoding of all files named index_zh_TW.html anywhere in the /web branch is
Big5. There are no exceptions to this rule, so stop processing if it applies.

TeamSite Administration Guide 297


Appendix F: Specifying Content Encoding

<match reg_vpath=
"^/web/(STAGING|WORKAREA|EDITION).*/index_zh_TW.html"
val_encoding= "Big5"/>

Note that the “or” capability of regular expressions, expressed by the pipe character
( | ), enables this single rule handle three cases at once (STAGING or WORKAREA or
EDITION).

„ The encoding is always "Shift_JIS".


<match val_encoding="Shift_JIS"/>

When there are no reg_ conditions, the assignment always executes if the rule is
encountered. Any rules that occur after this statement are unused.

Regular Expression Syntax


The regex_map interpreter uses Perl-Compatible Regular Expressions (PCRE) as its
regular expression engine. The PCRE is similar to the Perl regular expression engine
and includes advanced features such as “lookahead” assertions.

Regular expressions in regex_map are case-sensitive by default. If a variable is listed in


the opt_case_insensitive attribute of <regex_map>, all regular expressions applied to
that variable in the regex_map are case-insensitive.

For example, because filenames and URLs are case-insensitive on Microsoft Windows,
the following declaration would be recommended when writing a regex_map for a
TeamSite server on Microsoft Windows:
<regex_map opt_case_insensitive="vpath url">
<subst reg_vpath="..." .../>
<match reg_url="..." .../>
</regex_map>

Variables
Variables store strings to be passed in the following ways:
„ As input to a regex_map from an application.
„ From rule to rule within a regex_map.
„ As results from a regex_map to the application.

Variable names are case-sensitive and must begin with a letter and may contain any
sequence of alphanumeric characters and the underscore character ( “ _ ” ). References to
any variable whose value is not set by the application or by rules in the regex_map
evaluates to an empty string.

Interwoven, Inc. 298


Appendix F: Specifying Content Encoding

Application Variables
Any application that uses a regex_map gives it a set of inputs before execution and
inspects a set of output variables when the regex_map processing completes. These
input and output variables are known as application variables.

Intermediate Variables
You may find it helpful to assign intermediate results to your variables in regex_map
rules before arriving at final output values. These intermediate variables can help make
a complex set of rules more manageable by factoring out several separate conditions
into one condensed case. You can then write one rule to act on the condensed case,
instead of repetitively writing the same actions for the individual initial conditions.
“Strategies for Effective regex_maps” on page 303 contains an example of factoring.

Intermediate variables should have names that begin with x_ to avoid conflicts with
application variables that Interwoven may create in the future.

Interpolation of Variables and Captured Subexpressions


When assigning a value to a variable, the values of other variables can be included. In
val_attributes, each occurrence of ${varname} or $varname causes the value of
varname to be inserted instead, as shown in the following example:

Input Variables
good = "Bon"
my = "mon"
friend = "ami"

regex_map

<regex_map>
<subst val_french="${good}jour"/>
<match val_friend="copain"
val_french="$french, $my $friend!"/>
</regex_map>

Output Variables
good = "Bon"
my = "mon"
friend = "copain"
french = "Bonjour, mon ami"

TeamSite Administration Guide 299


Appendix F: Specifying Content Encoding

In the preceding example:


„ In the <subst> rule, curly braces ({ }) are required to separate the variable name
good from the literal string jour that immediately follows.

„ In the <match> rule, there is no need to disambiguate the three variables because the
variable names french, my, and friend are followed by a comma, a space, and an
exclamation point, none of which can be confused as being part of a variable name.
„ In the second rule, the values of friend and french are taken from the time at which
the rule was encountered. All assignments in a rule appear to occur simultaneously
and do not affect each other.

It is also possible to include just portions of variables. Placing parentheses around


portions of a regular expression applied to varname creates a captured subexpression
variable that can be used when assigning values. The longhand form of a captured
subexpression variable is ${varname:n}, which refers to the string captured by the n th

pair of parentheses in reg_varname.

NOTE
Pairs of parentheses are numbered according to the order in which their left parenthesis
occurs within the regular expression. Parentheses of the form (?:some_expression) are
used solely for grouping characters in the regular expression, not for capturing text
during matching, and are excluded from the count.

The shorthand version of a captured subexpression variables is $n. Note that the
shorthand notation can only be used when the variable being modified is the same as the
variable from which the subexpression was captured.

Unlike application and intermediate variables, captured subexpression variables are


scoped to the <subst> or <match> rule that created them. If a captured subexpression
variable needs to be used in a subsequent rule, it should be stored in an intermediate
variable.

For example, the pair of rules in the following regex_map makes the assignment
message="regex_maps are awesome maps!" in an inefficient way:

Interwoven, Inc. 300


Appendix F: Specifying Content Encoding

Input Variables
text = "My, how large your eyes are!"
message = "regards some maps with awe"

regex_map

<regex_map>
<subst reg_text="This regular expression match fails"
reg_message="some (m[aeiou]ps)"
val_text="so this assignment never occurs..."
val_message="... and the $1 capture is wasted."/>
<subst reg_text="(?:(bloop)|([a-z]+)(!))"
reg_message="(...)ards ((.{4}) (.{4})) with (.*)"
val_message="$1ex_${4} ${text:2} ${message:5}$2${text:3}"/>
</regex_map>

Output Variables
text = "My, how large your eyes are"
message = "regex_maps are awesome maps!"

In the previous example:


„ The first rule does not apply because the value of the text variable does not match
the regular expression in reg_text.
„ While performing the regular expression match for message, the special variable
${message:1} (the $1 variable associated with message) takes on the value maps
within the scope of the rule. However, since the entire rule is inapplicable, it has no
effect. Neither of the two val_assignments happens, and the temporary
${message:1}="maps" binding is discarded.

„ The second rule does apply, since both of the reg_text and reg_message matches
succeed. The parentheses also capture the text in the strings, resulting in the
following temporary bindings:
${text:1} = empty string
${text:2} = are
${text:3} = !
${message:1} = reg
${message:2} = some maps
${message:3} = some
${message:4} = maps
${message:5} = awe
„ Finally, variable interpolation occurs for the val_message assignment. Since the $1,
${4}, and $2 occur in a val_message context, they are treated as shorthand for
${message:1}, ${message:4}, and ${message:2}, respectively. The curly braces
for ${4} are optional in this case, and could be used in other situations to clarify
where the variable name ends and literal text begins.

TeamSite Administration Guide 301


Appendix F: Specifying Content Encoding

Quoting
Inside a val_ attribute, dollar signs ($) have special meaning—they mark the start of
captured subexpression names. To force a dollar sign to lose this special meaning (and
be treated as a literal dollar sign), it must be escaped by preceding it with a backslash.
Similarly, a backslash is treated as a special quoting character unless it is escaped by a
preceding backslash.
Input Variable
hello = "Hi"

regex_map

<regex_map>
<subst reg_hello="(.*)"
val_hello="$1! Parking costs \$1\\hr."
</regex_map>

Output Variable
hello = "Hi Parking costs $1\hr."

In the preceding example, hello is assigned the value "Hi! Parking costs $1\hr."
(with the deliberately “wrong” backslash used instead of a forward slash for
demonstration purposes).

Also, because regex_map is written in XML, characters with special meaning in XML
need to be represented using XML entities. These special characters are described in the
following table.

Table 23 XML Special Characters


Special XML Character Visual Representation XML Entry
Double quote ” &quot;

Apostrophe ’ &apos;

Ampersand & &amp;

Greater than > &gt;

Less than < &lt;

For example,
<subst val_statement="Programmers think &quot;1 &amp; 1 is 1.quot;"/>

assigns the following value to the statement variable:


Programmers think “1 & 1 is 1.”

Interwoven, Inc. 302


Appendix F: Specifying Content Encoding

Strategies for Effective regex_maps


The regex_map grammar is a powerful string manipulation language yet still allows
simple configurations to be expressed simply. This is due to:
„ the ability to work with multiple variables
„ the use of regular expressions with the capability to reference captured
subexpressions
„ the option to chain rules with <subst> or stop processing with <match>

By taking advantage of these features, you can write configuration files that are compact
and manageable.

The following example demonstrates how factoring and intermediate variables can
make a regex_map configuration scale to handle complex situations. Suppose that a
system-wide reorganization forced you to rename all files named README to README.TXT
and relocate all files under the /a/b branch to the /c/d branch. You could list all of the
possibilities as follows:
<regex_map>
<!- Handle both branch move and file extension addition ->
<match reg_vpath= "/a/b/((WORKAREA|EDITION|STAGING).*)README$"
val_vpath= "/c/d/$1README.TXT"/>

<!- Handle branch move only ->


<match reg_vpath= "/a/b/((WORKAREA|EDITION|STAGING).*)"
val_vpath= "/c/d/$1"/>

<!- Handle file extension addition only ->


<match reg_vpath= "(.*)/README$"
val_vpath= "$1/README.TXT"/>
</regex_map>

But this strategy could become extremely complicated if there were more combinations.
A factored set of rules can handle each change independently:
<regex_map>
<!- Handle a possible branch move ->
<subst reg_vpath= "/a/b/((WORKAREA|EDITION|STAGING).*)"
val_vpath= "/c/d/$1"/>

<!- Handle a possible file extension addition ->


<subst reg_vpath= "(.*)/README$"
val_vpath= "$1/README.TXT"/>
</regex_map>

A complicated set of rules could be clarified with intermediate variables, for example:
<regex_map>
<!-- Decompose vpath into branch, area, directory, filename -->
<!-- Decomposition could be done in just one rule, -->
<!-- but we choose to break it up with the help of x_rest. -->

TeamSite Administration Guide 303


Appendix F: Specifying Content Encoding

<subst reg_vpath="^(.*?)/((?:WORKAREA|EDITION|STAGING).*)"
val_x_branch="${vpath:1}"
val_x_rest="${vpath:2}"/>
<subst reg_x_rest="((?:WORKAREA|EDITION)/[^/]+|STAGING)(.*)"
val_x_area="${x_rest:1}"
val_x_rest="${x_rest:2}/>
<subst reg_x_rest="(.*)(/.*)"
val_x_dir="${x_rest:1}"
val_x_file="${x_rest:2}"/>
<!-- End decomposition -->

<!-- Do the transformations -->


<subst reg_x_branch="^/a/b$"
val_x_branch="/c/d"/>

<subst reg_x_file="^/README$"
val_x_file="/README.TXT"/>
<!-- End transformations -->

<!-- Put vpath back together. -->


<subst val_vpath="$x_branch$x_area$x_dir$x_file"/>
</regex_map>

In the preceding example, factoring out the vpath decomposition logic simplifies the
actual transformation rules. In a complex situation with many transformation rules,
adding a few standardized rules at the beginning and end of the regex_map is
worthwhile.

Internationalization and regex_maps


TeamSite regex_maps should be written in UTF-8 and should provide UTF-8 input
values and expect UTF-8 output values for all variables. The regular expression engine
is UTF-8-aware. For example, a period (.) in a regular expression matches a single
character, regardless of the number of bytes needed to represent that character.

If you need to specify non-ASCII literal characters in your regex_maps, ensure the text
editor you are using can edit and save the file_encoding.cfg in UTF-8 encoding.
Refer to page 314 for details about text editor encodings.

Interwoven, Inc. 304


Appendix F: Specifying Content Encoding

VisualPreview and file_encoding.cfg


To determine the encoding of a text file, VisualPreview mimics the behavior of your
web browser by performing the following series of checks:
„ First, VisualPreview checks the Content-Type header from the content webserver. If
the MIME type (text/html or text/plain) is followed by a character encoding
declaration (for example, Content-Type: text/plain; charset=UTF-8), it uses
the specified encoding.
„ If the file is an HTML document, VisualPreview searches for a character encoding
declaration in an HTML META tag (for example, <META
HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=Big5">), which it
uses if found.
„ If the aforementioned methods do not return the encoding, VisualPreview computes
the encoding using the regex_map configuration in the file_encoding.cfg file. It
uses the vpath as the input variable and the encoding as the expected output.

Source Differencing and Merging and


file_encoding.cfg
Unlike VisualPreview, the Source Differencing and Interwoven Merge tools do not
mimic your web browser. Instead, they rely entirely on the file_encoding.cfg file to
determine the character encoding of text documents. The Source Differencing and
Interwoven Merge tools assume that the “other” file and the “common ancestor” file
share the character encoding of the workarea file.

The following list of encodings are the IANA preferred charset names
(http://www.iana.org/assignments/character-sets) and are valid entries for the
file_encoding.cfg file:

English, German:
„ ISO-8859-1
„ ISO-8859-15
„ windows-1252

Japanese:
„ Shift_JIS
„ EUC-JP

Korean:
„ EUC-KR

TeamSite Administration Guide 305


Appendix F: Specifying Content Encoding

Simplified Chinese:
„ EUC-CN
„ GB2312

Unicode:
„ UTF-8

NOTE
file_encoding.cfg has no effect on the file encoding seen in visual differencing. This
is so that what is seen in the visual differencing tool most closely approximates what
will be seen in the production environment.

Sample file_encoding.cfg
<?xml version="1.0" encoding="UTF-8"?>

<!-- Input variable: vpath -->


<!-- Output variable: encoding -->
<vpath_to_encoding_map>

<!-- Ignore upper and lower case when


evaluating reg_vpath and reg_encoding conditions. -->
<regex_map opt_case_insensitive="vpath encoding">
<!-- Set the default result. A default like this is highly
recommended. -->
<subst val_encoding="8859_1"/>

<!-- Make a note of Japanese files scattered about. -->


<subst reg_vpath="(?:_ja|_jp|_jpn)\."
val_x_lang="Asian:Japanese"/>

<!-- Likewise with Chinese files. -->


<subst reg_vpath=".*\.zh\.txt$"
val_x_lang="Asian:Chinese"/>

<!-- As site policy, our Japanese files are Shift-JIS -->


<subst reg_x_lang="Asian:Japanese"
val_encoding="Shift-JIS"/>

<!-- As site policy, our Chinese files are Big5 -->


<subst reg_x_lang="Asian:Chinese"
val_encoding="Big5"/>

<!-- Otherwise, the directory name at the top of the area is the
result. -->

Interwoven, Inc. 306


Appendix F: Specifying Content Encoding

<subst reg_vpath="(?:(?:WORKAREA|EDITION)/[^/]+|STAGING)/([^/]+)/"
val_encoding="${vpath:1}"/>

<!-- Canonicalize encoding names. Try Shift_JIS, then SJIS. -->


<match reg_encoding="(sjis|shift[_-]jis)"
val_encoding="Shift_JIS"/>
</regex_map>
</vpath_to_encoding_map>

TeamSite Administration Guide 307


Appendix F: Specifying Content Encoding

Interwoven, Inc. 308


Appendix G

Internationalization

The following topics are specifically addressed in this chapter:


„ Overview
„ Supported Client and Server Platforms
„ Supported Content
„ Limitations and Assumptions
„ Content Stores and Character Encoding
„ About UTF-8
„ URL Commands with Multibyte Characters
„ Interfacing with Localized Operating Systems
„ Accessing the Localized Interface
„ Language of the VisualPreview Tool Bar
„ Running TeamSite CLTs in DOS Console Mode
„ Specifying File Encoding of Text Files
„ Usage Scenarios

Overview
TeamSite is engineered with your global enterprise in mind. This includes
internationalizing the TeamSite server to support multibyte languages and locales at the
operating system, and localizing the ContentCenter user interface and documentation.
Internationalized TeamSite supports the following needs:
„ International user data. Enables users to enter data, content, and field values in
English, Korean, Traditional Chinese, Simplified Chinese, French, German, and
Japanese.
„ Localized operating system. The TeamSite server runs on any one of the following
localized operating systems: English, French, German, Korean, Simplified Chinese,
Traditional Chinese, and Japanese (one locale per instance of iwserver).
„ Localized user interfaces. The ContentCenter Professional and ContentCenter
Standard interfaces have been localized into French, German, Japanese, Korean,
Traditional Chinese, and Simplified Chinese.

TeamSite Administration Guide 309


Appendix G: Internationalization

„ Localized file names. You are no longer restricted to having file and directory
names in ASCII character encoding. For example, file, directory, branch, workarea,
and edition names can have Japanese names on Japanese servers, German names on
German servers, Simplified Chinese names on Simplified Chinese servers, and so
forth.
„ Continued support for processing of non-English metadata and FormsPublisher
content.

NOTE
Information on localized servers contained in this chapter is only valid with localized
TeamSite versions. Check the Release Notes to determine whether localized servers are
supported in your TeamSite version.

Supported Client and Server Platforms


The client connecting to the TeamSite server must use the same language as the server
(they can be different locales of the same language). For example, running
ContentCenter on German Windows 2000 connected to a Solaris 2.8 TeamSite server
running in the German Latin 1 locale (de) is supported. However, if that same German
Windows 2000 client logged into a Windows 2000 Japanese TeamSite server and added
files with names containing German High ASCII characters, those files would not be
supported by the TeamSite server due to limitations with the native file system and
handling of characters outside of its code pages.

Supported Content
TeamSite supports non-ASCII characters in branch, area, directory, vpath, and file
names in addition to the contents of a file.

Limitations and Assumptions


„ An internationalized TeamSite server does not mean that your TeamSite server can
be run in multiple locales concurrently. The TeamSite server can run in any
supported locale, but one locale at a time.
„ It is expected that the locale in which the TeamSite server runs is the same locale as
the rest of file system and server operating systems. Consider the following
scenario:
a. You have a file server which runs in ja (Japanese Extended UNIX Code) locale,
with a hierarchy of file and directory structures with names encoded in Japanese
EUC.

Interwoven, Inc. 310


Appendix G: Internationalization

b. You install and run your TeamSite server on this file server.
c. You use the file system interface to migrate your existing hierarchy of files and
directories into the TeamSite File System.
d. The TeamSite server must run in the ja locale for these file and directory names
to be processed correctly. If you change the locale to ja_JP.PCK (Japanese
Shift-JIS) before TeamSite server is started, the TeamSite server would
incorrectly interpret the imported file and directory names as ja_JP.PCK
encoded. This is not a supported scenario.
„ Mixed-locale file systems are not supported. For example, a scenario where a parent
directory has directory names encoded in ja_JP.PCK (Japanese Shift-JIS, and child
directories have file names encoded in ja is not supported.
„ If TeamSite server is running on a German operating system using a German Latin1
locale, it is possible to create a branch or workarea on the TeamSite File System
with Japanese names using ContentCenter. However, when viewed with the file
system interface, these Japanese names would appear as illegible characters because
the server is running in a Latin1 locale and does not include the Japanese character
set. This is not a supported scenario.
This scenario is supported for Metadata because Metadata entered using the
ContentCenter does not interact with server operating system. Any data that is
interchanged with the server operating system (including VPATHs) are only
meaningful if they are within the server locale’s encoding.
„ If the TeamSite File System is functioning as a networked file server, it is expected
that all other networked file system clients (for example, NFS clients) are operating
in the same locale as the TeamSite File System file server.
Currently, NFS does not enforce this restriction and therefore enables NFS clients to
be in a different locale than the NFS server. However, NFS protocol does not do
encoding conversion. Therefore, file and directory attributes (including names) are
passed through in binary format. This would not work for TeamSite File System
functioning as a file server because it does encoding conversion from and into
UTF-8 based on the server file system’s locale.

Content Stores and Character Encoding


User-defined Content Stores that are named using multibyte characters must have a
corresponding entry in the iw.cfg file. Refer to the TeamSite Installation Guide for
detailed information on creating Content Stores.

About UTF-8
UTF-8 is the 8-bit encoding format for Unicode. Unicode is a system for exchanging,
processing, and displaying diverse written languages. Unicode supports the principal
written languages of the world as well as many classical languages.

TeamSite Administration Guide 311


Appendix G: Internationalization

URL Commands with Multibyte Characters


When constructing URL commands when parameters contain multibyte characters,
make sure that these parameters are URL- and UTF-8--encoded. Multibyte characters
should be URL-encoded based on their Unicode representation in UTF-8.

For example, the URL to edit the file:

/archive/main/WORKAREA/area/ .html

would be:
/iw/iw-cc/edit?vpath=/archive/main/WORKAREA/area/%e5%ba%9c.html

since the Japanese character is Unicode character U+30D5, which is encoded as the
bytes 0xe5 0xba 0x9c in the UTF-8 format.

Interfacing with Localized Operating Systems


The internationalized TeamSite server’s virtualized Intelligent File System (IFS)
functions the same way a regular file system does on localized operating systems. For
example, if TeamSite runs on a server that is running in the EUC-JP locale, the
TeamSite IFS displa