Ts 671sp1 Wfdev v01 en

TeamSite ®
Workflow Developer’s
Guide
Release 6.7.1
Service Pack1
© 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, ContentServices, ControlHub, DataDeploy, DeskSite, FileSite, iManage,

LiveSite, MediaBin, MetaCode, MetaTagger, OffSite, OpenDeploy, Primera, Scrittura, 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, GBRI # 1053523, US #
6,480,944, US# 5,845,270, 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, KORS 10-0576487, JAPA
#2968582, MX #219522, NZ #516340, SING #109524, 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, US #7,092,969 or other
patents pending application for Interwoven, Inc.
Interwoven, Inc.
160 Tasman Drive
San Jose, CA 95134
http://www.interwoven.com
TeamSite Workflow Developer’s Guide

Part #01-011-01-EN
August 2007
Table of Contents
About This Book 13
Notation Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13
Notation of iw-home on UNIX and Windows Systems . . . . . . . . . . . . . . . . . . . . . . .14
Windows Path Name Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14
Chapter 1: Introduction 15
Workflow Terminology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .15
Workflow Models. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .15
Jobs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16
Workflow Templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .17
Job Specifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .17
Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .17
Transitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18
Workflow Illustrated . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18
Workflow Templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .20
Instantiator CGI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .20
Browser Interface (GUI) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .21
Job Specification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .21
Server-Side Workflow Subsystem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .21
Workflow Development . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .21
Chapter 2: Using Workflows 23
Default Template Descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .24
Example Template Descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .24
Enabling Workflows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .25
Integrating with OpenDeploy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .27
Workflow Configuration Files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .28
available_templates.cfg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .29
Specifying Template Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .30
Regular Expression Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .33
available_templates.dtd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .34
iw.cfg. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .35
[iwsend_mail] Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .35
[workflow] Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .36
Querying Workflows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .37
External Task Commands Using URLs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .39
Sample Files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .40
Demonstrating the Workflow CGI Task . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .40
Roles Considerations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .41
Specifying Reviewer Roles in Workflow Templates . . . . . . . . . . . . . . . . . . . . . .41
Configuring Callout Buttons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .42
TeamSite Workflow Developer’s Guide 3

Contents
Chapter 3: Using Solution Workflows 43

Solutions Workflows Illustrated . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .43
Author Submit with Deploy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .44
Author Submit with Email . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .45
Author Submit with Metadata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .46
Configurable Author Assignment. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .47
Configurable Author Submit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .48
Configurable Default Submit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .49
Review Subflows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .49
Serial Review . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .50
Return on First Reject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .51
All At Once . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .52
Concurrent Review. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .53
Configurable Workflow Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .54
Workflow-Specific Configuration Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .54
Workflow.cfg File Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .54
configurable_author_submit.cfg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .55
configurable_default_submit.cfg. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .55
configurable_author_assignment.cfg. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .55
Workflow.properties File Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .55
VisualAnnotate and Configurable Workflows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .56
Configurable Workflow Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .56
Email Notification Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .57
Metadata Capture Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .58
Deployment Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .59
Review Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .60
Simple Examples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .61
Advanced Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .62
Add Files Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .63
Configurable Workflows and Localization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .64
Chapter 4: Creating Workflow Template Files 65
Workflow Template File Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .65
Simple Workflow Template File. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .66
<template_script> Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .67
CGI_info Directive. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .68
TAG_info Directive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .70
TAG_info(): iw_setwfarg_ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .73
__ELEM__ Directive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .73
__TAG__Directive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .74
__INSERT__ Directive. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .77
__VALUE__ Directive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .77
Other Elements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .79
Using Variables in Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .79
Scenario 1: Basic Variable Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .79
Scenario 2: Including Quotation Marks in Insertions . . . . . . . . . . . . . . . . . . .79
Scenario 3: Preferred Ordering of Single and Double Quotes. . . . . . . . . . . . .80
Complex Workflow Template File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .80
is_user_in_roles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .82
Interwoven, Inc. 4
Contents
Chapter 5: Job Specification Files 83

Job Specification File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .83
Job Specification DTD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .84
workflow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .89
DTD Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .89
Associated Subelements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .89
Associated Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .89
description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .90
DTD Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .90
variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .90
DTD Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .90
areavpath . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .91
DTD Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .91
timeout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .91
DTD Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .91
succ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .92
DTD Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .92
files and file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .92
DTD Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .92
activation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .93
DTD Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .93
inactivate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .94
DTD Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .94
resets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .94
DTD Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .95
eastartop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .95
DTD Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .95
eafinishop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .96
DTD Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .96
wfvarstartop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .97
DTD Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .97
wfvarfinishop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .98
DTD Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .98
usertask . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .98
DTD Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .98

Contents
successors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .100
DTD Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .100
Associated Subelements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .100
Associated Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .100
grouptask . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .101
DTD Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .101
sharedby . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .102
DTD Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .102
user. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .103
DTD Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .103
group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .103
DTD Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .103
externaltask . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .104
DTD Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .104
command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .105
Use with externaltask . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .105
Use with cgitask . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .106
DTD Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .106
cgitask . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .107
DTD Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .107
submittask . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .109
DTD Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .109
updatetask . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
DTD Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .111
srcareapath . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .113
DTD Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .113
endtask . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .113
DTD Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .113
dummytask . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .114
DTD Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .114
Interwoven, Inc. 6
Contents
locktask . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .115
DTD Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .115
wftask. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .116
DTD Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .116
jobfile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .117
DTD Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .117
wftfile. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .118
DTD Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .118
success . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .118
DTD Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .118
failure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .119
DTD Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .119
Perl Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .120
TeamSite::WFsystem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .120
Synopsis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .120
Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
Examples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .120
TeamSite::WFworkflow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .121
Synopsis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .121
Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
TeamSite::WFtask . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .122
Synopsis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .123
Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
Sample Job Specification File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .125
Running Manually Created Jobs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .129
Chapter 6: Using VisualAnnotate 131
Task Checklist for Using VisualAnnotate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .131
VisualAnnotate Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .132
Sample Scenario. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .132
Installing the VisualAnnotate Client Toolbar . . . . . . . . . . . . . . . . . . . . . . . . . . . . .134
Configuring VisualAnnotate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .135
Email Template Settings. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .136
Prompt Initiator Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .137
Review Cycles Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .137
Variables Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .137
Approval Label Settings. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .138
Disabling VisualAnnotate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .139
Preserving Images In Snapshots . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .139
Editing the Administrator Email Address . . . . . . . . . . . . . . . . . . . . . . . . . . . . .140

Contents
VisualAnnotate Port Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .140

Testing the VisualAnnotate Installation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .140
Chapter 7: Template-Based Email 141
How Template-Based Email Works. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .141
The Header. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .142
The HTML Part . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .143
The Plain Text Part. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .143
Using HTML and Plain Text in Combination. . . . . . . . . . . . . . . . . . . . . . . . . . .143
Use in Workflows. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .144
The Structure of the XML Document. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .145
Template Creation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .146
Flex Roles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .148
Debugging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .148
iw_solution_email.ipl Data Flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .148
Chapter 8: Debugging Techniques 151
Debugging Workflow Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .151
iw_debug_mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .151
iw_output_file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .151
Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .151
Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .152
Workflow Log File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .152
Appendix A: Workflow Tutorial 153
Terms. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .153
Task Symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .154
Designing a Workflow. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .154
Determine Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .154
Diagram the Workflow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .155
Use Existing Workflows. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .155
Begin Customized Implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .155
Document Your Work. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .155
Mapping Out Workflows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .156
Resets and Inactivate. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .157
Locks. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .158
Locks External to Workflow Engine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .159
Audit Trail Archival . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .159
Complex Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .159
externaltask . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .159
Debugging an externaltask script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .160
Additional Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .161
cgitask . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .161
Debugging a cgitask Script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .162
Additional Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .162
Retrieving File Comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .163
Callbacks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .164
iwcallback and TeamSite::WFtask::CallBack(). . . . . . . . . . . . . . . . . . . . . . .164
TeamSite::CGI_lite::iwcallback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .165
Sending Email Notification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .165
Interwoven, Inc. 8
Contents
Prompting for Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .166

Setting the Size of the Instantiation Window . . . . . . . . . . . . . . . . . . . . . . . . . . .166
Debugging Hints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .166
Error Messages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .167
Active Workflow with No Active Tasks. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .168
Appendix B: iwsend_mail.ipl Script 169
Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .169
Constructing Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .170
Command Line Vs. Task Variable Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .170
Command Line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .170
Determining Email Addresses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .171
Sending to Multiple Recipients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .172
Command-Line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .172
Task Variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .172
Specifying the Sender . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .173
Command Line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .173
Task Variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .173
Specifying the Subject Line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .173
Command Line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .173
Task Variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .174
Composing the Message Body . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .174
Command Line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .174
Task Variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .175
URL Formatting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .175
Command Line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .175
Task Variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .176
HTML Formatting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .176
Command Line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .176
Task Variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .176
Next Task Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .177
Task Level Variables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .177
Enabling Error Capturing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .177
Command Line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .177
Task Level. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .178
iwsend_mail.ipl Workflow Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .179
Associated File Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .179
iw.cfg File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .179
email_map.cfg File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .179
Workflow Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .180
Command Line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .180
Task Variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .180
Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .180
Using URL Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .181
Using HTML Mode. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .182

Contents
Appendix C: CGI Task Example 183

Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .183
Installation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .184
Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .184
Background . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .184
Sample CGI Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .185
Possible Enhancements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .188
Sample Workflow Template . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .188
Frequently Asked Questions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .190
Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .191
Appendix D: External Task Example 193
Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .193
Installation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .194
Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .194
Background . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .195
Command Line Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .196
Importance of the Callback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .196
Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .197
Sample Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .198
Sample Workflow Template . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .199
Frequently Asked Questions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .201
Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .202
Index 205
Interwoven, Inc. 10
List of Figures
Figure 1 Workflow model of an Author Assignment business process. . . . . . . . . . .16
Figure 2 Workflow with assigned users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16
Figure 3 Workflow Components. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .19
Figure 4 Diagram of the Author Submit with Deploy solution workflow . . . . . . . .44
Figure 5 Diagram of the Author Submit with Email solution workflow. . . . . . . . . .45
Figure 6 Diagram of the Author Submit with Metadata solution workflow . . . . . . .46
Figure 7 Diagram of the Configurable Author Assignment solution workflow . . . .47
Figure 8 Diagram of the Configurable Author Submit solution workflow . . . . . . . .48
Figure 9 Diagram of the Configurable Default Submit solution workflow . . . . . . .49
Figure 10 Diagram of the Return on First Reject review workflow . . . . . . . . . . . . . .51
Figure 11 Diagram of the All-at-once Review workflow . . . . . . . . . . . . . . . . . . . . . .52
Figure 12 Diagram of the Concurrent review workflow. . . . . . . . . . . . . . . . . . . . . . .53
Figure 13 Review Email. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .58
Figure 14 Task List. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .134
Figure 15 Task Details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .134
Figure 16 VisualAnnotate Toolbar installation screen . . . . . . . . . . . . . . . . . . . . . . .135
Figure 17 Data flow for solution email . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .149
Figure 18 Task Symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .154
Figure 19 State Transition Diagram . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .156
Figure 20 Workflow diagram with descriptive titles . . . . . . . . . . . . . . . . . . . . . . . .157
Figure 21 Workflow diagram with logical conditions . . . . . . . . . . . . . . . . . . . . . . .158
Figure 22 Sample email message using HTML mode . . . . . . . . . . . . . . . . . . . . . . .182
Figure 23 CGI Task screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .186
Figure 24 CGI task debugging information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .187
Figure 25 CGI Task completion message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .187
Figure 26 Workflow process. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .189
Figure 27 Job instantiation form for a CGI task . . . . . . . . . . . . . . . . . . . . . . . . . . . .189
Figure 28 Workflow process. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .199
Figure 29 Job instantiation form for an external task . . . . . . . . . . . . . . . . . . . . . . . .200

List of Figures
Interwoven, Inc. 12
About This Book
The TeamSite Workflow Developer’s Guide is a guide to configuring and using TeamSite
workflows. This document is primarily intended for TeamSite Administrators and
Master users, and workflow developers.
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 (including menu items, buttons,
or elements 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.
Monospaced Monospaced italics are used for command-line variables. For
italic example:
iwckrole role user
Means you must replace role and user with actual role and user
values.
Monospaced Monospaced bold represents user input. The > character that appears
bold 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 Monospaced bold italic text is used to indicate a variable in user
bold 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.

About This Book
Table 1 Notation Conventions (Continued)

Convention Definition and Usage
[] 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.
Notation of iw-home on UNIX and Windows

Systems
This manual uses iw-home as the symbolic name of the directory that contains your
TeamSite program files on Windows and UNIX systems. The italics are an Interwoven
convention identifying iw-home as a variable. You should interpret the iw-home notation
used in this manual as follows:
On UNIX systems, the directory containing the TeamSite program files. The default
is /Interwoven/TeamSite.
On Windows systems, the directory containing the TeamSite program files. The
default is: C:\Program Files\Interwoven\TeamSite
The administrator that performed the TeamSite installation may have chosen an
installation directory different from the default.
Windows Path Name Conventions

In most cases, you can specify path names using standard Windows naming conventions
(which allow 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:\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. 14
Chapter 1
Introduction
Workflow encompasses the procedures, tasks, people, and equipment that define
business practices and processes within an organization. Using TeamSite to define and
automate workflow ensures that the business practices associated with your content are
performed in a logical and consistent manner leading to better organization and
increased productivity.
This chapter provides a high-level overview of workflows. Later chapters examine

workflow components and various methods of creating workflows.
Workflow Terminology
This section defines workflow terminology as it relates to TeamSite. Many of these
terms have more general definitions outside of the context of TeamSite.
Workflow Models
A workflow model is a general description of a recurring business process. Each
workflow model describes a process consisting of a series of tasks, or units of work, and
can be represented by a flow diagram, illustrating the task sequences and decisions
involved.
Figure 1 shows a simple assign-edit-approve workflow model. Email is sent to the

participants at each stage of the process, and an automated content deployment task is
performed at the end.

Chapter 1: Introduction
Figure 1 Workflow model of an Author Assignment business process
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 Task:
Email sent reviews Email sent submitted Automated
to Author Author’s to Author to staging deployment
work area
The people involved in this description are not actual people, but are abstractly
represented as an editor and an author. Similarly, no specific files are mentioned. This is
an important distinction between the generalized workflow model, representing a
recurring business process, and a specific instance of this process.
Jobs
A job is a specific instance of a workflow model. One example of a TeamSite job is the
set of tasks needed to prepare a new section in a marketing Web site to support a new
product launch.
shows the workflow model depicted in the previous section being used for the
marketing Web site’s new product launch. This job instance now includes specific
TeamSite users: Andre (the editor) and Pat (the author), and specific files that need to be
edited: index.html and banner.gif.
Figure 2 Workflow with assigned users
Task:
Task: Pat edits Task:
Andre Email sent Email sent
initiates job index.html
to Pat and to Andre
banner.gif
Reject Task: Approve Task:

Task: Andre Task: Content Task:
Email sent reviews Email sent submitted Automated
to Pat Pat’s to Pat to the deployment
work staging area
Interwoven, Inc. 16
NOTE
You may find it helpful to refer to Chapter 3, “Using Solution Workflows,” for diagrams
showing actual solution workflows provided with TeamSite.
Because jobs follow predefined workflow models, tasks cannot be added to or removed
from individual jobs.
In TeamSite, a description of a workflow model is called a workflow template. When a

job is created, the job creator supplies all the specific information for that job,
effectively “filling out” the workflow template to create a job specification. When a job
specification is then loaded into the workflow subsystem it becomes a job instance. Each
job is a specific instance of a workflow model.
Workflow Templates
Workflow templates are XML files, with a .wft extension, that describe a particular
workflow model. You can create these files and then transfer them to your TeamSite
server where they can be instantiated by users, as needed, to become specific jobs.
The configuration file available_templates.cfg lists all the workflow templates

available to users to be instantiated.
Job Specifications
Job specifications are XML files that describe a specific job instance. You can create
these files either directly or by invoking the instantiation of a workflow template
through a TeamSite GUI.
Tasks
A task is a both a logical unit of work, when describing business processes, and an
actual unit of work performed by a single user or process during the execution of a
specific job. Each task is associated with a TeamSite branch and workarea and, possibly,
one or more files. The user or process owning a task can modify, add files to, or remove
files from the task (provided the task is not a read-only task for content approval).
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). After the task has been activated, users or
external programs can work on it.

For example, after a user task has been activated, the user can work on the files
contained in that task. After an external task has been activated, the appropriate external
program can run on the files contained in that task.
Inactive tasks are tasks that have been completed, or that have not been activated yet.
Transitions
When one task is finished in a workflow, a transition to the next task (if any) occurs. For
example, when an external task program makes a callback to the workflow engine to say
that it is done and has succeeded, that callback is making a task transition. In an
approval workflow, when the reviewer approves or rejects something, a transition to the
subsequent task occurs.
A workflow can have a maximum of 1000 transitions.
Workflow Illustrated
This section includes a detailed illustration that focuses primarily on the server
processes and the interaction with the end-user (job creators and authors). It introduces
the Instantiator CGI and depicts the four other main components involved in using
workflow templates to create jobs:
Workflow template. Defines the workflow rules through a set of workflow markups
and a set of general workflow configuration instructions.
Instantiator CGI. Interprets the workflow rules and data from end users, produces
browser graphics and prompts, generates a job specification, and instantiates the
job.
Instantiator CLT (iwwft_compile.ipl). An alternative to the Instantiator CGI, this
Command Line Tool interprets the workflow rules and data from end users,
generates a job specification, and instantiates the job.
TeamSite browser-based GUI. Displays forms that prompt end-users for input.
Job specification file. Generated by the workflow instantiator (CGI or CLT).
Server-side workflow subsystem. Provides a framework for controlling processes
involved with these.
Figure 3 shows how these components work together. Sections after the diagram explain
each diagram step and component in detail. The diagram key is displayed following the
illustration.
Interwoven, Inc. 18
Figure 3 Workflow Components
Workflow
Template File
• Workflow
markup
• General
workflow
configuration
instructions
2 5
Instantiator CGI or
1 CLT
Browser • Reads workflow
markups Job Server-Side
• End user Specification Workflow
• Generates forms
selects 3 (not CLT) 6 7 • Subsystem
template • Job-specific
from GUI • Compares data with rules • Runs jobs
• End user fills WF rules • Can
in WF form 4 • Combines data with optionally be
WF instructions written to an
XML file
• Generates job
specification and
instantiates job
In TeamSite ContentCenter Professional, an end user selects a workflow template from

the Actions > New Job menu item. The workflow instantiator (the CGI, in this case)
reads the file available_templates.cfg to determine which workflow template files
are available for that given TeamSite area, file content, or user’s role.
1. The workflow instantiator goes to the specified workflow template file and
iteratively reads and processes all of the workflow’s markup, which consists of Perl
instructions residing in the workflow template file’s template_script element.
(See “<template_script> Element” on page 67 for details about syntax and usage.)
2. Based on the workflow markup, the instantiator CGI (only) creates one or more
workflow forms into which an end user can enter specific job information.
3. An end-user using TeamSite ContentCenter Professional enters information in the
workflow form and submits it back to the instantiator CGI.
4. The instantiator CGI consults the rules in the workflow template file’s workflow
markup to verify the validity of the data entered by the end user. If the data meets all
necessary criteria, it is parsed by the workflow instantiator (see step 6). If the data
does not meet all necessary criteria, the interface re-prompts the end user so that
data can be reentered (default notification is the invalid field turning red in the
workflow form).
5. After determining that the workflow form contains valid data, the workflow
instantiator combines the data with the general instructions from the workflow
template file to create a job specification (and optionally a job specification file) for
this specific job.

If a job specification file is created, it is equivalent to the file you would create
manually if you defined a job as described in Chapter 5, “Job Specification Files.”
When a job specification file is not created (which is typically the case), the
workflow instantiator performs the functional equivalent of writing a job
specification file to disk and then invoking the iwjobc and iwinvokejob commands
to instantiate and execute the job instance.
For an explanation of workflow template file structure and supported element
syntax, see “Workflow Template File Structure” on page 65. For an example of a job
specification file, see “Sample Job Specification File” on page 125.
6. The job is instantiated on the server and started. These actions could be done
manually (using iwjobc and iwinvokejob) as described in “Running Manually
Created Jobs” on page 129.
The following sections provide more details about each diagram component.
Workflow Templates
A workflow template is an XML file that can contain any or all of the elements that are
valid in a job specification file. These elements form the set of general workflow
configuration instructions shown in the diagram in “Workflow Illustrated” on page 18.
See “Workflow Template File Structure” on page 65 for details about these elements.
In addition, the workflow template file can contain <template_script> elements and a
set of directives to define the workflow markups also shown in the diagram on Figure 3.
All instructions residing within a <template_script> element are interpreted by the
workflow instantiator as Perl code. See “Workflow Template File Structure” on page 65
for details and a sample file illustrating these concepts.
Instantiator CGI
TeamSite includes a standard instantiator CGI, iwwft_instantiator.cgi, to perform
the following functions:
Create and display the workflow information form based on information in the
workflow template file.
Evaluate data entered by end users based on the workflow rules in the workflow
template file.
Combine user-entered data with general workflow configuration instructions to
create a job specification.
Instantiate the job specification on the TeamSite server and start the job.
Interwoven, Inc. 20
NOTE
The CLT iwwft_compile.ipl can be used instead, to perform all but the first of these
functions.
Browser Interface (GUI)

End users interact with the workflow subsystem through several different user interfaces
and forms. Within the ContentCenter user interfaces, users can view active job and task
lists and detailed information on a specific task or job. Users can also attach, remove, or
edit files attached to a task. All instructions in this manual refer to the ContentCenter
interfaces.
When a user initiates a new job, a workflow selection list may appear (if more than one
workflow is available to that user in that user’s current TeamSite folder, workarea, or
branch), allowing a user to select which workflow should be instantiated. Once a
workflow has been selected, the workflow information form is then displayed to gather
information from the end user for the specific job being initiated.
Workflows may also trigger external tasks, which, in turn, may create forms or display
other visual elements with which end users may interact.
Job Specification
For an explanation of file structure and supported element syntax, see “Job Specification
File” on page 83. See “Sample Job Specification File” on page 125 for a sample job
specification file.
Server-Side Workflow Subsystem

The server-side workflow subsystem resides on the TeamSite server and contains all the
executable files that provide workflow functionality.
Workflow Development
Workflow development conceptually consists of three sequential phases:
Design: understanding the business process being modeled and breaking it down
into logical tasks. The output from the design phase is a workflow model.
Development: turning a workflow model into a workflow template by writing a
workflow template file. Alternatively, a job specification file could be written.

Execution: instantiating and executing a workflow template file or executing a job

specification file.
In practice, the phases will typically occur iteratively as the underlying business process
is better understood and as development and testing occurs.
Interwoven, Inc. 22
Chapter 2
Using Workflows
The following workflows are installed by the TeamSite installation program into one of
the three directories listed. These workflows were designed to provide functionality that
was commonly being implemented by users who were modifying the
Interwoven-provided workflow template files (wft). The workflows that are active by
default (that is, they have an entry in the available_templates.cfg file) are marked
with an asterisk (*):
iw-home/local/config/wft/default/
author_assignment.wft
author_submit.wft
author_submit_dcr.wft*
default_assign.wft
default_submit.wft
default_TFO_submit.wft*
These templates are described in “Default Template Descriptions” on page 24.

iw-home/local/config/wft/examples/
author_assignment_with_nested_job.wft
cgi_task_test.wft
concurrent_approval.wft
external_task_test.wft
url_external_task_test.wft
serial_approval.wft
These templates are described in “Example Template Descriptions” on page 24.

iw-home/local/config/wft/solutions/
author_submit_with_deploy.wft
author_submit_with_email.wft
author_submit_with_metadata.wft
configurable_author_assignment.wft*
configurable_author_submit.wft*
configurable_default_submit.wft*
These templates are described in Chapter 3, “Using Solution Workflows.”

Chapter 2: Using Workflows
Default Template Descriptions

The following workflow templates are installed in
iw-home/local/config/wft/default:
Table 2
Template Name Description
author_assignment.wft Lets an Editor, Administrator, or Master assign a job to an
Author. The assigner selects an author and enters a task
description. The assigner also selects a branch and
workarea if the job is initiated from the To Do List view.
An approval sequence is also included for the author
assignment.
author_submit.wft Submits content to the STAGING area. This is the default
workflow invoked when a user logged in as an author
clicks Submit. Includes review/approval task by the owner
of the workarea.
author_submit_dcr.wft Submits a data record to the staging area when an Author
clicks Save and Exit in the FormsPublisher window. This
automates the submission process, eliminating the need for
the Author to initiate the submission manually after
creating or editing a data record.
default_assign.wft Designed for use with the assign action. It enables a user
to assign one or more assets to another user, and then
review changes prior to submitting changes to STAGING.
default_submit.wft In addition to submitting the files, provides support for
pre-submit activities including approval, file type
recognition, and user-specific destinations.
default_TFO_submit.wft Submits content to the staging area. This workflow can be
configured for use by Front-Office users when they submit
files from the TeamSite Briefcase or from a Microsoft
Office application, such as Word.
Example Template Descriptions

The templates in iw-home/local/config/wft/examples are included as reference
examples that are applicable to some installations. The functionality provided by these
examples is included in a more generalized form in the work_order.wft template. The
templates in the examples directory are provided as shorter, more modular examples of
how you can develop custom workflow templates.
To make the example files available to end-users, you must edit

available_templates.cfg as described in “available_templates.cfg” on page 29.
Interwoven, Inc. 24
The following example templates reside in iw-home/local/config/wft/examples:
Table 3
Template Name Description
cgi_task_test.wft Example workflow template that demonstrates
the functionality of a cgitask. Uses
iw-home/httpd/iw-bin/sample_cgi_task.ipl.
concurrent_approval.wft Same as serial_approval.wft, except the
reviewers review content in parallel.
external_task_test.wft Example workflow template that demonstrates
the functionality of a cgitask.
Uses
iw-home/local/config/wft/examples/sample_
external_task.ipl
serial_approval.wft Lets Editors, Administrators, and Masters assign
a task to a content contributor and specify one or
more users as the approvers.
You should examine each .wft file for details about its construction and the features of
the job it defines. After examining each file, you can choose to use it as is, or modify it
for your specific installation using the information from “Workflow Template File
Structure” on page 65.
Enabling Workflows
The optional (non-default) workflows can be activated by completing the following
procedure:
1. Verify that you have satisfied the following two requirements:
Install and license TeamSite (which includes FormsPublisher)—Workflow
email notifications use the presentation template compiler installed with
FormsPublisher.
The permissions on the iw-home/tmp and the iw-home/tmp/cci directories must
be readable and writable to all TeamSite users (the email notifications are
temporarily placed in these directories while being created).
And consider the following compatibility issues:
Install MetaTagger 3.6 or later (optional)—MetaTagger 3.5 and earlier are not
supported. If you are integrating with MetaTagger, TeamSite must be installed
before MetaTagger or the MetaTagger GUI will not work.
Install OpenDeploy 5.5.1 or later (optional)—You must have a base server on
the TeamSite server.
2. Open the iw-home/local/config/wft/available_templates.cfg file (see
page 29).
3. Add an entry for each new workflow.

For example, to add the Author Submit Workflow workflow, add the following
entry:
<template_file name='Author Submit Workflow'
path='solutions/configurable_author_submit.wft'>
<allowed>
<and>
<command name="submit"/>
<role name="author"/>
</and>
</allowed>
</template_file>
For your convenience, a file containing entries for each new workflow is provided.
It is called available_templates.cfg.fragment and is located in the
iw-home/local/config/wft/solutions directory. You can copy any or all of the
workflow entries from this file into your available_templates.cfg file.
4. If you are replacing another workflow, you can deactivate it by any of these
methods:
Delete the entry
Comment out the entry using 
Add the attribute active=“no”
5. Save and close the available_templates.cfg file.
6. For each configurable workflow that you added to your available_templates.cfg
file, edit the corresponding .cfg file to activate the desired functionality.
The .cfg file contains question and answer pairings for each configurable option.
For example, in the Email Notification section:
# Should a email notification be sent if a deploy task fails?
email_no_deploy=no
Change the default from no to yes on any feature you want to activate. For a
detailed description of the configurable features available in each workflow, refer to
“Configurable Workflow Settings” on page 56.
7. If you are using the Email Notification functionality:
a. Ensure that your iw.cfg file contains entries for maildomain and mailserver in
the [iwsend_mail] section.
If it does not, add the appropriate entries. For example:
[iwsend_mail]
maildomain=yourcompany.com
mailserver=mail.yourcompany.com
b. Edit the solutions/email_map.cfg file to specify the mapping from user
names to email addresses if adding @yourcompany.com to the username is not
adequate.
8. If you are using Metadata Capture functionality:
a. Ensure that the metadata_capture_ui properties in the workflow-specific .cfg
files have the desired setting for either MetaTagger or TeamSite Metadata.
Interwoven, Inc. 26
b. Ensure that iw-home/local/config/ contains datacapture.cfg and

metadata-rules.cfg files, and that these files contain the desired settings.
c. Ensure the mt-home/conf/metatagger.cfg file contains the desired entries. See

MetaTagger Administration Guide “Configuring MetaTagger to Work with
TeamSite” for integration instructions.
d. Ensure that the category tag values in the metatagger.cfg file match
corresponding item name values in the datacapture.cfg file.
e. Optionally, test your metadata capture configuration from a custom menu item
before you try it from a workflow.
9. If you are using Deployment functionality:
a. Copy the deployment configuration file (solutions/wft_opendeploy.xml) to
the od-home/conf directory.
b. Edit solutions/wft_opendeploy.cfg file to specify the mapping from branch
names to the corresponding destination nodes and paths.
See “Integrating with OpenDeploy” on page 27 for detailed information about these
entries.
Integrating with OpenDeploy

The TeamSite installation program installs the following files that are required for
integration with OpenDeploy:
wft_opendeploy.xml—Deployment configuration file
wft_opendeploy.ipl—Perl script that starts the deployment
wft_opendeploy.cfg—OpenDeploy configuration file which provides a mapping
between the branch name and the corresponding deployment attributes (node name
and the target directory) required for deployment. Each deployment mapping
contains three required items, delimited by commas:
Branch name—Name of the source branch.
Destination node name—Logical node name of the OpenDeploy receiver that is
configured in the source OpenDeploy machine's iwodhome/etc/odnodes.xml
file.
Destination path—Path on the destination server where the content will be
deployed. This path must be included as an allowed directory in the
OpenDeploy receiver’s iwodhome/etc/odbase.xml or
iwodhome/etc/odrcvr.xml configuration file.
These files are installed in iw-home/local/config/wft/solutions.
Complete the following steps to configure the deployment integration:

1. Copy the wft_opendeploy.xml file to the $ODHOME/conf directory.

2. Edit or comment out the last three lines of the wft_opendeploy.cfg file to reflect
the mapping between the branch names containing the files to be deployed and their
destinations. If content from only one branch are being deployed, edit one line and
comment out the other two lines. If content from more than three branches are being
deployed, add lines as appropriate.
branchName=/default/main/br3/,dst=/space/vijay/odreceive2,useNode=INTERNET
branchName=/default/main/br2/,dst=/space/vijay/odreceive1,useNode=INTERNET
branchName=/default/main/br1/,dst=/space/vijay/odreceive,useNode=INTERNET
source branch destination path destination node name
NOTE
The destination node name (dst=) must use forward slashes (/) on UNIX and
backslashes (\) on Windows.
When adding branch entries, enter the more specific (lower-level branch) entries
before the more general (higher-level branch) entries. This is because when a
deployment is run from a workflow external task using wft_opendeploy.ipl, and
the areavpath matches more than on entry in wft_opendeploy.cfg, the first
matching entry is used.
For example, if there are entries for three branches in the following order:
/default/main/web
/default/main/web/UK
/default/main/web/DE
/default/main/web/DE
/default/main/web/UK
/default/main/web
the /default/main/web/DE entry is used.
3. Add or delete lines according to the number of source branches and deployment
destinations you need to configure.
4. Save and close the file.
Workflow Configuration Files

The TeamSite workflow functionality uses three configuration files to store information
about the availability of workflow templates on your TeamSite server. These files apply
regardless of the type of workflow you are using. These files are:
available_templates.cfg—XML file installed as part of the TeamSite installation
procedure that stores information about the conditions under which users can access
workflow templates.
Interwoven, Inc. 28
available_templates.dtd—File used by available_templates.cfg that contains

a collection of declarations (elements and attributes) that describe the expected
document structure.
Additionally, workflow configuration settings must be made in the main TeamSite

configuration file: iw.cfg.
These files are described in detail in the sections that following. Information specific to
each of the workflows that are installed with TeamSite are described in Chapter 4,
“Creating Workflow Template Files.”
available_templates.cfg
The available_templates.cfg file is an XML configuration file that lists all of the
workflow templates that are available for use on the TeamSite server. For each
workflow, this file indicates the name of workflow, the location of the workflow
template file, and the conditions under which the workflow is available.
By default, the available_templates.cfg file is located in:

C:\Program Files\Interwoven\TeamSite\local\config\wft (Windows)
/Interwoven/TeamSite/local/config/wft (UNIX)
NOTE
If available_templates.cfg is edited and contains non-ASCII text, it must be saved in
UTF-8 encoding.
The available_templates element is the container element for the file. This element
contains the following attribute:
require_workarea—specify whether (true) or not (false) workflow templates

selection screen will include a branch/workarea chooser if workarea context is not
present. Most of the out of the box workflow template examples require this to be
enabled (require_workarea="true") to work properly. Default value is true.
Within the available_templates element is the template_file element:

<available_templates require_workarea="true">
<template_file name="Author Submit Workflow"
path="solutions/configurable_author_submit.wft">
...
</template_file>
</available_templates>
NOTE
This option should only be set to false if the following conditions are in effect:
TeamSite has been upgraded to TeamSite 6.7.1 or later.

The workarea chooser should not display in the workflow templates selection screen.
Flexible roles are not in effect in the workflow templates selection.
The template_file element has the following attributes:

name—specify the title of the workflow, for example:
name="Author Submit Workflow"
active—indicate whether (yes) or not (no) the workflow template is enabled.

Default value is yes.
path—specify the path where the template file resides. Template files must reside in
one of the following locations:
iw-home/local/config/wft/default
iw-home/local/config/wft/examples
iw-home/local/config/wft/solutions
The value you specify is relative to the iw-home/local/config/wft directory, so if

the template file resided in the following absolute path:
iw-home/local/config/wft/default/author_submit.wft
then you would specify the value:

path="default/author_submit.wft"
Specifying Template Access
You can configure access to each template listed in the available_templates.cfg file
by using any combination of the following categories:
Command
Role
Group
User
Branch
The categories can be combined using boolean terms such as AND, OR, and NOT to
include and exclude those that meet the inclusion or exclusion criteria you configure.
Template access is configured within the allowed element, which is a subelement of

template_file:
Within the template_file element is the allowed element, where you can configure
user access by matching workflow commands with user roles:
<template_file ...>
<allowed>
...
</allowed>
Interwoven, Inc. 30
</template_file>
Command Access
Workflow commands are specified by the command element. The command element
specifies the user-activity that starts the corresponding workflow. For example, the
following configuration:
specifies that the associated workflow is started when performing a Submit and that it
cannot be invoked by other means.
The valid command values that you can associate with a workflow are:
submit (submitting files)
assign (assign button or menu item)
new_job (new job)
tfo_workflow (new job, in TeamSite FrontOffice)
tt_data (saving FormsPublisher data records)
tt_deletedcr (deleting FormsPublisher data records in ContentCenter Standard
only)
all (all possible values from this list)
NOTE
The tt_data command is valid in ContentCenter Standard and can be configured in
ContentCenter Professional; see the TeamSite User Interface Customization Guide. The
tt_deletedcr command is only valid when users are using the ContentCenter Standard
interface; in ContentCenter Professional, this command is not valid and data records are
treated like any other assets.
Role Access
Access based on TeamSite roles is specified by the role element’s name attribute. For
example, the following configuration:
specifies that if the user is logged in as an Author.
Group Access
Access based on user groups is specified by the group element:

<group name="marketing"/>

User Access
Access based on individual user name is specified by the user element:

<user name="jdoe"/>
Branch Access
Access based on TeamSite branch is specified by the branch element:

<branch="/default/products"/>
Combining Access Categories
Pairings of individual or multiple access elements can be included or excluded using the
and, or, and not elements within the allowed element. You can use boolean logic to
create combinations of categories that can either have access to a specific template, or
be excluded from it.
In the following example:

<template_file name="Author Submit" path="default/author_submit.wft">
<allowed>
<and>
<or>
<role name="editor"/>
<group name="marketing"/>
<and>
<role name="admin"/>
<not>
<user name="jdoe"/>
</not>
</and>
</or>
</and>
</allowed>
</template_file>
the following individuals have access to the Author Submit workflow:

Those who are authorized to perform submit commands.
Those who have the author or editor role.
Those who are members of the marketing group.
Those who have the admin role, with the exception of the user jdoe.
If no access category is specified, it is assumed that category has full access to the
workflow template.
Interwoven, Inc. 32
Regular Expression Support
You can use regular expressions when specifying branch element constraints within
available_templates.cfg to search for a specified pattern and specify what to do
when matching patterns are found. Using regular expressions allows a greater level of
flexibility when adding items.
For example, if you want only the users in the three administration_1 branches (a1,
a2, and a3) to access a workflow template, you can set the following constraint:
<allowed>
<or>
<branch name="/default/main/administrator_1/a1"/>
</or>
...
</allowed>
If a new branch called a4 is added to /default/main/administrator_1 you could

manually update the available_templates.cfg file to allow access for users in the new
branch by adding the branch element to the existing ones:
Or you could modify the available templates.cfg file to use the following regular
expression and, thus, automate the constraints placed on the a4 branch:
<allowed>
<and>
<branch name="/deault/main/administrator_1/.*"/>
</and>
...
</allowed>
This regular expression allows users from any branch under

/deault/main/administrator_1 to have access to the template.
Path Separators
When using regular expressions, the path-separators (“\”, “\\”, “/”) are all translated to
“/” in both the pattern and the string to match against before attempting the match.
In the following example:

<branch name="foo"/>
any branch path that includes the string foo will be matched. Here the following
examples match:
/default/main/food/...
/default/main/barfoo/...
In the next example:

<branch name="^/default/main/foo"/>

any branch path that begins with the value-string will be matched. Here the following
example matches:
/default/main/food/...
while this one does not:

/default/main/barfoo/...
The following examples are all treated as identical on both Windows and UNIX.
<branch name="^/default/main/foo" include="yes"/>
<branch name="^\default\main\foo" include="yes"/>
<branch name="^\\default\\main\\foo" include="yes"/>
<branch name="^/default\main\\foo" include="yes"/>
available_templates.dtd
The available_templates.cfg file begins with the following prolog:
<?xml version="1.0" standalone="no" ?>
<!DOCTYPE available_templates SYSTEM './available_templates.dtd'>
It declares that the available_templates.cfg uses the available_templates.dtd to

describe the expected document structure. The available_templates.dtd file is a
collection of declarations divided into two types:
ELEMENTS—Defines an element and what it can contain.
ATTLIST—Defines the attributes that are allowed for an element.
By default, the available_templates.dtd file is installed in the same directory as the

available_templates.cfg, either:
C:\Program Files\Interwoven\TeamSite\local\config\wft (Windows servers)

Interwoven/TeamSite/local/config/wft (UNIX servers)
The following available_templates.dtd defines the default behavior of the

available_templates.cfg file:
<!ELEMENT available_templates (template_file)* >
<!ATTLIST available_templates
require_workarea (true|false) "false">
<!ELEMENT template_file ((allowed)?) >

<!ATTLIST template_file
name CDATA #IMPLIED
active (yes|no) "yes"
path CDATA #REQUIRED>
<!ENTITY % acl_sub_elements "command|branch|role|user|group|and|or|not">

<!ELEMENT allowed ((%acl_sub_elements;)?)>
<!ELEMENT and ((%acl_sub_elements;)+)>
<!ELEMENT or ((%acl_sub_elements;)+)>
Interwoven, Inc. 34
<!ELEMENT not (%acl_sub_elements;)>
<!ENTITY % common_name_attr "name CDATA #REQUIRED">

<!ELEMENT user EMPTY >
<!ATTLIST user %common_name_attr;>
<!ELEMENT group EMPTY >

<!ATTLIST group %common_name_attr;>
<!ELEMENT role EMPTY >

<!ATTLIST role %common_name_attr;>
<!ELEMENT command EMPTY >

<!ATTLIST command %common_name_attr;>
<!ELEMENT branch EMPTY >

<!ATTLIST branch %common_name_attr;>
iw.cfg
The iw.cfg file is the main TeamSite server configuration file. It includes configuration
settings for the way TeamSite looks and responds to various requests. By default, the
file is located in /etc (Solaris) or iw-home/etc (Windows). This section includes
information about workflow-related settings in three parts of the iw.cfg file:
[iwserver]
[iwsend_mail]
[workflow]
For details about TeamSite configuration issues that do not concern workflow, refer to
the TeamSite Administration Guide for your server platform (Windows or UNIX).
[iwsend_mail] Parameters
The Perl script iwsend_mail.ipl was specifically designed for use within TeamSite
workflows to simplify the creation of external task scripts for email notification. Modify
the [iwsend_mail] section of your iw.cfg file to include the following lines:
[iwsend_mail]
maildomain=interwoven.com
mailserver=mail1.interwoven.com
use_mapping_file=true
email_mapping_file=c:/iw-home/local/config/wft/email_map.cfg
debug_output=c:/tmp/iwsend_mail.log

For detailed information about the iwsend_mail.ipl script, refer to Appendix B,

“iwsend_mail.ipl Script.”
[workflow] Parameters
The [workflow] section of iw.cfg contains by default these commented parameters and
their corresponding default values:
external_task_add_filelist=false
wftask_nesting_depth_allowed=3
external_task_retry_wait=1
presubmit_check=true
task_areavpath_file_access_check=true
delete_jobs_on_completion=false
permit_add_locked_files_to_locking_tasks=true
Each of these parameters also contains a commented description. To activate any of the
parameters, remove the single pound sign (#) that precedes the line. You can also change
the default setting. Ensure the double pound signs (##) preceding the description are not
removed.
[workflow]
## Set 'external_task_add_filelist' to false if you want to prevent
## TeamSite from adding files to the command line of external task
## command callouts (recommended on WinNT/2K). Defaults to true.
#external_task_add_filelist=false
##
## The maximum depth of nesting allowed for nested jobs (wftask);
## defaults to 3. Values less than 1 are ignored.
#wftask_nesting_depth_allowed=3
##
## Set external_task_retry_wait to the number of minutes you want the
## workflow engine to wait before it re-attempts to run an external
## task after failing. Defaults to 1 minute.
#external_task_retry_wait=1
##
## Causes the submittask to check for possible locking & conflict
## issues with files before attempting the submit. This provides
## a greater likelihood that the submittask files will be submitted
## all at once, or none at all. Defaults to false if not specified.
#presubmit_check=true
##
## If set to true, workflow engine will check more strictly at job
## creation time to prevent non-readonly tasks from being assigned to
## users who don't have access to modify the files in the workarea;
## otherwise uses an older less precise test. Defaults to false if
## not specified.
#task_areavpath_file_access_check=true
Interwoven, Inc. 36
##
## If set to false, workflow engine will *not* delete jobs from the
## backing store upo completion, and they can be retrieved using
iwgetwfobj CLT and deleted usig iwrmjob (but not searched against).
##Default is true.
#delete_jobs_on_completion=false
##
## If set to false, workflow engine will return an error if a user
## tries to create a job with (1) a start task with lock='t' and
## transferonly='f' and (2) files in that task's filelist that are
## locked in an area other than the task's areavpath. This corresponds
## to the behavior of the workflow engine if that task were already
## running.
##
##By default, the value of this parameter is true (i.e., the WF
##engine doesn’t check whether files are locked when creating the
##job and its tasks).
#permit_add_locked_files_to_locking_tasks=false
##
Querying Workflows
TeamSite provides two CLTs, iwquerytasks and iwqueryjobs, that allow you to search
for tasks or jobs (respectively) with various attributes. The query criteria are to be
specified in XML (refer to TeamSite Command-Line Tools for the DTDs for the XML
files and for examples.
The syntax for the iwquerytasks CLT is:

iwquerytasks [-h] [-v] [-x] [-o offset] [-m max] [-l locale]
[-s servername] <query
-h Print this message.

-v Print version.
-x Output result in XML.
-s servername Use servername as the TeamSite server.
-o offset Skip the first offset results. The number of results specified
are skipped before results are returned.
-m max Maximum number of results to return.
-l locale Locale for server-side sorting.
<query The query is read from stdin.
For example, in order to find all tasks currently active and owned by the user 'jsmith',
you could save the following query XML in a temporary file (for example,
myquery.xml):
<taskquery>

<and>
<active/>
<ownedby v="jsmith"/>
</and>
</taskquery>
Then call the iwquerytasks CLT as follows:

iwquerytasks < myquery.xml>
The attributes of tasks that may currently be queried against are:

active
job active
job owner
workflow id
needsattention
task type
sharedby (that is, all group tasks shared by a specific user)
undoableby (that is, all tasks undoable by a specific user)
tryingtolock
readonly
task areavpath
task activationtime
task file (that is, all tasks with a specific file in their file lists)
Query results may also be sorted and/or filtered by job or task description and variables.
In addition to specifying the field to sort by, you can also specify case sensitivity,
descending order, and primary sort fields. For example, the previous query, with results
sorted by areavpath in descending order, would be:
<taskquery>
<and>
<active/>
<ownedby v="jsmith"/>
</and>
<sortby>
<field name="areavpath" order="descending"/>
</sortby>
</taskquery>
To construct more complex queries, refer to the DTDs.
The syntax for the iwqueryjobs CLT is:
Interwoven, Inc. 38
iwqueryjobs [-h] [-v] [-x] [-o offset] [-m max] [-l locale]
[-s servername] <query
-h Print this message.

-v Print version.
-x Output result in XML.
-s servername Use servername as the TeamSite server.
-o offset Skip the first offset results. The number of results specified are
skipped before results are returned.
-m max Maximum number of results to return.
-l locale Locale for server-side sorting.
<query The query is read from stdin.
The attributes of jobs which may currently be queried against are:

job owner
active
job activationtime
External Task Commands Using URLs

You can configure an external task to run a URL command on your TeamSite server
host, or on a remote host. This remote host must be running Java to use this feature.
Configuration is similar to that of other external task workflows. When the external task
is executed, the URL is checked for validity. If it is valid, it is executed in the manner
described in this section. Otherwise, it is treated as a conventional external task.
NOTE
Only HTTP URL commands are supported.
To configure an external task with URL workflow in a workflow template, follow these
steps:
1. Specify the external task URL command using the following format:
<command
v="http://servername/iw-cc/ urlexternaltask?param1=value1&param2=va
lue2"/>
where servername is the local host on which the workflow is being run, and
param=value are the user-defined parameters.
2. Add the value ClassName as a variable to the external task, for example:
<variables>
<variable key="ClassName"
value="com.corp.custom.URLExternalTaskTest"/>

</variables>
3. Create a Java class that implements the following interface:
com.interwoven.cssdk.workflow.CSURLExternalTask
4. Place the Java class in the appropriate location relative to the following directory:
iw-home/local/config/lib/content_center/customer_src/src
For example, if you created the following class”
com.corp.custom.URLExternalTaskTest
then the full path would be:
iw-home/local/config/lib/content_center/customer_src/src/com/corp/
custom/URLExternalTaskTest.java
5. Rebuild the Web applications.
6. Add that workflow template to the available_templates.cfg file. See
“available_templates.cfg” on page 29 for more information.
Sample Files
The following sample files are provided for use with this feature.
Workflow template file.
iw-home/local/config/wft/examples/url_external_task_test.wft
Java class.
iw-home/local/config/lib/content_center/customer_samples_src/src/com/
corp/custom/URLExternalTaskTest.java
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).
3. Add this workflow to iw-home/local/config/wft/available_templates.cfg for

the desired command, branches, etc. For example:
Interwoven, Inc. 40
<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>
Roles Considerations
As a workflow developer, you need to aware of the role constrains. If you allow some
users with certain roles to do some workflow tasks, you need to make sure those users
have the privileges to perform their tasks, such as preview, compare, merge, and so
forth. Otherwise, those users will not be able to complete their tasks.
To workaround these role constraints, you can choose to use external task scripts.
External scripts run in master mode and ignore role constrains.
The following sections describe issues related to the use of flexible roles in TeamSite
workflows.
Specifying Reviewer Roles in Workflow Templates

It is recommended that you write workflow templates that allow only users with roles
that have permission to preview files to be the reviewers, or the reviewers will not be
able to see the content when reviewing and approving the task. For example, in the
configurable_author_assignment.cfg solutions workflow template residing in the
following location:
iw-home/local/config/wft/solutions
use either of the following lines to specify who can be the reviewer:
review_type=serial[select[role:admin,role:master,role:editor],

select[role:admin,role:master,role:editor]]
or
review_type=areaowner
The value areaowner is a special value specifying that only the workarea owner needs
to be reviewing the task. Only set review_type to roles that have preview access to the
workarea.
Configuring Callout Buttons

In order for flexroles to work in this release, it is recommended that you use the
following examples when making callout buttons:
use TeamSite::Flexroles qw(get_users_having_roles);
$vpath = "a_branch_vpath_to_get_roles_and_users_from";
my @users = get_users_having_roles($vpath, ("author", "editor"));
Using the above code section, a list of users is returned from the call to
get_users_having_roles in Flexroles.pm. You can then use this list of users to
construct any kind of HTML list as you want in their workflow template files.
Interwoven, Inc. 42
Chapter 3
Using Solution Workflows
The solution workflows are designed to incorporate functionality that was commonly
being implemented either by modifying the Interwoven-provided workflow template
files (wft) or by modifying the Perl code. They have features and supporting files that
make them easier to use. It is recommended that you use or revise these workflows
when possible.
Three of these workflows are variations on the author_submit default workflow

included with earlier TeamSite releases. The other three workflows are configurable
alternatives to the previous default workflows included with earlier versions of
TeamSite.
Solutions Workflows Illustrated

This section shows diagrams and descriptions of workflows in the solutions directory,
located in iw-home/local/config/wft. These workflows are available for your use and
also illustrate the tasks and transitions included in workflows. The configurable steps
are marked as “optional”.

Chapter 3: Using Solution Workflows
Author Submit with Deploy

Figure 4 illustrates an author submit combined with a deployment.
Figure 4 Diagram of the Author Submit with Deploy solution workflow
1. Author clicks Submit to submit

Submit modified files, which initiates a new
Job and prompts the author for the
following information:
• Submit comment (required)
Author Work • Information comment (optional)
iw_author • Individual file comments (optional)
reject 2. Author-submitted content is sent to a

reviewer. The reviewer is defined as
the owner of the workarea from which
the files are submitted.
Review
iw_areaowner
3. The reviewer either:
approve • Approves the work.
• Rejects the work (which is sent
back, as a task, to the author who
Submit modifies the work, and resubmits it
iw_areaowner for approval by clicking Finish on
that task).
4. When approved, the files are

failure submitted to the staging area.
Deploy Resolve Deployment
Problem
retry
5. The files are then deployed to the
location specified in the
End wft_opendeploy.cfg file.
Note: wft_opendeploy.cfg must be

configured before this OOTB solution
can be used.
Interwoven, Inc. 44
Author Submit with Email

Figure 5 illustrates an author submit combined with an email.
Figure 5 Diagram of the Author Submit with Email solution workflow
1. Author clicks Submit to submit modified files,

Submit which initiates a new Job and prompts the author
for the following information:
• Information comment (optional)
Author Work • Individual file comments (optional)
iw_author
2. The submitted files trigger an email

notification to a reviewer. The reviewer is
defined as the owner of the workarea to which the
files are submitted.
Email to Reviewer
• Approves the work.
reject • Rejects the work (which is sent back, as a task,
to the author who modifies the work, and
resubmits it for approval by clicking Finish on
Review that task). When resubmitted, another email is
iw_areaowner sent to the reviewer).
approve
4. When approved, the files are submitted to the
staging area.
Submit
iw_areaowner
End

Author Submit with Metadata

Figure 6 illustrates an author submit with metadata capture.
Figure 6 Diagram of the Author Submit with Metadata solution workflow
Submit 1. Author clicks Submit to submit modified files,

which initiates a new Job and prompts the author
for the following information:
Author Work
• Individual file comments (optional)
iw_author
2. Author-submitted content is then processed for
metadata capture (by either the TeamSite Tagger
GUI or through MetaTagger integration).
3. Author-submitted content is sent to a reviewer.

Metadata Capture The reviewer is defined as the owner of the
iw_user workarea from which the files are submitted.
reject 3. The reviewer either:

Review • Rejects the work (which is sent back, as a task,
iw_areaowner to the author who modifies the work, and
resubmits it for metadata capture and approval
by clicking Finish on that task).
approve
4. When approved, the files are submitted to the

Submit staging area.
iw_areaowner
End
Interwoven, Inc. 46
Configurable Author Assignment

Figure 7 illustrates a configurable author assignment.
Figure 7 Diagram of the Configurable Author Assignment solution workflow
1. A new job is initiated, typically by an

editor; the initiator may have already
New Job
selected files to be worked on by the
author (prior to initiating the job) or may
attach them to the job.
(optional)
Add Files to Job
2. (Optional) Email notification of the
assigned work and any associated files is
(optional) sent to the author.
Email to Author
3. Author completes assigned work and
marks the task as Done by clicking
Author Work Finish on that task.
iw_author
4. (Optional) Content is processed for

(optional) metadata capture (by either the TeamSite
Metadata Capture Tagger GUI or through MetaTagger
integration).
5. Work is submitted to the review

Review Subflow subflow for approval or rejection. See
reject (See “Review “Review Subflows” on page 49 for more
Subflows” on information.
page 49 for more
approve • Approves the work, in which case the
(optional) files are submitted to the staging area.
Submit Email Notification of
iw_areaowner Deployment Problem • Rejects the work, in which case the job
is returned to step 2.
failure
(optional) Deploy Resolve Deployment 7. (Optional) The file is deployed to the

Problem location specified in the
retry iw_areaowner wft_opendeploy.cfg file (email is sent
to the initiator if there is a deployment
cancel job problem).
End

Configurable Author Submit

Figure 8 illustrates a configurable author submit.
Figure 8 Diagram of the Configurable Author Submit solution workflow
Submit 1. Author clicks Submit to submit

modified files, which initiates a
new Job and prompts the author for
the following information:
(optional) • Submit comment (required)
Add Files to Job
(optional) • Individual file comments
Email to Author (optional)
2. (Optional) The author selects
additional files to be submitted.
Author Work 3. (Optional) Author-submitted
iw_author content is then processed for
metadata capture (by either the
TeamSite Tagger GUI or
MetaTagger integration).
(optional)
reject Metadata Capture
iw_user 4. Work is submitted to the review
subflow for approval or rejection.
See “Review Subflows” on page 49
Review Subflow for more information.
(See “Review
Subflows” on
page 49 for more 5. The reviewer either:
information.)
• Approves the work and the files
approve are submitted to the staging area.
(optional) • Rejects the work, in which case
Submit Email Notification of optional email requesting
iw_areaowner Deployment Problem revisions is generated and a
revision task occurs.
failure
(optional) Deploy Resolve Deployment 6. (Optional) The file is deployed

Problem to the location specified in the
retry iw_areaowner wft_opendeploy.cfg file (email is
sent to the initiator if there is a
cancel job
End deployment problem).
Interwoven, Inc. 48
Configurable Default Submit

Figure 9 illustrates a configurable default submit.
Figure 9 Diagram of the Configurable Default Submit solution workflow
1. A user—whose work does not

Submit need review—submits a file.
2. (Optional) Content is processed

for metadata capture (either in the
TeamSite Tagger GUI or through
MetaTagger integration), then
submitted to the staging area.
(optional)
Metadata Capture
iw_user 3. (Optional) The file is deployed to
the location specified in the
wft_opendeploy.cfg file (email is
(optional) sent to the initiator if there is a
Submit Email Notification of deployment problem).
iw_user Deployment Problem
failure
(optional) Deploy Resolve Deployment

Problem
retry iw_areaowner
cancel job
End
Review Subflows
The review subflow is the process by which one or more reviewers examine the
author-submitted work, and either approve or reject it. What happens next depends on
the type of review that is occurring.
NOTE
This subflow is not a nested workflow, it is a part of the configurable author submit and
assignment workflows.
This review subflow process is shown in as a single box in the overall workflow
illustrations. This section contains an illustration detailing this subflow process.

Serial Review
Serial reviews provide for tiers of reviewers. If the first reviewer approves the work, it is
forwarded to the next reviewer. Depending on the type of serial review, a rejection either
automatically sends the work back to an author for revision (“return on first reject”), or
passes the work to the next reviewer (“all at once”).
Interwoven, Inc. 50
Return on First Reject
Figure 10 illustrates a return on first reject. This serial review allows for a sequential
review of the work. If any of the reviewers reject the work, the work is automatically
sent back to an author for revisions, and no further reviewing is done until the work is
resubmitted.
Figure 10 Diagram of the Return on First Reject review workflow
1.(Optional) Email notification is

Start Review sent to first reviewer configured in
the workflow configuration file.
(optional)
Start Review 2. The reviewer either:
Cycle
• Rejects the work.
(optional)
Email 3. One of the following actions
Reviewer 1
occurs:
• If approved, the workflow
Review 1
(optionally) emails the next
(reviewer 1 reviewer (if any) configured in
or group 1) the workflow configuration file.
The work is then forwarded to the
approve next reviewer.
(optional) • If rejected, an email is triggered
Email
Review 2 to the author for modification.
4. The review procedure is repeated

Reviewer 2 for each reviewer of the work until
(reviewer 2
or group 2) there is either a rejection, or all the
reviewers approve the work.
approve
(optional)
Email
Reviewer n
Review n
(reviewer n
or group n)
approve
(optional)
End Review
Cycle
Reject Approve

All At Once
Figure 11 illustrates an all-at-once. This serial review permits each reviewer to approve
or reject the work. If the work is rejected, it is still forwarded to the next reviewer. This
way the author can receive input from all reviewers, even if there is a rejection.
After all reviews are complete, a selection criterion is applied to the work based on the
cumulative approvals and rejections to determine the work’s status. All-at-once serial
reviews are typically used in conjunction with VisualAnnotate.
Figure 11 Diagram of the All-at-once Review workflow
1.(Optional) Email notification is

Start Review sent to first reviewer configured in
the workflow configuration file.
(optional)
Start Review 2. The reviewer either:
Cycle
(optional)
Email 3. The work is forwarded to the
Reviewer 1
next reviewer configured in the
workflow configuration file. An
email can optionally be sent to the
Review 1 next reviewer.
(reviewer 1
or group 1)
reject approve 4. The review procedure is repeated

for each reviewer until all the
(optional) reviewers have reviewed the work.
Email
Review 2
5.After the last reviewer finishes, a

selection criterion, based on all the
Reviewer 2 cumulative approvals and
(reviewer 2
or group 2) rejections, is applied to the work to
determine if the work has passed
reject approve review.
(optional)
Email
Reviewer n
Review n
(reviewer n
or group n)
reject approve
(optional)
Reject End Review Approve
Cycle
Interwoven, Inc. 52
Concurrent Review
Figure 12 illustrates a concurrent review. This provides for a simultaneous distribution
of the work to all the reviewers. This differs from the serial review where the work is
seen by only one reviewer at a time. At the end of the concurrent review, the reviewers’
decisions and comments are tallied, and a decision is made on whether the work has
passed review.
Figure 12 Diagram of the Concurrent review workflow
1. (Optional) Email notifications

Start Review are sent to all reviewers configured
in the workflow configuration.
(optional)
Start Review 2. Each reviewer either:
Cycle
(optional) Review 1
Email (reviewer 1 approve
Reviewer 1 or group 1)
3. If any reviewer rejects the work,
the review is immediately
reject
terminated. Otherwise, the review
is passed when every reviewer has
approved the work.
(optional) Reviewer 2 approve

Email (reviewer 2
Review 2 or group 2)
reject
(optional) Review n
Email (reviewer n approve
Reviewer n or group n)
reject
OR AND
Review Review
rejection approval
Reject Approve

Configurable Workflow Overview

The following three solutions workflows are activated by default and are configurable:
configurable_author_assignment.wft
configurable_author_submit.wft
configurable_default_submit.wft
Each of the configurable workflows has a number of configurable options specified in

an external configuration file called workflow_name.cfg. For example, the
configurable_author_submit.wft file has a corresponding configuration file called
configurable_author_submit.cfg. Each configurable workflow also has a
corresponding properties file called workflow_name.properties. These configuration
files are described in “Workflow-Specific Configuration Files” on page 54 and the
properties files in “Workflow.properties File Overview” on page 55.
NOTE
To activate any of the optional (non-default) workflows, complete the procedure
described in “Enabling Workflows” on page 25.
Workflow-Specific Configuration Files

This section introduces the workflow-specific configuration files used by files in the
solutions subdirectory. The solutions workflows and their associated configuration
files are installed by the TeamSite installation program in the
iw-home/local/config/wft/solutions directory.
For detailed information about a specific .cfg or .properties file, refer to the
“Configurable Workflow Overview” on page 54 for an overview of a specific workflow
or “Configurable Workflow Settings” on page 56 for details about each configuration
option.
Workflow.cfg File Overview

Each workflow_name.cfg file contains entries for a number of optional features that can
be defined as on (feature=yes) or off (feature=no) without having to edit the wft file.
The configuration of a feature (for example, email notification) is identical in each
workflow where it is included. The following list contains the configurable features that
are available in each of the cfg files.
Interwoven, Inc. 54
configurable_author_submit.cfg
Add Files
Deployment
Email Notification
Metadata Capture
Review
configurable_default_submit.cfg
Deployment
Email Notification
Metadata Capture
configurable_author_assignment.cfg
Add Files
Deployment
Metadata Capture
Review
Workflow.properties File Overview

The workflow_name.properties file contains the text strings that are displayed in the
ContentCenter interfaces. These text strings include:
Field Labels
Error messages
Window and dialog box titles
Image files
User prompts
Task names and transition labels
In addition to the workflow_name.properties file, there is a

workflow_name_locale.properties file for each of the supported locales. For more
information about these files, see “Configurable Workflows and Localization” on
page 64.

VisualAnnotate and Configurable Workflows

VisualAnnotate is a review tool that is installed by the TeamSite installation program. It
enables users to annotate HTML pages from within their browser window. Reviewers
can draw, change text, and add “sticky notes” directly on the pages they are viewing.
These annotations are stored separately from the file as extended attributes.
VisualAnnotate reviews are implemented within the following solution workflows:

configurable_author_submit
configurable_author_assignment
Using or adapting these solutions eliminates the need to build separate VisualAnnotate
workflows. Refer to Chapter 6, “Using VisualAnnotate,” for more information about
VisualAnnotate and its configuration.
NOTE
Because VisualAnnotate is not supported on non-English servers, remove the
VisualAnnotate functionality from these workflows before using them on a non-English
server.
Configurable Workflow Settings

All three configurable workflows share the following functionality:
Email Notification
Metadata Capture
Deployment
The configurable_author_assignment and configurable_author_submit workflows

also add the functionality to have submitted files reviewed by a configurable reviewer.
The reviewer section of these workflow configuration (.cfg) files is where the email
notification system obtains instructions to determine the email address of the reviewer.
NOTE
The configurable_author_assignment workflow also adds the functionality to attach
files to a workflow task.
The general procedure for configuring these options is the same for each of the
configurable workflows:
1. Open the workflow_name.cfg file that corresponds with the configurable workflow
you want to implement.
By default, these files are located in iw-home/local/config/wft/solutions.
2. Edit the entries that correspond with the functionality you want to enable.
Interwoven, Inc. 56
3. Save and close the file.

4. Ensure the workflow is activated as described in “Enabling Workflows” on page 25.
The following sections describe each of these options in detail.
Email Notification Settings

All configurable workflows have the ability to send email notifications to alert the user
of work assignments, requests for review of completed work, or problems deploying
files.
## Email Notification
##
# Should an email notification be sent to an Author when a task
# is pending?
email_notification_to_author=no
Change this entry to email_notification_to_author=yes if you want the email sent to authors
who have either had work assigned to them by an assignment workflow or by having
submitted work rejected by a reviewer. If set to yes, email is sent to the author to whom
the work is assigned (author_assignment workflows) or to the author who performs the
submit (author_submit workflows).
# Should an email notification be sent to a reviewer when a task
# is pending?
email_notification_to_reviewer=no
Change this entry to email_notification_to_reviewer=yes if you want to email sent to

reviewers who have had work assigned to them for review (that is, the status of the task
is pending). If set to yes, you must configure the reviewer in the reviewer section of
the configurable_author_assignment.cfg or configurable_author_submit.cfg
files.
# Should an email notification be sent if a deploy task fails?
email_no_deploy=no
Change this entry to email_no_deploy=yes if you want to email sent to the job initiator
when a deploy task fails.
# Should the initiator be prompted to confirm or change these
# choices when initiating a job?
# If yes, the values of email_notification_to_author,
# email_notification_to_reviewer, and email_no_deploy will serve
# as the defaults.
ask_email_notification_to_author=no
ask_email_notification_to_reviewer=no
ask_email_no_deploy=no

Change these entries to ask_email_...=yes if you want the person initiating the job to be
prompted to override (on a job-by-job basis) whether email should be sent for any of the
three situations.
# Templates for the headers and bodies of email messages.
reviewer_email_header_template=reviewer_iwmailheader.tpl
reviewer_email_body_template=reviewer_iwmailbody.tpl
author_email_header_template=author_iwmailheader.tpl
author_email_body_template=author_iwmailbody.tpl
no_deploy_email_header_template=no_deploy_iwmailheader.tpl
no_deploy_email_body_template=no_deploy_iwmailbody.tpl
If you want to replace the Interwoven logo file (ts_logo.gif) with a graphic file containing
your organization’s logo:
Copy the file into iw-home/httpd/iw-icons/solutions directory.
Open the appropriate _mailbody.tpl file in a text editor.
Replace the ts_logo.gif reference in the  section with a reference to the
new graphic file.
Figure 13 shows an example of an email sent to a reviewer:
Figure 13 Review Email
Replaceable
logo file
Submitter
Task type
and number
Link to file
to view
Metadata Capture Settings

The workflow_name.cfg files contain the following metadata capture entries. They use
a question-and-answer format with the question commented out (preceded by #)
followed on the next line by the answer. The answer is set to no by default and may be
followed by additional settings.
## Metadata Capture
##
# Should there be a task to capture metadata from the Author?
metadata_capture=no
Interwoven, Inc. 58
Change this entry to metadata_capture=yes if you want to include a metadata capture

task for the corresponding workflow. If set to yes, when a task is marked as Done, the
workflow will display either the MetaTagger capture screen (requires that the
MetaTagger product is installed) or the default TeamSite metadata capture screen
depending on a setting later in this file.
# Should the initiator be prompted to confirm or change this
# choice when initiating a job?
# If yes, the value of metadata_capture will serve as the default.
ask_metadata_capture=no
Change this entry to ask_metadata_capture=yes if you want the person initiating the
job to be prompted to override (on a job-by-job basis) whether the submitter is required
to enter metadata.
# If there is a task to capture metadata, which UI should be presented?
# iwmetadata.cgi is the TeamSite metadata capture UI.
metadata_capture_ui=iwmetadata.cgi
# mtmetaproxy.cgi is the MetaTagger metadata capture UI (requires
MetaTagger).
#metadata_capture_ui=mtmetaproxy.cgi
If a metadata task is included in the workflow, the default metadata capture interface
displayed to the submitter is the TeamSite metadata capture form (iwmetadata.cgi). If
you have installed MetaTagger 3.1 or later, and would like to have it displayed by the
workflow, comment out the metadata_capture_ui=iwmetadata.cgi line (add a # at the
beginning of the line) and uncomment the #metadata_capture_ui=mtmetaproxy.cgi
line (remove the #).
For more information about capturing metadata, refer to the:

TeamSite Administration Guide for information about iwmetadata.cgi.
MetaTagger user documentation for information about mtmetaproxy.cgi.
Deployment Settings
The workflow_name.cfg files contain the following deployment entries. They use a
question-and-answer format with the question commented out (preceded by #) followed
on the next line by the answer. The answer is set to no by default and may be followed
by additional settings.
## Deployment
##
# Should there be a Deploy task at the end of a job to deploy files
# after they have been submitted?
deploy_task=no
Change this entry to deploy_task=yes if you want the files being submitted to be
deployed by the workflow using OpenDeploy.
# Should the initiator be prompted to confirm or change this
# choice when initiating a job?

# If yes, the value of deploy_task will serve as the default.

ask_deploy_task=no
Change this entry to ask_deploy_task=yes if you want the person initiating the job to
be prompted to override (on a job-by-job basis) whether the files associated with this job
should be deployed when submitted.
# Should the job form include an info field?
ask_for_info=yes
By default, the job form presented to the submitter includes a field where details about
the submission can be included. Any information entered by the submitter is stored in a
submit-info variable of the submit task and, as such, can be queried or displayed.
Review Settings
The configurable_author_submit.cfg and configurable_author_assignment.cfg
workflows contain functionality that requires files be reviewed before they are
submitted. The configuration involves defining who the reviewer is. The default
reviewer for these workflows is the owner of the workarea to which the file is being
submitted.
The following commented section from these files summarize how reviewers can be
specified:
## Review
##
# Who should review the Author's work? The format of the review_type is:
#
# "review_type=" <review_task> | <serial> | <concurrent>
# <review_task> =
"areaowner"|"job_initiator"|<user>|<grouptask>|<select>
# <user> ::= "user:" <os_user_name>
# <grouptask> ::= "grouptask[" (<group>|<user>) ("," (<group>|<user>))*
"]"
# <group> ::= "group:" <os_group_name>
# <select> ::= "select[" <role> ("," <role>)* "]"
# <role> ::= "role:" ( "author"|"editor"|"admin"|"master"| etc. )
# <serial> ::= "serial[" <review_task> ("," <review_task>)* "]"
# <concurrent> ::= "concurrent[" <review_task> ("," <review_task>)* "]"
The following sections describe simple examples (those that use <review_task> as the
review_type value), and advanced examples (those that use <serial> or <concurrent>
as the review_type value).
Interwoven, Inc. 60
Simple Examples
Each of these examples specifies a review process with only one review task.
review_type=areaowner
review_type=user:worldcorp\andre
review_type=grouptask[group:demomaster,user:jsmith]
review_type=select[role:editor,role:author]
In the first two examples, the review task is a usertask assigned to the area owner, or the
specific user (worldcorp\andre).
NOTE
In the second example, the domain is specified for Windows only; on a UNIX system, it
would be simply the username (andre).
In the third example, the review task is a grouptask that is shared by the specified users
and groups. In the fourth example, the review task is a usertask, and the owner of that
task will be selected by the job initiator from a selection list of those users who are
authors or editors.
The configurable_author_submit workflow uses areaowner by default.To specify one

of the following reviewers, comment out (with #) the line review_type=areaowner and:
Job initiator—Uncomment the line # review_type=job_initiator.
Specified user—Uncomment the line # review_type=user:worldcorp\andre, and
replace worldcorp\andre with the username and (Windows only) domain.
Specified group—Uncomment the line
# review_type=grouptask[group:demomaster,user:jsmith], and replace
demomaster with one or more groups, defined in the operating system, and replace
jsmith with one or more user names (and, on Windows, their domains). Separate
each group and user name with a comma. You can include groups and users in any
number and combination.
Selection list from which to choose a reviewer or group of reviewers and respective
roles —Uncomment the line # review_type=select[role:editor,role:author]
and specify the desired reviewer roles in any number or combination. The users
whose roles match one or more of the reviewer roles specified will be displayed in a
selection list to the job initiator. For example, the file
configurable_author_assignment.cfg has a commented out line
review_type=select[role:editor]. If this were specified, then the selection list
would contain all users with the Editor role.
Figure 13 shows an example of an email sent to a reviewer.

Advanced Examples
review_type=serial[select[role:editor],areaowner,select[role:master,role:
admin]]
This example specifies a review process with three review tasks that are executed in a
serial manner. The first review task is assigned to a user selected from among the
Editors. The second review task is assigned to the area owner. The third task is assigned
to a user selected from among the Masters and Administrators.
review_type=concurrent[select[role:editor],select[role:editor],select[rol
e:editor]]
This example specifies a review process with three concurrent review tasks. Each task is
assigned to a selected editor.
Use with VisualAnnotate
For workflows that employ VisualAnnotate, it is recommended that a serial review

process be in place. For example:
review_type=serial[select[role:admin,role:master,role:editor],select[role
:admin,role:master,role:editor]]
Return on First Reject?
In a serial review process, you must decide whether the workflow will return to the
author as soon as a single reviewer rejects, bypassing all remaining reviewers.
return_on_first_reject=yes
If you decide no, the workflow will reach all reviewers before deciding whether to
return to the author.
Minimum Number of Reviewers
You must also determine the minimum number of reviewers that the job initiator must
specify.
min_reviewers=3
This indicates the minimum number of reviewer selections that are required. For
example, if review_type indicates a serial review with three tasks, with one reviewer
type specified and two to be chosen from selection lists, and min_reviewers=1, then one
reviewer selection will be required and one will be optional.
If you do not specify a minimum, the job initiator must select a reviewer for every
review task that specifies a selection list.
Interwoven, Inc. 62
Automatically Forward to Next Reviewer?
You must decide whether the job should automatically forward the review task on to the
next reviewer (or to the author) if a certain amount of time elapses.
review_timeouts=yes
NOTE
Depending on the workflow’s specified selection criteria, based on cumulative
approvals and rejections, to determine if the work being reviewed has passed review,
such automatic forwarding may result in the work not passing review.
If you choose yes, you must specify how long in hours and minutes the amount of time
will be, using the +HHHHMM format.
review_timeout_duration=+004800
When using the +HHHHMM format, you must use all six digits, including leading zeros if
necessary.
Add Files Settings

The configurable_author_assignment.cfg and configurable_author_submit.cfg
workflows contain functionality for the initiator to attach files to a job. When a new job
is created by selecting Assign, Submit, or New Job, all of the selected files are attached
to the job. The configuration specifies whether the workflow will begin with a user task
for the initiator to add additional files (the default is no for both of the following
options).
## Add Files
##
# Should there be an "Add Files" task at the beginning of the job
# to permit additional files to be added?
include_add_files=yes
# Should the initiator be asked if an "Add Files" task is desired

# when initiating a job?
# If yes, the value of include_add_files will serve as the default.
ask_include_add_files=yes

Configurable Workflows and Localization

In addition to the workflow_name.cfg file and workflow_name.properties files
installed by the TeamSite installation program, there are additional properties files
that have been localized in TeamSite versions that support localization:
workflow_name_de.properties (German)
workflow_name_en.properties (English)
workflow_name_fr.properties (French)
workflow_name_ja.properties (Japanese)
workflow_name_ko.properties (Korean)
workflow_name_zh_CN.properties (Simplified Chinese)
These files contain the localized text strings that display in the ContentCenter interfaces
if the user’s browser is operating in a locale that matches one of these files. If the locale
of the browser does not match one of the locales, the default
workflow_name.properties file (the one without a locale specified) is used to provide
the text strings.
NOTE
The contents of these files use Latin-1 encoding, therefore multibyte characters are
represented using Unicode characters.
Interwoven, Inc. 64
Chapter 4
Creating Workflow Template

Files
This chapter describes the structure and contents of workflow template files. It contains
an introduction to the components used in workflow templates; an excerpt from a basic
sample workflow template file; an explanation of all file components (some of which
are not included in the basic sample file); and a second, more sophisticated sample file
(which shows how to use more of these file components).
The actual ready-to-use workflow templates installed with TeamSite are described
beginning on page 43.
Workflow Template File Structure

Workflow template files are installed by default in three subdirectories in
iw-home/local/config/wft and end with a .wft extension. Workflow template files
may contain the following components:
<template_script> elements containing arbitrary Perl code.
CGI_info directives to control the look and feel of workflow forms generated by the
instantiator CGI.
TAG_info directives to control the data collection, validation, and error messages
displayed in workflow forms.
__ELEM__(tagname); directives to return the number of elements in a tag.
__TAG__(tagname); directives to insert the HTML-encoded data associated with the
form POST/GET key tagname into the job specification.
__INSERT__(string); directives to insert text into a job specification
programatically.
__VALUE__(tagname); directives to return unescaped POST/GET data associated
with $tagname.
Other elements identical to those used by job specification files.

Chapter 4: Creating Workflow Template Files
Simple Workflow Template File

The following is a fragment from a simple workflow template file that fills in blank
fields (indicated by__TAG__directives) with HTML-encoded CGI data.
<?xml version="1.0" standalone="no"?>

<!DOCTYPE workflow SYSTEM "iwwf.dtd">
<template_script><![CDATA[
TAG_info(
description => "<input type='text' value='dark and stormy

night'>",
job_name => "<input type='text' value='edit story'>",
);
]]></template_script>
<workflow name="__TAG__('job_name');"
owner="__TAG__('iw_areaowner');"
description="__TAG__('description');">
Things to note in the preceding example:

POST/GET data keynames appear on the left hand side of the arrow in the TAG_info
directive.
The HTML form input field that collects data for the template is located to the right
of the arrow in the TAG_info directive.
The TAG_info directive is located within a <template_script> element.
You can refer to POST/GET data that was not explicitly collected by the HTML
form input fields you specified in TAG_info. For example, iw_areaowner is
provided by default, so you do not need to give the template instantiator CGI an
input field HTML fragment for iw_areaname within the TAG_info directive.
Suppose that, in the user interface for this form, you want the field that collects data for
job_name to have a label of “Job Name” instead of “job_name”. The following template
file section would accomplish that:
TAG_info(
description => "<input type='text' value='dark and stormy night'>",
job_name => [ html => "<input type='text' value='edit story'>",

label => "Job Name",
],
);
Interwoven, Inc. 66
This example illustrates the TAG_info attributes html and label. There are many more,
but all of them follow the same simple pattern:
[ ...some_attribute... => ...a_value...,
...another_attribute... => ...another_value...,
... and so on...
],
As described later in this chapter, the template developer can do far more sophisticated
things than just filling in the blanks. For example, you can generate workflow
dynamically, and intersperse dynamically generated workflow, data, and tags with
hard-coded information. The following sections explain the details of workflow
template file components and how you can use them to create workflow templates
ranging from simple to elaborate. For another example of how to use many of these
component, see “Complex Workflow Template File” on page 80.
<template_script> Element
A workflow template file can contain any number of <template_script> elements.
Each <template_script> element contains arbitrary Perl code that can perform the
following actions:
Define the rules that a workflow instantiator (either the CGI or CLT) employs to
combine user-entered data with:
hardcoded workflow XML from the workflow template file.
programmatically generated workflow XML produced within
<template_script> elements.
Programmatically generate a job specification (and/or intersperse hard-coded XML

job specification information with programmatically generated XML).
Optionally send the job specification to a file in addition to, or instead of,
instantiating it into the workflow subsystem. This can be helpful if you need to see
exactly what XML is being produced by the workflow template file and a workflow
instantiator.
Define the rules that validate user-entered data.
Define the custom error messages displayed when the template's data validation
rules are not satisfied (see “TAG_info Directive” on page 70).
Inspect incoming POST/GET data, and (under certain conditions) execute code on
the basis of this data. For example, rules in a <template_script> element can tell
the instantiator to generate different job specifications depending on what a user’s
name is.
For example, if the an Author “Andre” needs three approvers for his work, but the
Author “Jerome” needs only one approver, you can define rules in a
<template_script> element to perform this job customization automatically based
on whether Jerome or Andre is the Author.

Merge POST/GET data with the hard-coded workflow XML from the workflow
template file.
Determine the look and feel of the automatically generated workflow form that
collects end-user data for a job (see “CGI_info Directive” on page 68).
Because TeamSite workflow templates must be valid XML documents, all content in a
<template_script> element must be declared as CDATA to protect it from interpretation
by an XML parser. For example:
# arbitrary Perl code
Together, all of the <template_script> elements in a workflow template file form a

single Perl program. If a workflow template file contains more than one
<template_script> element, all variables, functions, and libraries set in one element
are available in the others.
For example:
<...hard-coded workflow XML...>
use Lib1; # you can import libraries
sub some_function # you can define functions
{
return "Please enter beverage choice";
}
my $beverage = "tea"; # you can define variables
<...hard-coded workflow XML...>
# The variable $beverage is accessible in this
# section, and contains the value "tea".
# The function some_function() may also be called here.
CGI_info Directive
The following section contains information about the CGI_info directive.
Usage
CGI_info( ...list of key/value pairs... );
Interwoven, Inc. 68
Description
Sets various defaults that affect the look and feel of workflow forms generated by the
instantiator CGI. The CGI_info directive may only appear within a <template_script>
element. Properties that you can set are:
Table 4 CGI_Info Directive Properties

Property Description
error_data_bgcolor Data field background color displayed if an end user
enters invalid data (validity is determined by the
instantiator CGI). By default, all non-empty fields are
valid, but you can customize this on a field-by-field basis.
Color in this property and all other color properties shown
in this table can be specified using standard HTML color
syntax (for example, "red", "green", "#FFFFFF").
error_label_bgcolor Label field background color displayed if an end user
enters invalid data in the data field.
error_text_color Error message text color.
valid_bgcolor Background color displayed if an end user enters valid
data.
title Browser window title.
html_body_options Sets the options for the <body> element of the instantiator
CGI. For general information about <body> elements, see
http://www.w3.org/TR/REC-html40/struct/
global.html#edef-BODY
tag_table_options Sets the options for the <table> element of the
instantiator CGI. For general information about <table>
elements, see
http://www.w3.org/TR/REC-html40/struct/
tables.html#h-11.2.1
pre_tagtable_html Defines what is displayed in a workflow form between the
banner and tag table areas.
post_tagtable_html Defines what is displayed in a workflow form after the tag
table area.
NOTE
TeamSite comes with a set of standard defaults to govern the look and feel of workflow
forms.
Example
CGI_info(
error_bgcolor => "red",
valid_bgcolor => "green",
title => "TeamSite Workflow Template",
html_body_options => "bgcolor='yellow'",
tag_table_options => "border=5 cellspacing=2 cellpadding=8",

pre_tagtable_html => "<h2>Whatever you want...</h2>",

post_tagtable_html => "...this appears after the tagtable...",
);
TAG_info Directive
The following section contains information about the TAG_info directive.
Usage
TAG_info(list of key/value pairs);
Description
Establishes a relationship between a list of tag names and the information the
instantiator CGI uses to collect data for them. There are two ways to build these
associations:
Style 1 (simple):
tagname => "...html that collects data for tagname...";
Style 2 (highly flexible):

tagname =>[ html => "...html that collects data for tagname...",
is_required => "true",
valid_input => "...Perl expression...",
label => "...html label...",
error_msg => "...html error message...",
];
When the instantiator CGI processes the TAG_info directive, the name attribute in the
resulting HTML code is automatically set to tagname. For example, given the following
TAG_info directive:
TAG_info(
beverage => "<input type='text' value='tea'>",
);
The internal representation of the resulting HTML code is:

"<input type='text' name='beverage' value='tea'>"
Because this is done automatically, it is impossible for the tag names to get out of sync
with the resulting HTML code. For example, if you attempted to explicitly set the name
attribute to something other than tagname:
TAG_info(
beverage => "<input type='text' name='drink' value='tea'>",
};
Interwoven, Inc. 70
then name='drink' gets removed and automatically replaced by name='beverage'.
The TAG_info directive may appear only within a <template_script> element. While it
is legal to have any number of TAG_info directives in a workflow template file, it is
often convenient to consolidate all necessary data into one TAG_info directive.
Properties that you can set for each tag in a TAG_info directive are described in the
following table:
Table 5 Tag_Info Directive Properties

Property Description
html Valid HTML input form field (which optionally may contain a default
value). This is required if you are using Style 2.
is_required Whether end-user input in the tag is required. Defaults to true if not
set.
valid_input Rules to check input validity. Default is to check for an empty string
if not set.
error_msg An HTML message returned if end-user input is invalid. Default
message is Valid input required if not set.
label The HTML label displayed beside the HTML input field for this tag.
Defaults to the value of tagname if not set.
If all of the user input fields (i.e., TAG_info() fields) in a workflow template have a
default value and are set to is_required=>'false', TeamSite normally tries to compile
the job automatically, without user intervention.
To force user input but not require all fields, include the following code in your .wft
file:
if (!defined(__VALUE__(iw_first_time)))
{
TAG_info(
first_time_hidden_placeholder =>
[
html => "<input type=hidden value=''>",
is_required => 'true',
],
);
}

Array Validators
When validating input in a valid_input expression, both $_ and @_ are set

appropriately. Therefore, when collecting information in a multi-select list, a tag’s
validator can be implemented as follows:
TAG_info(
a_tag_name => [ html => "html that collects data for a_tag_name...",
valid_input => 'a_tag_validator(@_)',
]
)
Example
The following example shows definitions for three tags (named food, beverage, and
music). Each tag can be used any number of times by the instantiator CGI to prompt for
and collect end-user input in a workflow form.
The definition for tag food specifies that the HTML element used to collect data for this
CGI variable is a text field.
The tag beverage has the following characteristics:

It only accepts text input.
It automatically displays a default value of Beverage: tea in its entry field.
A value in its entry field, either end-user input or the default, is required.
The label Enter beverage choice is displayed beside the text field that collects
user input.
valid_input specifies that all data entered by an end user must begin with the string
Beverage:.
error_msg specifies the error message to be displayed if end-user input does not
begin with Beverage:.
The tag music displays a default value of Punk.

TAG_info(
food => "<input type='text'>",
beverage => [ html => "<input type='text' value='Beverage:tea'>",
label => '<strong>Enter beverage choice</strong>',
valid_input => '/^Beverage:/',
error_msg => '<br><strong>'.
'ERROR: input must begin with "Beverage:"'.
'</strong>',
],
music => "<input type='text' value='Punk'>",
);
Interwoven, Inc. 72
TAG_info(): iw_setwfarg_
You can declare form variables within the TAG_info() section that automatically
become workflow variables by prefixing the name of the form variable with the string:
iw_setwfarg_.
For example, if you had the following snippet of code in your workflow template:
TAG_info(
iw_setwfarg_title = "<input type=’text’></input>",
);
And the person who creates an instance of this job fills in the prompt for “Title” with
“Technical Writer,” the generated workflow contains:
<variables>
<variable key="title" value="Technical Writer"/>
</variables>
This also means that this information can be retrieved in an externaltask or cgitask script
similar to:
use TeamSite::WFworkflow;
my($job) = new TeamSite::WFworkflow($ARGV[0]);
my($title) = $job->GetVariable('title');
__ELEM__Directive
The following section contains information about the__ELEM__directive.
Usage
__ELEM__($tagname);
Description
Returns the number of data elements associated with tag tagname. If tagname is
undefined, 0 is returned. The__ELEM__directive may appear inside and/or outside of a
<template_script> element. You can also embed an__ELEM__directive within an
__INSERT__directive. A workflow template file can contain any number of__ELEM__
directives.

Example
The following TAG_info directive defines the tag reviewers to accept multiple
selections. Therefore, this one tag can have multiple values. By default, two reviewers
(Bob and Jerry) have been selected. If an end user accepts these default values,
__ELEM__('reviewers'); will yield 2. If an end-user also selects Phil as a reviewer,
__ELEM__('reviewers');
will yield 3.
TAG_info(
reviewers => [ html => "<select multiple>" .

" <option>Phil" .
" <option selected>Bob" .
" <option selected>Jerry" .
"</select>",
label => "Pick reviewers",

],
);
__TAG__Directive
The following section contains information about the __TAG__ directive.
Usage
__TAG__($tagname);
Description
When the workflow instantiator creates a job specification, it uses each__TAG__

directive in the workflow template file as an insertion point for the HTML-encoded
value associated with the form input key tagname. Thus, user input from any tag can be
inserted at any point in a job specification file in HTML-encoded form.
In addition, the__TAG__directives can mention form input key names that are not
defined in TAG_info as long as the POST/GET data is provided for these keys
programmatically. The following POST/GET keys are always passed, and are therefore
always available for use in a workflow template file or job specification file. The set of
passed tags differs depending on how the job is started as shown in the following tables.
Interwoven, Inc. 74
If started by Submit:
Key Name Description

iw_areaowner The owner of the workarea
iw_branch The branch’s vpath (/default/main/subranch1)
iw_home The iw-home directory
iw_role The user’s role
iw_session The session string
iw_template_file The template file’s path and name relative to
iw-home/local/config/wft
iw_template_name The template name to be displayed in TeamSite GUI
iw_use_default Use the default argument of the template (defaults to true)
iw_user The user’s name
iw_workarea The workarea’s vpath (/default/main/WORKAREA/user1)
If started by New Job:
Key Name Description

iw_home The iw-home directory
iw_role The user’s role
iw_session The session string
iw_template_file The template file’s path and name relative to
iw-home/local/config/wft
iw_template_name The template name to be displayed in TeamSite GUI
iw_use_default Use the default argument of the template (defaults to true)
iw_user The user’s name
Additionally, the iw_overwrite POST/GET key makes the status of the Overwrite
button in ContentCenter available to the workflow subsystem. For example, if
Overwrite is selected, an iw_overwrite value of true is passed as POST/GET data to
the instantiator CGI, making it available for use in a job specification. If Overwrite is
not selected, the value of iw_overwrite is false.

Additional POST/GET keys could also be available, depending on the job’s

configuration. To display a list of all POST/GET keys available in a specific job, run
show_env.cgi by naming it in the job’s <cgitask> element. For example:
<workflow name="minimal" owner="jon" creator="jon"

description="This is a minimal example of a CGI task">
<cgitask name="cgi" start="t" owner="chris"
description="First CGI task" immediate="t">
<areavpath v="/default/main/wfregr2/WORKAREA/chris"/>
<successors>
<successorset description="Success">
<succ v="end"/>
</successorset>
</successors>
<command v="show_env.cgi"/>
</cgitask>
<endtask name="end"/>
</workflow>
The__TAG__directive may appear inside or outside of a <template_script> element.

You can also embed a__TAG__directive within an__INSERT__directive. A workflow
template file can contain any number of__TAG__directives. To determine how many
elements a tag contains, refer to the__ELEM__directive. See “Using Variables in Strings”
on page 79 for details about the syntax of variables used within the__TAG__directive.
Examples
If your workflow template file contained the following text:
I wish I had a__TAG__('beverage');
and the instantiator CGI POST/GET data for tag beverage was cup of tea, the job
specification would contain:
I wish I had a cup of tea
Similarly, if beverage were an array tag (for example a multi-select or checkbox), and 2
were a valid index, the following would be a valid entry in the workflow template file:
I wish I had a__TAG__('beverage[2]');
In this case, the third element from tag beverage would be inserted by__TAG__. The
third element is chosen because arrays start at element 0.
Interwoven, Inc. 76
__INSERT__Directive
The following section contains information about the__INSERT__directive.
Usage
__INSERT__($string);
Description
Inserts the value of the variable (or hard coded string) $string into the workflow
template file, where $string can be any arbitrary text (typically, workflow XML).
$string can optionally include embedded tags (using the__TAG__directive) and/or
elements (using the__ELEM__directive). Embedding tags within an__INSERT__directive
is especially useful when the template’s output needs to be generated dynamically. See
“Using Variables in Strings” on page 79 for details about the syntax of variables used
within the__INSERT__directive.
Example
The following example shows the portion of a workflow template file that sequentially
inserts the values of tags a, b, and c into the job specification file.
my $i;
my @tag_array = ('a','b','c');
for ($i=0; $i<3; ++$i)
{
__INSERT__("I am__TAG__($tag_array[$i]); pleased!\n");
}
Note that an__INSERT__directive can also process complex expressions both inside and
outside of a <template_script> element (for example, it can process quoted fragments
containing nested__TAG__(...); directives, possibly joined by ‘.’).
__VALUE__ Directive
The following section contains information about the__VALUE__directive.
Usage
__VALUE__($tagname);
__VALUE__($tagname,$encoding);

Description
By default, returns the unescaped POST/GET data associated with tag $tagname, but
unlike__TAG__($tagname), it does not insert anything into the job specification when
the instantiator CGI processes the workflow template file. If the value of the optional
parameter $encoding is set to html, the HTML-encoded version of the data is returned
instead of the raw value.
This is useful when the template’s output needs to be generated dynamically based on
the POST/GET values the instantiator CGI receives. The values returned by the variable
$tagname are as follows:
If $tagname does not refer to a defined POST/GET key name, undef is returned.
If $tagname is a scalar POST/GET key name, a scalar is returned.
If $tagname is an array POST/GET key name, a list is returned.
If $tagname is a subscripted array POST/GET key name, a scalar is returned.
The__VALUE__directive may only appear within a <template_script> element. In a

__VALUE__($tagname); directive, if the tagname is a subscripted array, the subscript
can be an expression.
Example
The following example uses__VALUE__of tag x to set the upper limit of $i. This example
assumes that the form input key name x contains an integer.
for (my $i=0; $i <__VALUE__("x"); ++$i)

{
__INSERT__("very nice $i\n");
}
# Advanced users: if x were an array tag (CGI form input keyname),

# then it could be subscripted as follows, assuming 2 is a valid
# array index (cf:__ELEM__):
#
# for (my $i=0; $i <__VALUE__("x[2]"); ++$i)
#
Interwoven, Inc. 78
Other Elements
A workflow template file can also contain any element that is legal in a job specification
file. These elements, described in “Workflow Template File Structure” on page 65, make
up the set of general workflow configuration instructions shown in the workflow
template file box in the diagram in Figure 3.
Using Variables in Strings

The following scenarios describe syntax rules that apply to variables in strings used by
__TAG__and__INSERT__directives. The scenarios start with the simplest method of
variable substitution and end with the most advanced.
Scenario 1: Basic Variable Usage
When inside a quoted string, the argument for a__TAG__directive does not need any kind
of quoting at all.
For example, assuming you have a POST argument named color1, you can just say:
__INSERT__("shirtcolor='__TAG__(color1);' accepted!!");
Other valid usage examples are:

__INSERT__("... __TAG__('color1'); ...");
__INSERT__('... __TAG__("color1"); ...');
__INSERT__("... __TAG__(color1); ...");
__INSERT__('... __TAG__(color1); ...');
__INSERT__("... '__TAG__(color1);' ...");
__INSERT__('... "__TAG__(color1);" ...');
__TAG__("color1");
__TAG__('color1');
The following is not valid because the argument color1 is not quoted in any way, and
__TAG__is not nested within an__INSERT__directive:
__TAG__(color1);
Scenario 2: Including Quotation Marks in Insertions
Continuing with the preceding example and adding the following information:
You have a Perl variable named $var1 whose value is workarea
A POST input key named workarea whose value is jon
then the following statements all insert the string jon into the job:
__INSERT__("...__TAG__($var1); ...");
__INSERT__("...__TAG__('$var1'); ...");
__TAG__($var1);

The following expression inserts the string 'jon' into the job:
__INSERT__("... '__TAG__($var1);' ...");
Therefore, to insert a tag into a job within single quotes you could say:
__INSERT__("var1='__TAG__(color1);' accepted!!");
And to insert a tag into a job within double quotes, you could say:
__INSERT__('var1="__TAG__(color1);" accepted!!');
Scenario 3: Preferred Ordering of Single and Double Quotes
If you specify either of the following:
__INSERT__('__TAG__("$var1");');
__INSERT__('__TAG__($var1);');
you will probably get an error message about not finding data for the FORM input
keyname $var1 because the outer-most quotation marks on the__INSERT__directive are
single quotes. In Perl, single quotes are interpreted as:
"Do not interpolate anything in this string as a Perl variable."
Hence $var1 is literally the set of characters $,v,a,r,1 (and not a variable named $var1
whose value is workarea).
In general you should place the double quotes outside and the single quotes inside:
__INSERT__("var1='__TAG__(color1);' accepted!!");
For example:
my $status = "not in stock.";

__INSERT__("var1='__TAG__(color1);' currently $status");
Complex Workflow Template File

The workflow template file on the following page is more elaborate than the sample file
shown in “Simple Workflow Template File” on page 66; it shows the use of several
additional file components as explained in the preceding sections. Specifically, this file:
Generates a form that captures the deployment date for this job.
Ensures that the “Timed Deployment” accepts a correctly formatted date.
Sets the label in the form that collects data for the deploy date to “Timed
Deployment”.
Interwoven, Inc. 80
Sets the owner attribute for the XML element <workflow> to the HTML-encoded
data associated with the form input key iw_areaowner (and similar operations for
the other__TAG__directives).
For each file that has been selected in ContentCenter, it inserts a line that reads:
<file path='...filename...' comment='File to time deploy'/>
When the job specification is generated, these lines appear between the XML tags
<files> and </files>.
In addition to the code shown, you also need:

Perl code that converts the date entered in YYYY-MM-DD format into a date compatible
with a timeout element attribute of MMDDYYYYHHMM.
A dummytask after the submittask with that timeout value.
To set the successor of the dummytask to an externaltask that actually performs the
deployment.
TAG_info(
deploy_date => [ html => "<input type='text' value=''>",
valid_input => '/d\d\d\d-\d\d-d\d\/',
label => "Timed Deployment",
error_msg => "Date format is YYYY-MM-DD",
],
);
<workflow name="TimedDeploy" owner="__TAG__('iw_areaowner');"

creator="__TAG__('iw_areaowner');"
description="Timed Deployment">
<usertask name="AuthorWork" owner="__TAG__('iw_areaowner');"

description="Editing files to time deploy" start="t">
<successors>
<successorset description="One Minute">
<succ v="Submit"/>
</successorset>
</successors>
<files>

for (my $i=0; $i < __ELEM__('iw_file'); ++$i)

{
__INSERT__("<file path='__TAG__(iw_file[$i]);' comment='File
to time deploy'/>\n");
}
</files>
</usertask>
<submittask name="Submit" owner="__TAG__('iw_areaowner');"

description="Staging for deployment.">
.
.
.
is_user_in_roles
The following out-of-the-box workflow template files call is_user_in_roles() from
Flexroles.pm:
default/author_assignment.wft
default/default_assign.wft
examples/author_assignment_with_nested_job.wft
solutions/configurable_author_assignment.wft
You need to use the user IDs and role IDs when calling this API, rather than the user and
role display names as these are showed from the TeamSite user interface. The workflow
engine and workflow template files only work with unique IDs rather than display
names.
Interwoven, Inc. 82
Chapter 5
Job Specification Files
Job specification files are XML files created by workflow instantiators when a
workflow template is instantiated. Typically, a job specification file is not actually
created as a file on disk, but is simply instantiated and executed immediately as a job
instance within the server workflow system. Understanding how job specification files
are structured is useful when developing workflow templates.
In addition to creating job files by writing and instantiating a .wft file (as described in
Chapter 4, “Creating Workflow Template Files”), you can create a job by directly editing
an XML job specification file.
A job specification file must:

Be structured as described in “Job Specification File” on page 83
Use elements as described in “Job Specification DTD” on page 84
See “Sample Job Specification File” on page 125 for an example of this type of file.
Refer to the following Web site for a detailed XML specification:
http://www.xml.com/axml/testaxml.htm
Job Specification File

A job specification file describes a single job. It is structured as a hierarchy of sections,
each containing an element definition that enables you to control a job parameter. An
initial <workflow> section defines the overall characteristics of the job. It is followed by
one or more task sections describing specific tasks that occur as part of the job.
The following list shows all of the possible elements that can define sections in a job
specification file. Indentation shows nesting levels:
workflow
usertask
updatetask
submittask
externaltask
endtask
grouptask

Chapter 5: Job Specification Files
cgitask
dummytask
locktask
wftask
All of these elements, their attributes, and their subelements are described in the
following section. See “Sample Job Specification File” on page 125 for examples of files
that use these elements.
Job Specification DTD

The following DTD (iwwf.dtd) excerpts describe the syntax for each job specification
file element. These elements are also valid in a workflow template file.
<!ELEMENT workflow (description?, variables?,

(usertask|submittask|updatetask|
externaltask|cgitask|endtask|grouptask|dummytask|locktask|wftask)+)>
<!ATTLIST workflow name ID #REQUIRED
owner CDATA #REQUIRED
creator CDATA #REQUIRED
description CDATA #IMPLIED>
<!ELEMENT description (#PCDATA)>
<!ELEMENT usertask (description?, areavpath, successors, timeout?,

files?, activation?, inactivate?, resets?,
eastartop*, eafinishop*, wfvarstartop*, wfvarfinishop*,
variables?)>
<!ATTLIST usertask owner CDATA #REQUIRED
name ID #REQUIRED
start (t|f) "f"
description CDATA #IMPLIED
lock (t|f) "f"
transferonly (t|f) "f"
readonly (t|f) "f">
<!ELEMENT grouptask (description?, areavpath, successors, sharedby,

timeout?,
eastartop*, eafinishop*, wfvarstartop*,
wfvarfinishop*,
variables?)>
<!ATTLIST grouptask name ID #REQUIRED
start (t|f) "f"
lock (t|f) "f"
Interwoven, Inc. 84
retainowner (t|f) "f"

readonly (t|f) "f">
<!ELEMENT sharedby (user|group)+>
<!ELEMENT user EMPTY>

<!ATTLIST user v CDATA #REQUIRED>
<!ELEMENT group EMPTY>

<!ATTLIST group v CDATA #REQUIRED>

<!ELEMENT submittask (description?, areavpath, successorset | (success,
failure?),
timeout?, files?, activation?, inactivate?, resets?,
variables?)>
<!ATTLIST submittask owner CDATA #REQUIRED
name ID #REQUIRED
start (t|f) "f"
skipconflicts (t|f) "f"
skiplocked (t|f) "f"
override (t|f) "f"
unlock (t|f) "f"
savecomments (t|f) "f"
<!ELEMENT updatetask (description?, areavpath, successorset | (success,

failure?),
srcareavpath, timeout?, files?, activation?,
inactivate?,
resets?, eastartop*, eafinishop*, wfvarstartop*,
wfvarfinishop*, variables?)>
<!ATTLIST updatetask owner CDATA #REQUIRED
name ID #REQUIRED
start (t|f) "f"
delete (t|f) "t"
overwritemod (t|f) "f"
lock (t|f) "f">
<!ELEMENT externaltask (description?, areavpath, successors, command,

wfvarfinishop*,
variables?)>
<!ATTLIST externaltask owner CDATA #REQUIRED
name ID #REQUIRED
start (t|f) "f"


lock (t|f) "f"
readonly (t|f) "f"
retry (t|f) "t">
<!ELEMENT cgitask (description?, areavpath, successors, command,

variables?)>
<!ATTLIST cgitask owner CDATA #REQUIRED
name ID #REQUIRED
start (t|f) "f"
lock (t|f) "f"
immediate (t|f) "f"
readonly (t|f) "f">
<!ELEMENT wftask (description?, areavpath, successors, (jobfile|wftfile),

variables?)>
<!ATTLIST wftask owner CDATA #REQUIRED
name ID #REQUIRED
start (t|f) "f"
<!ELEMENT endtask (activation?, eastartop*, eafinishop*, wfvarstartop*,

wfvarfinishop*)>
<!ATTLIST endtask name ID #REQUIRED
<!ELEMENT dummytask (description?, timeout,

activation?, inactivate?, resets?,
wfvarfinishop*,
variables?)>
<!ATTLIST dummytask name ID #REQUIRED
start (t|f) "f"
<!ELEMENT locktask (description?, areavpath, success, failure,

variables?)>
<!ATTLIST locktask owner CDATA #REQUIRED
name ID #REQUIRED
start (t|f) "f"
Interwoven, Inc. 86
<!ELEMENT success (succ+)>
<!ELEMENT failure (succ+)>

<!ATTLIST failure firsttimeonly (t|f) "f">
<!ELEMENT variables (variable+)>

<!ELEMENT variable EMPTY>
<!ATTLIST variable key CDATA #REQUIRED
value CDATA #REQUIRED>
<!ELEMENT command EMPTY>

<!ATTLIST command v CDATA #REQUIRED>
<!ELEMENT jobfile EMPTY>

<!ATTLIST jobfile v CDATA #REQUIRED>
<!ELEMENT wftfile EMPTY>

<!ATTLIST wftfile v CDATA #REQUIRED
background (t|f) "f">
<!ELEMENT areavpath EMPTY>

<!ATTLIST areavpath v CDATA #REQUIRED>
<!ELEMENT successors (successorset+)>
<!ELEMENT successorset (description?, succ+)>

<!ATTLIST successorset description CDATA #IMPLIED>
<!ELEMENT succ EMPTY>

<!ATTLIST succ v IDREF #REQUIRED>
<!ELEMENT files (file+)>
<!ELEMENT file EMPTY>

<!ATTLIST file path CDATA #REQUIRED
comment CDATA #REQUIRED>
<!ELEMENT activation (and|or|not|pred)>

<!ELEMENT and (and|or|not|pred)*>
<!ELEMENT or (and|or|not|pred)*>
<!ELEMENT not (and|or|not|pred)>
<!ELEMENT pred EMPTY>

<!ATTLIST pred v IDREF #REQUIRED>
<!ELEMENT inactivate (pred+)>
<!ELEMENT resets (reset+)>

<!ELEMENT reset EMPTY>
<!ATTLIST reset v IDREF #REQUIRED>
<!ELEMENT srcareavpath EMPTY>

<!ATTLIST srcareavpath v CDATA #REQUIRED>
<!ELEMENT eastartop EMPTY>

<!ATTLIST eastartop op (set|append|delete) #REQUIRED
name CDATA #REQUIRED
<!ELEMENT eafinishop EMPTY>

<!ATTLIST eafinishop op (set|append|delete) #REQUIRED
<!ELEMENT wfvarstartop EMPTY>

<!ATTLIST wfvarstartop op (set|append|delete) #REQUIRED
<!ELEMENT wfvarfinishop EMPTY>

<!ATTLIST wfvarfinishop op (set|append|delete) #REQUIRED
<!ELEMENT timeout (succ+)>

<!ATTLIST timeout v CDATA #REQUIRED>
NOTE
Subelements within an element must be ordered as shown in the DTD. See
iw-home/localconfigwftiwwf.dtd for the complete workflow DTD.
Interwoven, Inc. 88
workflow
The workflow element defines a job’s name and owner.
DTD Definition
In the job specification DTD, the workflow element is defined as:
<!ELEMENT workflow (description?, variables?,

(usertask|submittask|updatetask|externaltask|cgitask|endtask|grouptask|
dummytask|locktask|wftask)+)>
<!ATTLIST workflow
name ID #REQUIRED
creator CDATA #REQUIRED
description CDATA #IMPLIED >
Associated Subelements
The following subelements are associated with the workflow element:

description—see page 90.
variables—see page 90.
usertask—see page 98.
submittask—see page 109.
updatetask—see page 111.
externaltask—see page 104.
cgitask—see page 107.
endtask—see page 113.
grouptask—see page 101.
dummytask—see page 114.
locktask—see page 115.
wftask—see page 116.
Associated Attributes
The following attributes are associated with the workflow element:

name—specifies the name of the job. Job names are not unique identifiers. However,
each job that is instantiated is identified by a unique ID number.
owner—specifies the owner responsible for the job (defined in workflow template
file rules).

creator—specifies the user who started the job via the TeamSite GUI’s workflow
form.
description—provides a description of what the job does. Can be specified as both
an attribute and a subelement of the workflow element.
description
The description element specifies a description of what the job does. It can be
specified as both an attribute and a subelement of the workflow element.
DTD Definition
In the job specification DTD, the description element is defined as:
<!ELEMENT description (#PCDATA)>
variables
The variables element is a container for one or more variable elements.
The variables element defines a key-value pair that can be stored in and retrieved from
job instances. They are used to allow separate CGI tasks and external tasks to
communicate with each other during job execution. Workflow variables are manipulated
using the iwjobvariable CLT or by specifying them at job creation time.
DTD Definition
In the job specification DTD, the variables and variable elements are defined as:
<!ELEMENT variables (variable+)>

<!ELEMENT variable EMPTY>
<!ATTLIST variable
key CDATA #REQUIRED
The following attributes are associated with the variable element:

key—specifies the name of the variable. For example:
key="color"
value—specifies the value associated with the variable. For example:

value="blue"
Interwoven, Inc. 90
areavpath
The areavpath element specifies the TeamSite area associated with this task.
DTD Definition
In the job specification DTD, the areavpath element is defined as:

<!ELEMENT areavpath EMPTY>
<!ATTLIST areavpath
v CDATA #REQUIRED >
The v attribute is associated with the areavpath element. It specifies the path to the
TeamSite area associated with the task. For example:
v="/default/main/WORKAREA/johndoe"
timeout
The timeout element specifies an optional time limit for the completion of a task. When
time runs out the task is inactivated and the succ elements are signalled to become
active.
DTD Definition
In the job specification DTD, the timeout element is defined as:

<!ELEMENT timeout (succ)+>
<!ATTLIST timeout v CDATA #REQUIRED>
The succ subelement is associated with the timeout element. For details about this
subelement, see page 92.
The following attribute is associated with the timeout element:

v—specifies the time value for the timeout element is specified as the v attribute in
two possible formats:
+HHHHMM—which is the number of hours and minutes after the task becomes
activated that the timeout should occur. For example:
v="+150030"
You must use all six digits, including leading zeros if necessary, for example:

v="+005000"
MMDDYYYYHHMM, which is the month, day, year, hour, and minute at which the
timeout should occur. For example:
v="123120032359"
succ
The succ element specifies a named task, such as a submit task, that can be activated by
a task transition, such as a success, failure, or timeout.
DTD Definition
In the job specification DTD, the succ element is defined as:

<!ELEMENT succ EMPTY>
<!ATTLIST succ
v IDREF #REQUIRED>
The following attribute is associated with the succ element:

v—references a named task element. For example, if you wanted to reference a
submittask element named Deploy:
v="Deploy"
files and file

The files element is a container for one or more file elements.
The file element specifies the files that the actions of a task affect. The files can be
specified at configuration time (but only on start tasks) or dynamically (but only on
active tasks). It is expected that the user interface will allow users to modify and/or add
to the comment field.
DTD Definition
In the job specification DTD, the files and file elements are defined as:
<!ELEMENT files (file+)>
<!ELEMENT file EMPTY>
<!ATTLIST file
path CDATA #REQUIRED
comment CDATA #REQUIRED>
Interwoven, Inc. 92
The following attributes are associated with the file element:

path—specifies the path to a file relative to the TeamSite area specified in the
areavpath element. For example:
path="reports.txt"
If the areavpath element specified the TeamSite area as:

/default/main/WORKAREA/jdoe
then the full path to the file would be:

/default/main/WORKAREA/jdoe/reports.txt
comment—specifies a comment related to the file in this particular job. For example:
comment="This is a data report file."
activation
The activation element specifies the conditions under which a task will become
active. The body of the activation element specifies a logical expression. When a
finishing task signals a successor task, the successor task notes that the finishing task
has signaled and then evaluates the logical expression to determine if it should become
active.
DTD Definition
In the job specification DTD, the activation element is defined as:

<!ELEMENT activation (and|or|not|pred)>
<!ELEMENT and (and|or|not|pred)*>
<!ELEMENT or (and|or|not|pred)*>
<!ELEMENT not (and|or|not|pred)>
<!ELEMENT pred EMPTY>
<!ATTLIST pred
v IDREF #REQUIRED >
For example, given tasks A, B, C that can signal task D, the <activation> element for
D looks like this:
<activation>
<and>
<pred v="A"/>
<or>
<pred v="B"/>
<pred v="C"/>
</or>
</and>
</activation>

This means (in more conventional notation): A & (B | C). When A, B or C signals D, D
notes the fact that it has been signaled, and evaluates A & (B | C) where the values of A,
B and C are whether they have signalled D. In this example, D becomes active if and
only if A has signalled and B or C have signalled.
inactivate
The inactiviate element defines when a task becomes inactive. A task becomes
inactive at the time it signals its successors. However it is often necessary to inactivate
tasks other than those which have signalled a task when that task becomes active. For
example, suppose a user completes a task and routes it simultaneously to five users for
review. If one of those reviewers rejects the work, the task should be inactivated and
removed from the lists of the other four reviewers.
DTD Definition
In the job specification DTD, the inactivate element is defined as:

<!ELEMENT inactivate (pred+)>
For example, given tasks A and B that can signal it, task C has the following
<activation> and <inactivate> sections:
<activation>
<or>
<pred v="A"/>
<pred v="B"/>
</or>
</activation>
<inactivate>
<pred v="A"/>
<pred v="B"/>
</inactivate>
When C becomes active, by being signalled by either A or B, it inactivates both A and

B. Specification of the <inactivate> element is optional. If the <inactivate> element
is unspecified it is the same as specifying an <inactivate> element containing all
possible predecessor tasks.
resets
The resets element is a container for one or more reset elements.
The reset element defines when a task can be reset. A task can be configured to reset
the activation state of an arbitrary set of other tasks when it becomes active. Resetting
the activation state of a task simply means that such tasks are set to a state of no tasks
having activated them. This capability is useful in certain parallel task configurations.
Interwoven, Inc. 94
DTD Definition
In the job specification DTD, the resets element is defined as:

<!ELEMENT resets (reset+)>
<!ELEMENT reset EMPTY>
<!ATTLIST reset v IDREF #REQUIRED>
The following attribute is associated with the resets element:

v—references a named task element. For example, if you wanted to reference a
submittask element named Deploy:
v="Deploy"
eastartop
The eastartop element defines how TeamSite extended attributes can be set, modified,
or deleted on the files contained by the task when the task becomes active.
DTD Definition
In the job specification DTD, the eastartop element is defined as:

<!ELEMENT eastartop EMPTY>
<!ATTLIST eastartop
op (set|append|delete) #REQUIRED
The following attributes are associated with the eastartop element:

op—specifies one of the following options:
set—results in the name attribute set to the value attribute.
append—results in the value attribute being appended.
delete—results in the extended attribute with key name being deleted.
If the op attribute of either the eastartop or eafinishop elements is set, the
extended attribute with key name will be set to value. If op is append, value will be
appended. If op is delete, the extended attribute with key name will be deleted.
name—specifies the key value of the extended attribute.

value—contains the following macros of the form %name; that will be expanded
before being set as an extended attribute:
Macro Name Description

%workflow; Name of the job
%workflowid; ID of the job
%task; Name of the task
%taskid; ID of the task
%taskowner; Owner of the task
%time; The current wall clock time
%area; VPATH of the task's area
%path; Path of the file from area root
%fullpath; Full path of the file from server root
%taskcomment; Task-specific comment added to the extended attribute
%filecomment; File-specific comment added to the extended attribute
eafinishop
The eafinishop element defines how TeamSite extended attributes can be set,
modified, or deleted on the files contained by the task when the task becomes inactive.
DTD Definition
In the job specification DTD, the eafinishop element is defined as:

<!ELEMENT eafinishop EMPTY>
<!ATTLIST eafinishop
value CDATA #REQUIRED >
The following attributes are associated with the eafinishop element:

set—results in the name attribute set to the value attribute.
append—results in the value attribute being appended.
delete—results in the extended attribute with key name being deleted.
If the op attribute of either the eastartop or eafinishop elements is set, the
extended attribute with key name will be set to value. If op is append, value will be
appended. If op is delete, the extended attribute with key name will be deleted.
Interwoven, Inc. 96
name—specifies the key value of the extended attribute.

value—contains the following macros of the form %name; that will be expanded
before being set as an extended attribute:
Macro Name Description

%workflow; Name of the job
%workflowid; ID of the job
%task; Name of the task
%taskid; ID of the task
%taskowner; Owner of the task
%time; The current wall clock time
%area; VPATH of the task's area
%path; Path of the file from area root
%fullpath; Full path of the file from server root
%taskcomment; Task-specific comment added to the extended attribute
%filecomment; File-specific comment added to the extended attribute
wfvarstartop
The wfvarstartop element defines how workflow job variables can be set, modified, or
deleted on the job to which the task belongs when the task becomes active.
DTD Definition
In the job specification DTD, the wfvarstartop element is defined as:

<!ELEMENT wfvarstartop EMPTY>
<!ATTLIST wfvarstartop
The following attributes are associated with the wfvarstartop element:

set—results in the job variable represented by the name attribute being set to the
value of the value attribute.
append—results in the value attribute being appended to the current value of
the job variable.
delete—results in the job variable with key name being deleted.

name—specifies the key value of the job variable.

value—specifies the key value associated with the name attribute.
wfvarfinishop
The wfvarstartop element defines how workflow job variables can be set, modified, or
deleted on the job to which the task belongs when the task becomes in active.
DTD Definition
In the job specification DTD, the wfvarfinishop element is defined as:

<!ELEMENT wfvarfinishop EMPTY>
<!ATTLIST wfvarfinishop
The following attributes are associated with the wfvarfinishop element:

set—results in the job variable represented by the name attribute being set to the
value of the value attribute.
append—results in the value attribute being appended to the current value of
the job variable.
delete—results in the job variable with key name being deleted.
name—specifies the key value of the job variable.
value—specifies the key value associated with the name attribute.
usertask
A usertask element defines user tasks that appear on a user’s task list.
DTD Definition
In the job specification DTD, the usertask element is defined as:

<!ELEMENT usertask (description?, areavpath, successors, timeout?, files?,
activation?, inactivate?, resets?, eastartop*, eafinishop*,
wfvarstartop*, wfvarfinishop*, variables?)>
<!ATTLIST usertask
Interwoven, Inc. 98
name ID #REQUIRED
start (t|f) "f"
lock (t|f) "f"
readonly (t|f) "f" >
The following subelements are associated with the usertask element:

areavpath—see page 91.
successors—see page 100.
timeout—see page 91.
files—see page 92.
activation—see page 93.
inactivate—see page 94.
resets—see page 94.
eastartop—see page 95.
eafinishop—see page 96.
wfvarstartop—see page 97.
wfvarfinishop—see page 98.
The following attributes are associated with the usertask element:

owner—specifies the owner of the task.
name—specifies the name of the task. A task is uniquely identified within its job by
its name.
start—specifies whether the task should be active upon its containing job’s
invocation.
description—provides a description of what the task does.
lock—when the lock attribute is set to t the task will acquire TeamSite locks on all
the files it contains when it becomes active. If the task cannot acquire locks for one
or more of the files it contains it will release any locks it has already acquired and
try again every five minutes until it successfully acquires all locks. When a locking
task tries to acquire a lock for a file it checks first to see if that file is locked by some
other task in its own job. If it is, the locking task “steals” the lock from the other
task. This behavior can result in submit time conflicts. In general it is best to ensure

that no task will try to acquire locks that could already be owned by another active
task.
transferonly—when transferonly is set to t and lock is set to t, files that were
locked by a predecessor task will have the lock modified when a task becomes
active. The workflow engine only attempts to get locks on attached files if (1) files
are already locked by the job owner, or (2) files are locked by one of the predecessor
task owners.
readonly—specifies a task as “read only”, which prevents users from adding,
removing, or modifying files.
successors
The successors element is a container for one or more successorset elements.
The successorsset element specifies the possible alternative sets of successor tasks to
signal when the user task is finished. The GUI presents the user with a set of options for
finishing a task. The text of the description of the task is used to label the alternatives
for the user (for example, “Mark Done”, “Reject”, “Approve” and so on).
DTD Definition
In the job specification DTD, the successors and successorset elements are defined
as:
<!ELEMENT successors (successorset+) >
<!ELEMENT successorset (description?, succ+) >
<!ATTLIST successorset
The following subelements are associated with the succesorset element:

succ—see page 92.
The following attribute is associated with the succesorset element:

description—serves as the label for the transition when used with a usertask or
grouptask element. For example, if a usertask has successorsets with descriptions
of Deploy Now and Send to Author for Rewrite, then when the user finishes the
task these two options will be presented.
Interwoven, Inc. 100

grouptask
A grouptask element is similar to a user task in that it appears on a user’s task list. A
group task, however, belongs to an arbitrary group of users and therefore shows up in
the task list of every user who belongs to that arbitrary group. A group task becomes
identical in behavior to a user task when one user from the group takes ownership of the
task via the GUI or the CLT iwtaketask.
DTD Definition
In the job specification DTD, the grouptask element is defined as:

<!ELEMENT grouptask (description?, areavpath, successors, sharedby,
timeout?, files?, activation?, inactivate?, resets?, eastartop*,
eafinishop*, wfvarstartop*, wfvarfinishop*, variables?)>
<!ATTLIST grouptask
name ID #REQUIRED
start (t|f) "f"
lock (t|f) "f"
readonly (t|f) "f"
retainowner (t|f) "f" >
The following subelements are associated with the grouptask element:

sharedby—see page 102.

The following attributes are associated with the grouptask element:

its name.
invocation.
that no task will try to acquire locks that could already be owned by another active
task.
task owners.
retainowner—prevents the owner of a grouptask from being reset upon subsequent
activations, so subsequent entries into it from a looping process will maintain the
ownership of the task.
sharedby
The sharedby element specifies the arbitrary set of users who share this group task. The
element allows an arbitrary combination of individual TeamSite users and OS groups to
be shared owners of the group task.
DTD Definition
In the job specification DTD, the sharedby element is defined as:

<!ELEMENT sharedby (user|group)* >

The following subelements are associated with the grouptask element:

user—see page 103.
group—see page 103.
user
The user element defines each individual TeamSite user who will be a shared owner of
the group task.
DTD Definition
In the job specification DTD, the user element is defined as:

<!ELEMENT user EMPTY >
<!ATTLIST user
v CDATA #REQUIRED >
The following attribute is associated with the user element:

v—specifies the individual TeamSite user, for example:
v="jdoe"
group
The group element defines each operating system group that will be a shared owner of
the group task.
DTD Definition
In the job specification DTD, the group element is defined as:

<!ELEMENT group EMPTY >
<!ATTLIST group
v CDATA #REQUIRED >
The following attribute is associated with the group element:

v—specifies the operating system group, for example:
v="tech-pubs"

externaltask
The externaltask element defines an external task that runs external programs when it
becomes active.
DTD Definition
In the job specification DTD, the externaltask element is defined as:

<!ELEMENT externaltask (description?, areavpath, successors, command,
<!ATTLIST externaltask
name ID #REQUIRED
start (t|f) "f"
lock (t|f) f"
readonly (t|f) "f"
retry (t|f) "t" >
The following subelements are associated with the externaltask element:

command—see page 105.

The following attributes are associated with the externaltask element:

its name.
invocation.
that no task tries to acquire locks that could already be owned by another active
task.
task owners.
retry—specifies whether a failure to execute the externaltask command results in a
subsequent attempt. This attribute is tied in with the external_task_retry_wait
setting in the [workflow] section of the iw.cfg file. A retry only occurs in cases
where the server fails to spawn a process (a condition that usually indicates low
swap space.) The retry does not occur in cases where the command executes but
subsequently errors out.
On UNIX, when [iwserver] use_process_daemon=true (the default value) is set
in iw.cfg, a retry only occurs in cases where the workflow engine cannot connect to
the process daemon.
command
The command element defines a command to be run in conjunction with a task.
Use with externaltask
When used with, or in, an externaltask element, the command element specifies the
full path of the program to be run on activation, followed by any desired initial

command line arguments. When the program is run by the workflow system, the
following arguments are passed in after any of the previously mentioned desired
command line arguments:
job id (integer)
task id (integer)
area vpath (string)
file0 (string)
...
fileN (string)
In the [workflow] section of the iw.cfg file, if external_task_add_filelist=false,

then the list of task files will not be added to the argument list. The default value is true
for backwards compatibility. However, it is recommended that you change it to false.
Setting it to false is generally preferred because developers can use the
TeamSite::WFtask method GetFiles() to retrieve the list of files associated with the
task, rather than pulling them from the command line arguments.
This also makes it easier to debug scripts under development, because you do not have
to put all that information on the command line yourself. It is also recommended that
you use the GetArea() method for retrieving the areavpath associated with the task,
rather than pulling that off the command line as well. This way you can debug a
program by running it as:
myperlscript.ipl jobid taskid
On UNIX, the program will be run as the owner of the task. On Windows, the program
will be run as the SYSTEM user, and usually includes the command engine:
C:/iw-home/iw-perl/bin/iwperl c:/..../myscript.ipl
Use with cgitask
When used with the cgitask element, the command is the name of a CGI script to run
relative to iw-home/httpd/iw-bin/.
DTD Definition
In the job specification DTD, the command element is defined as:

<!ELEMENT command EMPTY>
<!ATTLIST command
v CDATA #REQUIRED>
The following attribute is associated with the command element:

v—specifiesthe path to the program to be run. When used with the externaltask
command, a full path is specified, for example:

v="/iw-home/local/bin/ascript.ipl -f mumble" or
v="C:/iw-home/iw-perl/bin/iwperl C:/iw-home/local/bin/bscript.ipl"
When used with the cgitask element, a path relative to iw-home/httpd/iw-bin/ is

specified. For example, if you wanted to run the following command:
/usr/iw-home/httpd/iw-bin/show_env.cgi
you would specify the following value for the v attribute:

v="show_env.cgi"
When an external program finishes, it must run the iwcallback program, passing the
job and task IDs and a return code as arguments, to tell the server that it is finished. The
server does not wait for an external task to finish. The server uses the return code passed
to iwcallback to choose the set of successors to signal. If the return code is out of the
range 0..n-1 (where n is the number of successorset elements), an error is returned.
cgitask
The cgitask element defines a CGI task. A CGI task behaves much like an external
task. The only difference is that a CGI task does not run its command element (it relies on
the user interface for that). A CGI task expects to have iwcallback called to notify it of
program completion.
A cgi task script can run automatically upon the cgi task becoming activated under the
following situations:
The cgitask element’s immediate attribute’s value is specified as t and one of the
following:
The start attribute has a value of t and owner attribute for the task is the same
as the owner attribute for the workflow or
The cgi task follows a user or group task owned by the same user, or
The cgi task follows another cgitask, both owned by the same user, and the first
cgitask script used the TeamSite::CGI_lite::iwcallback() method to initiate
a callback to the workflow engine.
In all other circumstances, the owner of the cgi task will have to initiate the running of
the script manually by selecting “Start” in ContentCenter.
DTD Definition
In the job specification DTD, the cgitask element is defined as:

<!ELEMENT cgitask (description?, areavpath, successors, command, timeout?,
files?, activation?, inactivate?, resets?, eastartop*, eafinishop*,
<!ATTLIST cgitask
name ID #REQUIRED
start (t|f) "f"


lock (t|f) "f"
immediate (t|f) "f"
readonly (t|f) "f" >
The following subelements are associated with the cgitask element:

command—page 105.
variables—see page 90
The following attributes are associated with the cgitask element:

its name.
invocation.
lock—when the lock attribute is set to t, the task acquires TeamSite locks on all the
files it contains when it becomes active. If the task cannot acquire locks for one or
more of the files it contains, it releases any locks it has already acquired and try
again every five minutes until it successfully acquires all locks. When a locking
task tries to acquire a lock for a file, it checks first to see if that file is locked by
some other task in its own job. If it is, the locking task “steals” the lock from the
other task. This behavior can result in submit time conflicts. In general it is best to

ensure that no task tries to acquire locks that could already be owned by another
active task.
task owners.
immediate—specifies whether a cgi task script can run automatically upon the cgi
task becoming activated under the situations listed in the description of the cgitask
element. See page 107 for more information on the useage of the immediate
attribute.
submittask
The submittask element defines a task that performs a submit operation on its
contained files.
DTD Definition
In the job specification DTD, the submittask element is defined as:

<!ELEMENT submittask (description?, areavpath, successorset | (success,
failure?), timeout?, files?, activation?, inactivate?, resets?,
eastartop*, eafinishop*, wfvarstartop*, wfvarfinishop*, variables?)>
<!ATTLIST submittask
name ID #REQUIRED
start (t|f) "f"
skipconflicts (t|f) "f"
skiplocked (t|f) "f"
override (t|f) "f"
unlock (t|f) "f"
savecomments (t|f) "f"
If the submit task succeeds, the successor tasks specified in the <successorset>
element are signaled. If the submit task fails, the submit task goes into a special state
that the user interface can detect. When the user interface has resolved any conflicts, it
retries the operation so that the job can continue.
If you use success and failure instead of successorset, then if the submit task
succeeds, it follows the success successor tasks. If it fails for any reason, it
immediately follows the failure successor tasks, if they are defined, otherwise the task
goes into the special state described in the previous paragraph.

For the purposes of workflow, a submit task is considered successful even if some of its
contained files were not submitted because of being up to date with the staging area.
The following subelements are associated with the submittask element:

successorset—see page 100.
success—see page 118.
failure—see page 119.
The following attributes are associated with the submittask element:

its name.
invocation.
skipconflicts—does not submit conflicting files.
skiplocked—does not submit locked files.
override—overwrites the staging area version of conflicting files.
unlock—causes files to be unlocked after the submit operation.
savecomments—specifies whether to allow comments that were directly associated
with the files during the course of the workflow to remain associated with those
files, in the workflow context, even after the files have been submitted. This is

useful if you are going to try to extract those comments for something like email
notification after the submit task.
The submit task will always add the comment “Submitted.” to each of the files
associated with the task.
If savecomments is true (="t"), any pre-existing comments associated with the
files remain accessible within the workflow after the submit operation, the last
comment [chronologically] will be “Submitted.”
If savecomments is false (="f") (default), all pre-existing comments associated
with the files are discarded after the submit operation, and the only comment
left for each file is “Submitted.”
updatetask
The updatetask element defines a task that does the equivalent of Get Latest (if the
source is the staging area) or Copy To (if the source is another workarea or edition) on
its contained files.
DTD Definition
In the job specification DTD, the updatetask element is defined as:

<!ELEMENT updatetask (description?, areavpath, successorset | (success,
failure?), srcareavpath, timeout?, files?, activation?, inactivate?,
resets?, eastartop*, eafinishop*, wfvarstartop*, wfvarfinishop*,
variables?) >
<!ATTLIST updatetask
name ID #REQUIRED
start (t|f) "f"
delete (t|f) "t"
overwritemod (t|f) "f"
lock (t|f) "f" >
If the update task fails because of conflicts, it goes into a state similar to that of a failed
submit task. If failure was not specified, then the user, through the user interface, is
responsible for resolving conflicts and retrying the update task.
The following command sub elements are associated with the updatetask element:

successorset—see page 100.

scrareapath—see page 113.
The following attributes are associated with the updatetask element:

its name.
invocation.
delete—propagates deleted files to the destination area.
overwritemod—overwrites conflicting versions of files in the destination area.
or more of the files it contains, it releases any locks it has already acquired and tries
again every five minutes until it successfully acquires all locks. When a locking
task tries to acquire a lock for a file, it checks first to see if that file is locked by
some other task in its own job. If it is, the locking task “steals” the lock from the
other task. This behavior can result in submit time conflicts. In general it is best to
ensure that no task tries to acquire locks that could already be owned by another
active task.


task owners.
srcareapath
The srcareapath element specifies the area from which files are copied.
DTD Definition
In the job specification DTD, the srcareapath element is defined as:

<!ELEMENT srcareavpath EMPTY>
<!ATTLIST srcareavpath v CDATA #REQUIRED>
The v attribute is associated with the srcareapath element. It specifies the TeamSite
path from which the files are copied. For example:
v="/default/main/WORKAREA/jdoe"
endtask
The endtask element defines an end task. An end task is a marker for the end of a job.
When an end task becomes active, its associated job is terminated and all locks held in
the job are released.
DTD Definition
In the job specification DTD, the endtask element is defined as:

<!ELEMENT endtask (activation?, eastartop*, eafinishop*, wfvarstartop*,
wfvarfinishop*)>
<!ATTLIST endtask
name ID #REQUIRED
The following subelement is associated with the endtask element:



The following attributes are associated with the endtask element:

its name.
dummytask
The dummytask element defines a task that waits for its mandatory timeout to expire. If
+000000 is specified as a timeout value, the dummytask element becomes a spacer task.
Dummy tasks let a workflow designer create a time interval unrelated to any actual job
activity. A dummy task does not have an owner or areavpath.
DTD Definition
In the job specification DTD, the dummytask element is defined as:

<!ELEMENT dummytask (description?, timeout, activation?, inactivate?,
resets?, eastartop*, eafinishop*, wfvarstartop*, wfvarfinishop*,
variables?)>
<!ATTLIST dummytask
name ID #REQUIRED
start (t|f) "f"
The following subelements are associated with the dummytask element:



The following attributes are associated with the dummytask element:

its name.
invocation.
locktask
A locktask element is a task that attempts to acquire locks on the files it owns. If it
succeeds, it transitions to the successors specified in its success element. If it fails, it
transitions to the successors specified in its failure element. This provides users with a
way of backing out of a job or choosing an alternate path in a job that cannot acquire its
locks.
DTD Definition
In the job specification DTD, the locktask element is defined as:

<!ELEMENT locktask (description?, areavpath, success, failure, files?,
activation?, inactivate?, resets?, eastartop*, eafinishop*,
<!ATTLIST locktask
name ID #REQUIRED
start (t|f) "f"
The following subelements are associated with the locktask element:



The following attributes are associated with the locktask element:

its name.
invocation.
wftask
The wftask element defines a nested workflow job, one that is contained within other
jobs or tasks. The nesting process creates a parent-child relationship with the task as the
parent and the job as the child.
Workflow tasks can be defined within the wftask element either with a path to a job
specification file or to a workflow template file. In the case of a job specification file,
upon activation of the workflow task, TeamSite compiles and instantiates a new job
using the specification file. In the case of a workflow template file, the task owner must
manually start the task to input job variables and subsequently initiate the job.
DTD Definition
In the job specification DTD, the wftask element is defined as:

<!ELEMENT wftask (description?, areavpath, successors, (jobfile|wftfile),
<!ATTLIST wftask
name ID #REQUIRED
start (t|f) "f"

The following subelements are associated with the wftask element:

jobfile—see page 117.
wftfile—see page 118.
The following attributes are associated with the wftask element:

its name.
invocation.
jobfile
The jobfile element specifies the path to a job specification file.
DTD Definition
In the job specification DTD, the jobfile element is defined as:

<!ELEMENT jobfile EMPTY>
<!ATTLIST jobfile v CDATA #REQUIRED>

The v attribute is associated with the jobfile element. It specifies the full path to the
job specification file. For example:
v="__IW_HOME__/local/jobs/nestedwftask_B.xml"
wftfile
The wftfile element specifies the path to a workflow template (.wft) file to be used for
the nested job.
DTD Definition
In the job specification DTD, the wftfile element is defined as:

<!ELEMENT wftfile EMPTY>
<!ATTLIST wftfile v CDATA #REQUIRED
background (t|f) "f">
The v attribute is associated with the wftfile element. It specifies the full path to the
workflow template file. For example:
v="__IW_HOME__/local/config/wft/devnet/nestedwftask_B.wft"
The background attribute is associated with the wftfile element. If set to t, TeamSite
will attempt to start the nested job using the wftfile, assuming that all necessary
arguments will be provided in task variables. If background job creation then fails, the
TeamSite GUI will present the user the option to start this job (and provide the
necessary arguments). Default is f (false); to require user intervention before starting
the nested job.
success
The success element defines the successor tasks that become active when the lock,
submit, or update task succeeds.
DTD Definition
In the job specification DTD, the success element is defined as:

<!ELEMENT success (succ+)>

The following subelement is associated with the success element:

succ—see page 92.
failure
The failure element defines the successor tasks that become active when the lock,
submit, or update task fails.
DTD Definition
In the job specification DTD, the failure element is defined as:

<!ELEMENT failure (succ+)>
<!ATTLIST failure firsttimeonly (t|f) "f">
The succ subelement is associated with the failure element. For information, see
page 92.
The firsttimeonly attribute is associated with the failure element and applies to only
submit and update tasks. If failure successor tasks are not defined, then this attribute
has no effect. If failure successor tasks are defined and firsttimeonly is t (true), then
the failure successor tasks will be activated only when the submit or update task first
fails. Any subsequent failures, when the submit or update task is reactivated by the
workflow system, will then cause the submit or update task to await user intervention. If
failure successor tasks are defined and firsttimeonly is f (false), then the failure
successor tasks will always be activated. Default is f (false).
NOTE
The scenario where failure successor tasks are defined, firsttimeonly is f (false),
and failure successor tasks are always activated, can result in infinite loops if the
defined failure successor tasks are not robust. For example, if the failure successor
tasks include only an email notification task, followed by retrying the submit or update
task, an infinite loop of email notifications will occur if the submit or update task
continues to fail.

Perl Modules
These Perl modules are provided as reference for workflow template developers. Refer
to the Perl modules for the latest documentation, or see iw-home/iw-perl/bin/perldoc
module.
TeamSite::WFsystem
The following sections describe the TeamSite::WFsystem module.
Synopsis
Utilities for accessing the TeamSite workflow engine. This provides access to functions
for querying the entire workflow system.
use TeamSite::WFsystem;
$system = new TeamSite::WFsystem();
Functions
new() Creates a new WFsystem object. This only works on the

local TeamSite server.
GetWorkflows() Returns an array of WFworkflow objects corresponding to

all jobs in the system.
GetActiveWorkflo Returns an array of WFworkflow objects corresponding to
ws() all active jobs in the system.
GetTasks() Returns an array of WFworkflow objects corresponding to
all tasks in the system.
GetActiveTasks() Returns an array of WFtask objects corresponding to all
active tasks in the system.
CreateWorkflow($ Creates a workflow instance from $spec (a workflow
spec) , specification in the form of a string). Returns a
CreateWorkflow($ TeamSite::WFworkflow. If the $tmpfile arg is set,
spec,$tmpfile) tmpfile is used instead of stdin. Using this option in
the context of HTTP may result in timing security
issues.
Refresh() Call after changes have been made.
Examples
$system = new TeamSite::WFsystem();
$wfs = $system->GetWorkflows();
$wfs = $system->GetActiveWorkflows();
$wfs is a reference to an array containing references to TeamSite::WFworkflow objects.

$tasks = $system->GetTasks();
$tasks = $system->GetActiveTasks();

$tasks is a reference to an array containing TeamSite::WFtask references.

my $wf_system = TeamSite::WFsystem->new();
my $wf = $wf_system->CreateWorkflow($spec);
if ((!defined $wf) || !$wf->IsValid() || $wf->GetError())
{
... handle error...
}
TeamSite::WFworkflow
The following sections describe the TeamSite::WFworkflow module.
Synopsis
Utilities for using the TeamSite workflow engine. This supplies functions for
manipulating and querying workflows.
$workflow = new TeamSite::WFworkflow($id)

Functions
new($id) Creates a new WFworkflow object.

GetId() Fetches the workflow ID.
GetError() Fetches the last error message (if any).
SetError($error_ the error message to $error_string and returns the previous error
string) message (if any).
IsValid() Determines whether this a valid workflow object.
GetTasks() Gets the tasks owned by this workflow.
GetOwner() Returns owner of workflow.
GetCreator() Returns the creator of this workflow.
GetName() Returns the name of the workflow.
($success, TaskName should be specified in UTF-8 encoding. Returns task in the
$task)=GetTaskBy workflow with name $taskname. $task is a possibly invalid
Name($taskname) TeamSite::WFtask object. $success is 1 if successful.
GetDescription() Returns the description for this workflow.
GetParentTask() Returns a TeamSite::WFtask object or undef if this is not a nested
job.
Invoke() Starts this workflow running. Returns a TeamSite::WFtask object. If
the returned object is valid, then a CGI task that wishes to be run.
GetVariables() Get the value of a workflow variable. Returns undef if variable does
not exist.
GetVariable($nam Gets the value of a workflow variable.
e)
SetVariable($nam Sets the value for a workflow variable.Returns exit status of
e, $value) underlying CLT (non-zero indicates an error occurred).
CreateVariable($ Creates a workflow variable. If the variable already exists, this
name, $value) fails.
DeleteVariable($ Deletes a workflow variable.
name)
setDescription($ Value should be specified in UTF-8 encoding. Changes the description
value) of a job. Returns exit status of underlying CLT (non-zero indicates
an error occured).
SetOwner($user) Changes the owner of a job. Returns exit status of underlying CLT
(non-zero indicates an error occured).
Refresh() Call when workflow object has been modified.
Examples
$workflow = new TeamSite::WFworkflow($id);
$tasks = $workflow->GetTasks();
$tasks is a reference to a list containing TeamSite::WFtask objects.
TeamSite::WFtask
The following sections describe the TeamSite::WFtask module.

Synopsis
Utilities for using the TeamSite workflow engine. This supplies functions for
manipulating and querying tasks.
Functions
new($id) Creates a new WFtask object. For example,$task = new

TeamSite::WFtask($id);
GetId() Returns the task ID.
GetType() Returns the task type.
GetOwner() Gets the owner of this task.
GetName() Returns the name of this task.
GetState() Returns the state of this task.
IsTryingToLock() Returns 't' or 'f' indicating whether the task is trying to lock files.
NeedsAttention() Returns 't' or 'f' indicating whether the task needs attention (this is not
set for active cgitasks).
GetSharedBy(\@user, Returns the users and groups that share this task as lists of strings. For
\@groups) example:my @users;
my @groups;
$task->GetSharedBy(\@users, \@groups);
print "Users: ", join(", ", @users), "\n";
print "Groups: ", join(", ", @groups), "\n";
GetTimeout() Returns a string containing the timeout, possibly undef.
GetActivationTime() Returns the activation time of this task in seconds since the epoch (for
example, UNIX time), or undef if the task has not been activated.
GetUnactivationTime() Returns the unactivation time of this task in seconds since the epoch (for
example, UNIX time), or undef if the task has not been unactivated.
GetDuration($dec, Returns a string containing the task duration formatted according to the
$delta_format) rules of Date::Manip::DeltaFormat. It will be undef has not been
activated. If the task is active, the duration is up until now.
If $delta_format is undef, the result will be in seconds instead of a
formatted string.
It is possible for the duration to be negative if the task was activated and
inactivated previously, and then was reactivated and is still active. Thus
the current activation is after the last inactivation.
GetDescription() Returns the description for this task.
GetCommand() Gets the command string for an cgitask.
Refresh() Call when the server side object has been changed.
GetWorkflowId() Returns the ID of the job that owns this task.
AddFile($path, Adds a file with comment to a task.
$comment)

AddMultipleFiles(\@path Adds one or more files with the same comment to a task. Path and
s, $comment) comment should be specified in UTF-8 encoding.
Note that first argument is a reference to an array of file paths. Paths
should be specified with respect to root of task areavpath (no leading
slash). Returns zero on error, non-zero if successful.
RemoveFile($path, Path and comment should be specified in UTF-8 encoding. Removes a
$comment) file from a task's file list (does not delete the file itself). Returns zero on
error, non-zero if successful.
SetDescription($value) Value should be specified in UTF-8 encoding. Change the description of
a task Returns 0 on success, non-zero if error occurred.
SetComment($comment) Sets comment on task.
SetOwner)$user) Only support User name in ASCII encoding is supported. Modifies the
owner of a task. Returns zero on error; non-zero on success.
SetArea($area) Area should be specified in UTF-8 encoding. Modifies the areavpath of a
task. Returns zero on error; non-zero on success.
SetTimeout($timeout) Modifies the timeout period for a task. Only valid if task already contains
a timeout successor. Returns zero on error; non-zero on success.
SetAttribute($name, Name and value should be specified in UTF-8 encoding. Set value of a
$value) task attribute. Returns exit status of underlying CLT (non-zero indicates
an error occurred).
AddUser($user) Adds a shared user to a grouptask. Returns zero on error; non-zero on
success.
RemoveUser($user) Removes a shared user from a grouptask. Returns zero on error; non-zero
on success.
AddGroup($group) Adds a shared group to a grouptask. Returns zero on error; non-zero on
success.
RemoveGroup($group) Removes a shared group from a grouptask. Returns zero on error;
non-zero on success.
TakeTask($user) Assigns a shared task to a specified user. Returns zero on error; non-zero
on success.
UntakeTask($user) Removes the current ownership of a shared grouptask. Returns zero on
error; non-zero on success.
($success, SelectTransition($which, $comment)
$immediatetask) =
Comment should be specified in UTF-8 encoding. Selects a transition for
this task. $success is a boolean and $immediatetask is a possibly
invalid TeamSite::WFtask to run.
($success, CallBack($retcode, $comment)
$immediatetask) =
Comment should be specified in UTF-8 encoding. Callback from a CGI
task or external task. $immediatetask is a possibly invalid
TeamSite::WFtask to run.
IsValid() Returns true if this is a valid task.
GetSubmitEvents() Returns a (possibly empty) array of SubmitEvent objids (as strings). It
returns an array because there may have been conflicts or other problems
which could produce multiple events.
GetUpdateEvents() Returns a (possibly empty) array of UpdateEvent objids (as strings). It
returns an array because there may have been conflicts or other problems
that could produce multiple events.

GetFiles() Returns a (possibly empty) array of file names.

GetFilesAndComments(\%f Returns a (possibly empty) hash ref with file names as the keys and
_and_c) values are refs to an array of hash refs (see GetFileComments).
GetArea() Gets the area for the task, such as /default/main/dev/WORKAREA/andre
GetWftFile() Returns a string contain the wftfile, possibly undef.
GetJobFile() Returns a string contain the jobfile, possibly undef.
GetNestedJobs() Returns an array containing the job IDs of jobs nested in this task
(possibly empty) or undef if this is not a wftask.
GetComments(\@list) Gets the comments for the task. The result is an array of hash refs, where
each hash has keys of 'date', 'task', 'user', and 'body'.
GetFileComments(\@list, Gets the file comments for the task. The result is an array of hash refs,
$felement) where each hash has keys of 'date', 'task', 'user', and 'body'.
GetError() Retrieves the last error message (if any).
SetError($error_string) Sets the error message to $error_string and returns the previous error
message (if any).
GetVariables() Returns a reference to a hash containing key/value pairs corresponding to
the variables of the task. Returns undef if no variables exist.
GetVariable($name) Get the value of a task variable. Returns undef if variable does not exist.
SetVariable($name, Name and value should be specified in UTF-8 encoding. Set value of a
$value) task variables. Returns exit status of underlying CLT (non-zero indicates
an error occurred).
CreateVariable($name, Name and value should be specified in UTF-8 encoding. Create a task
$value) variable. If the variable already exists this will fail. Returns exit status of
underlying CLT (non-zero indicates an error occurred).
DeleteVariable($name) Name should be specified in UTF-8 encoding. Delete a task variable.
Returns exit status of underlying CLT (non-zero indicates an error
occurred).
Sample Job Specification File

The following job specification file could be created by direct editing (see “Running
Manually Created Jobs” on page 129) or by configuring a workflow template file to
generate it based on data provided by an end-user. This file defines a workflow for this
sequence of events:
1. A worker named Mark generates a set of documentation about a new product called
B4000.
2. A worker named Bill then receives this documentation and prepares it for the web.
3. Bill’s manager and the legal department review Bill’s and Mark’s efforts.
4. Material is submitted and deployed on the live web server.



<workflow name="B4000" owner="BillsManager"

description="Standard workflow for new product information.">
<usertask name="MarkWork" owner="Mark"
description="Write copy for B4000" start="t">
<areavpath v="/default/main/WORKAREA/Mark"/>
<successors>
<successorset description="Done">
<succ v="MarkToBill"/>
</successorset>
</successors>
<activation>
<or>
<pred v="BillToMark"/>
<pred v="ReviewToMark"/>
</or>
</activation>
</usertask>
<updatetask name="MarkToBill" owner="Bill"

description="Update Bill's Workarea">
<areavpath v="/default/main/WORKAREA/Bill"/>
<successorset>
<succ v="BillWork"/>
</successorset>
<srcareavpath v="/default/main/WORKAREA/Mark"/>
<activation>
<pred v="MarkWork"/>
</activation>
</updatetask>
<usertask name="BillWork" owner="Bill"

description="Webify this doc.">
<successors>
<successorset description="Done">
<succ v="BillToReview"/>
</successorset>
<successorset description="Send back to Mark">
<succ v="BillToMark"/>
</successorset>
</successors>
<activation>
<or>
<pred v="MarkToBill"/>
<pred v="ReviewToBill"/>
</or>
</activation>

</usertask>
<updatetask name="BillToReview" owner="Manager"

description="Update the Review area from Bill's Workarea.">
<areavpath v="/default/main/WORKAREA/Review"/>
<successorset>
<succ v="LegalReview"/>
<succ v="ManagerReview"/>
</successorset>
<srcareavpath v="/default/main/WORKAREA/Bill"/>
<activation>
<pred v="BillWork"/>
</activation>
</updatetask>
<usertask name="LegalReview" owner="Legal"

description="Limit exposure." readonly="t">
<successors>
<successorset description="Okay">
<succ v="Submit"/>
</successorset>
<successorset description="Legal problem">
<succ v="ReviewToMark"/>
</successorset>
</successors>
<activation>
<pred v="BillToReview"/>
</activation>
</usertask>
<usertask name="ManagerReview" owner="Manager"

description="Final Approval" readonly="t">
<successors>
<successorset description="Okay">
<succ v="Submit"/>
</successorset>
<successorset description="Send back to Mark">
</successorset>
<successorset description="Send back to Bill">
</successorset>
</successors>
<activation>
<pred v="BillToReview"/>
</activation>
</usertask>

<submittask name="Submit" owner="Manager"

description="Final submission.">
<successorset>
<succ v="Deploy"/>
</successorset>
<activation>
<and>
<pred v="LegalReview"/>
<pred v="ManagerReview"/>
</and>
</activation>
</submittask>
<externaltask name="Deploy" owner="Manager"

description="Deploy to live server.">
<areavpath v="/default/main/STAGING"/>
<successors>
<successorset description="Successful Deployment">
<succ v="End"/>
</successorset>
<successorset description="Deployment failed">
<succ v="End"/>
</successorset>
</successors>
<command v="/scriptorium/do_deploy.pl"/>
<activation>
<pred v="Submit"/>
</activation>
</externaltask>
<endtask name="End">
<activation>
<pred v="Deploy"/>
</activation>
</endtask>

<updatetask name="ReviewToBill" owner="Bill"

description="Update Bill's workarea form the Review workarea.">
<successorset>
<succ v="BillWork"/>
</successorset>
<srcareavpath v="/default/main/WORKAREA/Review"/>
<activation>
</activation>
</updatetask>

<updatetask name="BillToMark" owner="Mark"

description="Update Mark's workarea from Bill's">
<successorset>
<succ v="MarkWork"/>
</successorset>
<srcareavpath v="/default/main/WORKAREA/Bill"/>
<activation>
<pred v="BillWork"/>
</activation>
</updatetask>
<updatetask name="ReviewToMark" owner="Mark"

description="Update Mark's workarea from Review">
<successorset>
<succ v="MarkWork"/>
</successorset>
<srcareavpath v="/default/main/WORKAREA/Review"/>
<activation>
<or>
<pred v="LegalReview"/>
</or>
</activation>
</updatetask>
</workflow>
Running Manually Created Jobs

After creating a job specification file to define a workflow model, run the job by
completing the following procedure:
1. Change to the directory that corresponds with your platform:
(UNIX)—iw-home/bin
(Windows)—C:\Program Files\Interwoven\TeamSite\bin
2. Execute iwjobc from the command-line to create an instance of the job on your
TeamSite server.
3. Execute the iwinvokejob utility.
NOTE
While a job specification file can only define a single workflow model, it is possible to
instantiate multiple, identical, concurrent jobs by instantiating and executing the same
job specification file more than once using iwjobc and iwinvokejob. Upon invocation,

the job runs until one of its end tasks is activated. Once a job ends, its instance is
removed, and you must re-instantiate it to run it again.
Other command-line utilities enable you to destroy jobs, view the state of any object in
the workflow system, add files to a particular task within the job, and otherwise interact
with running jobs. See TeamSite Command-Line Tools for details about the following
workflow utilities:
iwaddtaskfile
iwcallback
iwgetwfobj
iwinvokejob
iwjobc
iwqueryjobs
iwquerytasks
iwretrywfop
iwrmjob
iwrmtaskfile
iwtaketask
iwtaskselect
iwundochoice
While the workflow subsystem can be configured to create and save a job specification
file for any job, the normal scenario is for the job to be instantiated without the job
specification being saved in a file. Saving the job specification in a file is a step that is
usually taken only when you need to view the file for debugging.

Chapter 6
Using VisualAnnotate
VisualAnnotate is a review tool that enables reviewers to annotate HTML pages using
tools installed on their web browsers. Reviewers can draw, edit text, and add comments
on “sticky notes” directly on the pages they are viewing. These annotations are saved
and returned by workflow as instructions or comments to the content’s author. The
annotations are stored separately from the file as extended attributes.
The VisualAnnotate server functionality is installed by the TeamSite installation

program and is incorporated into the following configurable solutions workflows:
NOTE
Because VisualAnnotate is currently not supported on non-English servers, remove
VisualAnnotate functionality from these workflows if you are using a non-English
TeamSite server.
Users are prompted to install the VisualAnnotate client toolbar after clicking on a
Review link for a file associated with a VisualAnnotate-enabled workflows (either in an
workflow generated email or in Task Details from within a TeamSite GUI).
The installation of VisualAnnotate server is part of the TeamSite installation; refer to the
TeamSite Installation Guide for your server platform. For detailed information about
installing the VisualAnnotate client toolbar in your supported browser, refer to
“Installing the VisualAnnotate Client Toolbar” on page 134.
Task Checklist for Using VisualAnnotate

The following list provides an overview of the tasks that you must perform to configure,
and use VisualAnnotate successfully.
Activate VisualAnnotate in configurable solutions workflows (recommended) or
integrate it into custom serial-review workflow templates. See “Configuring
VisualAnnotate” on page 135.
Ensure that your VisualAnnotate-enabled workflow templates are available to
TeamSite users. See “Configuring VisualAnnotate” on page 135.

Chapter 6: Using VisualAnnotate
Teach users how to install and use the VisualAnnotate toolbar on their client
systems. See the VisualAnnotate tutorial and online help.
Familiarize yourself with the information about solutions workflows in Chapter 3,
“Using Solution Workflows”.
VisualAnnotate Overview
VisualAnnotate is used in the context of TeamSite workflow. That is, VisualAnnotate
tools are activated when users view HTML files in a browser that are part of tasks
associated with a VisualAnnotate-enabled workflow job.
Users access files attached to tasks through one of the following interfaces:
VisualAnnotate email.
The Tasks Details view in a ContentCenter GUI.
After opening these files in a browser, users annotate them with tools located in their
browser’s VisualAnnotate toolbar. Although users can view files in the context of the
entire site, they cannot annotate files that are not included in a VisualAnnotate workflow
task.
Sample Scenario
Typically, VisualAnnotate is used in an approval process initiated when
content-contributors submit modified content from a workarea to a staging area.
Consider the following use case, which assumes the following prerequisites:
A workflow job with VisualAnnotate enabled is available to TeamSite users.
Users have email and browser clients that support VisualAnnotate.
Pat, a content contributor, edits some files in her workarea and submits them to a staging
area using ContentCenter. In the TeamSite environment where Pat works, she is given a
selection of workflow templates on which to base the new submit job. In this case, Pat
chooses to initiate a job that enables the reviewers she selects, Chris and Andre, to use
VisualAnnotate in series.
After Pat creates the job, the system creates a task for Chris (the first reviewer) in his
Task list. If the system is configured to send VisualAnnotate email, Chris also receives
an email message notifying him of the review task. In addition to Review and Annotate
links for each file, VisualAnnotate email includes links that enable reviewers to approve
or reject files, as a set or individually, without annotating them.
Because the TeamSite environment where he works is configured to send

VisualAnnotate email, Chris initiates his review directly from the email by clicking the
Review and Annotate link to one of the documents.

The document opens in a browser window. In this case Chris already has a current
version of the VisualAnnotate toolbar installed in his browser; if he did not, a message
would be displayed prompting him to install the toolbar. Chris proceeds to mark up the
content using VisualAnnotate tools. As he reviews the file, he can view it in the context
of the entire site (but cannot annotate pages that are not included as part of his current
task).
When he is done, Chris stamps the file Please Revise and saves his work. The system
stores a snapshot of the way the document is displayed at the time Chris stamped it.
Snapshots make it possible to view the comments of different reviewers separately and
also provide an audit trail of the content’s development. After Chris reviews all the files
in the task and stamps them, the job transitions to the next task: a review task for Andre.
Andre initiates his review through the My Tasks module of the ContentCenter interface.
He starts his task and clicks on the file to open it. With the file displayed in a browser
window, Andre can use the Reviews menu on the VisualAnnotate toolbar to do the
following:
Select the unannotated file (as submitted by Pat) from which he can create his own
snapshot.
Select Chris’s snapshot where he can read Chris’s comments and add his own
annotations to it.
Andre is satisfied with Pat’s work and has nothing to add to Chris’ remarks. He stamps
all of the files Approved and transitions the job to the next task.
The system creates an author-work task for Pat and notifies her by email. Pat views the
files she is asked to revise, edits them according to instructions indicated by Chris’
annotations, then marks them Done moving the job to the next task and starting a new
review cycle.
Chris and Andre approve the revisions. The submission of the files to the staging area is
now complete.

Installing the VisualAnnotate Client Toolbar

TeamSite prompts users to install the VisualAnnotate client toolbar when they attempt
to review a file associated with a VisualAnnotate-enabled workflows. The following
scenario describes the process leading up to the VisualAnnotate client toolbar
installation:
1. After you log in to ContentCenter, you can display your assigned tasks (Figure 14).
Figure 14 Task List
In this example, both of the assigned tasks are part of VisualAnnotate-enabled

workflow jobs (specifically, the configurable_author_submit workflow).
2. Click one of the task numbers.
The Task Details (Figure 15) display for the selected task.
Figure 15 Task Details
3. Click File > Review link.

If the VisualAnnotate client toolbar is not installed, the following screen is
displayed (Figure 16):

Figure 16 VisualAnnotate Toolbar installation screen
4. Close all other browser windows—only one browser window can be open during
the installation.
5. Click Install.
Configuring VisualAnnotate
VisualAnnotate is used in the context of serial-review workflow. The VisualAnnotate
settings you specify in a workflow configuration file or a workflow template affect the
behavior of the system and the appearance of the VisualAnnotate toolbar on client
browsers.
VisualAnnotate is incorporated into the following configurable solutions workflows:

NOTE
VisualAnnotate cannot be used with concurrent-review workflows which enable users to
review files simultaneously. If two reviewers annotate the same document concurrently,
only the work of the reviewer who saves his annotations last is stored; the annotations of
the other reviewer are lost.
The settings for the features that have been added to those workflows are contained in
example configuration files that correspond to the actual configuration files for these
workflows. The default location of the example configuration files is:
iw-home/local/config/wft/solutions/workflow_name.cfg.example
It is recommended that you use the VisualAnnotate-ready configurable workflows.

VisualAnnotate can, however, be integrated into custom serial-review workflow

templates. You can find information and examples about how to do that on the
Interwoven Developer’s Network at:
http://devnet.interwoven.com
To activate VisualAnnotate in a configurable workflow:

1. If this is your first time working with the configurable workflows, you can simply
rename the example file for the workflow you want to use to workflow_name.cfg
and proceed to step 3.
If you want to use VisualAnnotate with a configurable workflow that you have
implemented prior to installing VisualAnnotate, copy the VisualAnnotate section
from the workflow_name.cfg.example file to the actual configuration file
(workflow_name.cfg) and proceed to step 2.
2. (Optional) If you want to use other enhancements to the workflow, copy the settings
for the functionality you want from the example configuration file to the actual
configuration file.
3. Edit the entries in the workflow_name.cfg file that correspond to the options you
want to enable.
4. Ensure that the workflow is enabled in the available_template.cfg file.
The following sections describe the configurable options for VisualAnnotate. Details
about other settings can be found in developer comments throughout the example
configuration files.
Email Template Settings

The workflow_name.cfg.example files for the two VisualAnnotate-ready configurable
workflows contain the following section:
##
## VisualAnnotate
##
# email templates
va_reviewer_email_header_template=/vannotate/templates/va_mailheader_revi
ewer.tpl
va_reviewer_email_body_template=/vannotate/templates/va_mailbody_reviewer
.tpl
va_reviewer_email_text_body_template=/vannotate/templates/text/va_mailbod
y_reviewer_text.tpl
va_author_email_header_template=/vannotate/templates/va_mailheader_author
.tpl
va_author_email_body_template=/vannotate/templates/va_mailbody_author.tpl
va_author_email_text_body_template=/vannotate/templates/text/va_mailbody_
author_text.tpl
VisualAnnotate uses these email templates. Email functionality is controlled by settings

located in the Email Notification section of the workflow_name.cfg file. You can

modify these templates; instructions are located in comments throughout the example
configuration files and the following ReadMe files:
iw-home/local/config/wft/vannotate/templates/README_vannotate_templates.
txt
iw-home/local/config/wft/solutions/README_VisualAnnotate.txt
Prompt Initiator Settings

The ask_va_enabled=yes setting enables job initiators to select in the job instantiation
form whether they want to enable VisualAnnotate. When ask_va_enabled=no, change
the va_enabled setting to yes to enable VisualAnnotate for all jobs created from the
workflow.
# Should the initiator be prompted to confirm or change these

# choices when initiating a job?
# If yes, the value of va_enabled will serve as the default.
va_enabled=no
ask_va_enabled=no
Review Cycles Settings

Review cycles are always tracked when VisualAnnotate is enabled. Change the
review_cycles option to yes if you want to use review cycles when VisualAnnotate is
not enabled.
# Setting this property to yes will enable a non-VA-enabled job

# to keep track of review cycles. (All VA-enabled jobs automatically # #
# keep track of review cycles, regardless of the value of the
# property.)
review_cycles=no
Variables Settings
The entries listed in the VisualAnnotate variables section determine the functionality
and appearance of the VisualAnnotate toolbar.
# VisualAnnotate variables
va_show_cycles=all
va_show_snapshots=all
va_show_reviewers=all
va_create_snapshots=unlimited
va_default_page=snapshot
va_show_live_option=true
va_which_snapshot=last
va_show_save_button=true

The following table describes each variable:
Table 6 VisualAnnotate Variables

Variable Value (default in bold) Description
va_show_cycles all | active | Specifies the number of review cycles to
number display on the toolbar Reviews menu. A
value of active displays only the active
review cycle.
va_show_snapshots all | Specifies which snapshots are displayed
active_user on the toolbar Reviews menu. A value
of active_user displays only those
snapshots created by the active user.
va_show_reviewers all | A value of active_user only displays
active_user the current (logged in) user’s
annotations and does not allow that user
to see anyone else’s annotations.
va_create_snapshots unlimited | Specifies how many snapshots a user
one_per_cycle | can create.
one_per_reviewer
va_default_page snapshot | live Specifies the type of page that the
toolbar displays when entering review
mode. A value of live will display the
unannotated page.
va_show_live_option true | false Specifies whether to display the Show
Unannotated Page menu option on the
toolbar.
which_snapshot first | last Specifies which snapshot in the active
review cycle is displayed by default. A
value of first displays the first
snapshot in the active review cycle.
show_save_button true | false Specifies whether to display the Save
button on the toolbar.
Approval Label Settings

You can change the two default labels that are displayed to users during the approval
cycle. These settings are used by all VisualAnnotate-enabled workflows, and are located
in the workflow properties file
(iw-home/local/config/wft/solutions/workflow_name.properties) for the
workflow you are using. The default settings are Approved and Please Revise and use
the following format:
approved_label=Approved
please_revise_label=Please Revise
You can change the stamp labels by editing the corresponding entry in the properties
file.

Disabling VisualAnnotate
You can disable VisualAnnotate without uninstalling it. The main TeamSite
configuration file (iw-home/etc/iw.cfg) contains a [visualannotate] section that
contains the following three default entries:
[visualannotate]
va_enabled=true
harvest_images=false
va_support_email=username@domain.com
To disable VisualAnnotate:
1. Open the iw.cfg file on the TeamSite server.
2. In the [visualannotate] section, change the va_enabled setting to false.
3. Reset the TeamSite GUI by issuing the iwreset –ui command.
If you want to disable VisualAnnotate only on a particular workflow, set the va_enabled
setting in the configuration file for that workflow to no (see page 136).
Disabling VisualAnnotate does not remove it from your server; it merely disables
VisualAnnotate functionality. Toolbars already installed by users on client systems are
not visibly affected.
Preserving Images In Snapshots

When reviewers save annotations, a snapshot of the document as it is displayed is
created. Snapshots provide an audit trail of content development because they are views
of the content and associated annotations at various stages in the review process.
However, snapshots might contain references to images in TeamSite. By default those

references point to “live” images that users might modify. That is, when a user views a
snapshot that contains an image he sees the latest version of that image, which might be
different from the version of the image at the time the snapshot was created.
The harvest_images setting in the [visualannotate] section of the iw.cfg file

enables you to specify whether you want snapshots to point to live images
(harvest_images=false) or to preserve images as displayed when snapshots are created
(harvest_images=true).
You must reset the TeamSite ContentCenter after you edit the harvest_images setting:
% iwreset -ui
NOTE
Enabling this feature can result in slower performance and can greatly increase the
amount of disk space needed for your Content Store.

Editing the Administrator Email Address

The email address that you entered when installing TeamSite is stored in the
[visualannotate] section of the iw.cfg file. It is used by the client toolbar to send
email that contains information that can help administrators troubleshoot problems with
the system. The email is sent to the address specified in the va_support_email entry in
the iw.cfg file.
You can edit this setting if you get a new VisualAnnotate administrator or if the
administrator’s email address changes.
VisualAnnotate Port Usage

The VisualAnnotate server functionality is a web application installed with TeamSite.
The VisualAnnotate client toolbar communicates with the VisualAnnotate server using
the host and ports (HTTP and HTTPS) specified in the [iwwebd] section of iw.cfg.
Testing the VisualAnnotate Installation

If you want to test VisualAnnotate before placing it into production, ensure that content
contributors and reviewers are unique users and that you log in as the correct user when
you initiate a task. VisualAnnotate does not support the same user as both a content
contributor and a reviewer in the same job.

Chapter 7
Template-Based Email
Many TeamSite users want to customize email messages with rich formatting (layout
control, fonts, colors, graphics), not just plain text messages. The customizations may
be simple (such as using their company’s logo) or may be quite extensive. And the
desired message format may be different for different situations (different tasks or
different workflows).
Template-based email provides a solution to this demand. This solution employs a

reusable script (iw_solution_email.ipl) that is used in conjunction with the
FormsPublisher presentation templates. The script takes care of retrieving the necessary
input data and transmitting the email message. The templates take care of transforming
the data into the desired email format. Different email tasks can use different templates
to suit the needs of those tasks, and they can all use the same script as an email
generating engine. The script uses the FormsPublisher technology that creates HTML
Web pages from data records (DCRs). There is no additional scripting technology to
learn.
NOTE
It is strongly recommended that template-based email be used instead of
iwsend_mail.ipl (described in Appendix B, “iwsend_mail.ipl Script”).
How Template-Based Email Works

The standard way to send a richly formatted email message is to use MIME
(Multipurpose Internet Mail Extensions) with an HTML part. This HTML part is
essentially just an HTML document that is attached to the message, but most email
clients display the formatted HTML page when the user reads the message.
A MIME message can have multiple parts of various types with complex relationships
among the parts. The iw_solution_email.ipl script (which is used by the solutions
workflows to send email) creates a “multipart/alternative” message that may consist of
three parts:
A header
An HTML part
A plain text part

Chapter 7: Template-Based Email
The script requires that a message have a header and either an HTML part or a plain text
part. A single email task can have all three parts.
The script transforms one XML document into the three parts of the email message by
applying each of the three templates as though it were a presentation template being
applied to a data record. If one of the templates is not specified, the corresponding part
is not created.
The Header
The email header specifies basic routing and delivery information, such as to whom the
message is being sent (“To:”), from whom the message should appear to be sent
(“From:”), and the subject. The header template produces a “headers” XML document
that conforms to the DTD below. The script then parses this XML document to produce
the actual mail headers. The other_header elements may be used to specify any
additional RFC 822-compliant mail headers such as Date, Sender, Message-ID or an
extension field.
The elements and attributes used in the header are derived from the header DTD
(header_xml.dtd):
<!ELEMENT headers (to+, cc?, from, subject, other_header*)>
<!ELEMENT to (addr+)>
<!ELEMENT cc (addr+)>
<!ELEMENT from (addr)>
<!ELEMENT subject (#PCDATA)>
<!ELEMENT addr (#PCDATA)>
<!ATTLIST addr
fullname CDATA #IMPLIED>
<!ELEMENT other_header (#PCDATA)>
<!ATTLIST other_header
name CDATA #REQUIRED>
The following example shows how the header structure is used:

<headers>
<to>
<addr>harpo.marx@harps.com</addr>
<addr fullname="Chico Marx">cmarx@piano.com</addr>
</to>
<cc>
<iwov_emailmap user="gummo"/>
</cc>
<from>
<addr>gmarx@mustache.org</addr>
</from>
<subject>Have I got a horse for you?</subject>
<other_header name="X-MovieReference">A Day at the Races
</other_header>
</headers>

In the email message, this example translates into the following information:
From: gmarx@mustache.org
To: harpo.marx@harps.com, Chico Marx <cmarx@piano.com>
Cc: gummo.marx@seldom-seen.org
Subject: Have I got a horse for you?
X-MovieReference: A Day at the Races
Within the header template, you may want to use the tag iwov_emailmap. This tag
produces an addr element from a user name. It first tries to looks up the user in the
following file:
iw-home/local/config/wft/solutions/email_map.cfg
If it does not find an entry in the map file for the user, it simply uses the bare user name
(removing the Windows domain, if any) and the default mail domain obtained from
iw.cfg.
NOTE
This script does not use the same configuration file that is used by iwsend_mail.ipl
and the other older scripts.
The HTML Part

The HTML part is essentially just an HTML document. It can contain anything that you
can put into an HTML document, including links to other documents or links into
ContentCenter. The template for the HTML part must output valid HTML.
For many organizations, it is sufficient to create email messages with only two
parts—the header and the HTML part. In those cases, you would use just two templates
and ignore the plain text part.
The Plain Text Part

The plain text part can contain anything you want, but it will not be rendered in a
formatted manner. If you include HTML directives inside this part, they show as raw
code and are not rendered as they would be for the HTML part.
For some organizations, HTML email messages may not be desired or may not be
supported. In those cases, the email message has two parts (a header and a plain text
part) and thus uses just two templates.
Using HTML and Plain Text in Combination

It is possible for both features to be needed when an organization supports a mixture of
mail client programs, of which some handle HTML formatted messages and others do

not handle HTML well or at all. In these cases, a choice may be made to produce email
messages that have both HTML and plain text. In those cases, the email message will
have all three parts. However, there is extra work involved because three templates must
be used. The script cannot automatically produce an attractive plain text part from an
HTML part.
A multipart/alternative message is used for representing the same data in multiple

formats. Therefore the HTML and plain text templates should be designed to output the
same information. When an email client receives such a message with both an HTML
part and a plain text part, it usually displays one part or the other based upon the user’s
preferences. However, no guarantee can be made regarding what the user will see
because this is a function of the client program. Therefore, the result may be different
for different users.
Use in Workflows
An email task is just an external task whose command sends an email message. To send
a template-based email notification from within a workflow, create an external task
using the command iw_solution_email.ipl. The templates to be used for the three
email parts are specified as task variables with the following names:
iw_mailheader_pt—the header (required)
iw_mailbody_pt—the HTML part
iw_mailbody_text_pt—the plain text part
The value for each task variable is the path to a template. If it is not specified as an
absolute path, the script first looks for the template relative to the wft directory and then
relative to the wft/solutions directory.
The following example is from the author_submit_with_email.wft template:

<externaltask name="Email_Approver" owner="__TAG__('iw_user');">
...
__INSERT__(get_cmd("iw_solution_email.ipl", "Approver"));
...
<variables>
<variable key="iw_mailheader_pt"
value="reviewer_iwmailheader.tpl"/>
<variable key="iw_mailbody_pt" value="reviewer_iwmailbody.tpl"/>
</variables>
</externaltask>
Because each email task specifies the templates that it will use, multiple email tasks
within a workflow may use the same templates or different templates. And email
templates may be shared across multiple workflows. You could have just one set of
email templates (for example, the header and HTML part) used by every email task, or
you could have separate templates customized for every single email task.

All three types of email templates are applied to an XML document that contains
information about the workflow job and one or more tasks in that job.
An email task in a workflow is often used to send a message regarding another task in
the workflow; most likely a task immediately preceding or immediately following the
email notification task itself. For example:
An email task may precede a user task to notify the user that there is a task that
requires attention.
An email task may follow an external task to notify someone that there was a
problem or an unusual condition, or that some operation has been completed.
In these situations, the email templates may want to use information regarding the
subject task, such as its owner or events. In the command for the email task, these
additional tasks are specified by name using the -t flag. For example, on a UNIX host,
the command could be:
<command v="__IW_HOME__/local/config/wft/solutions/iw_solution_email.ipl
–t 'Wake Up' –t 'Get Dressed' ">
The above command could be used to send email regarding two tasks, named “Wake
Up” and “Get Dressed”. The XML document that is given to the templates would then
have information regarding three tasks; the email task itself (which is implied) would be
task 0, the task named “Wake Up” (which was specified first on the command line)
would be task 1, and the task named “Get Dressed” would be task 2.
The Structure of the XML Document

The XML document that is created for the templates has a workflowinformation
element as its root node. The first child of the workflowinformation element is a
workflow element. This has the same data obtained by calling the iwgetwfobj
command-line tool for the job, except that this node also has an id attribute whose value
is the job ID.
The remaining children of the workflowinformation element are “task” elements. Each
of these elements has the same data obtained by calling the iwgetwfobj command for
the email task and any additional subject tasks, except for the following differences:
The name of the element is task instead of usertask, externaltask, and so forth.
The element has a type attribute whose value is the name of the iwgetwfobj
element (usertask, externaltask, and so forth.)
The element has an id attribute whose value is the task ID.
The following example shows a sample XML file:

<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<workflowinformation>
<workflow id="20736" name="Author Submit With Email" active="t" ...>
<description>Author Content Approval</description>
<tasks>...</tasks>

<starttasks>...</starttasks>
<activetasks>...</activetasks>
...
</workflow>
<task type="externaltask" id="20737" name="Email_Approver" ...>
<description>Please complete the task</description>
<areavpath v="/default/main/devnet/WORKAREA/shared"/>
...
<variables>
<variable key="iw_mailbody_pt"
value="reviewer_iwmailbody.tpl"/>
<variable key="iw_mailheader_pt"
value="reviewer_iwmailheader.tpl"/>
</variables>
...
<command v=’c:\iw-home/local/config/wft/solutions/
iw_solution_email.ipl -t "Approver"’/>
</task>
<task type="usertask" id="20738" name="Approver"...>
<description>Author Content Approval</description>
<areavpath v="/default/main/devnet/WORKAREA/shared"/>
...
</task>
</workflowinformation>
Refer to the section in TeamSite Command-Line Tools on the iwgetwfobj command for
the attributes and subelements of the workflow element and the various types of task
elements.
Template Creation
The solutions directory includes two sets of example templates:
reviewer_iwmailheader.tpl and reviewer_iwmailbody.tpl are intended for use
when notifying users that they have a pending review task.
author_iwmailheader.tpl and author_iwmailbody.tpl are intended for use when
notifying users that they have a pending user task involving author work.
These templates are used, by default, in the configurable workflows within the solutions
directory.
You may choose to create your own customized email templates instead of using the
templates provided. To create your own templates, there are two approaches to consider:
Create new templates from scratch, or
Create templates by modifying copies of the example templates.

The approach that is best for you depends upon how different you want your templates
to be from the examples provided. If you want to make small changes, like replacing the
logo or changing the wording, then it will be easier to just modify copies of the example
templates. However, if you are considering a radically different layout, it may be easier
to start fresh and just refer to the examples as a guide. If you want to create a template
by modifying an example template, we recommend that you copy the template and give
it a new name.
Here are some recommendations to consider if you are going to create a new template:
Try to establish the desired layout and visual design before writing any code.
Develop the rough layout on scratch paper, on a whiteboard or in a drawing tool.
Think about what information will be the most important to the typical recipient of
the message, and make that the most visible. Try not to overwhelm the reader with
too much detail.
Create static HTML pages with typical results using an HTML or text editor. Create
alternative proposals and have them reviewed by representative users. Try to display
the results in all of the browsers, in all of the email client programs, and on all of the
platforms that will be used because the appearance may change.
After creating a static example of the desired output, turn it into a template by
replacing static data with the appropriate templating tags.
Try to avoid browser-specific features unless your organization has control over the
client software.
If you include URLs within your message (for example, an image, style sheet, or
page reference), consider that the recipient may not be connected to the internet, or
may not have access to your intranet, at the time that the message is read. Therefore,
the referenced resources may not be accessible.
If you create a plain text template, remember that white space is significant. The use
of indentation (spaces or tab characters) or blank lines that makes an HTML
template much easier to read can produce undesired gaps in plain text.
In general, for plain text, consider keeping line lengths to 75 characters or less and
assume that any tab character is roughly equivalent to 8 character spaces. But keep
in mind that the text inserted by a tag may be much longer or shorter than the tag
itself, so it may be difficult to predict the final line length.
Because the development, debugging, and testing of your template will probably
require many iterations before you reach the final result, you will want to run the
template from a command line, separate from any workflow job. Create an example
of an XML input file and then invoke iwpt_compile.ipl directly from the
command line.
The easiest way to create a valid, example XML input file is to run an email task
with iw_solution_email.ipl and capture the XML file that is produced. Normally,
this XML file is deleted after an email message is sent. If you edit the script and
enable debugging (see below), the file is left in the iw-home/tmp directory.
Alternatively, you could manually construct an example of XML file with the
structure described above. You can call the iwgetwfobj command on representative
jobs and tasks to get some of the data.

Flex Roles
The out-of-the-box email template is not configured to honor flex roles, and cannot
determine which links to enable. If you are using flex roles in workflows that include
template-based email, you may need to modify your email template accordingly with
the appropriate links.
Debugging
There is a debugging flag in iw_solution_email.ipl. If $DEBUG is changed from 0 (off)
to 1 (on), then data regarding the activity of this script will be logged to the file
iw-home/tmp/iw_solutions_debug.log, and the temporary XML files that are
produced will be left in iw-home/tmp/.
A second flag, $VERBOSE is also included. With $DEBUG on (1) and $VERBOSE off (0) the
log file will have basic logging information. When both of these flags are on, the log file
will include excruciating detail about what has transpired, including interactions with
the mail server.
NOTE
Remember to set $DEBUG and $VERBOSE back to 0 when you finish so that the script can
run more efficiently.
iw_solution_email.ipl Data Flow

Figure 17 summarizes the data flow that occurs every time iw_solution_email.ipl
executes. Information is gathered regarding the job, the email task and additional tasks,
and it is combined into a single XML document. The templates are then individually
applied to that single, combined document to produce the header, HTML, and text parts
that make up the final email message.

Figure 17 Data flow for solution email
Job Header
Information Templat Header
e
Email Task Email HTML Email

Information Message Templat HTML Part Message
Information e
(XML)
Other Task Text

Information Templat Plain Text
e Part


Chapter 8
Debugging Techniques
This chapter describes debugging techniques used with workflows.
Debugging Workflow Files

Two additional POST/GET keys are available for debugging workflow template and job
specification files. Details are as follows.
iw_debug_mode
The iw_debug_mode key instructs the instantiator CGI to process input data from a
submitted form as it normally would, and then display job-specific information in a
Debug Mode page rather than instantiate the job on the server.
The Debug Mode form always contains two default sections: the Perl code (including
line numbers) that generates the job specification, and the XML job specification itself.
This job specification is what would have been instantiated on the server if debug mode
had been turned off. A third section showing syntax errors appears in the Debug Mode
form if the workflow instantiator found errors in the Perl code it generated based on
form input.
iw_output_file
The iw_output_file key instructs the instantiator CGI to process input data from a
submitted form as it normally would, and then capture the output in an XML job
specification file rather than instantiate the job on the server. After it is created, you can
manually instantiate the job specification file on the server at any time via iwjobc.
Usage
You can define the iw_debug_mode and iw_output_file key names in a TAG_info
directive (causing the keys to appear in the workflow form), or you can provide
definitions programmatically via POST/GET data.

Chapter 8: Debugging Techniques
Example
The following example shows definitions that are set within a TAG_info directive:
TAG_info(
iw_debug_mode => "<input type='text' value='true'>",
iw_output_file => "<input type='text' value='/tmp/my_job.xml'>",
);
Things to note in the preceding example:

For either element, setting type to text, the element appears on the workflow form.
Setting type to hidden causes the element not to be displayed on the workflow
form.
You can toggle debug mode on or off by setting value to true or false.
The file named in value must be writable by httpd.
Workflow Log File

Output from workflow runtime diagnostics is logged in:
iw-home\local\logs\iwjoberrors.log (Windows)
/var/adm/iwjoberrors.log (UNIX)

Appendix A
Workflow Tutorial
This appendix contains a tutorial for putting together and implementing a TeamSite
workflow.
Terms
The following table lists and describes terms used throughout this appendix:
Table 7 Description of Terms

Term Description
Workflow Model / Also referred to as a WFT file as the filenames end with a .wft
Workflow Template extension. This file contains a combination of Perl and XML.
(WFT)
The Workflow Template file defines the framework and the
fields of information needed to generate a static workflow job
specification.
Workflow / Job A Workflow can either be generated from a WFT or written
Specification statically.
The Workflow, or job specification, file is in XML format and

ends with the extension .xml. It defines the complete process
to be followed from start to finish, including all state
transitions that are possible.
Job This refers to an instantiated Workflow or, in other terms, an
instance of a workflow object. It is identified by both the name
of the workflow from which it was created and by an ID
number. Any given workflow can be represented in multiple
instances as Jobs.
From the User perspective, a Job is a set of interdependent

Tasks that need to be performed.
Task 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
area 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 (provided it is not a read-only Task for content
approval)

Appendix A: Workflow Tutorial
Task Symbols
Figure 18 shows the task symbols used in the workflow diagrams in this appendix.
Figure 18 Task Symbols
User Task Group Task Lock Task
Dummy
Update Task Submit Task Task
External CGI Task Workflow Task

Task
End Task
AND OR NOT
Designing a Workflow
The following sections describe the process of designing a workflow.
Determine Requirements
The better defined the process, the easier it will be to construct. The following is a list of
potential requirements:
What should be considered mandatory?
What should be considered optional?
Which parts should be serial?
Which parts should be parallel?
How many different people are involved at each major phase of the process?
Which roles are involved in which phase?

Each workflow task has its own particular needs and requirements. Do not treat this list
as a comprehensive set of requirements, but rather as a general starting point.
Diagram the Workflow

Follow the guidelines and examples described in this document.
Use Existing Workflows

If possible, try to choose an existing workflow template from which to base your
customized work.After you have chosen a base, test it to make sure the base works. This
may involve modifying the iw-home/local/config/wft/available_templates.cfg
file.
Create a copy of this workflow and give it a simple name such as test.wft. While in
test.wft, strip out parts of that do not apply to your customized effort, and again test it
to make sure it works.
Begin Customized Implementation

After you have a working base, create a copy of it and begin adding code to the
workflow template. Start with the TAG_info() section if you need to modify the prompts
for information during job instantiation. In our example, this would be a change to the
contributor section, and probably changes to the reviewer section.
Test your changes. If they work, continue with another iteration. If the changes don’t
work, spend some time trying to figure out why they don’t work. If you cannot figure it
out within an hour, take a fresh copy of the working base and begin trying to add code
again, in smaller steps.
Make sure that you have at least one “working” version of your workflow template at all
times. In this context, working means that it is syntactically correct, and functions
correctly with regard to the degree that the code has been written, even though it may
not do everything you want.
Document Your Work

You should be documenting most of this work during the entire process. After you have
a version of the workflow template that does what you believe the client asked for, take
the time to create a reasonably finished document that includes both graphic and textual
descriptions of the workflow process.

This document is extremely important in making sure that you and the client are on the
same page with respect to the work you have just spent several hours or days working
on. In addition, this document will serve as a guide for the next person who comes along
to modify the workflow template.
Mapping Out Workflows

It is strongly advised that you map out your workflows before attempting to write them.
You should also follow the process of thoroughly documenting the workflow before
attempting to implement it. This process lets you use your document as a guide while
coding the workflow.
As you begin to map out your workflow, you should think of the various kinds of tasks
involved and use an appropriate symbol or stylization so that when you start coding you
know exactly what type of tasks you are creating.
Your task diagram also becomes your state transition diagram (Figure 19).
Figure 19 State Transition Diagram

Create New Job
externaltask externaltask externaltask
usertask usertask submittask
endtask
As you put the boxes together, you start to draw lines between them. Most workflows
incorporate some form of loop-back to a prior state in the event of something not being
approved or failing for some other reason. Many workflows incorporate optional flows
that allow you to either circumvent or choose certain paths to take. All these possible
transitions should be clearly marked on your diagram.
Your diagram or additional documentation should call out information such as the
players or roles involved, and any other information that may assist you when you
finally start to code.

After you finish blocking out the diagram, go back and add descriptive titles (Figure 20),
noting any special attribute settings and variable usage to the various tasks.
Figure 20 Workflow diagram with descriptive titles
Create New Job Author (Creator)

Job Author
(creator) Reviewer
(1) (3) (5)

“NotifyAuthor” “NotifyReviewer” “NotifyRejection”
[iw_user] [author] [reviewer]
(start)
Reject
(2) (4) (6)

“CreateDoc” “ReviewDoc”
“SubmitWork”
[author] [reviewer]
Approve [reviewer]
(readonly)
(7) “End”
After you are familiar with the relationship of shapes to task-types, you can skip the first
diagram example and start with the second diagram example.
Resets and Inactivate

Resets and inactivate subelements of a task are primarily for use within a branched,
concurrent workflow design where there is the need for logical conditions to be placed
on the transitions between the various tasks.
In Figure 21, if the owner of either tasks B1 or B2 says “No,” you want to transition
back to A and cancel requests for B1 and B2. In other words, A wants to inactivate
both B1 and B2 whenever it (A) becomes activated.

Figure 21 Workflow diagram with logical conditions
B1
Yes
No
A C
B2 No
Yes
This process is simple if you assume that the owner of whichever task (B1 or B2)
finishes first says “No.” But what happens if the owner of the B1 task says “Yes” and
then the owner of the B2 task says “No”? If you imagine a table existing within task C
that records all of its activators, in this case just prior to the owner of the B2 task saying
“No,” it would appear like the following:
Activators
B1 B2
Yes ---
If, as noted previously, B2 being set to “No” would cause A to become activated again,
and would inactivate both B1 and B2, what would happen once A transitions back to B1
and B2 for the next iteration? If the owner of B2 happens to act first this time and says
“Yes,” task C is automatically activated and the owner of B1 never has a chance to say
anything. This is because the table associated with C already has a mark in it saying the
owner of B1 said “Yes” and this was never cleared out when the previous time the
owner of B2 said “No.”
Locks
Locks on files can be very advantageous. If the files associated with a task are not
locked except by workflow directives or editing commands initiated within a workflow
process, then the workflow engine can transfer the locks from task owner to task owner
as desired.
Unfortunately, if you lock a file within TeamSite before associating that file with a
workflow, the lock is considered to be outside the realm of control of the workflow
engine. As such, any task attempting to take that lock, will fail—but not necessarily in a
predictable way. If you run iwgetwfobj on a task that is in an uncertain state because it
is trying to get locks, you see an attribute on the task element named tryingtolock that
is set to t (true).

Locks External to Workflow Engine

If you set the lock attribute to t for most tasks in a workflow, your workflow may
appear to go into limbo. For these tasks, the workflow engine will attempt to get locks
on all files attached to the tasks. It will fail if any of these files are locked by locks
external to the workflow engine. If it does fail to get a lock, then it will sleep for a small
amount of time and try again, until all external locks have been released and it succeeds
in getting them.
If you use a locktask element, which has a success and a failure branching structure,
this situation leads directly to the failure branch.
You can configure an external task to run iw-home/local/bin/unlock.ipl to remove

external-to-workflow locks on files associated with the job.
Audit Trail Archival

The audit trail for a given Job is preserved in the Jobs List view until the Job itself is
completed, and then it is removed. To preserve the audit trail for longer periods of time,
you will need to use an external task and write a script to dump audit trail information
into a flat file or database.
Complex Tasks
While most of the tasks are relatively simple in concept there are at least two
exceptions: the externaltask and the cgitask. These are considered complex because they
rely on external scripts that need to be written carefully to make use of and to provide
information to and from the workflow.
The following sections relate to the scripts invoked as part of these tasks.
externaltask
Scripts called from an external task (see Appendix D, “External Task Example”) are
automatically, implicitly, passed the following arguments:
The workflow or job ID
The task ID
The areavpath
In addition, if there are any files associated with the task, these are included after the
areavpath by default. To avoid potentially exceeding the operating system’s
command-line argument length limitations, it is recommended that you set the iw.cfg

option external_task_add_filelist to false (its default is true) and use the Perl
method TeamSite::WFtask::GetFiles() within your script.
If you declare any other command line arguments as part of your command definition in
the wft, they will precede these implicitly passed arguments. For example, in Perl, if you
declare your command as:
<command v="iw-home/local/bin/myscript –foo"/>
The argument -foo will be in $ARGV[0], and the workflow ID will be in $ARGV[1] and
so forth.
In order to use this information and access other information from, or provide additional
information to, the associated workflow, use the following Perl library modules:
TeamSite/WFworkflow.pm
TeamSite/WFtask.pm
These are both object-oriented Perl modules located within the iw-home/iw-perl/
directory structure. Documentation for them is included within the modules themselves
in POD format and can be accessed by running the utility perldoc on the files.
As an example of usage:
use TeamSite::WFtask;
my($jobid, $taskid) = (shift, shift);
my $task = TeamSite::WFtask->new($taskid);
my $area = $task->GetArea();
my(@files) = $task->GetFiles();
... [do stuff] ...
$task->CallBack(0, "Success");
exit(0);
This is essentially a boilerplate for any externaltask script.
Debugging an externaltask script
An externaltask interacts with the workflow as follows:

The externaltask becomes active.
The workflow engine kicks off the command script.
The command script uses a callback to notify the workflow engine when it has
completed and which successorset should be activated.
Things to do to help eliminate and resolve problems with externaltask scripts include the
following:
Ensure there are not any syntax errors in the Perl script by running the command:
iwperl –w –c scriptname-with-path
Verify that the script is working properly by attempting to run it from the command
line in the same way that the workflow engine would. TeamSite will append (at

least) the job ID and task ID, respectively, to a command given to an external task,
and run it. For example:
iwperl scriptname-with-path 123 124
where “123” and “124” are the job ID and task ID for your current workflow.
NOTE
Make sure that the environment variable settings and owner privileges when
running the script from the command line match those when it is run from workflow
engine.
If the script appears to work, but the workflow does not transition afterwards, it is
usually an indication of a problem with, or lack of, the callback to the workflow
engine. Verify that the owner of the external task script process is in the
iw-home/conf/roles/master.uid file (on Windows, the owner must be SYSTEM),
and that you are using a callback in your script.
On a similar front, to assist in the testing and debugging of externaltask scripts, disable
the callback in the script until you are sure that it’s working. By doing this, you should
be able to select the Start Task menu option repeatedly until you are satisfied with the
results.
As mentioned above, you can manually call externaltask scripts using this syntax from a
shell or command prompt to test its functionality (without transitioning from and thus
deactivating the associated task):
<scriptname> [<your-args>] <wfid> <taskid>
In addition, check the log files as indicated in “Debugging Hints” on page 166.
Additional Information
An externaltask script is specified with an absolute path to the script to be invoked, and
should be written to use Interwoven’s iwperl that knows where to find the TeamSite Perl
module libraries.
If your TeamSite server is on UNIX, make sure the executable bits are set (chmod 755).
If on Windows, the script name should end with .ipl.
cgitask
While cgitask scripts share some commonalities with externaltask scripts, command line
arguments are not used for cgitask scripts. Instead, information is passed implicitly as
“form” data. See the example in Appendix C, “CGI Task Example”.
To assist with this, one additional Perl module should be used: TeamSite/CGI_lite.pm.

As theses scripts are generally more complex than externaltask scripts, it is a little
harder to provide a template for them. The following, however, will hopefully provide
you sufficient information for how to go about creating such a script:
use TeamSite::CGI_lite;
… [do stuff] …
my($cgi) = TeamSite::CGI_lite->new();
$cgi->parse_data();
my($taskid) = $cgi->{form}{iw_taskid} || $cgi->{form}{task_id};
$tasked = $$tasked[0] if (ref($tasked) eq "ARRAY");
my($task) = TeamSite::WFtask->new($taskid);
my(@files) = $task->GetFiles();
… [do stuff] …
$task->CallBack(0, "Regenerated HTML File");
print join("",
"<script language='JavaScript'>",
"if (opener.top.Ctl) { opener.top.Ctl.pw_refresh(); }",
"else { opener.location.reload(); }",
"window.close();",
"</script>");
The “print” statement at the end achieves two things: (1) it forces the To Do List
window to refresh; (2) it closes the sub-window created to run the CGI script.
NOTE
This is no longer the recommended way to transition a workflow CGI task. Instead, a
CGI should invoke the URL command transitiontask, as described in the TeamSite
User Interface Customization Guide.
Debugging a cgitask Script
To assist in the testing and debugging of cgitask scripts, disable the callback in the script
until you are sure that it is working. By doing this, you should be able to select the Start
Task menu option repeatedly until you are satisfied with the results.
It is also recommended that you first utilize the show_env.cgi program as your cgitask
script, so that you can easily see all the form variables available for use within the actual
script.
In addition, check the log files as indicated in “Debugging Hints” on page 166.
Additional Information
All cgitask scripts must be located in: iw-home/httpd/iw-bin/.

Do not pass parameters to the script on the command line (this is unreliable). Instead,
turn the parameters into task variables and have the cgitask script retrieve them using
TeamSite::WFtask::GetVariable(). In addition, these scripts should be written to use
Interwoven’s iwperl that knows where to find the TeamSite Perl module libraries.
If your TeamSite server is on UNIX, the script should end with the extension .cgi and
have its execute bits turned on (chmod 755).
If your TeamSite server is on Windows, it may be necessary to create a wrapper binary.

The reason for doing this on Windows is that IIS will only run binary programs as CGI’s
so a wrapper binary is needed which determines the name it was called with
(myscript.cgi), replaces the extension with .ipl and then explicitly invokes the Perl
script (myscript.ipl).
If the #! line at the beginning of the .ipl file points to the correct location of iwperl,
then you do not need to create a wrapper binary for that file. In this case, the workflows
(or custom menu configurations) will need to refer directly to myscript.ipl and not
myscript.cgi.
If the #! line at the beginning of the .ipl file does not point to the correct location of
iwperl, then you should copy the file show_env.cgi and rename the copy to be the
name of your program with a .cgi extension. For example, if you have a script called
myscript.ipl copy show_env.cgi to myscript.cgi.
This same procedure is used for menu customization CGI scripts.
Retrieving File Comments

There are times, within either an external task or CGI task script, that you may want to
get not only the list of files associated with the job, but also all the comments associated
with those files. Here’s how to do it:
my($task) = new TeamSite::WFtask($ARGV[1]);

my(%files);
# notice – this is a hash variable
$task->GetFilesAndComments(\%files);
# notice, passed by reference (leading ‘\’)
for my $file (sort(keys(%files))){

print "File: '$file'\n";
my(@vals) = @{$files{$file}};
for my $data (@vals){
# note: $data is a reference to another hash
# to access use '$$data{key}'

print "$$data{date}:$$data{user}: '$$data{body}'\n";
# note: not printed is $$data{task} which is the ID of the task

# when the comment was added.
}
}
Callbacks
The workflow callback mechanism comes in the following forms:
iwcallback command-line tool
TeamSite::WFtask::CallBack() method
TeamSite::CGI_lite::iwcallback() method
iwcallback and TeamSite::WFtask::CallBack()
The iwcallback command-line tool and TeamSite::WFtask::CallBack() method each

take two parameters.
But first, a little background information. If you look at the definition of a task, you will
see that almost all task definitions (with the exception of locktask and endtask
elements) have successorset subelements. In many cases there can be more than one,
and so they are grouped together within a successors element:
<successors>
<successorset description="fruit">
<succ v="apple"/>
<succ v="banana"/>
</successorset>
<successorset description="vegetable">
<succ v="asparagus"/>
<succ v="broccoli"/>
</successorset>
</successors>
This collection of elements can be thought of as a Perl array:

my @fruits = ("apple", "banana";
my @vegetables = ("broccoli", "asparagus");
my @successors = (\@fruits, \@vegetables);
The first parameter to the CallBack is essentially an index into the successors
array—and as in Perl, the index starts with 0 and increments up from there. In the above
example, a CallBack of 0 would trigger the tomato task, and a CallBack of 1 would
trigger the broccoli task.
You can only use an index number from 0 to one-less-than-the-number-of-successorsets.

In the above example, only values 0 and 1 are accepted. If I were to use a value of 2 as

the first parameter of the CallBack mechanism, the task would not transition to either of
the next two tasks.
The second parameter of the CallBack method is a comment. That comment will be
entered into the workflow as a comment for the task. If you collect information about
things that occur within your script and then put them into the CallBack, you will have
effectively transferred that information into the workflow.
Consider the following as only a rough example of how you might be able to use this
functionality:
...
my($COMMENT) = "=" x 70 . "\n" . scalar(localtime) . "\n";
...
if (something){
$COMMENT .= "Something happened\n";
else {
$comment .= "Something else happened\n";
}
...
$task->CallBack(0, "$COMMENT");
TeamSite::CGI_lite::iwcallback
The TeamSite::CGI_lite::iwcallback method takes the description string of the

successor as the first argument, rather than the index. For example:
...
my $cgi = new TeamSite::CGI_lite();
...
$cgi->iwcallback("fruit", "$COMMENT");
#-OR-
$cgi->iwcallback("vegetable", "$COMMENT");
Sending Email Notification

You can implement using email notification in your workflow using one of the
following methods:
Template-based email—see Chapter 7, “Template-Based Email” for more
information.
External task scripts for notification using iwsend_mail.ipl—see Appendix B,
“iwsend_mail.ipl Script” for more information.
NOTE
Using Template-based email, not external task scripts and iwsend_mail.ipl, is strongly
recommended.

Prompting for Information

Often, a large part of a cgitask script is the presentation of existing information, and the
prompting for additional information to be used elsewhere in the workflow process.
The WFtask.pm library module provides many (40+) routines that can be used in
conjunction with standard CGI programming to assist in these efforts. Examples
include:
GetOwner
GetDescription
AddFile
SetComment
GetFiles
GetVariable
SetVariable
CreateVariable
As mentioned previously – it is highly recommended that you run the utility perldoc on
this module to get more information about these and the other library routines available
for use within your CGI script.
Setting the Size of the Instantiation Window

Often times you will need to prompt for more information than what will generally be
visible when the instantiation window comes up, because the initial window that allows
you to choose which workflow to run is relatively small.
The standard response to this is that the user will simply have to scroll the form or
enlarge the window themselves to see everything.
To get around this, in your workflow template, include a CGI_info() section with
something like the following:
CGI_info(
html_body_options => onLoad='top.resizeTo(600,400);'",
);
The parameters to resizeTo are the width and height respectively.
Debugging Hints
This section offers some additional hints on debugging workflows, to be used in
conjunction with the information described in Chapter 8, “Debugging Techniques.”

There are several ways of debugging problems found while testing and executing your
workflows and workflow templates. The first is to examine the end of several log files:
iwjoberrors.log and iwtrace.log for starters, and your Web server’s log file too.
In addition, it is often helpful to turn on the workflow’s built-in debugging interface that
displays information via a browser window. To do this you will need to add the
following lines in your wft (these can be written in various ways—this is just one
example):
iw_output_file => "<input type='text' value='/tmp/foo.xml'>",
iw_debug_mode => "<input type='text' value='false'>",
Some additional tools you can use for simplified sanity testing of your XML are Internet
Explorer and XMLSpy.
If you view your workflow template in Internet Explorer, it will not tell you if it is
correct or works, because it does not do any real validation with respect to that.
However, it will tell you if you have all your opening and closing XML tags lined up
correctly, and sometimes that is all you need to be able to find and fix a problem that
might otherwise frustrate you for hours. This requires that you write the workflow
template such that it starts with the XML headers, followed by the workflow header, and
ends with the </workflow> tag. All template_script elements must be within the
workflow element.
If you use such tools on the generated workflow, you will probably have to modify the
path specification for the DTD to point to your iw-home/local/config/wft/iwwf.dtd.
Error Messages
It is not uncommon to receive error messages when you are developing your workflow.
Most often these will show up as dialog boxes. It is also a good idea to check the
iwtrace.log and or iwjoberrors.log whenever something is not working.
The following table lists likely error messages and their explanations.
Table 8
Message Explanation
Invalid workflow … This message may or may not contain more
Workflow xxx does not information. It is usually an indication that an
exist
areavpath associated with one of the tasks is invalid. If
the information about the bad areavpath shows up in
the dialog box on NT, it is usually devoid of
path-separators because the dialog box doesn’t
gracefully handle the back-slashes (‘\’) in the path.
Could not add successors This is an indication that there is a <succ v="xxx"/>
for task xxx in the noted task which refers to a successor task by
name that does not exist. Check spelling of all
successors very carefully.

Table 8
Message Explanation
Not well formed at line This message indicates that there is an XML syntactic
xxx problem with the generated workflow. The line
number is relative to the generated workflow not the
workflow template. To help pinpoint the line number,
enable workflow debugging and look at the green
section (or view the generated XML file itself).
Task xxx could not This error most often occurs when the user you've
activate successor xxx selected to own the submittask does not have
permission to submit from the areavpath of the
submittask.
Bad file number at This is usually an indication that the mail server and
…/Mail/Mailer.pm line xxx mail domain settings have not been configured
properly in the iw.cfg file.
Active Workflow with No Active Tasks

Try to determine the ID of the task you believe should be active and perform an
iwgetwfobj on that task-id. If you find an entry that says tryingtolock="t" the
problem is that the task which should be active is stuck, waiting to obtain a lock on a
particular file(s) associated with the task.
The workflow engine will continuously cycle through the attempt to obtain the lock,
first after a few seconds and then for increasingly larger amounts of time. If you can
determine which files, associated with the job, were locked outside of the workflow
context and unlock them explicitly, the workflow engine should be able to pick up the
locks the next time through and then you should get the active task you were originally
expecting.

Appendix B
iwsend_mail.ipl Script
The Perl script iwsend_mail.ipl was originally created to ease creation of externaltask
scripts for notification within TeamSite workflows. This script allows functionality
(such as setting mail headers and the formatting of the message) to be controlled via
either command line arguments or task-level variables. The script is located in the
iw-home/bin directory.
NOTE
This script has been replaced by template-based email, described in Chapter 7,
“Template-Based Email.” It is strongly recommended that template-based email be used
instead of iwsend_mail.ipl.
Parameters
There are some parameters that need to be configured in the iw.cfg file in order for this
script to work:
[iwsend_mail]
maildomain=mycompany.com
mailserver=smtp.mycompany.com
use_mapping_file=false
Each of these parameters is described below and is required unless otherwise noted:
maildomain—set to the email domain used for email addresses that are not
otherwise qualified with a domain address. For example:
maildomain=mycompany.com
mailserver—set to the mail server used for SMTP. For example:

mailserver=smtp.mycompany.com
NOTE
The mailserver setting is also used by template-based email.

Appendix B: iwsend_mail.ipl Script
use_mapping_file—(optional) if the value is true, all email addresses are matched

against a specified mapping file to see if they need to be altered from their present
settings. The default value is false.
email_mapping_file—(required if use_mapping_file=true) specifies the full
path to the email mapping file. For example:
debug_output—(optional) debugging information is sent to the file specified. For

example:
Constructing Messages
The following sections describe the configuration of email messages.
Command Line Vs. Task Variable Usage

When specifying options for iwsend_mail.ipl, you have the choice of either using
command line flags or task variables. Command line arguments always override both
defaults and task-level variable settings.
Command Line
Command line flags and values are used in conjunction with the command element and
the script specified by its v attribute:
<command v="/usr/iw-home/bin/iwsend_mail.ipl" />
You can add additional flags and values to this command to accomplish specific tasks
described later in this section. For example:
Using command line strings has the following advantages:

Backwards compatible with older versions of the same script.
Can be used in non-workflow context.
Overrides task-level settings if needed for specific debugging purposes.
Using task variables has the following advantages:

Reduces the length of the command line, eliminating the chance of running into a
command line length limitation imposed by some operating systems or shells.
Allows for options to be modified within the context of the workflow by another
external task or cgi task script.

Easier to debug the script from command line because only the job ID and task ID
arguments need to be provided on command line.
You can determine which solution works best for you. Both solutions are presented for
the following topics.
Determining Email Addresses

The value of use_mapping_file and email_mapping_file determines which of two
areas of the convert_email() section will be performed.
When use_mapping_file is set to false (the default), the script uses the TeamSite
user name(s) that has been passed to the script for the email address.
If this user name has a Windows domain listed prior to the user ID, it will be
stripped off and just the user ID is used for the email address. Once this is taken care
of, if the value passed in contains an @ it will be left alone, otherwise the
maildomain value is appended.
For backwards compatibility, $ARGV[0] is checked against the regex /^\d+$/ to
determine if it is a Workflow ID or not. If not, it assumes that it is the name of the
intended recipient.
When use_mapping_file is set to true, the script uses a flat file to map the
TeamSite user name to a corresponding email address.
The TeamSite administrator must maintain the flat file whenever new users are
added. The script first sets up a default email address by using the values of the
specified recipients as passed into the script. Next, the email mapping flat file is
opened and the contents are parsed looking for a match for the specific recipient. If
a match is found, $email_address is set to the corresponding value. If no match is
found, the recipient value is left unchanged except that any Windows domain
information is stripped off. In both cases @maildomain is appended if needed.
The email mapping flat file has a specific format that must be followed. Its location
is specified by the email_mapping_file parameter described in “Parameters” on
page 169. The recommended value is:
iw-home/local/config/email_map.cfg
The format for the file is a list of names and their corresponding email addresses,
separated by colons:
(UNIX)
tsuser1: jdoe
tsuser2: rroe@mycompany.com
tsuser3: tech-pubs
(Windows)
MYDOMAIN\tsuser1: jdoe
MYDOMAIN\tsuser2: rroe@mycompany.com
MYDOMAIN\tsuser3: tech-pubs

The email address can be the internal user name (jdoe) or the fully-qualified name
(rroe@mycompany.com), depending on your organizational needs and requirements.
You can also specify a departmental or group alias, for example tech-pubs.
Sending to Multiple Recipients

You can specify multiple recipients for both To: and Cc: fields. There must be either a
mail_to task variable set, or at least one -t specification.
Command-Line
You can send messages to multiple recipients from the command line using the -t flag
to present those address associated with the To: field, and the -c flag for those addresses
associated with the Cc: field. These flags can be used in either of two ways (or a
combination of both). For example
<command v="/usr/iw-home/bin/iwsend_mail.ipl -t tsuser1 -t tsuser2 />
<command v="/usr/iw-home/bin/iwsend_mail.ipl
-t "MYDOMAIN\tsuser1,MYDOMAIN\tsuser2" ... />
<command v="/usr/iw-home/bin/iwsend_mail.ipl -c tsuser1

–c "tsuser2,tsuser3" ... />
Task Variable
You can configure task variables for sending to multiple recipients in the following
manner:
<externaltask name="notify" ...>

...
<variables>
<variable key="mail_to" value="tsuser1,tsuser2"/>
<variable key="mail_cc" value="tsuser3,tsuser4"/>
</variables>
</externaltask>

Specifying the Sender

You can specify who the sender of the message is supposed to be. The sender address
will be validated in the same way as each recipient name. The default value is the task’s
owner.
Command Line
You can specify the sender from the command line using the -f flag and an associated
sender value. For example:
<command v="/usr/iw-home/bin/iwsend_mail.ipl ... -f tsuser1" />
Task Variable
You can configure a task variable to specify the sender in the following manner:

...
<variables>
<variable key="mail_from" value="tsuser1"/>
</variables>
</externaltask>
Specifying the Subject Line

The default subject line is the following:
TeamSite Task Notification
However, you can substitute a different subject line if you want.
Command Line
You can specify the subject line from the command line using the -s flag and an
associated value. For example
<command v="/usr/iw-home/bin/iwsend_mail.ipl ... -s ATTENTION" />
If your value includes spaces, you must enclose the value in quotes. For example:
<command v="/usr/iw-home/bin/iwsend_mail.ipl ...
-s 'Alert Notification' " />

Task Variable
You can configure a task variable to specify the subject line in the following manner:

...
<variables>
<variable key="mail_subject" value="ATTENTION"/>
</variables>
</externaltask>
Composing the Message Body

The body of the message is comprised of the following parts:
Summary information (Job ID, Areavpath, Job Name, Job Description)
Message (defaults to: “A task in job JobId has been assigned to you.”)
List of comments associated with the task (if any)
List of files associated with the task (if any)
The message portion is replaceable with another value using the methods described in
the following sections.
Command Line
You can replace the message portion with your own text by using one of the following
options:
-m 'message_text'—inserts the associated message directly into the message
body. For example:
<command v="/usr/iw-home/bin/iwsend_mail.ipl ... -m 'This Space
Available for Advertising' "/>
-b path_to_message_file—specifies a full path to a text file containing the

content that is inserted into the message body. For example:
<command v="/usr/iw-home/bin/iwsend_mail.ipl ... -b /usr/message.txt
"/>
If both options are specified, the -m option is ignored.

Task Variable
You can replace the message portion with your own text using a task variable in the
following manner:

...
<variables>
<variable key="mail_message" value="my one line message text"/>
</variables>
</externaltask>
or
...
<variables>
<variable key="mail_message_file" value="/usr/message.txt"/>
</variables>
</externaltask>
The variable mail_message_file takes precedence over the mail_message variable if

both are present.
URL Formatting
URLs can be used to provide a means for the email recipients to quickly display the task
associated with the email and any one of the files associated with the task for
previewing. By default, no URLs are presented in the email message because in
plain-text formatting they can take up a lot of space and are difficult to read. However,
you can enable TeamSite URL commands lines in plain-text email messages.
NOTE
In order to supply a link to the task in the email, you must supply the name of the task
you wish to provide a link for as described in “Next Task Information” on page 177.
Command Line
You can enable URL commands lines in plain-text email messages using the -u flag. For
example:
<command v="/usr/iw-home/bin/iwsend_mail.ipl ... -u />

Task Variable
You can enable TeamSite URL command lines in plain-text email messages using a task
variable in the following manner:

...
<variables>
<variable key="mail_url" value="1" />
</variables>
</externaltask>
HTML Formatting
If everyone involved with the content creation process uses mail readers that can handle
HTML formatting, you can enable HTML formatting of the email message that
automatically enables URL command inclusion since the technical details of the URLs
can be hidden from the casual email recipient by use of simpler link labels.
NOTE
In order to supply a link to the task in the email, you must supply the name of the task
you wish to provide a link for as described in “Next Task Information” on page 177.
Command Line
You can enable HTML formatting of the email message using the -H flag. For example:
<command v="/usr/iw-home/bin/iwsend_mail.ipl ... -H" />
Task Variable
You can enable HTML formatting of the email message using a task variable in the
following manner:

...
<variables>
<variable key="mail_html" value="1"/>
</variables>
</externaltask>

Next Task Information

When using iwsend_mail.ipl, you can specify what the next task is within the
workflow by using the -N flag and the task name. For example:
<command v="/usr/iw-home/bin/iwsend_mail.ipl ... -N ‘Author Work’"/>
Task Level Variables
You can specify the next task using a task variable in the following manner:

...
<successors>
<successorset>
<succ v="AuthorWork"/>
</successorset>
</successors>
...
<variables>
<variable key="mail_taskname" value="AuthorWork"/>
</variables>
</externaltask>
Enabling Error Capturing

You can enable the iwsend_mail.ipl script to capture error information relating to
notifications. The script traps such error conditions and enables you to have it send a
distinct CallBack value of 1 rather than the value of 0 indicating success. In addition, it
passes an error message as the second parameter.
Command Line
You can enable error capturing using the -e flag. For example:
<command v="/usr/iw-home/bin/iwsend_mail.ipl ... -e />

Task Level
You can enable error capturing using a task variable in the following manner:
<externaltask name="notify" …>

...
<successors>
<successorset>
</successorset>
<successorset>
<succ v="AdminTask"/>
</successorset>
</successors>
...
<variables>
<variable key="mail_error" value="1"/>
</variables>
</externaltask>
If you enable this feature, but do not modify the task definition to have two
successorsets elements, an error in sending results in a “hung” external task on
someone’s To Do List. However, the error message will still have been added to the task,
so examining the Job Details will provide some indication of why the process is hung.
For example:
...
<successors>
<successorset>
</successorset>
</successors>
...
<variables>
</variables>
</externaltask>

Instead, this configuration should be:

...
<successors>
<successorset>
</successorset>
<successorset>
<succ v="MailError"/>
</successorset>
</successors>
...
<variables>
</variables>
</externaltask>
iwsend_mail.ipl Workflow Example

This section presents an example of the iwsend_mail.ipl script used in a workflow.
Associated File Configurations

The following associated configurations apply to this example:
iw.cfg File
The iw.cfg file includes the following configuration:
[iwsend_mail]
maildomain=my_company.com
mailserver=smtp.my_company.com
use_mapping_file=true
email_mapping_file=/iw-home/local/config/email_map.cfg
email_map.cfg File
The email_map.cfg file contains the following configuration (depending on the

operating system):
(UNIX)
tsuser1: jdoe
tsuser2: xman@interwoven.com

(Windows)
MYDOMAIN\tsuser1: jdoe
MYDOMAIN\tsuser2: xman@interwoven.com
Workflow Configuration
The following sections display equivalent configurations for a command line- and task
variable-based scripts.
Command Line
From the command line, the configuration would be:
<command v=" '/usr/iw-home/bin/iwsend_mail.ipl -t 'tsuser1, tsuser2'

-c chico -f Harpo@Marx-Brothers.com -m 'This Space Available for
Advertising' -s 'Sample Subject Line' "/>
Task Variable
As an alternative to the command line method, the same results could be accomplished
with a command specification in the workflow like the following:
<command v="/usr/iw-home/bin/iwsend_mail.ipl"/>
as long as the same task contains the following variables section:

<variables>
<variable key="mail_to" value=”tsuser1, tsuser2"/>
<variable key="mail_cc" value=”chico"/>
<variable key="mail_from" value=Harpo@Marx-Brothers.com/>
<variable key="mail_message" value="This Space Available for
Advertising"/>
<variable key="mail_subject” value="Sample Subject Line"/>
</variables>
Output
The output appears as the following:
Subject: Sample Subject Line

To: jdoe@mycompany.com, xman@interwoven.com
From: Harpo@Marx-Brothers.com
Cc: chico@mycompany.com
Date: Thu, 22 Feb 2001 13:03:20 -0500 (EST)
======================================================================
Job: 274972 Area:

/default/main/devnet/WORKAREA/shared Name: EmailTestWorkflow

Description: Demonstration of new iwsend_mail.ipl script
----------------------------------------------------------------------
This Space Available for Advertising Date: Thu Feb 22 10:03:44 2001 Task:
274973 User: MYDOMAIN\jdoe
> Transitioning from first user task to first externaltask using the new
iwsend_mail.ipl
What do you think?
----------------------------------------------------------------------
============================= File list =============================
> move_files.ipl
> deploy.ipl
> rmreplicant.ipl
----------------------------------------------------------------------
Using URL Mode
If the -u option were used in the our example, or the variable mail_url were set to a
non-zero value in the preceding alternative, the message would look like this:

X-Mailer: Mail::Mailer[v1.18] Net::SMTP[v2.15]
Date: Thu, 22 Feb 2001 13:03:20 -0500 (EST)
======================================================================
Job: 274972 (http://tsserver/iw/webdesk/task?taskid=274972)
Area: /default/main/devnet/WORKAREA/shared Name:
EmailTestWorkflow Description: Demonstration of new
iwsend_mail.ipl script
----------------------------------------------------------------------
This Space Available for Advertising Date: Thu Feb 22 10:03:44 2001 Task:
274973 User: MYDOMAIN\jdoe
> Transitioning from first user task to first externaltask using the new
iwsend_mail.ipl
What do you think?
----------------------------------------------------------------------
============================= File list =============================
>
http://tsserver/iw/webdesk/sce?vpath=/default/main/devnet/WORKAREA/shared
/move_files.ipl>
/deploy.ipl>
/rmreplicant.ipl
----------------------------------------------------------------------

Using HTML Mode
If the -H option were used in the our example, or the variable mail_html were set to 1 in
the preceding alternative, the message would look like Figure 22:
Figure 22 Sample email message using HTML mode

Date: Thu 22 Feb 2001 13:03:20 -0500 (EST)
This Space Available for Advertising
Job Details
Job: 274972
Area: /default/main/devnet/WORKAREA/shared
Name: EmailTestWorkflow
Description: Demonstration of new iwsend_mail.ipl script
Job Comments
Date: Thu Feb 22 10:03:44 2001 Task: 274973 User: MYDOMAIN\jdoe
Transitioning from first user task to first externaltask using the new iwsend_mail.ipl
What do you think?
File List
move_files.ipl Thu Feb 22 10:03:40 2001 MYDOMAIN\jdoe Pre-selected file
deploy.ipl Thu Feb 22 10:03:40 2001 MYDOMAIN\jdoe Pre-selected file
rmreplicant.ipl Thu Feb 22 10:03:40 2001 MYDOMAIN\jdoe Pre-selected file

Appendix C
CGI Task Example
This appendix contains a complete, working example of a TeamSite workflow with a

CGI task. The example consists of two parts:
sample_cgi_task.ipl: A simple CGI program written in Perl
cgi_task_test.wft: A workflow template that may be used to exercise a CGI task.
The CGI program is a complete, though fairly simple, example, like a “Hello, World!”
program. However, it also contains code that may be useful in developing and
debugging a CGI program, like a “Snoop” program.
The workflow template is also a complete, though fairly simple, example that can be
used to run the sample CGI program or another CGI program. These two parts can be
used in any combination:
You can use sample_cgi_task.ipl with cgi_task_test.wft as a simple
demonstration of a workflow with a GCI task.
You can make a copy of sample_cgi_task.ipl and use the copy with
cgi_task_test.wft to develop and test a new CGI program.
You can use cgi_task_test.wft as a test harness to test or debug your own CGI
program.
You can use sample_cgi_task.ipl as a temporary substitute for your CGI program
in your own workflow to assist in debugging the workflow.
You can copy useful bits of code from sample_cgi_task.ipl for your own use.
Prerequisites
This document is intended for software developers who plan to develop or maintain CGI
programs that are used in TeamSite workflow. The reader should already be familiar
with the basic concepts and usage of TeamSite, TeamSite workflows, HTML, HTTP,
and Perl.

Appendix C: CGI Task Example
Installation
To install the complete example as is, add an entry to available_templates.cfg for the
cgi_task_test workflow template. For example:
<template_file name="CGI Task Test"

path="examples/cgi_task_test.wft">
<command_list>
<command value="new_job" />
<command value="all" include="no" />
</command_list>
</template_file>
If you intend to make significant changes to the example code to develop your own
program or workflow, it is recommended that you copy the files.
Usage
To use the complete example as is, follow these steps:
1. Login to ContentCenter Professional as an Editor, Administrator or Master.
2. Navigate to any area (workarea, staging area, or an edition).
3. Optionally, select some files. They will not be modified within this workflow.
4. Click New Job, select CGI Task Test, and start the job.
5. A form displays. Answer the questions as you desire, select a transition from the
select list, and then press the OK button. A message displays indicating that the task
is complete.
6. If the Finish Job transition was selected in step 5, then the job has been completed.
7. If the Retry Later transition was selected in step 5, then you have an active user
task. Finish this task and the CGI task will run again. Repeat step 5.
Background
A “CGI program” (or “CGI script”) is a program that is executed on a web server to
handle an HTTP request. It obtains the HTTP request from standard input (if the request
was a POST) and from environment variables, and it writes the HTTP response to
standard output. Within this document, “CGI program” refers specifically to a CGI
program executed as part of a CGI task. TeamSite also uses CGI programs to implement
custom menu items, but those are not covered here.
A “CGI task” is a task of type “cgitask” in a TeamSite workflow. This is a task with user
interaction (via a browser window) to obtain or provide information related to the

workflow process. The properties of the task include its “owner” and “command”,
among others. When a CGI task is active, it can be started. It is always started as a result
of one of the following user actions that produces a server request:
A user selects Start Input Task from the Tasks Details screen in ContentCenter.
A user finishes a user, group, or CGI task that transitions to a CGI task that is
marked immediate and is owned by the same user, or
A user starts a new job, and the job starts with a CGI task that is marked immediate
and is owned by the same user.
The specified CGI program is then executed while impersonating the owner of the CGI
task. The output from this “initial execution” of the program is sent back to the user’s
browser as the response to the HTTP request that started the CGI task. There may be one
or more “subsequent executions” of the program if the output from the CGI program is
an HTML form that sends additional HTML requests back to the CGI program.
It is not necessary to use the same CGI program for both the initial execution in the CGI
task and for any subsequent executions. For simplicity, the sample CGI program serves
both of these roles. Each time it is executed, it looks at the set of request parameters to
determine whether or not it is being run within the context of an initial execution.
A CGI program does not have to be written in Perl. This example is written in Perl, and
the Perl modules TeamSite::WFworkflow and TeamSite::WFtask (part of the standard
TeamSite installation) provide easy access to common functionality.
However, any executable program may be used as long as it fulfills the following
obligations of a CGI program:
It must be installed in the following location:
iw-home/httpd/iw-bin/
It must be executable.
It must write an HTTP response—including a response header— to standard output.
It must notify the server (callback) that the CGI task is finished when appropriate. It
is up to the developer and the desired business logic to decide when the task is
finished. Typically the callback occurs whenever any modifications to the system
associated with the task have been completed.
To do useful work, it usually reads an HTTP request from standard input. But this is
not an absolute requirement.
Sample CGI Program

The sample CGI program produces an HTML page with the simple form (Figure 23).
The form contains three questions (for demonstration purposes), a text area for a
transition comment, a select list with a choice of transitions, a submit (OK) button, a
reset button, and a Cancel button.

Figure 23 CGI Task screen
The CGI program knows for which task it is being run because the parameter task_id
contains the ID of that task. Default answers to the three questions are taken from task
variables on the CGI task.
The Cancel button simply closes the browser window and leaves the task active. The
Reset button is a standard HTML reset button that restores the input fields to their initial
states.
When the form is submitted, the following parameters are sent to the server:
transition will have a value of 0 if Finish Job is selected, or 1 if Retry Later is
selected. The choice of transitions (Finish Job or Retry Later) is hard-wired into
the code.
comment will have the transition comment.
name, quest and color will have the responses to the three questions.
task_id (a hidden field) will have the ID of the CGI task.
session (a browser cookie) will identify the authenticated user.
The only parameter names that are special are task_id and session. The other
parameter names were just selected for this example.
The sample CGI program has a debugging feature that may be switched on and off. Set
the value of the variable $DEBUG to 0 (zero) to turn debugging off or to 1 to turn
debugging on. When debugging is on, the response page (Figure 24) will include
information that may be useful during development or troubleshooting.

Figure 24 CGI task debugging information
This includes key task and job information, form data (essentially, the HTTP parameters
sent to the server), the values received for cookies, and various values from the
environment in which the CGI program was executed. This debugging code also serves
as an example of how some these values can be accessed.
When the form is posted to the server, the CGI program is executed again. Assuming
that the task is still active, the program records the answers to the three questions as task
variables on the CGI task, runs the task callback (using the transition and comment
provided), and then sends an acknowledgement back to the user (Figure 25).
Figure 25 CGI Task completion message

If debugging is on, this acknowledgement also contains debugging information.
Possible Enhancements
In an effort to keep the example simple and easy to read, the example uses basic HTML
with a minimum of formatting and JavaScript. You may want to create a CGI programs
and HTML pages that are much more sophisticated, depending upon your specific
requirements. Here are a few possibilities:
Make the HTML pretty by adding graphics, colors, fonts, tabbing, etc.
For extensive formatting and consistency with other pages, consider using an
external stylesheet.
Add a link to online help, if the users may need additional guidance.
Add input validation (checking for required or allowed values). This could be done
with client-side JavaScript or on the server-side within the CGI program. However,
the latter would require changes to the logic of the CGI program.
Use other Perl modules. The example uses TeamSite::CGI_lite because it is small
and fast, and the example directly prints HTML tags. You may want to use some of
the many third-party Perl modules – such as LWP, CGI (which is very big,) CGI::*,
HTML::*, or HTTP::* – that are documented and available from sites like CPAN and
Perldoc.com. Many of these modules are installed with TeamSite installation.
Use cookies to store preferences or default values.
You can spend endless amounts of time enhancing a simple CGI task, so try to focus on
substance rather than flash. Keep in mind that as your code becomes more extensive and
complicated, it will become harder to maintain.
Sample Workflow Template

When you are developing a CGI program for use within a real workflow, it may be
difficult to create a job and get it to the state where the CGI task becomes active. You
may need to enter values that are only used by other parts of the workflow, and you may
need to set up a test environment with various branches, workareas, files and users. This
can become particularly annoying because the development of a user interface often
involves much iteration as you experiment with different layouts.
The cgi_task_test.wft can be used to demonstrate the sample CGI program. It may
also be used—with minor modification—as a test harness to exercise your own CGI
program. The workflow process (Figure 26) is quite simple:

Figure 26 Workflow process
CGI Test
Start 0: Finish Job End
Try Again
1: Retry Later
Wait for
next test
It runs a CGI task (“CGI Test”) immediately. The CGI task has two successors. The first
(Finish Job) transitions to the end task. The second (Retry Later) transitions to a user
task from which the CGI task can be reactivated. This allows you to test a CGI program
with more than one transition and gives you an opportunity to inspect the state of the job
after the CGI task has been completed.
To give the CGI program some data with which to work, the job instantiation form
prompts for a few inputs; a job description and file comments (if any files are selected).
There are also some hard-wired job and task variables; Department and Product on the
job, and sign and city on the CGI task. You can add any additional inputs that your
CGI program needs.
The job instantiation form (Figure 27) has a Write job spec to: input field
(iw_output_file):
Figure 27 Job instantiation form for a CGI task
When the form is submitted, the system writes a copy of the XML job spec to the
specified file (replacing any earlier version) and starts the job. However, if the Display
job spec instead check box (iw_debug_mode) is selected when the form is submitted, the
system displays the resultant XML job spec instead of creating a job.

Frequently Asked Questions

The following section contains frequently asked questions regarding the use of CGI
tasks.
What is this iw_cgi_wrapper.cgi?
This wrapper facilitates TeamSite impersonation. When a request is received of the form
/iw-bin/iw_cgi_wrapper.cgi/program, the wrapper program iw_cgi_wrapper.cgi is
executed. The wrapper looks at the request for a TeamSite session string that may be
either a request parameter named session or a cookie named session. The wrapper
then executes the wrapped program specified in the URL while impersonating the user
indicated by that session string and gives that program a request that includes the
parameters from the original request. The wrapper relays the response from the wrapped
program back to the client.
The net result of this impersonation is that the CGI program is run by the same user who
started the task (such that the process is owned by that user). If any files are created or
modified by the CGI program, the work appears to have been done by the user. Without
this impersonation, all CGI tasks would appear to be run by the owner of the Web server
process – iwui on UNIX, or SYSTEM on Windows.
How can data be passed from the WFT to the CGI program?
The most explicit way to pass data to a CGI program is by setting task variables on the
CGI task. A CGI program receives input from an HTTP request that include the ID of
the CGI task. From the task ID you can easily access the task’s variables. You can also
access the job ID and, in turn, the job’s variables. You can also access data associated
with another task within the same job—if you know its name—by using the Perl method
TeamSite::WFworkflow::GetTaskByName.
You cannot include command-line arguments in the command attribute of a CGI task as
you can with an external task.
What value should be used for my form’s METHOD?
An HTML page can use either GET or POST to send a request back to the server.
However, POST is recommended for a couple of reasons. First, there may be a limit to
the amount of data that your browser can send via GET. You may not encounter this
limit initially, but if you add fields to your form over time, or if a user enters particularly
long text, you may discover that some data is silently discarded before it reaches the
CGI program. Second, a convention in HTTP is that GET should only be used as a “safe
and independent method”. That is, GET should not take any action other than retrieval,
and repeating the same GET should give the same result.

What is the “immediate” attribute on a CGI task?
If the immediate attribute of a CGI task is "f" (false), a user must explicitly start the
task after it has become active. The task is started by selecting Start in ContentCenter.
If the immediate attribute is "t" (true), the task may start automatically (implicitly).
This can happen when the owner of the task finishes a user, group or other CGI task that
causes the CGI task to become active, or if the CGI task is a start task and the owner of
the task starts the job. If the user does not finish the task (for example, simply closes the
browser), the task can be explicitly started at a later time.
What is the “readonly” attribute on a CGI task?
Setting the readonly attribute to "t" (true) indicates that the task cannot be modified;
that files cannot be added to or removed from the task. It does not mean that the files
attached to the task are readonly.
In a CGI program, where does STDERR go?
Output sent to standard error will be recorded in error.log unless the program
redirects the output. The Troubleshooting section describes this in more detail.
Why are there duplicate values for some request parameters?
For the initial execution of a CGI program, several request parameters are provided in
both the request query string and the request body. The module TeamSite::CGI_lite
combines the values from both of these sources into a single set of request parameters so
those parameters have two values. However, the two values are the same so you can
safely use the first value and ignore the other.
Troubleshooting
If your CGI program does not seem to work at all, try the following:
Check your CGI program for syntax errors by compiling it from the command line.
For example:
iwperl -c -w sample_cgi_task.ipl
Verify that the CGI task in your workflow job is specifying the correct command.
Try to activate the CGI program from a browser (after logging into TeamSite) by
directly entering the URL, for example:
http://server/iw-bin/iw_cgi_wrapper.cgi/sample_cgi_task.ipl or
http://server/iw-bin/sample_cgi_task.ipl
and see what happens. If the CGI program does some error handling, it may return a
more informative response than just the following message:

Server Error
If your CGI program executes but does not produce the desired result, it may be helpful
to inspect the following log files for warnings or errors:
error.log in iw-home/iw-webd/logs/ on Windows, /var/adm/iwui/error_log on
UNIX . If the following message is displayed in your browser:
Internal Server Error
this log should indicate the cause.

iwtrace.log in iw-home/local/logs/ on Windows, in /var/adm/ on UNIX.
iwevents.log (in the same directory as iwtrace.log).

Appendix D
External Task Example
This appendix chapter contains a complete, working example of a TeamSite workflow

with an external task. The example consists of two parts:
sample_external_task.ipl: A simple Perl program for use with an external task.
external_task_test.wft: A workflow template with an external task that uses the
program.
The sample program is a complete, though fairly simple, example, like a “Hello,
World!” program. However, it also contains code that may be useful in developing and
debugging an external task and demonstrates how various types of information may be
accessed.
The workflow template is also a complete, though fairly simple, example that can be
used to run the sample program, or another program. These two parts can be used in any
combination:
You can use sample_external_task.ipl with external_task_test.wft as a
simple demonstration of a workflow with an external task.
You can make a copy of sample_external_task.ipl and use the copy with
external_task_test.wft to develop and test a new external program.
You can use external_task_test.wft as a test harness to test or debug your own
external program.
You can use sample_external_task.ipl as a temporary substitute for your external
program in your own workflow to assist in debugging the workflow.
You can copy useful bits of code from sample_external_task.ipl for your own use.
Prerequisites
This appendix is intended for software developers who plan to develop or maintain
external tasks that are used in TeamSite workflow. The reader should already be familiar
with the basic concepts and usage of TeamSite, TeamSite workflows, and Perl.

Appendix D: External Task Example
Installation
To install the example, add an entry to the available_templates.cfg for the workflow
template. For example:
<template_file name="External Task Test"
path="examples/external_task_test.wft">
<command_list>
<command value="new_job" />
<command value='all' include="no" />
</command_list>
</template_file>
If you intend to make significant changes to the example code to develop your own
program or workflow, it is recommended that you copy the files.
Usage
To use the complete example as is, follow these steps:
1. Login to TeamSite as an Editor, Administrator or Master.
2. Navigate to any area (workarea, the staging area, or an edition).
3. Optionally, select some files. They will not be modified within this workflow.
4. Select New Job, select External Task Test, and start the job.
5. The external task activates immediately and the program executes. TeamSite
displays the Task list with the newly created job (with the active task External
Task) at the top of the list.
6. If you refresh your browser a moment later, instead of seeing the external task you
should then see the user task Wait for next test with the description Iteration
1 of 3. This indicates that the external task has completed and the job has
transitioned to the user task.
7. From the Actions menu next to the user task, select Try Again to activate the
external task a second time. Refresh your browser again to show the user task. The
description of the user task should now be Iteration 2 of 3.
8. Repeat step 6 and the job will complete.
Alternatively, you may select Remove Job from the Actions menu to remove the job at
any time.

Background
An external task, when activated, runs an external program. This is a general escape
mechanism that has been used for many different purposes where automated processing
(without any user interaction) is desired as part of a workflow process. Some examples
of external programs include:
Modifying the contents or the metadata of files.
Adding files to or removing files from a job.
Sending an email message.
Updating a database.
Deploying files.
Changing the properties (such as the owner) of another task within a job.
Branching (automatically selecting the next task).
External task arguments are passed in UTF-8 encoding.
Every external program has its own purpose. Before writing an external program, it is
important to determine in advance exactly what the program is expected to do.
However, there are a few considerations that are unique to an external program run in
this manner.
It may not be necessary to create a new external program for every external task. If the
needs of two external tasks within a workflow, or in different workflows, are similar
enough, they may be able to use the same external program.
An external program does not have to be written in Perl. This example is written in Perl,
and the Perl modules TeamSite::WFworkflow and TeamSite::WFtask (part of the
standard TeamSite installation) provide easy access to common functionality. However,
any executable program may be used as long as it fulfills the following obligations:
It must be executable.
It must be able to handle the command line arguments that are passed to it.
It must be able to run without user interaction.
It must notify the server (callback) that the task is finished when appropriate. It is up
to the developer to decide when the callback should be made. Typically the callback
is made at the end of the program’s execution, but in some situations it may be
desirable for the program to signal the callback earlier.
NOTE
There is a buffer limit of 256 bytes (value key) and 4096 bytes (value) for task and job
variables. This limit is hard-coded into iwserver and cannot be changed. When you
reach the limit, the variable returned produces errors in the code attempting to evaluate
it (for example, as truncated XML or a parse error).

Command Line Arguments

The command element of an external task specifies the full path of the program to be run,
optionally followed by any initial arguments. If one of these initial arguments contains
white space, it must be quoted so as to be treated as a single argument, and if it contains
a quote character then that character must itself be escaped. Because of these
complications, you may prefer to pass information into the program as task variables
instead of arguments, especially if a value being passed in comes from a string whose
contents are unknown to the workflow developer.
When the program is run by the workflow system, the following arguments will be
added after the initial arguments:
The containing job’s ID (as a decimal number).
The ID of the external task (as a decimal number).
The areavpath of the external task.
Each file attached to the task (as an area relative path). The order of the files is the
same as in TeamSite::WFtask::GetFiles, which is usually the order in which the
files were added to the job.
Of those arguments automatically added by the workflow system, the task ID is the only
one that is really needed because all of the additional information (job ID, areavpath and
files) may be obtained from the task. However, the other values are provided as a
convenience.
It is worth noting that a task can potentially have a very large number of files. If the
[workflow] section of the server’s iw.cfg file contains an entry for
external_task_add_filelist set to false, then the list of task files are not added to
the argument list. Although the default value of this parameter is true, it is
recommended that you change it to false, particularly on a Windows server where the
length of the command line can overrun the size of the command buffer.
Importance of the Callback

As indicated earlier, an external program must notify the server (callback) that the task
is finished when appropriate. In order for the workflow to function correctly, this is very
important. The server does not get any indication of when the program has terminated,
so if the callback does not occur the external task remains active. Unless the external
task has a timeout or the job has some concurrent task, the job halts.
In particular, if an error occurs during the execution of the program and causes the
program to terminate before the callback has been made, the job will never make
progress beyond this task. When designing an external program, try to anticipate the
exceptional cases that could arise (such as permission denied while accessing a file) and
handle those situations in a reasonable way. Endeavor to make the program as robust as
possible.

Consider what the workflow should do if an unexpected (or expected) problem occurs
during the execution of the program. Depending upon the purpose of the external task,
you may want the job to continue despite the problem. You may want to include an
explicit “problem” transition from the external task if none of the existing transitions are
appropriate.
Also consider setting a timeout on an external task in case an uncaught error prevents a
successful callback. The timeout can serve as a safety net that keeps the job from
halting. However, be careful not to make the timeout too short. A one-minute timeout
may seem fine during some initial tests, but consider the longest possible execution time
for the worst-case input values (for example, a task with hundreds of files) when the
server is under heavy load.
Although it may seem in opposition to what has previously been stated, it may
sometimes be useful to not have a callback during development and testing of an
external task program. If the external task follows a user task, and the external task does
not modify itself (such as by adding or removing files associated with the task), then
from the Task list, you can use Actions > Take back task on the user task and re-initiate
the external task program.
Logging
Because an external program is designed for background processing, there is no simple
way for it to display messages to a user. When it runs, the owner of the task may not
even be logged into TeamSite. Therefore, the most commonly employed means of
debugging an external program seems to be writing messages to a log file. Because the
server invokes the program, it can be challenging to attach a debugger, but it is possible.
If the program is going to write a lot of data to a log file, it is often desirable to have a
separate file for each execution of the program. This not only eliminates the problem of
trying to figure out where the output from one execution begins and ends in a single log
file; it also eliminates the possibility of interleaved output from concurrent executions.
The sample program creates a separate log file for each execution. It also opens and
closes the log file repeatedly, writing only a small amount of information at a time. This
technique is very inefficient (as compared to opening the file just once), but it ensures
that the output is progressively committed to the file in case the program terminates
unexpectedly.
During the development of an external program, the performance of debugging code

and the size of the log file are generally unimportant. However, you may want to disable
verbose logging before a program goes into production, especially if the program is
going to be invoked frequently.

Sample Program
The sample program sample_external_task.ipl was created for demonstration
purposes. It performs the following processing:
It gets the value of a task variable ITERATION (defaulting to 0), increments the value,
and stores the new value for the task variable.
It gets the value of a task variable MAX_ITERATIONS (defaulting to 1).
It changes the description of another task within the job.
It signals transition 1 if the new value of ITERATION is less than MAX_ITERATIONS;
otherwise it signals transition 0.
When used in conjunction with the sample workflow, the external task controls an
iterative loop where the external task can be executed repeatedly but the number of
iterations cannot exceed the value of MAX_ITERATIONS.
The sample program has a debugging feature that may be switched on and off. Set the
value of the variable $DEBUG to 0 (zero) to turn debugging off or to 1 to turn debugging
on. When debugging is on, the program writes information into a text file that may be
useful during development or troubleshooting (see below). This includes the
command-line arguments, key task and job information, and various values from the
environment in which the program was executed. This debugging code also serves as an
example of how these values can be accessed. Each execution of the program creates a
separate debugging output file in the directory iw-home/tmp/, for example:
iw-home/tmp/sample_external_task_FY9gx
The following page contains a sample debugging output (partial) from the program.
[START 2003-02-06 17:36:57

/usr/iw-home/local/config/wft/examples/sample_external_task.ipl]
Command Line Arguments
1: red
2: white
3: and blue
4: 30735
5: 30736
6: /default/main/test/WORKAREA/jsmith
7: JackAndJill.txt
8: RubADub.txt
Task Information
Task ID: 30736
Name: External Task
Description: Let a user run the external program
Command: /usr/iw-home/iw-perl/bin/iwperl
/usr/iw-home/local/config/wft/examples/sample_external_task.ipl "red"
"white" "and blue"
Area: /default/main/test/WORKAREA/jsmith

Variables
MAX_ITERATIONS: 3
city: Paris
sign: Virgo
Files
JackAndJill.txt
RubADub.txt
Files and File Comments
JackAndJill.txt
Date User Comment Task
Thu Feb 6 17:36:55 2003 jsmith Moved the hill to an urban setting 30736
RubADub.txt
Date User Comment Task
Thu Feb 6 17:36:55 2003 jsmith Changed the tub to a shower 30736
Job Information
Job ID: 30735
Name: External Task Test
Description: Update these well-known stories
Environment
Program Name:
/usr/iw-home/local/config/wft/examples/sample_external_task.ipl
Current User: jsmith
Current Directory: /usr/iw-home
[...snip...]
[END 2003-02-06 17:36:59
/usr/iw-home/local/config/wft/examples/sample_external_task.ipl]
Sample Workflow Template

When you are developing an external program, it may be difficult to create a job and get
it to the state where the external task becomes active. You may need to enter values that
are only used by other parts of the workflow, and you may need to set up a test
environment with various branches, workareas, files, and users.
The external_task_test.wft can be used to demonstrate the sample external program.

It may also be used—with minor modifications—as a test harness to exercise your own
external program. The workflow process (Figure 28) is quite simple:
Figure 28 Workflow process
External Task
Test
Start 0: Finish Job End
Try Again
1: Retry Later
Wait for
next test

It immediately runs the external task. The external task has two successors. The first
(Finish Job) transitions to the end task. The second (Retry Later) transitions to a user
task from which the external task can be reactivated. This allows you to test an external
program with more than one transition and gives you an opportunity to inspect the state
of the job after the external task has been completed.
To give the external program some data to work with, the job instantiation form prompts
for a few inputs; a job description, file comments (if any files are selected), and the
maximum number of iterations. There are also some hard-wired job and task variables;
Department and Product on the job, and sign and city on the external task. You can
add any additional inputs that your program needs.
The job instantiation form (Figure 29) has a Write job spec to: input field
(iw_output_file):
Figure 29 Job instantiation form for an external task
When the form is submitted, the system writes a copy of the XML job spec to the
specified file (replacing any earlier version) and starts the job. However, if the Display
job spec instead check box (iw_debug_mode) is selected when the form is submitted, the
system displays the resultant XML job spec instead of creating a job.

Frequently Asked Questions

The following section contains frequently asked questions regarding use of external
tasks.
How can data be passed from the workflow template to an external

program?
The two most explicit ways of passing data to an external program are by using
command-line arguments and by setting task variables on the external task. One of the
arguments that is automatically passed to an external program is the ID of the external
task. From the task ID, you can easily access the task’s variables, the job ID, and, in
turn, the job’s variables.
External programs often need to access data related to another task within the job. To do
this, the external program needs the task ID of the other task, which unfortunately is not
available to the WFT since the task ID’s are not assigned until the job has been
instantiated. However, if you know the name of a task you can obtain its ID by using the
Perl method TeamSite::WFworkflow::GetTaskByName or the iwgettaskbyname
command. Therefore, it is common for an external task to provide an external program
(either through command-line arguments or task variables) with the name of another
task, so that the program can then obtain the ID of that other task and access its data.
You can also include your own command-line arguments in the command attribute of an
external task. However, you cannot change the command—and therefore cannot change
those arguments—once a job has been instantiated. Also, you have to be careful if one
of arguments may be long or may contain spaces (in which case it would need to be
quoted). Therefore, task variables are recommended over command line arguments.
What value should be used for the “command” attribute on an external

task?
The command specifies the full path of the program to be run when the task is activated,
optionally followed by initial arguments.
On Windows, if the external program is a Perl script, then the command should specify
the full path to the Perl interpreter, with the full path to the Perl script as a command line
argument to the Perl interpreter. For example:
iw-home/iw-perl/bin/iwperl full_path_to_script.ipl initial args
On UNIX the command can just specify the full path to the Perl script, provided that the
script is executable and the #! line has been set correctly to point to the Perl interpreter.
Who is the owner of the process when an external program is run?
On UNIX, the program will be run as the owner of the external task. On Windows, it
runs as the user SYSTEM.

What is the “retry” attribute on an external task?
When an external task is activated, the server tries to spawn a process to execute the
task’s command. If the server fails to spawn a process and the retry attribute is set to "t"
(true, the default), then the server will wait awhile and then try again until it is
successful. It will continue retrying indefinitely. The interval between these attempts is
controlled by the iw.cfg parameter [workflow] external_task_retry_wait which
defaults to 1 minute. The spawn may fail if the system is running low on some
resource, such as swap space, of if the command is not valid.
If the retry attribute is set to "f" (false), then the server will not attempt to spawn a
process more than once for a task. However, if this attempt is unsuccessful the task will
remain active.
NOTE
There is a distinction between a failure to spawn the process for the external program,
and the external program exiting prematurely. The latter case does not cause a retry to
be attempted so the job may halt.
What is the “readonly” attribute on an external task?
Setting the readonly attribute to "t" (true) indicates that the task cannot be modified;
that files cannot be added to or removed from the task. It does not mean that the files
attached to the task are readonly.
Troubleshooting
If your external program does not seem to work at all, try the following:
Check your program for syntax errors by compiling it from the command line. For
example:
iwperl -c -w sample_external_task.ipl
Verify that the external task in your workflow job specifies the correct path to the
program.
If your program runs but does not produce the desired or expected result, try running
your program from the command line. However, this is not always easy to do because
the program typically expects command line arguments that include the ID of a task, and
the task may need to be in a particular state. Some developers include support for an
optional command-line debugging flag (for example, –debug) that enables the program
to be run in a simplified test environment. Alternatively, in order to develop and refine
your code, you could create another program that has similar code but that does not need
to run within a workflow. You could also put the bulk of your code into a shared module
that is used by both versions of the program.

Be aware that when an external program is run by the workflow system, the execution
environment will be different than when you run a stand-alone program. Look for any
dependencies upon the owner of the process, the current directory, the command
processor (shell) or environment variables (including paths used to locate programs and
libraries).
If your program does not run or produces unexpected results, it may also be helpful to
inspect the following log files:
iwevents.log: This log will show whether the external task was in fact activated, if
the callback to the task was received, and which transition was selected.
iwtrace.log: This log may show output that was generated while the program was
running, or other problems report by the TeamSite server.
iwserver.log: This log may show error messages that were reported while the
program was running.


Index
Symbols name (locktask) 116
__ELEM__ directive 73 name (submittask) 110
__INSERT__ directive 77 name (updatetask) 112
syntax 79 name (usertask) 99
__TAG__ directive 74 name (wftask) 117
syntax 79 name (wfvarfinishop) 98
__VALUE__ directive 77 name (wfvarstartop) 98
name (workflow) 89
op (eafinishop) 96
A op (eastartop) 95
activation element 93 op (wfvarfinishop) 98
areavpath element 91 op (wfvarstartop) 97
array validators 72 override 110
ask_va_enabled 137 overwritemode 112
attaching files 63 owner (cgitask) 108
attributes owner (externaltask) 105
comment 93 owner (locktask) 116
creator 90 owner (submittask) 110
delete 112 owner (updatetask) 112
description (cgitask) 108 owner (usertask) 99
description (dummytask) 115 owner (wftask) 117
description (endtask) 114 owner (workflow) 89
description (externaltask) 105 path 93
description (grouptask) 102 readonly (cgitask) 109
description (locktask) 116 readonly (externaltask) 105
description (submittask) 111 readonly (grouptask) 102
description (successorset) 100 readonly (usertask) 100
description (updatetask) 112 retainowner 102
description (usertask) 99 retry 105
description (wftask) 117 savecomments 110
description (workflow) 90 skipconflicts (submittask) 110
immediate 109 skiplocked 110
key 90 start (cgitask) 108
lock (cgitask) 108 start (dummytask) 115
lock (externaltask) 105 start (externaltask) 105
lock (grouptask) 102 start (grouptask) 102
lock (updatetask) 112 start (locktask) 116
lock (usertask) 99 start (submittask) 110
name (cgitask) 108 start (updatetask) 112
name (dummytask) 115 start (usertask) 99
name (eafinishop) 97 start (wftask) 117
name (eastartop) 95, 96 transferonly (cgitask) 109
name (endtask) 114 transferonly (externaltask) 105
name (externaltask) 105 transferonly (grouptask) 102
name (grouptask) 102 transferonly (updatetask) 113

Index
transferonly (usertask) 100 comment attribute 93

unlock 110 Configurable Author Assignment 47
v (command) 106 Configurable Author Submit 48
v (group) 103 Configurable Default Submit 49
v (reset) 95 configurable workflows 131, 132, 135
v (srcareapath) 113 configurable_author_assignment.cfg file 55
v (succ) 92 configurable_author_assignment.wft file 47, 54
v (timeout) 91 configurable_author_submit.cfg file 55
v (user) 103 configurable_author_submit.wft file 48, 54
value 90 configurable_default_submit.cfg file 55
audit trail 159 configurable_default_submit.wft file 49, 54
Author Submit with Deploy 44 configuration 131
Author Submit with Email 45 files 136
Author Submit with Metadata 46 workflows 132
author_assignment.wft template file 24 configuration files 28
author_submit_with_deploy.wft file 44 .cfg 54
author_submit_with_email.wft file 45 .properties 55
author_submit_with_metadata.wft file 46 available_templates.dtd 34
available_templates.cfg file configurable_author_assignment.cfg 55
structure 29 configurable_author_submit.cfg 55
available_templates.dtd file 34 configurable_default_submit.cfg file 55
email_map.cfg 179
B iw.cfg 35, 179
wft_opendeploy.cfg 27
buffer limit, task and job variables 195 wft_opendeploy.ipl 27
wft_opendeploy.xml 27
C workflow 54
callbacks 164 conventions
iwcallback 164 notation 13
TeamSiteCGI_liteiwcallback 165 path name 14
TeamSiteWFtaskCallBack() 164 creator attribute 90
cgi task 161
background 184 D
debugging 162 debugging
demonstrating 40 iw_debug_mode key 151
enhancements 188 iw_output_file key 151
example 183 techniques 166
troubleshooting 191 workflow 151
CGI_info directive 68 workflow log file 152
error_data_bgcolor property 69 default_submit.wft template file 24
error_label_bgcolor property 69 delete attribute 112
error_text_color property 69 delete_jobs_on_completion 36
html_body_options property 69 deployment settings 59
post_tagtable_html property 69 description (cgitask) attribute 108
pre_tagtable_html property 69 description (dummytask) attribute 115
tag_table_options property 69 description (endtask) attribute 114
title property 69 description (externaltask) attribute 105
valid_bgcolor property 69 description (grouptask) attribute 102
cgitask element 107 description (locktask) attribute 116
used with command 106 description (submittask) attribute 111
command element 105 description (successorset) attribute 100
used with cgitask 106 description (updatetask) attribute 112
used with external task 105 description (usertask) attribute 99

Index
description (wftask) attribute 117 variables 90

description (workflow) attribute 90 wftask 116
description element 90 wftfile 118
design 154 wfvarfinishop 98
directives wfvarstartop 97
__INSERT__ 77 workflow 89
__TAG__ 74 workflowinformation 145
__VALUE__ 77 email 132
_ELEM__ 73 customizing 136
CGI_info 68 debugging 148
TAG_info 70 from workflow 144
disable VisualAnnotate 139 header 142
dummytask element 114 HTML and plain text combination 144
html part 143
E plain text part 143
settings 57
eafinishop element 96 template-based 141
eastartop element 95 templates 136
elements
email_map.cfg file 179
activation 93
endtask element 113
areavpath 91
error messages 167
cgitask 107
error_data_bgcolor property 69
command 105
error_label_bgcolor property 69
description 90
error_msg property 71
dummytask 114
example files 136
eafinishop 96
example use case 132
eastartop 95 extended attributes
endtask 113 annotations 56
externaltask 104 external task 159
failure 119 background 195
file 92, 94 callback 196
files 92, 94 command line arguments 196
group 103 debugging 160
grouptask 101 example 193
inactivate 94, 157 logging 197
jobfile 117 troubleshooting 202
locktask 115 URL-based 39
reset 94 external_task_add_filelist 36
resets 157 external_task_retry_wait 36
sharedby 102 externaltask element 104
srcareapath 113 used with command 105
submittask 109
succ 92
success 118 F
successors 100 failure element 119
successorset 100 file comments, retrieving 163
template_script 67 file element 92, 94
timeout 91 files
updatetask 111 configuration 136
user 103 ReadMe 137
usertask 98 workflow properties 138
variable 90 worklow 131, 135
files element 92, 94

Index
flexroles J
callout buttons 42
job specification 17
considerations 41
job specification DTD 84
reviewers 41
job specification files 83
sample 125
G job specifications 17
group element 103 job variable buffer limit 195
grouptask element 101 jobfile element 117
jobs 16
running 129
H
html property 71
html_body_options property 69
K
key attribute 90
I
immediate attribute 109
L
inactivate element 94, 157 label property 71
instantiation window, size 166 localization 64
instantiator CGI 20 lock (cgitask) attribute 108
integrating lock (externaltask) attribute 105
with OpenDeploy 27 lock (grouptask) attribute 102
is_required property 71 lock (updatetask) attribute 112
is_user_in_roles 82 lock (usertask) attribute 99
iw.cfg file 35, 140, 179 locks 158
iwsend_mail parameter 35 external to workflow engine 159
workflow parameter 36 locktask element 115
iw_debug_mode key 151
iw_output_file key 151 M
iw_setwfarg 73
iw_solution_email.ipl metadata capture 58
data flow illustrated 148 settings 58
iwcallback 164 models 15
iwsend_mail.ipl script 169
command line 170 N
composing email message body 174 name (cgitask) attribute 108
email addresses 171 name (dummytask) attribute 115
email sender 173 name (eafinishop) attribute 97
email subject line 173 name (eastartop) attribute 95
error capturing 177 name (endtask) attribute 114
example 179 name (externaltask) attribute 105
HTML formatting 176 name (grouptask) attribute 102
messages, constructing 170 name (locktask) attribute 116
multiple email recipients 172 name (submittask) attribute 110
next task 177 name (updatetask) attribute 112
parameters 169 name (usertask) attribute 99
task variable usage 170 name (wftask) attribute 117
URL formatting 175 name (wfvarfinishop) attribute 98
name (wfvarstartop) attribute 98
name (workflow) attribute 89
notation conventions 13
notifications 165

Index
O R
op (eafinishop) attribute 96 ReadMe files 137
op (eastartop) attribute 95 readonly (cgitask) attribute 109
op (wfvarfinishop) attribute 98 readonly (externaltask) attribute 105
op (wfvarstartop) attribute 97 readonly (grouptask) attribute 102
OpenDeploy readonly (usertask) attribute 100
integration 27 regular expressions 33
solutions workflows 27 path separators 33
override attribute 110 reset element 94
overwritemode attribute 112 resets element 157
owner (cgitask) attribute 108 retainowner attribute 102
owner (externaltask) attribute 105 retry attribute 105
owner (locktask) attribute 116 review cycles 137
owner (submittask) attribute 110 review settings 60
owner (updatetask) attribute 112 review_cycles 137
owner (usertask) attribute 99
owner (wftask) attribute 117 S
owner (workflow) attribute 89
savecomments attribute 110
serial_approval.wft file 25
P server-side workflow subsystem 21
parameters sharedby element 102
iwsend_mail 35 show_save_button 138
workflow 36 skipconflicts (submittask) attribute 110
path attribute 93 skiplocked attribute 110
path name conventions 14 solutions workflows 23
Perl modules 120 activating 25
TeamSiteWFsystem 120 attaching files 63
TeamSiteWFtask 122 author_submit_with_deploy.wft file 44
TeamSiteWFworkflow 121 author_submit_with_email.wft file 45
Perl scripts author_submit_with_metadata.wft file 46
iwsend_mail.ipl 169 configurable_author_assignment.wft file 47, 54
permit_add_locked_files_to_locking_tasks 36 configurable_author_submit.wft file 48, 54
ports 140 configurable_default_submit.wft file 49, 54
VisualAnnotate 140 deployment 59
post_tagtable_html property 69 email notification 57
pre_tagtable_html property 69 enabling 23
presubmit_check 36 localization 64
properties metadata capture 58
error_data_bgcolor 69 OpenDeploy, integrating 27
error_label_bgcolor 69 review 60
error_message 71 settings 56
error_text_color 69 solutions workflows, <em>See</em>
html 71 configurable workflows 131
html_body_options 69 srcareapath element 113
is_required 71 start (cgitask) attribute 108
label 71 start (dummytask) attribute 115
post_tagtble_html 69 start (externaltask) attribute 105
pre_tagtable_html 69 start (grouptask) attribute 102
tag_table_options 69 start (locktask) attribute 116
title 69 start (submittask) attribute 110
valid_bgcolor 69 start (updatetask) attribute 112
valid_input 71 start (usertask) attribute 99
start (wftask) attribute 117

Index
submittask element 109 V

succ elements 92 v (command) attribute 106
success element 118 v (group) attribute 103
successors element 100 v (reset) attribute 95
successorset element 100 v (srcareapath) attribute 113
v (succ) attribute 92
T v (timeout) attribute 91
TAG_info directive 70 v (user) attribute 103
array validators 72 va_create_snapshots 138
error_msg property 71 va_default_page 138
html property 71 va_enabled 137
is_required property 71 va_show_cycles 138
iw_setwfarg_ 73 va_show_live_option 138
label property 71 va_show_reviewers 138
valid_input property 71 va_show_snapshots 138
tag_table_options property 69 valid_bgcolor property 69
task variable buffer limit 195 valid_input property 71
task_areavpath_file_access_check 36 value (eafinishop) attribute 97
tasks 17 value (eastartop) attribute 96
cgi 183 value (wfvarfinishop) attribute 98
external 193 value (wfvarstartop) attribute 98
TeamSiteWFtask module 122 value attribute 90
TeamSiteWFtaskCallBack() 164 variable element 90
TeamSiteWFworkflow module 121 variables
template_script element 67 ask_va_enabled 137
template-based email 141 buffer limit 195
templates review_cycles 137
workflow 17 show_save_button 138
terminology, workflow 15 va_create_snapshots 138
test VisualAnnotate 140 va_default_page 138
timeout element 91 va_enabled 137
title property 69 va_show_cycles 138
toolbar 132 va_show_live_option 138
activation of 132 va_show_reviewers 138
transferonly (cgitask) attribute 109 va_show_snapshots 138
transferonly (externaltask) attribute 105 which_snapshot 138
transferonly (grouptask) attribute 102 variables element 90
transferonly (updatetask) attribute 113 VisualAnnotate 56
transferonly (usertask) attribute 100 disable 139
transitions 18 extended attributes 56
tutorials introduced 56
workflow 153 ports 140
test 140
variables 137
U workflow settings 136
unlock attribute 110
updatetask element 111
use case 132
user element 103
usertask element 98

Index
W workflow tutorial 153, 154

WFsystem module 120 audit trail 159
wft_opendeploy.cfg file 27 callbacks 164
wft_opendeploy.ipl file 27 cgi task 161
wft_opendeploy.xml file 27 debugging techniques 166
wftask element 116 error messages 167
wftask_nesting_depth_allowed 36 external task 159
wftfile element 118 file comments, retrieving 163
wfvarfinishop element 98 inactivate 157
wfvarstartop element 97 information, prompting for 166
which_snapshot 138 instantiation window 166
workflow 132, 136 locks 158
components 18 mapping workflows 156
configuration files 28, 54 notifications 165
debugging 151 requirements 154
designing 154 resets 157
email task 144 task symbols 154
enabling solution workflows 25 terms 153
job specification 17
job specification files 83
job specifications 17
jobs 16
model 15
properties files 138
requirements 154
schematic of 19
solutions 23
tasks 17
template file 66
template files 65
terminology 15
terms 153
transitions 18
variables 136
VisualAnnotate 56
workflow element 89
workflow log file 152
workflow template 20
workflow template files 65
workflow templates 17
author_assignment.wft 24
default 24
default_submit.wft 24
examples 24
regular expressions 33
sample 23
serial_approval.wft file 25
structure 65

Index

Ts 671sp1 Wfdev v01 en

Încărcat de

Informații document

Descriere originală:

Titlu original

Drepturi de autor

Formate disponibile

Partajați acest document

Partajați sau inserați document

Opțiuni de partajare

Vi se pare util acest document?

Este necorespunzător acest conținut?

Drepturi de autor:

Formate disponibile

Ts 671sp1 Wfdev v01 en

Încărcat de

Drepturi de autor:

Formate disponibile

TeamSite ®

Interwoven, ConfirmSite, ContentServices, ControlHub, DataDeploy, DeskSite, FileSite, iManage,

TeamSite Workflow Developer’s Guide

TeamSite Workflow Developer’s Guide 3

Chapter 3: Using Solution Workflows 43

Chapter 5: Job Specification Files 83

TeamSite Workflow Developer’s Guide 5

TeamSite Workflow Developer’s Guide 7

VisualAnnotate Port Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .140

Prompting for Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .166

TeamSite Workflow Developer’s Guide 9

Appendix C: CGI Task Example 183

TeamSite Workflow Developer’s Guide 11

Table 1 Notation Conventions

TeamSite Workflow Developer’s Guide 13

Table 1 Notation Conventions (Continued)

Notation of iw-home on UNIX and Windows

Windows Path Name Conventions

For example, instead of:

you can try:

This chapter provides a high-level overview of workflows. Later chapters examine

Figure 1 shows a simple assign-edit-approve workflow model. Email is sent to the

TeamSite Workflow Developer’s Guide 15

Figure 1 Workflow model of an Author Assignment business process

Editor Task: Task: Task:

Reject Task: Approve Task:

Figure 2 Workflow with assigned users

Reject Task: Approve Task:

In TeamSite, a description of a workflow model is called a workflow template. When a

The configuration file available_templates.cfg lists all the workflow templates

TeamSite Workflow Developer’s Guide 17

A workflow can have a maximum of 1000 transitions.

Figure 3 Workflow Components

In TeamSite ContentCenter Professional, an end user selects a workflow template from

TeamSite Workflow Developer’s Guide 19

Browser Interface (GUI)

Server-Side Workflow Subsystem

TeamSite Workflow Developer’s Guide 21

 Execution: instantiating and executing a workflow template file or executing a job

These templates are described in “Default Template Descriptions” on page 24.

These templates are described in “Example Template Descriptions” on page 24.

These templates are described in Chapter 3, “Using Solution Workflows.”

TeamSite Workflow Developer’s Guide 23

Default Template Descriptions

Example Template Descriptions

To make the example files available to end-users, you must edit

The following example templates reside in iw-home/local/config/wft/examples:

TeamSite Workflow Developer’s Guide 25

b. Ensure that iw-home/local/config/ contains datacapture.cfg and

c. Ensure the mt-home/conf/metatagger.cfg file contains the desired entries. See

Integrating with OpenDeploy

These files are installed in iw-home/local/config/wft/solutions.

Complete the following steps to configure the deployment integration:

TeamSite Workflow Developer’s Guide 27

source branch destination path destination node name

the /default/main/web/DE entry is used.

Workflow Configuration Files

 available_templates.dtd—File used by available_templates.cfg that contains

Additionally, workflow configuration settings must be made in the main TeamSite

By default, the available_templates.cfg file is located in:

require_workarea—specify whether (true) or not (false) workflow templates

Within the available_templates element is the template_file element:

Execution: instantiating and executing a workflow template file or executing a job

available_templates.dtd—File used by available_templates.cfg that contains

active—indicate whether (yes) or not (no) the workflow template is enabled.

C:\Program Files\Interwoven\TeamSite\local\config\wft (Windows servers)