Teamsite Workflow Dev Guide ts.650.wf

TeamSite®
Workflow Developer’s
Guide
Release 6.5
© 1997-2004 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, TeamSite, Content Networks, OpenDeploy, MetaTagger, DataDeploy, DeskSite, iManage,

MailSite, MediaBin, MetaCode, MetaFinder, MetaSource, OpenTransform, Primera, TeamPortal,
TeamXML, TeamXpress, VisualAnnotate, WorkKnowledge, WorkDocs, WorkPortal, WorkRoute,
WorkTeam, the respective taglines, logos and service marks are trademarks of Interwoven, Inc., which
may be registered in certain jurisdictions. All other trademarks are owned by their respective owners.
Some or all of the information contained herein may be protected by patent numbers: US # 6,505,212, EP
/ ATRA / BELG / DENM / FINL / FRAN / GBRI / GREC / IREL / ITAL / LUXE / NETH / PORT /
SPAI / SWED / SWIT # 1053523, US # 6,480,944, US# 5,845,270, US #5,384,867, US #5,430,812,
US #5,754,704, US #5,347,600, AUS #735365, GB #GB2333619, US #5,845,067, US #6,675,299,
US #5,835,037, AUS #632333, BEL #480941, BRAZ #PI9007504-8, CAN #2,062,965, DENM / EPC
/ FRAN / GRBI / ITAL / LUXE / NETH / SPAI / SWED / SWIT #480941, GERM #69020564.3,
JAPA #2968582, NORW #301860, 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,845,270, US #5,923,785, US #5,982,938,
US #5,790,131, US #5,721,543, US #5,982,441, US #5,857,036, GERM #69902752.7 or other
patents pending application for Interwoven, Inc.
This Interwoven product utilizes third party components under the following copyrights with all rights
reserved: Copyright 1997 Eric Young; Copyright 2000-2003, Apache Software Foundation
(www.apache.org); Copyright 1999, ExoLab Group; Copyright 1999-2001, Intalio, Inc. If you are
interested in using these components for other purposes, contact the appropriate vendor.
Interwoven, Inc.
803 11th Ave.
Sunnyvale, CA 94089
http://www.interwoven.com
Printed in the United States of America
Release 6.5.0
Part #90-11-00-650-210
October 2004
Table of Contents
About This Book 11
Notation Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Notation of iw-home on UNIX and Windows Systems. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Windows Path Name Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
What’s In This Manual . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Chapter 1: Introduction 15
Workflow Terminology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Workflow Models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Jobs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Workflow Templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Job Specification Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Workflow Illustrated. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Workflow Template File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Instantiator CGI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Browser Interface (GUI) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Job Specification File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Server-Side Workflow Subsystem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Chapter 2: Using Workflows 21

Default Template Descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Example Template Descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Enabling Workflows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Integrating with OpenDeploy. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Workflow Configuration Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
The available_templates.cfg File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
The available_templates.dtd File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
The available_templates.ipl File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
The iw.cfg File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
[iwsend_mail] Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
[workflow] Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Querying Workflows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
Chapter 3: Using Solution Workflows 39

Solutions Workflows Illustrated . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
Author Submit with Deploy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
Author Submit with Email . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Author Submit with Metadata. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Configurable Author Assignment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
Configurable Author Submit. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
Configurable Default Submit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
3
Review Subflows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
Serial Review. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
Concurrent Review . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
Configurable Workflow Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
Workflow-Specific Configuration Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
Workflow.cfg File Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
Workflow.properties File Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
VisualAnnotate and Configurable Workflows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
Configurable Workflow Settings. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Email Notification Settings. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Metadata Capture Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
Deployment Settings. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
Review Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
Add Files Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
Configurable Workflows and Localization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
Chapter 4: Workflow Components 59

Workflow Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
Tasks. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
Transitions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
Conditions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
Task Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
Dummy Task Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
Email Task Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
End Task Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
External Task Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
Group Task Attributes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
Lock Task Attributes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
Nested Job Task Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
Submit Task Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
Update Task Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
User Task Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
Workflow Attributes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
WorkflowBuilder Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
Dynamic Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
User Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
System Variables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
Custom Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
Nested Workflow. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
4 Workflow Developer’s Guide

Chapter 5: Using WorkflowBuilder 75
Installation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
Installing the WorkflowBuilder Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
Installing the WorkflowBuilder Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
Uninstalling WorkflowBuilder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
WorkflowBuilder Graphical User Interface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
Toolbars . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
View Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
Getting Started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
Logging In . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
Viewing Sample Workflow Templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
Creating New Jobs and Workflow Templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
Placing Tasks on the Canvas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
Drawing Transitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
Adding Conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
Adding Text Labels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
Moving Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
Selecting Multiple Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
Aligning Objects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
Setting Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
Setting Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
Configuring Templates to Include Preselected Files . . . . . . . . . . . . . . . . . . . . . . . . . . 92
Editing Existing Workflow Templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
Sending Workflow Templates to the Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
WorkflowBuilder and available_templates.cfg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
Workflow Template Constraints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
Workflow Template Type Constraints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
User Constraints. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
Branch Constraints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
Defining a Workflow Constraint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
Effects on available_templates.cfg File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
Retrieving Files from the Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
Deleting Files from the Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
WorkflowBuilder Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
5
Chapter 6: Creating Workflow Template Files 107
Workflow Template File Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
Simple Workflow Template File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
<template_script> Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
CGI_info Directive. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
TAG_info Directive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
__ELEM__ Directive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
__TAG__ Directive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
__INSERT__ Directive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
__VALUE__ Directive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
Other Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
Using Variables in Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
Complex Workflow Template File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
Regular Expression Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
Path Separators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
Chapter 7: Job Specification Files 127

Job Specification File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
Job Specification DTD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
The workflow Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
The description Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
The variables Element. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
The areavpath Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
The timeout Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
The succ Subelement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
The files and file Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
The activation Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
The inactivate Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
The resets Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
The eastartop Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137
The eafinishop Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
The wfvarstartop Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
The wfvarfinishop Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
The usertask Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140
The successors Element. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141
The grouptask Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142
The sharedby Element. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
The user Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144
The group Element. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144
The externaltask Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145
The command Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
The cgitask Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
The submittask Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150
The updatetask Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151
The srcareapath Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
The endtask Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
The dummytask Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154
The locktask Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155

The wftask Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
The jobfile Element. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
The wftfile Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
The success Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158
The failure Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158
Perl Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159
TeamSite::WFsystem. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159
TeamSite::WFworkflow. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160
TeamSite::WFtask. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
Sample Job Specification File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
Running Manually Created Jobs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169
Chapter 8: Using VisualAnnotate 171

Task Checklist for Using VisualAnnotate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171
VisualAnnotate Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172
Sample Scenario . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172
Installing the VisualAnnotate Client Toolbar. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174
Configuring VisualAnnotate. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175
Email Template Settings. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176
Prompt Initiator Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
Review Cycles Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
Variables Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
Approval Label Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178
Disabling VisualAnnotate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179
Preserving Images In Snapshots. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179
Editing the Administrator Email Address . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180
VisualAnnotate Port Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180
Testing the VisualAnnotate Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180
Chapter 9: Template-Based Email 181

How Template-Based Email Works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181
The Header . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182
The HTML Part . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183
The Plain Text Part . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183
Using HTML and Plain Text in Combination . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183
Use in Workflows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184
The Structure of the XML Document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
Template Creation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187
Debugging. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188
iw_solution_email.ipl Data Flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189
Chapter 10: Debugging Techniques 191

Debugging Workflow Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191
iw_debug_mode. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191
iw_output_file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191
Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192
Workflow Log File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192
7
Appendix A: Workflow Tutorial 193
Terms. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193
Task Symbols. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
Mapping Out Workflows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195
Resets and Inactivate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197
Locks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198
Locks External to Workflow Engine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198
Audit Trail Archival . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198
Complex Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198
externaltask. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199
cgitask . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201
Retrieving File Comments. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203
Callbacks. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203
Sending Email Notification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205
Prompting for Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206
Setting the Size of the Instantiation Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206
Debugging Techniques . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207
Error Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208
Active Workflow with No Active Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208
Designing a Workflow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209
Determine Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209
Diagram the Workflow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209
Use Existing Workflows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209
Begin Customized Implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209
Document Your Work. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210
Sample Workflows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210
Sample Workflow 1: Serial Workflow with Deployment . . . . . . . . . . . . . . . . . . . . . 211
Sample Workflow 2: Concurrent Workflow with Optional Task . . . . . . . . . . . . . . . . 223
Appendix B: WorkflowBuilder Tutorial 233

Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233
Setting up the Tutorial Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234
Tutorial Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234
Development . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234
Deployment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236
Instantiation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236
Creating a New Workflow. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237
Variables Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239
Naming Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239
Custom Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239
Creating the sOwner Variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239
Creating the uDescription Variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240
Creating the cArea_VPath Variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240
Creating the cUnlockFile Variable. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241
Creating the uAuthor Variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241
Creating the cNested_Job Variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241

Defining Custom Variables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242
Specifying Workflow Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243
Specifying Task Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244
Specifying Transitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247
Printing Your Template . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248
Saving Your Template . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249
Sending Your Template to the TeamSite Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250
Testing Your Work . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251
Appendix C: iwsend_mail.ipl Script 253

Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253
Constructing Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254
Command Line Vs. Task Variable Usage. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254
Determining Email Addresses. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255
Sending to Multiple Recipients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256
Specifying the Sender . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256
Specifying the Subject Line. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257
Composing the Message Body. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257
URL Formatting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259
HTML Formatting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259
Next Task Information. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260
Enabling Error Capturing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260
iwsend_mail.ipl Workflow Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262
Associated File Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262
Workflow Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262
Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263
Appendix D: CGI Task Example 267

Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268
Installation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268
Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268
Background . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269
The Sample CGI Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270
Possible Enhancements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272
The Sample Workflow Template. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273
Frequently Asked Questions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275
Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277
9
Appendix E: External Task Example 279
Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279
Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279
Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280
Background. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281
Command Line Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282
The Importance of the Callback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282
Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283
The Sample Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284
The Sample Workflow Template . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286
Frequently Asked Questions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288
Troubleshooting. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289
Index 291

About This Book
The Workflow Developer’s Guide is a guide to configuring and using TeamSite workflow and
Interwoven WorkflowBuilder. This document is primarily intended for TeamSite
Administrators and Master users, and workflow developers.
Notation Conventions
This manual uses the following 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 example:
italic
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/index.html
11
Convention Definition and Usage
Monospaced Monospaced bold italic text is used to indicate a variable in user input.
bold italic
For example:
>iwextattr -s project=projectname workareavpath
means that you must insert the values of projectname and

workareavpath when you enter this command.
[] Square brackets surrounding a command-line argument mean that the
argument is optional.
| Vertical bars separating command-line arguments mean that only one
of the arguments can be used.
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.

What’s In This Manual
What’s In This Manual

This manual contains the following information:
! Chapter 1, “Introduction,” provides an overview of TeamSite workflow and
terminology.
! Chapter 2, “Using Workflows,” describes the workflow tht are provided with TeamSite
and describes how to make them available for use.
! Chapter 3, “Using Solution Workflows,” describes the category of workflows called
solution workflows and shows how to use the properties and configuration files shipped
with these workflows.
! Chapter 4, “Workflow Components,” describes the various workflow components such
as task attributes, variables, transitions, and so forth.
! Chapter 5, “Using WorkflowBuilder,” describes how to istnall and use the
WorkflowBuilder interface to create workflows.
! Chapter 6, “Creating Workflow Template Files,” tells how to write the workflow
template (.wft) files.
! Chapter 7, “Job Specification Files,” describes how to write jobs using the job
specification DTD.
! Chapter 8, “Using VisualAnnotate,” describes how to use the VisualAnnotate feature for
approving jobs in workflows.
! Chapter 9, “Template-Based Email,” describes how to set up email from workflows.
! Chapter 10, “Debugging Techniques,” contains debugging information.
! Appendix A, “Workflow Tutorial,” provides a tutorial for creating a workflow.
! Appendix B, “WorkflowBuilder Tutorial,” provides a tutorial for usig WorkflowBuilder.
! Appendix D, “CGI Task Example,” provides an example of creating a CGI task.
! Appendix E, “External Task Example,” provides an example of creating an external task.
13
Chapter 1
Introduction
Workflow encompasses the procedures, tasks, people, and equipment that define business
practices 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
may have more general definitions outside of the context of TeamSite.
Tasks
A task is a unit of work performed by a single user or process. Each task is associated with a
TeamSite branch and workarea and 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).
Additionally, 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 the task. After an external task has been activated,
the appropriate external program can run on the files contained in the task. Inactive tasks
are tasks that have been completed, or that have not been activated yet.
Note: A workflow task cannot have more than 512 predecessors.
Workflow Models
A workflow model is a general workflow specification that can be used repeatedly. Each
workflow model describes a process that can include user tasks and a wide variety of
automated tasks. Workflow models typically are designed by business managers and
configured by a system administrator or Interwoven Client Services (http://
www.interwoven.com/services).
15
Introduction
The following graphic shows a simple assign-edit-approve workflow model. Email is sent to
the participants at each stage of the process, and an automated task is performed at the end.
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
Figure 1: Workflow model
Note that the people involved are not actual people, but are represented as an editor and an
author, also note that no specific files are mentioned. This is an important distinction
between the generalized workflow model and the job instance described in the next section.
Jobs
A job is a specific instance of a workflow model containing a set of interdependent tasks.
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.
In TeamSite, a description of a workflow model is called a job specification. When a job

specification is loaded into the workflow subsystem it becomes a job instance. Each job is a
specific instance of a workflow model. When a job is created, the job creator must supply
all the specific information for that job.
The following graphic shows the workflow model depicted in the previous section being
used for the marketing Web site’s new product launch. Note that the job specification
includes specific TeamSite users: Andre (the editor) and Pat (the author), and specific files
that need to be edited: index.html and banner.gif.

Workflow Illustrated
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
Figure 2: Workflow with assigned users
Because jobs follow predefined workflow models, tasks cannot be added to or removed
from individual jobs.
You may find it helpful to refer to Chapter 3, “Using Solution Workflows,” for diagrams
showing actual workflows that are provided with TeamSite.
Workflow Templates
Workflow templates are XML files that describe a particular workflow model. You can create
these files using WorkflowBuilder, then transfer them to your TeamSite server where they
can be used to create a new job.
Note: The term workflow template is sometimes used to describe either a file that describes
a workflow model or a file that describes a particular job instance. Both types of file
end with the .wft extension.
Job Specification Files

Job specification files are XML files that describe a specific job. You can create these files using
WorkflowBuilder, then transfer them to your TeamSite server where they are immediately
invoked.
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. Workflow templates are
typically created using WorkflowBuilder as described in , “Using WorkflowBuilder”.
17
Introduction
! Instantiator CGI—Interprets the workflow rules and data from end users, produces
browser graphics and prompts, 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 instantiator CGI.
! Server-side workflow subsystem—Provides a framework for controlling processes
involved with these.
The following graphic 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.
Workflow
Template File
Workflow markup
General workflow
configuration
instructions
2 5
1 Instantiator CGI
Reads workflow markups
Browser
Generates forms Job Specification Server-Side
End user selects
Workflow
template from GUI 3 Compares data with WF
rules
6 Job-specific rules
Can optionally be 7 Subsystem
Combines data with WF written to an XML Runs jobs
End user fills in WF
instructions file
form
4 Generates job specification
and instantiates job
Figure 3: Workflow Components
1. In TeamSite ContentCenter Professional, an end user selects a workflow template from

the Actions > New Job menu item. The instantiator CGI reads the file
available_templates.cfg to determine which workflow template files are available
for that given TeamSite area or file content.
2. The instantiator CGI goes to the specified workflow template file and reads the
workflow markup, which consists of Perl instructions residing in the workflow template
file’s <template_script> elements. See “<template_script> Element” on page 109
for details about syntax and usage.
3. Based on the workflow markup, the instantiator CGI creates one or more workflow
forms into which an end user can enter workflow configuration information using a
ContentCenter Professional.

4. An end-user using TeamSite ContentCenter Professional enters information in the

workflow form and submits it back to the instantiator CGI.
5. 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 instantiator CGI (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).
6. After determining that the workflow form contains valid data, the instantiator CGI
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 7, “Job Specification Files.”
When a job specification file is not created (which is typically the case), the instantiator
CGI 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 107. For an example of a job
specification file, see “Sample Job Specification File” on page 165.
7. The job is instantiated on the server and started. These are actions you would execute
manually (via iwjobc and iwinvokejob) as described in “Running Manually Created
Jobs” on page 169.
The following sections provide more details about each diagram component.
Workflow Template File

A workflow template file 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 17. See
“Workflow Template File Structure” on page 107 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
instantiator CGI as Perl code. See “Workflow Template File Structure” on page 107 for
details and a sample file illustrating these concepts.
19
Introduction
Instantiator CGI
TeamSite includes a standard instantiator CGI, iwwft_instantiator.cgi, to perform the
following tasks:
! 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.
Browser Interface (GUI)

The browser-based GUI is a standard ContentCenter interface through which end users can
enter data in a workflow form. Instructions in this manual refer to using a ContentCenter
interface.
Job Specification File

For an explanation of file structure and supported element syntax, see “Job Specification
File” on page 127. See “Sample Job Specification File” on page 165 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.

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 22.
! iw-home/local/config/wft/examples/
" author_assignment_with_nested_job.wft
" cgi_task_test.wft
" concurrent_approval.wft
" external_task_test.wft
" serial_approval.wft
These templates are described in “Example Template Descriptions” on page 22.
! 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.”
Note: Do not use the WorkflowBuilder user interface to modify these installed
workflows.
21
Using Workflows
Default Template Descriptions

The following workflow templates are installed in iw-home/local/config/wft/default:
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 “The available_templates.cfg File” on page 28.

Enabling Workflows
The following example templates reside in iw-home/local/config/wft/examples:
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 107.
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 now 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 28).
3. Add an entry for each new workflow.
23
Using Workflows
For example, to add the Author Submit Workflow workflow, add the following entry:
<template_file name="Author Submit Workflow"
path="solutions/author_submit.wft">
<command_list>
<command value="submit"/>
<command value="all" include="no"/>
</command_list>
<role_list>
<role value="author" include="yes" allusers="yes"/>
<role value="all" include="no" allusers="yes"/>
</role_list>
</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 51.
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.

Enabling Workflows
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.
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 correspond-
ing 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 26 for detailed information about these
entries.
25
Using Workflows
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 the last three lines wft_opendeploy.cfg file to reflect the mapping between the
branch name containing the file to be deployed and the destination.
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 node name destination path
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.

Workflow Configuration Files
For example, if there are entries for three branches in the following order:
/default/main/web
/default/main/web/UK
/default/main/web/DE
and files are deployed from /default/main/web/DE/STAGING, the
/default/main/web entry is used. However, if the entries are reversed:
/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.

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.
! available_templates.dtd—File used by available_templates.cfg that contains a
collection of declarations (elements and attributes) that describe the expected
document structure.
! available_templates.ipl—Perl file installed as part of the TeamSite installation
procedure that parses the available_templates.cfg file and returns the names of
templates that are valid for the current user.
The available_templates.ipl is not user-configurable. All modifications—whether
made manually with a text editor or with WorkflowBuilder—are made to the
available_templates.cfg file.
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 6, “Creating
Workflow Template Files.”
27
Using Workflows
The available_templates.cfg File

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.
All available templates begin with a template_file element using the following format:
File Name
<template_file name='Author Submit Workflow' path='default/author_submit.wft'>
Title File Location
Where the file location (path=) refers to one of the three workflow template directories
created by the TeamSite installation program:
! iw-home/local/config/wft/default
! iw-home/local/config/wft/examples
! iw-home/local/config/wft/solutions
In addition to the template_file element, each workflow template includes rules defined
in the following two subelements:
! command_list
! role_list
Each subelement determines if the workflow is started when end-users match the
configuration of the subelement by having a value of yes. The workflow is started only if the
results of all subelements are yes.
Additionally, the following two subelements can be added to any of the template_file
elements in available_templates.cfg. These optional subelements offer additional
control when determining when workflows are started:
! user_list
! branch_list
Each of these subelements are described in the sections that follow.

command_list element
The commmand_list subelement specifies the user-activity that starts the corresponding
workflow. For example, the following code specifies that the associated workflow is started
when performing a Submit and that it cannot be invoked by other means:
<command_list>
<command value='submit' />
<command value='all' include='no' />
</command_list>
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)
! new_TFO_job (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 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_list element
The role_list subelement specifies access to workflows based on user role. For example
the following code specifies that if the user is logged in as a Master (that is, users with an
entry in the master.uid file), do not make the associated workflow template available. All
other roles can access the template.
<role_list>
<role value="master" include="no" allusers="no"/>
<role value="all" include="yes" allusers="no"/>
</role_list>
The allusers="no" qualifies the fact that all other roles are allowed but you should have a
valid user from the <user_list> element.
In the case where <role value="all" include="yes" allusers="yes"/> then even if

you appear invalid as defined by the user element, the role element has precedence over
the <user_list> element.
29
Using Workflows
user_list element
The user_list subelement specifies access to workflows based on user names. For
example, the following code means if the user is Joe, display the associated template,
otherwise do not display it.
<user_list>
<user value="joe" include="yes"/>
<user value="all" include="no"/>
</user_list>
The following code means if the user is Joe or Jane, do not display the associated template.
Because no other users are specifically identified, the form is not displayed for any other
users (this is added by default, as defined in available_template.dtd).
<user_list>
<user value="joe" include="no"/>
<user value="jane" include="no"/>
</user_list>
The following code means if the user is Joe, do not display the associated template. If it is
any other user, display it.
<user_list>
<user value="joe" include="no"/>
<user value="all" include="yes"/>
</user_list>
branch_list element
The branch_list subelement specifies access to workflow templates based on TeamSite
branch. For example, consider a Master user named Jerome, logged in to TeamSite as
follows, attempting a submit command.
role = "master";
user = "jerome";
branch = "/default/products";
command = "submit";

The following available_templates.cfg file is processed by the

available_templates.ipl program (the processing sequence and results of the request
are described following the file on page 31).
<available_templates>
<template_file active="yes" name="Custom" path="wfb/
custom_submit.wft"/>
<command_list>
<command include="no"value="new_job"/>
<command include="yes"value="all"/>
</command_list>
<role_list>
<role allusers="no"include="yes"value="administrators"/>
<role allusers="no"include="no"value="authors"/>
<role allusers="yes"include="yes"value="masters"/>
<role allusers="no"include="no"value="editors"/>
</role_list>
<user_list>
<user include="yes"value="jerome"/>
<user include="no"value="all"/>
</user_list>
<branch_list>
<branch value="all"include="yes"/>
</branch_list>
</template_file>
</available_templates>
The available_templates.ipl program checks the header of the

available_templates.cfg to find the associated DTD file. In this case, the DTD specified
is available_templates.dtd.
1. The available_templates.ipl program checks the active attribute and proceeds

because the value is "yes".
2. It then checks the command_list element.
The command rules in this example state to display the template for all types except
new_job; therefore, since the example input is command="submit", it returns "true".
3. It then checks the roles_list element.

The roles rules specify that:
" Some administrators are allowed (if they are listed in the user_list element)
" No authors are allowed
" All masters are allowed
" No editors are allowed.
This rule, when applied to the role of master in this example, returns "true".
The available_templates.ipl program only checks the user_list element for
roles in which allusers="no".
4. Lastly, the branch_list element is checked.
31
Using Workflows
In this example, all branches are allowed. Therefore the rules return "true", and the
template displays to the user Jerome.
See “The available_templates.ipl File” on page 33 for more information on this file.
WorkflowBuilder Constraints
The use of constraints in WorkflowBuilder can affect the composition of the
available_templates.cfg file. See “Effects on available_templates.cfg File” on page 99
for more information.
The available_templates.dtd File

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

<!ELEMENT template_file
((command_list)?,(role_list)?,(user_list)?,(branch_list)? >
<!ELEMENT path EMPTY>
<!ELEMENT command_list (command)+ >

<!ELEMENT role_list (role)+ >
<!ELEMENT user_list (user)+ >
<!ELEMENT branch_list (branch)+ >
<!ELEMENT command EMPTY>

<!ELEMENT role EMPTY>
<!ELEMENT user EMPTY>
<!ELEMENT branch EMPTY>

<!ATTLIST template_file
name CDATA #IMPLIED
active (yes|no) "yes"
path CDATA #IMPLIED>
<!ATTLIST command
value CDATA "all"
include (yes|no) "yes">
<!ATTLIST role
value (author | admin | master | editor | all) "all"
include (yes|no) "yes"
allusers (yes|no) "no">
<!ATTLIST user
value CDATA "all"
<!ATTLIST branch
value CDATA "all"
The available_templates.ipl File

The available_templates.ipl file consists of a single Perl function that parses the
available_templates.cfg file. It compares the constraints (for example, user or branch)
defined in the available_templates.cfg file with the request being made in the TeamSite
GUI. It then decides whether or not to list a template in the TeamSite GUI.
The Perl function processes requests based on the following input parameters:
! The command being issue (for example, new_job or submit).
! The branch to which the user is logged on.
! The user that is requesting the list.
! The role the user used to log into TeamSite in this session.
This enables you to create code that states: if command X is issued by user U whose role is
Master, and the Branch ID is B, then display templates A, B, C, and D. For example, if a
New Job command is issued by the user Joe, who is logged in with a role of Master, display
the Author Approval and Editor Approval workflow templates.
Note: Do not edit the available_templates.ipl file.
33
Using Workflows
The iw.cfg File

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

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

Querying Workflows
[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
##
## 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.
35
Using Workflows
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)

Querying Workflows
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:

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
37
Using Workflows

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.
These workflows are available for you use and also illustrate the tasks and transitions
included in workflows. The configurable steps are marked as “optional” and are described in
detail in Chapter 3, “Using Solution Workflows.”
39
Author Submit with Deploy

The following graphic illustrates an author submit combined with a deployment.
1. Author-submitted content is
Submit
sent to a reviewer. The reviewer
is defined as the owner of the
workarea to which the files are
submitted.
Author Work
iw_author
2. The reviewer either:
" Approves the work.
" Rejects the work (which
reject is sent to an author for
modification, and
resubmitted for
Review
iw_areaowner
approval).
3. When approved, the file is

approve
submitted for deployment.
Submit
4. The file is deployed to the
iw_areaowner location specified in the
wft_opendeploy.cfg file.
failure
Resolve Deployment
Deploy
Problem
retry
End
Figure 4: Diagram of the Author Submit with Deploy solution workflow

Author Submit with Email

The following graphic illustrates an author submit combined with an email.
1. Author clicks Submit to

Submit
submit modified files, which
initiates a new Job and prompts
the author for the following
information:
" Submit comment
Author Work
iw_author
(required)
" Information comment
(optional)
" Individual file comments
(optional)
Email to Reviewer 2. The submitted files trigger an

email notification to a reviewer.
The reviewer is defined as the
reject owner of the workarea to which
the files are submitted.
Review 3. The reviewer either:

iw_areaowner " Approves the work.
" Rejects the work (which
approve
is sent to an author for
modification. When
Submit resubmitted, another
iw_areaowner email is sent to the
reviewer).
End
4. When approved, the files are
submitted to the staging area.
Figure 5: Diagram of the Author Submit with Email solution workflow
41
Author Submit with Metadata

The following graphic illustrates an author submit with metadata capture.
Submit 1. Author-submitted content is

processed for metadata capture
(by either the TeamSite Tagger
GUI or through MetaTagger
integration).
Author Work
iw_author 2. The file is passed to a
reviewer. The reviewer is defined
as the owner of the workarea to
which the files are submitted.
3. The reviewer either:

Metadata Capture
iw_user
" Rejects the work (which is
sent to an author for
reject modification, then
resubmitted for metadata
capture and approval).
Review
iw_areaowner
4. When approved, the file is
approve submitted to the staging area.
Submit
iw_areaowner
End
Figure 6: Diagram of the Author Submit with Metadata solution workflow

Configurable Author Assignment

The following graphic illustrates a configurable author assignment.
1. A new job is initiated, typically by

New Job
an editor; the initiator (optionally)
selects files to be worked on by the
author.
(optional)
Add Files to Job 2. (Optional) Email notification of
the assigned work and associated files
is sent to an author.
(optional)
Email to Author 3. Author completes assigned work
and marks the task as Done.
Author Work
iw_author
4. (Optional) Content is processed
for metadata capture (by either the
TeamSite Tagger GUI or through
MetaTagger integration).
(optional)
Metadata Capture
5. Work is submitted to the review
subflow for approval or rejection. See
“Review Subflows” on page 45 for
Review Subflow more information.
(See “Review
reject
Subflows” on page 45
for more information.) 6. One of the following actions
occurs:
" If approved, the file is
approve submitted to the staging area.
(optional) " If rejected, the task is returned
Submit Email Notification of to step 2.
iw_areaowner Deployment Problem
failure 7. (Optional) The file is deployed to

the location specified in the
Resolve Deployment
(optional) Deploy wft_opendeploy.cfg file (email is
Problem
retry iw_areaowner
sent to the initiator if there is a
deployment problem).
cancel job
End
Figure 7: Diagram of the Configurable Author Assignment solution workflow
43
Configurable Author Submit

The following graphic illustrates a configurable author submit.
Submit 1. (Optional) The author selects

additional files to be submitted.
(optional)
2. Author-submitted files are
Add Files to Job
(optionally) processed for
metadata capture (by either the
(optional)
TeamSite Tagger GUI or
Email to Author
through MetaTagger
integration).
3. Work is submitted to the

Author Work
review subflow for approval or
iw_author
rejection. See “Review
Subflows” on page 45 for more
information.
(optional)
Metadata Capture
reject
iw_user 4. One of the following actions
occurs:
" If approved, the file is
submitted to the staging
Review Subflow
(See “Review
area.
Subflows” on page 45 " If rejected, the task goes
for more information.) to email notification of
approve
the author requesting
(optional)
revisions.
Submit Email Notification of
iw_areaowner Deployment Problem 5. (Optional) The file is
failure
deployed to the location
specified in the
Resolve Deployment wft_opendeploy.cfg file
(optional) Deploy
Problem (email is sent to the initiator if
retry iw_areaowner there is a deployment problem).
cancel job
End
Figure 8: Diagram of the Configurable Author Submit solution workflow

Review Subflows
Configurable Default Submit

The following graphic illustrates a configurable default submit.
1. A user—whose work does

Submit not need review—submits a
file.
2. (Optional) Content is
processed for metadata capture
(either in the TeamSite Tagger
GUI or through MetaTagger
(optional) integration), then submitted to
Metadata Capture
iw_user
the staging area.
3. (Optional) The file is

(optional) deployed to the location
Submit
iw_user
Email Notification of specified in the
Deployment Problem wft_opendeploy.cfg file
failure
(email is sent to the initiator if
there is a deployment problem).
Resolve Deployment
(optional) Deploy
Problem
retry iw_areaowner
cancel job
End
Figure 9: Diagram of the Configurable Default Submit solution workflow
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, but rather is a part of the configurable author
submit and assignment workflows.
The review subflow process is shown in general terms in the overall workflow illustrations.
This section contains an illustration detailing the 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”).
45
Return on First Reject

The “return on first reject” 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.
1.(Optional) Email notification

Start Review
is sent to first reviewer
configured in the workflow
configuration file.
(optional)
Start Review
Cycle 2. The reviewer either:
" Rejects the work.
(optional)
Email
Reviewer 1 3. One of the following actions
occurs:
" If approved, the reviewer
Review 1 (optionally) emails the
(reviewer 1
or group 1) next reviewer (if any)
configured in the
approve
workflow configuration
(optional) file. The work is then
Email
Review 2 forwarded to the next
reviewer.
" If rejected, an email is
Reviewer 2
(reviewer 2
triggered to an author for
or group 2) modification.
approve
4. The review procedure is
(optional)
Email repeated for each reviewer of
Reviewer n the work until there is either a
rejection, or all the reviewers
approve the work.
Review n
(reviewer n
or group n)
approve
(optional)
End Review
Cycle
Reject Approve
Figure 10: Diagram of the Return on First Reject review workflow

Review Subflows
All At Once
An “all-at-once” 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.
1.(Optional) Email notification

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

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

Reviewer 2
(reviewer 2 finishes, a selection criterion is
or group 2) applied to the work based on
the cumulative approvals and
reject approve
rejections, to determine
(optional) whether the work has passed
Email review.
Reviewer n
Review n
(reviewer n
or group n)
reject approve
(optional)
Reject End Review Approve
Cycle
Figure 11: Diagram of the All-at-once Review workflow
47
Concurrent Review
A concurrent review 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.
1. (Optional) Email
Start Review
notifications are sent to all
reviewers configured in the
workflow configuration.
(optional)
Start Review
Cycle 2. Each reviewer either:
" Rejects the work.
(optional) Review 1
Email (reviewer 1 approve
Reviewer 1 or group 1) 3. After each reviewer is done,
reject a selection criterion is applied
to the work based on the
cumulative approvals and
rejections, to determine
whether the work has passed
(optional)
Email
Reviewer 2
(reviewer 2
approve review or not.
Review 2 or group 2)
reject If any reviewer rejects the work,
the review is immediately
terminated. Otherwise, the
review is passed when every
reviewer has approved the
(optional) Review n work.
Email (reviewer n approve
Reviewer n or group n)
reject
OR AND
Review Review
rejection approval
Reject Approve
Figure 12: Diagram of the Concurrent review workflow

Configurable Workflow Overview
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 49 and the properties files in
“Workflow.properties File Overview” on page 50.
Note: To activate any of the optional (non-default) workflows, complete the procedure
described in “Enabling Workflows” on page 23.
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 49 for an overview of a specific workflow or
“Configurable Workflow Settings” on page 51 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.
configurable_author_submit.cfg
! Deployment
! Email Notification
! Metadata Capture
! Review
49
configurable_default_submit.cfg
! Deployment
! 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 58.
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 functionality is implemented with the following solutions workflows:

! configurable_author_submit
! configurable_author_assignment
Note: Because VisualAnnotate is not supported on non-English servers, remove the

VisualAnnotate functionality for these workflows if you are using a non-English
server.

Configurable Workflow Settings
This eliminates the need for separate VisualAnnotate workflows. Refer to Chapter 8, “Using
VisualAnnotate,” for more information about VisualAnnotate and its configuration.

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

add the functionality to have submitted files reviewed by a configurable reviewer. The
reviewer section of these cfg files is where the email notification obtains instructions to
determine the email address of the reviewer.
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.
3. Save and close the file.
4. Ensure the workflow is activated as described in “Enabling Workflows” on page 23.
The sections that follow describe each of these options in detail.
Email Notification Settings

All configurable workflows have the ability to send email notifications, including assignment
of work, requests for review of completed work, and problems deploying files.
## Email Notification
##
# Should a 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 had work assigned to them (that is, the status of the task is pending). If
set to yes, email is sent to the author who performs the submit (author_submit
51
workflows) or to the author to whom the work is assigned (author_assignment

workflows).
# Should a 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 a 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 this entry 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.

The following graphic shows an example of an email sent to a reviewer:
Replaceable
logo file
Submitter
Task type
and number
Link to file
to view
Figure 13: Review Email
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
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 mark 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 a metadata term.
# 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
53
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. The information entered by the submitter is displayed as a
submit-info variable on the submit task.

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 is as follows:
! For configurable_author_submit.cfg—Owner of the workarea to which the file is
being submitted.
! For configurable_author_assignment.cfg—Selected Editor.
The last line of this section contains the default setting (configurable_author_submit is
shown here):
## 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.
Simple Examples
Each of these examples specifies a review process with only one review task. In the first two
examples, the review task is a usertask assigned to the area owner, or the specific user
(worldcorp\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 among those users who are
authors or editors.
! review_type=areaowner
! review_type=user:worldcorp\andre
! review_type=grouptask[group:demomaster,user:jsmith]
! review_type=select[role:editor,role:author]
The configurable_author_submit (shown here) uses review_type=areaowner as its

default.To specify one of the following reviewers:
! Job initiator—Uncomment the # review_type=job_initiator

! Specified user—Uncomment the # review_type=user:worldcorp\andre, and
replace worldcorp\andre with the username and domain (Windows only).
55
! Specified group—Uncomment the

# review_type=grouptask[group:demomaster,user:jsmith], and replace
demomasterwith one or more groups, defined in the operating system, and replace
jsmith with one or
more user names. 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 # review_type=select[role:editor,role:author] and
substitute the reviewer roles in any number and combination your want. The reviewer
roles you add are displayed in a menu to the job initiator containing the choice of editor
and author.
Note that the configurable_author_assignment.cfg has a default defined as

review_type=select[role:editor] therefore the selection list will contain users with
the role of editor.
Ensure you place a comment (#) in front of the default setting if you select another
reviewer setting.
Figure 13 shows an example of an email sent to a reviewer.
Advanced Examples
This first 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.
The second example specifies a review process with three concurrent review tasks. Each
task is assigned to a selected editor. If fewer than three editors are selected, there are fewer
than three review tasks. This is only permitted if the min_reviewers option has been set to
a number less than 3.
review_type=serial[select[role:editor],areaowner,select[role:master,role:admin]]
review_type=concurrent[select[role:editor],select[role:editor],select[role: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 serial review with three tasks, and two are “select”, and
min_reviewers=1, then one reviewer selection will be required and one will be optional.
If you do not specify a minimum, the user must select a reviewer from every selection.
Automatically Forward to Next Reviewer?
You must decide whether the job should automatically forward to the next reviewer (or to
the author) if a certain amount of time elapses.
review_timeouts=yes
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 involves whether the workflow will begin with a user task for the
initiator to add additional files.
## 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
57
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.

Chapter 4
Workflow Components
You can write workflows using the following methods:

! Use WorkflowBuilder to generate the .wft file that provides a workflow template (see
Chapter 5, “Using WorkflowBuilder”).
! Write the .wft file and associated files (see Chapter 6, “Creating Workflow Template
Files”).
! Create a job specification file see Chapter 7, “Job Specification Files”).
This chapter provides an overview of the various workflow components that are used when
workflows are created.
Workflow Elements
There are three major types of workflow elements:
! Tasks
! Transitions
! Conditions
These elements are introduced in the following sections.
Note: The icons shown in the tables in this chapter are the icons used in
WorkflowBuilder.
Tasks
You can include the following tasks in your workflow template or job specification file. For
more information about task attributes, see page 61.
Task Description
User Defines the task that appears on a user’s task list.
Group Appears in the task list of each member of the arbitrary group of users
specified in the task. A group task becomes identical in behavior to a user
task when one user from the group takes ownership of the task using
ContentCenter or the CLT iwtaketask.
59
Workflow Components
Task Description
Submit Performs a submit operation on its contained files. If the submit task
succeeds, the specified successor tasks are signaled. If the submit task fails,
it goes into a special state that the user interface can detect. When the user
interface resolves a conflict, it retires the operation so that the job can
continue. For the purposes of workflow, a submit task is considered
successful even if some of its contained files were not submitted because of
not being up to date with the staging area.
Update Performs a Get Latest or Copy to Area on its contained files. If the
update task fails because of conflicts, it goes into a state like that for a
failed submit task. The user interface is responsible for resolving conflicts
and retrying the update task.
CGI Behaves much like an external task, but does not run a command element.
External Runs external programs when it is activated.
Email Sends email to specified users.
Dummy Used as a spacer or timed task. Dummy tasks let a workflow designer
create a time interval unrelated to any actual job activity. A dummy task
has no owner or areavpath.
Lock Attempts to acquire locks on files it owns. If it succeeds, it transitions to
the successors specified in its success transition. If it fails, it transitions to
the successors specified in its failure transition. 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.
End Ends a job.
Nested Creates a task that is started when another task within a job reaches a
certain state. Nested tasks are considered child tasks and the completed
Workflow Job tasks that trigger them are considered parent tasks. The attributes are
similar to a External tasks except you have to enter a workflow template
path or a job file name instead of a command name.
Transitions
You can choose among four different kinds of transitions for the transition you place
between all types of tasks, except the End task. An End task can only accept Successor or
Timeout transitions from predecessor tasks; an End task ends a workflow and does not
transition to any other task.

Task Attributes
Transitions can be qualified with logical conditions, such as AND, OR, or NOT.
Transition Description
Successor The most common type of transition. A successor transition specifies the
next task in the workflow.
Timeout Sets an optional time limit for the completion of a task. When time runs
out the task is inactivated and its successors are signalled to become active.
The time value can be specified in one of two forms: the number of hours
and minutes after the task becomes activated that the timeout should
occur, or the month day, year, hour, and minute at which the timeout
should occur.
Reset Resets a task so that it is in its original state. Note the distinction from
“inactivate” which maintains information about its prior state.
Inactivate A task becomes inactive at the time it signals its successors. However, it is
sometimes necessary to inactivate tasks other than those which have
signalled a task when that task becomes active.
Conditions
The AND, OR, and NOT condition elements specify the conditions under which a task
becomes active. When a finishing task signals a successor task, the successor task notes that
the finishing task has signaled and then evaluates the logic of the element to determine if it
should become active.
For example, if you want Task C to be activated only when Task A and Task B have been
completed, draw transition lines from the tasks A and B to a AND element, then draw a
transition line from the AND element to Task C. You can qualify a transition with any one
of the following condition elements:
Condition Description
AND All tasks linked to this element must be completed to activate a successor
task.
OR One of the tasks linked to this element must be completed to activate a
successor task.
NOT The task must not be completed to activate a successor.
Task Attributes
Workflow elements (jobs, tasks, and transitions) all have special attributes that you must
configure when you create a workflow template or job. Different types of tasks have
different possible attributes. Some of these attributes are mandatory and some are optional.
Some attributes can be set using variables. If attributes are set with user variables, the file is
a workflow template that may be invoked through the New Job menu item or the Submit
61
Workflow Components
button in TeamSite. If attributes are not set with user variables, the file describes a specific
job.
The attributes that are available for different tasks and other workflow elements are
described in the following sections.
CGI Task Attributes

These attributes are available for all CGI tasks:
Attribute Description
Name Name of the task. Each task within a job must have a unique name
(required).
Description A description of what the task does.
Owner Username of the task's owner (required).
Immediate When set to Yes (immediate="t"), this attribute specifies that any other
cgitasks in the workflow be executed immediately.
Lock Specifies whether or not the task will try to acquire locks on the files it
contains (can be Yes or No). For more information on locking, see the
TeamSite Administration Guide.
Start Specifies whether this task is activated at the time that the job is invoked
(can be Yes or No, but there must be one task set to Yes).
AreaVPath Specifies the TeamSite area associated with this task (required).
Command Specifies the full path of the program to be run on activation. The
program it references must be located in:
iw-home/httpd/iw-bin/ (required)
Files Specifies the files that the actions of a task affect. WorkflowBuilder can
only specify files for start tasks.
Variables Key (variable name)/value pairs that are set at the Task or Job level for use
by a CGI task or the TeamSite GUI. For example, the Priority variable is
used at the GUI-level to set the priority of a task.
Dummy Task Attributes

These attributes are available for all dummy tasks:
(required).
Start Specifies the files that the actions of a task affect. WorkflowBuilder can

Task Attributes
Dummy tasks require a timeout transition.
Email Task Attributes

These attributes are available for all email tasks:
(required).
Lock Specifies whether or not the task will try to acquire locks on the files it
contains (can be True or False). For more information on locking, see the
TeamSite Administration Guide.
Retry Specifies whether the email sent by this task should be resent if for any
reason it is not delivered to the recipient (default is Yes).
(can be True or False).
Email Specifies the email address to send mail to (required).
End Task Attributes

This attribute is available for all end tasks:
(required).
63
Workflow Components
External Task Attributes

These attributes are available for all external tasks:
(required).
Lock Specifies whether the task will try to acquire locks on the files it contains
(can be Yes or No). For more information on locking, see the TeamSite
Administration Guide.
Retry Specifies whether the command executed by this task should be retried if
it fails (default is Yes).
(can be Yes or No).
Command Specifies the full path of the program to be run on activation, followed by
any initial arguments (required).
by a CGI task or a TeamSite GUI. For example, the Priority variable is
Group Task Attributes

These attributes are available for all group tasks:
Name Name of the task. Each task within a job must have a unique name.
(can be True or False). For more information on locking, see the TeamSite
Administration Guide.
Readonly Specifies whether users can add, remove, or modify files in the task (can
be True or False).
RetainOwner After a group task has had someone take ownership of the first time,
setting this to Yes causes the group task to behave similar to a user task by
retaining the same owner from that point on.
For example, if you loop back to an previous task and once again transition
to that task, it will be considered as transitioning to the person who first
claimed ownership of the task and not go back into a “shared by pool”
waiting for someone to claim ownership again.

Task Attributes
(can be True or False).
Sharedby Specifies the set of users who share this group task. These users can be
individual TeamSite users, or Windows or UNIX user groups (required).
Lock Task Attributes

These attributes are available for all lock tasks:
(required).
Start Specifies whether or not this task is activated at the time that the job is
invoked (can be True or False).
only specify files for start tasks. In the case of a workflow template, this
can be a relative path under:
iw-home/local/config/wft.
Lock tasks also have two types of transition that are not available for other tasks: Success and
Failure. Both type of transitions are required for all lock tasks.
Nested Job Task Attributes

These attributes are available for all nested tasks:
(required).
65
Workflow Components
Start Specifies whether or not this task is activated at the time that the job is
invoked (can be Yes or No).
Wffile Specifies the full path of the workflow template or job specification file to
be run on activation (required).
Submit Task Attributes

These attributes are available for all submit tasks:
(required).
(can be Yes or No).
Skip Conflicts Specifies whether to submit conflicting files (can be Yes or No).
Skip Locked Specifies whether to submit locked files (can be Yes or No).
Override Specifies whether to overwrite the staging area version of conflicting
files (can be Yes or No).
Unlock If set to Yes, then the submittask will unlock all files following
successful submission.
SaveComments If set to Yes, the comments are saved. Defaults is Yes.
Variables Key (variable name)/value pairs that are set at the Task or Job level for
use by a CGI task or the TeamSite GUI. For example, the Priority
variable is used at the GUI-level to set the priority of a task.

Task Attributes
Update Task Attributes

These attributes are available for all update tasks:
(required).
(can be Yes or No).
Delete Specifies whether to propagate deleted files to the destination area (can be
Yes or No).
Overwrite Specifies whether to overwrite the destination area version of conflicting
files (can be Yes or No).
(can be Yes or No). For more information, see the TeamSite Administration
Guide.
SrcAreaVPath Specifies the area from which files are copied (required).
User Task Attributes

These attributes are available for all user tasks:
(required).
(can be Yes or No). For more information, see the TeamSite Administration
Guide.
Readonly Specifies whether users can add, remove, or modify files in the task (can
be True or False).
(can be Yes or No).
67
Workflow Components
Workflow Attributes
These attributes are available for all jobs and workflow templates:
Name Name of the job or workflow template (required).
Variables Key (variable name)/value pairs that are set at the Task or Job level for
use by a CGI task or the TeamSite GUI. For example, the Priority
variable is used at the GUI-level to set the priority of a task.
Description A description of what the job does.
Owner Username of the job's owner (required).
WorkflowBuilder Attributes
These attributes are used by WorkflowBuilder:
DebugMode Sets the Debug flag to On in the workflow template. When the job is
instantiated, rather than running the actual job, a Debug output page is
created. It contains details about what the instantiated XML looks like
plus what Perl variables were declared.
PreselectedFiles Enables end-users (using the TeamSite GUI) to configure the workflow
to automatically include files selected before starting the job. The
preselected files are attached and sent to other users along with assigned
tasks.
Dynamic Attributes
TeamSite includes the functionality to modify a number of important job and task attributes
given certain restrictions (including, but not limited to, those listed in the following table).
This ability to make changes to tasks already instantiated is supported from the
command-line and from ContentCenter.
Modification Restriction
Change the owner of a job Limited to masters and the current owner of a job
Add, remove, or change job Limited to masters and the current owner of a job
variables
Change the owner of a task Limited to masters, job owner, and task owner

Task Attributes
Modification Restriction
Add and remove users and groups Limited to masters, job owner, and task owner
from a grouptask (command-line only; not supported in GUI)
Change the timeout period for a Limited to masters, job owner, and task owner
task
Change the areavpath of a task Limited to masters, job owner, and task owner
Change various task attributes Limited to masters, job owner, and task owner
(for example: lock, read-only)
Add, remove, or change task Limited to masters, job owner, and task owner
variables (command-line only; not supported in GUI)
The procedures for making these dynamic modifications from the Workflow tab in
ContentCenter Professional are contained in the next section. The command-line reference
begins on page 72.
Dynamically Modifying Attributes Using the GUI

TeamSite allows you to manage and modify jobs and tasks and their corresponding
attributes. Complete the following procedure to display a job:
1. Log in to ContentCenter Professional as a Master user.
2. Select the Workflow tab.
3. Click the New Job link on the right side of the screen. The Select a Workflow window
displays.
4. In the Select a Workflow window, select one of the templates (for example: Author
Assignment); click Next. The Assignment template displays.
Figure 14: Sample workflow template - Assignment Workflow
69
Workflow Components
5. Complete the following steps in the Assignment template:

a. Select an Author from the drop-down menu.
b. Type a description of the new job, for example: Test of Dynamic Attributes.
c. Select a Branch from the drop-down menu.

d. Type the name of a workarea in the Workarea field.
e. Optionally, you can change the priority and add a due date in the appropriate fields.
f. Click Submit.
From the Jobs link in the Workflow tab, you can select the All Jobs view to see a listing
of all current jobs.
Figure 15: ContentCenter Professional Workflow tab showing jobs
6. Highlight the job and select Actions > Change Attributes.

The Job Properties window displays. You can change some of the properties of the job.
Click Advanced to view the tasks that make up the job. After you make changes, click
Save to save and close the Job Properties window.

Task Attributes
Figure 16: Job Properties window
From the Tasks link, you can view the user tasks in a job. Select Actions > Task
Properties to display the Task Properties window. You can change values for some
fields; the fields vary depending on the type of task. Click Save if you made changes you
wish to save. You may need to click the browser Refresh button to see the changes to
jobs or tasks in ContentCenter.
Figure 17: Task Properties window
7. Select the attribute you want to change from one of the four drop-down menus.
The top drop-down menu contains only the Change Job Owner option. The other three
offer the following options:
" Change Task Owner
" Change Area
" Change Attributes
71
Workflow Components
8. To change an attribute, perform the procedure described in the following table:
Window
Change Displayed Procedure Result
Job Owner Change Job Enter the new job owner The Properties window
Owner (this user must be a valid displays the new Job
TeamSite user). Owner.
Click Save.
Task Owner Change Task Enter the new task owner The Properties window
Owner (this user must be a valid displays the new Task
TeamSite user). Owner.
Click Save.
Area Change Task Area Enter the new workarea. The Properties window
Click Save. displays the new Task
Owner.
Attributes Change Task Click the corresponding The Properties window
(on a task) Attributes option to define whether displays the new
the corresponding task is attributes.
locked or read-only.
Click Save.
Attributes Change Task Click the corresponding The Properties window
(on author Attributes option to define the displays the new
content corresponding task: attributes.
approval) ! skipconflicts
! skiplocked
! override
! unlock
! savecomments
Click Save.
Dynamically Modifying Task and Job Attributes from the Command-line

In addition to the ContentCenter functionality, TeamSite includes Command-Line Tools
(CLTs) that provide equivalent functionality. These CLTs include:
! iwsettaskattrib
! iwsetjobowner
! iwsetjobdescription
! iwsettasktimeout
! iwsettaskownerandarea
! iwaddtaskowner
! iwrmtaskowner
! iwaddtaskgroup
! iwrmtaskgroup

Variables
Variables
Variables allow you to specify attributes that are subject to change. There are three types of
variables:
! User variables
! System variables
! Custom variables
You can use these variables when setting attributes of a workflow element. Each type of
variable is described in the sections that follow.
User Variables
User variables are variables that appear in a workflow template in TeamSite. The job creator
can set these variables to describe a specific job.
For example, you might describe the Owner attribute of a user task with a user variable.
When a job creator selects the workflow template in TeamSite, the task owner in the New
Job form has to be set.
System Variables
System variables are characteristics of the system or of the user who is creating a job from
your workflow template. Available system variables include the following:
Variable Description
iw_home Location of the TeamSite home directory.
iw_role Role of the user instantiating the job.
iw_session Current session string.
iw_template_file Path to the current workflow template.
iw_template_name Name of the current workflow template.
iw_use_default If all user variables have default values and this is enabled, those
default values are used to create the job (the value entry form does
not appear at job creation time).
iw_user Name of the current user, typically the job creator.
When a job is created, all its associated tasks are also created.
Therefore, any task or workflow attributes that were specified as
iw_user have their value set to the job creator's user ID.
iw_desc Description of the job entered in the job description box when
creating a job. This variable is usually used for the workflow's
description attribute.
iw_workarea Name of the current workarea (if you create the job from the
workarea view or using submit).
iw_areaowner Name of the user who owns the workarea where a job is created.
iw_branch Name of the current branch.
73
Workflow Components
Custom Variables
WorkflowBuilder includes a Perl Code Editor that enables you to add Perl code (including
custom variables) to workflow templates. This functionality is commonly used to control
the appearance of the forms associated with your template. Appendix B, “WorkflowBuilder
Tutorial” describes the creation and use of a number of custom variables.
Nested Workflow
TeamSite enables workflow developers to create nested workflow—workflow that is contained
within other jobs or tasks. The implementation of nested workflow is similar to external and
CGI tasks where the activation of workflow tasks is either automatically or manually
instantiated causing an association of a new job with the workflow task. The nesting process
creates a parent/child relationship with the task as the parent and the job as the child.
The relationship between a workflow task and its nested workflow includes:
! The ability to pass variables and file lists from the parent task to the child job
! The ability for nested jobs to pass some or all variables and file lists to the parent job
upon the child job’s completion
! The ability for the child job to cause a transition to occur in the parent task upon the
child job’s completion
! The lifetime of a nested job is dependent upon its parent task’s workflow lifetime—it
should not be removed from the Content Store until its parent task is deleted
Workflow tasks can either be specified with a path to a job specification file or to a workflow
template file (.wft). 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 using the New Job
window to input job variables and subsequently initiate the job.

Chapter 5
Using WorkflowBuilder
WorkflowBuilder provides a user interface so developers can graphically design workflows.

(.wft files). Using WorkflowBuilder is one option for creating .wft files. Refer to Appendix
B, “WorkflowBuilder Tutorial,” for a tutorial on using the WorkflowBuilder. TeamSite’s
WorkflowBuilder system consists of three main components:
! WorkflowBuilder—Client-side application that enables workflow developers to build
workflow templates using an intuitive, drag-and-drop graphical interface that can then
be transferred to a TeamSite server. WorkflowBuilder is supported on Windows client
platforms.
! WorkflowBuilder Server—Working with your TeamSite server, it provides a
framework for controlling complex Web site production processes. Your custom
workflow templates and sample templates (included with WorkflowBuilder) are stored
on the TeamSite server and made available to end users. WorkflowBuilder Server is
supported on Windows and UNIX platforms.
! Browser-based client-side user interface—Displays forms that enable end users to
enter data that defines and controls specific workflow actions. These end users include
those creating jobs based on the workflow templates and those performing the tasks
contained within these jobs.
The following graphic shows these three components:
Template development TeamSite Server TeamSite end-users

using WorkflowBuilder using ContentCenter
Workflow Editor
template creates new
created job based
(.wft & .wfb) .wft files Template on template
.wft & .wfb referenced in available to
files to available_ job creators
Workflow server templates.cfg Author receives
template assignment,
verified modifies
content file
.wfb files
stored on New content
server available on
Access TeamSite Editor
constraints server approves
defined modifications
to content file
Figure 18: Components of the Workflow Builder System
75
Installation
In addition to installing the TeamSite server and client as described in the TeamSite Installation
Guide, you must install two WorkflowBuilder components to complete the installation.
These components are:
! WorkflowBuilder Server—Must be installed on your UNIX or Windows server running
TeamSite.
! WorkflowBuilder client application—Must be installed on a Windows 2000 or
Windows XP system networked to your TeamSite server.
Note: If you design workflows using Workflow Builder and then edit the .wft files,
Workflow Builder cannot be used for additional modifications.
Do not attempt to use Workflow Builder to modify the Solutions workflows.
Prerequisites
Ensure these prerequisites are met before installing or upgrading the two WorkflowBuilder
components:
! A TeamSite server is properly installed and licensed as described in the TeamSite
Installation Guide.
! You have the WorkflowBuilder Server component that matches your server platform
(UNIX or Windows 2000).
! For the server where TeamSite is installed, you must have Administrator privileges
(Windows) or root access (UNIX).
! If you have made changes to a previously installed version of the
available_templates.ipl file and want to preserve the changes, make a backup copy
and rename it. This prevents the WorkflowBuilder Server installation program from
overwriting your existing available_templates.ipl file.
You can merge your customizations into the new available_templates.cfg file after
you have finished installing WorkflowBuilder.
Note: Do not edit the available_templates.ipl file.

Installation
Installing the WorkflowBuilder Server

Complete the following procedure that corresponds with your server platform.
Windows
To install the Workflow server software on your Windows server, follow these steps:
1. Log on to the system where your TeamSite server is installed as a user with
Administrator privileges.
2. Insert the TeamSite CD-ROM.
The WorkflowBuilder executables are on the same CD-ROM as the TeamSite server.
Figure 19: CD-ROM contents - WorkflowBuilder server
3. Double-click WFBServer.exe.
The remainder of the installation program is completed automatically.
Solaris Servers
To install the Workflow server software on your Solaris server, follow these steps:
1. Log on to the system where your TeamSite server is installed as the root user.
2. Insert the TeamSite CD-ROM.
The WorkflowBuilder installation files are on the same CD-ROM as the TeamSite
server. The top level of the CD contains the WorkflowBuilder Server installation file.
3. Copy the installation file to the TeamSite installation directory, iw-home:
% cp IWOVwfbserver-sol.x.x.x.Build####.tar.gz iw-home
4. Decompress the installation file:

% gunzip IWOVwfbserver-sol.x.x.x.Build####.tar.gz
% tar xvf IWOVwfbserver-sol.x.x.x.Build####.tar
5. In the wfbinstall.sh installation program, change the line:

rc=`${IWHOME}/bin/iwversion | grep '5.5.2'`
to
rc=`${IWHOME}/bin/iwversion | grep '6.x.0'`
77
6. Start the installation program:

% ./wfbinstall.sh
7. Respond to the prompts displayed by the installation program.
Installing the WorkflowBuilder Client

To install the WorkflowBuilder client software, follow these steps:
1. Log on to the system where you want to install WorkflowBuilder as a user with
Administrator privileges.
2. Insert the TeamSite CD-ROM in your local drive.
The WorkflowBuilder executables are on the same CD-ROM as the TeamSite server.
Figure 20: CD-ROM contents - WorkflowBuilder client
3. Double-click WorkflowBuilder.exe.
The WorkflowBuilder installation program prompts you to accept the default
installation directory:
C:\Program Files\Interwoven\WorkflowBuilder
4. Click Next to accept the default location, or Browse to specify a different location.
The remainder of the installation program is completed automatically.
Uninstalling WorkflowBuilder
Before upgrading the WorkflowBuilder client, you must uninstall the older version before
beginning the installation program.
To uninstall WorkflowBuilder, follow these steps:

1. Select Start > Settings > Control Panel.
2. Double-click the Add/Remove Programs icon.
3. Select Interwoven Workflow Builder, and click Add/Remove.
4. Click the Remove option button.

WorkflowBuilder Graphical User Interface
5. Click Next, then OK to confirm that you want to remove the WorkflowBuilder client.
Note: You cannot uninstall the WorkflowBuilder server. Whenever you install a new
version, it automatically overwrites the existing version.

The following sections describe the various WorkflowBuilder interface elements.
Toolbars
WorkflowBuilder contains the following four toolbars:
! Menu
! Task
! Alignment
! Zoom
To display a toolbar, select it from the View menu. You can drag a displayed toolbar
anywhere on your desktop.
When you move a toolbar outside the WorkflowBuilder GUI, it becomes a floating palette
and displays a title bar with a close button (X). Clicking the close button hides the toolbar; it
does not return it to its default location in the WorkflowBuilder GUI. To return the toolbar
into view, select Tools > Customize. Select the Toolbar tab and check the box next to the
corresponding toolbar.
Menu Toolbar
The Menu toolbar contains shortcuts for basic file operations (new, open, and save), edit
operations (cut, copy, and save), and print.
Figure 21: Menu Toolbar
Tasks Toolbar
The Tasks toolbar enables you to change your cursor to the selection pointer, place text
labels, transition lines, tasks, and conditions on your canvas.
Figure 22: Tasks Toolbar
79
Alignment Toolbar
The Alignment toolbar is activated when you select two or more objects. Objects are
aligned relative to the last object selected. The options are top-, center-, and
bottom-aligned on the horizontal axis, and left-, center-, and right-aligned on the vertical
axis.
Figure 23: Alignment Toolbar
Zoom Toolbar
The Zoom toolbar contains buttons to undo an action or redo an undone action.
Figure 24: Zoom Toolbar
It also contains three zoom buttons:
! Zoom
" Click Zoom (magnifying glass icon).
" Move the magnifying glass cursor over the object you want to view.
" Left click to zoom in (increase magnification), right click to zoom out (decrease
magnification).
! Zoom to Fit
" Click Zoom to Fit to resize your view so that all objects are magnified to the
maximum possible size within the boundary.
! Zoom to Fit Selected Objects
" Select the objects on the canvas you want to fit in your current view.
" Click Zoom to Selection. The view is resized so that the selected objects appear
magnified to the maximum possible size that keeps them within the boundary.
The Zoom toolbar also contains a Move button (hand icon) that enables you to grip the
page and move it up or down.

View Menu
Features in the View menu enable you to control your WorkflowBuilder environment. Use
them to open or close windows, hide toolbar items, set grid properties, zoom, and show
page boundaries.
Command Description
Workbook If you have more than one workflow file open, you can use the
Workbook view to display a tab for each open workflow file. The tabs
are displayed at the bottom of each file window. Click the tab to display
the corresponding file.
When Workbook is not checked in the View menu, display the file by
clicking in that file's window. You can move a file in either view by
grabbing its title bar.
Sticky Mode The Sticky Mode controls whether or not you can place multiple
workflow elements (tasks, transitions, conditions) on the canvas without
re-selecting the element from the Tasks toolbar. This option toggles
between on and off positions.
! When this option is checked, each mouse-click adds another of the
same element to the canvas until you right-click.
! When this option is not checked, a mouse-click adds one element to
the canvas. If you want to add another element, you must reselect the
element from the Tasks toolbar.
Toolbars Unchecking any of the toolbar items in the View menu removes the
toolbar from view. You can also move the toolbars around in the
WorkflowBuilder window, or display them as floating palettes. Grab the
grip on the left border of the toolbar to move it.
Status Bar The status bar is located on the bottom of the WorkflowBuilder window.
Uncheck Status Bar to hide it from view.
Set Canvas Canvas size is measured by page (8x11). You can set the height and wide
Size of your workflow file to between one and 1000 pages. If you plan to print
your workflow file, you may want to limit it to a size and layout suitable
for printing.
Grid You can create a contrasting background to help you align objects on the
page. Grid properties such as color, vertical and horizontal spacing, and
snapping can be customized in the Grid Properties dialog box.
Snap to Grid When Snap to Grid is checked, the objects you place (or move) on the
canvas align with the upper left corner of the nearest point on the grid
(points are defined by the intersection of horizontal and vertical lines).
When Snap to Grid is not checked, you can place (or move) objects
anywhere on the canvas.
Grid Use the Grid Properties dialog box to customize the grid. You can set
Properties visibility, snap options, color, as well as the height and width of grid lines.
Zoom Normal Select Zoom Normal to return the window to the default (100%) view.
Zoom to Fit Select Zoom to Fit to resize the view to a percentage that allows you to
view all selected objects without scrolling. First select the objects that you
want to fit in view, then select View > Zoom to Fit.
81
Command Description
Zoom Percent You can resize the view by selecting View > Zoom Percent and selecting
50%, 75%, 100%, or 200%.
Zoom Custom You can set a custom view size by selecting View > Zoom Custom and
entering the desired magnification.
Attributes You can open the Attributes window by selecting View > Attributes
Window Window. The Attributes window is where you specify attributes and
values for each workflow element (for detailed information about
attributes, see “Setting Attributes” on page 90).
Output You can open the Output window by selecting View > Output Window.
Window The Output window displays any error messages that are generated when
WorkflowBuilder tries to validate your job or workflow template.
Typically, these error messages have to do with required attributes of
tasks. After saving a job or workflow template, view the Output window
to ensure that no errors were generated. If an error message is displayed
in the Output window, set the required attributes and save your job or
workflow template again.
Perl Code You can open the Perl Code Editor by selecting View > Perl Code
Editor Editor. The Editor enables you to enter custom Perl code and to create
custom variables. The Perl Code Editor is described in detail in “Defining
Custom Variables” on page 242.
Getting Started
Each workflow template describes a business process that can include user tasks, group
tasks, and a wide variety of automated tasks. Using WorkflowBuilder, the actual creation of
workflow templates is simple—the more difficult part is negotiating the business rules with
the decision makers in your organization, and translating the logic into elements that can be
represented within WorkflowBuilder.
This section describes the functionality included in WorkflowBuilder including a number of

server management features.
Logging In
Each time you create or open a workflow template, WorkflowBuilder asks whether you
want to log in or work offline. Logging in to WorkflowBuilder allows you to receive
information from the TeamSite server to use in your job or workflow, such as lists of users,
TeamSite areas where you can create tasks, and lists of available files. If you have a network
connection to the TeamSite server, you should log in. If you do not have a network
connection, you can work in Offline Mode.
Offline mode enables you to use WorkflowBuilder even when you do not have access to a
TeamSite server. However, to use the workflow templates you generate, you will
eventually need to be able to connect to the TeamSite server. When you work in offline
mode, you do not have access to TeamSite-specific information, such as the lists of users or

Getting Started
TeamSite areas. You can generate workflow templates that do not include this information
when you work in offline mode, then update them at a time when you have a connection to
the TeamSite server.
To log in (online mode), follow these steps:

1. Select File > Select Workflow or File > Open Workflow.
The Login dialog box displays:
Figure 25: WorkflowBuilder Login dialog box
2. Enter your TeamSite username and password.

3. If your TeamSite server is running on Windows, enter your domain in the Domain
field.
4. Enter the name of the TeamSite server, or choose it from the pull-down menu if you
have connected to it before.
5. Enter the port number where you connect to your web server.
Port 80 and Port 81 are valid entries.
6. Click OK.
The name of the TeamSite server and the port number display in the title bar.
To work in offline mode instead, click Offline Mode.
Viewing Sample Workflow Templates

A good way to plan a custom workflow template is to view the sample templates shipped
with WorkflowBuilder. In addition to providing a guide for creating custom workflow
templates, these templates can be modified, saved, and sent to your TeamSite server. There
are three sample templates that include both the .wft and corresponding .wfb files. Both of
these files are required to display a template in WorkflowBuilder. These three files are
installed by the WorkflowBuilder installation program and are located by default in the
following location:
C:\Program Files\Interwoven\WorkflowBuilder\examples
83
You can open any existing workflow template file (.wft) that has a corresponding image file
(.wfb) and display it in WorkflowBuilder.
To view a workflow template file, follow these steps:

1. Select File > Open Workflow.
The Open window displays.
2. Navigate to the examples folder
(C:\Program Files\Interwoven\WorkflowBuilder\examples).
The three sample .wft files and corresponding .wfb files installed with
WorkflowBuilder are displayed.
Figure 26: Contents of the WorkflowBuilder\examples directory
3. Select one of the .wft files and click Open.

The Login dialog box displays.
4. In the Login dialog box, enter your login information, or choose Offline Mode (see
“Logging In” on page 82).
The selected file displays.
Multiple File Tables
Figure 27: WorkflowBuilder diagram of a workflow

Getting Started
Note: If you open more than one file, each file is stored on a tab view that can be selected
at the bottom left of the canvas (as shown in the preceding figure).
Creating New Jobs and Workflow Templates

When you create a workflow template you add elements such as tasks and transitions. Each
element has a series of attributes which must be defined. Some of these attributes are
mandatory and some are optional. Transitions between tasks specify when and how the next
task in the flow is signaled.
After completing and saving workflow templates, you can send them to your TeamSite
server. For information about transferring your workflow templates to TeamSite, refer to
“Sending Workflow Templates to the Server” on page 93.
Your workflow template can describe a general workflow model, or it can describe a
specific job. The difference between these two is in the way attributes are set.
To create a new job or workflow template, follow these steps:

1. Select File > New Workflow.
2. In the Login dialog box, enter your login information, or choose Offline Mode (see
“Logging In” on page 82).
3. Edit the workflow template:
Select View > Attributes Window to display the Attributes window so you can set
attributes on the elements you place in your workflow template. If attributes are set
with user variables (see “Setting Variables” on page 91), the file is a workflow template
that may be invoked through the New Job or the Submit links. If attributes are not set
with user variables, the file describes a specific job.
(Optional) Select View > Output Window to open the Output window to view
validation comments as you work.
4. Select elements from the toolbar and place them on the canvas in the order you want
(see “Placing Tasks on the Canvas” on page 86 and “Drawing Transitions” on page 86).
5. Set attribute values for each element (see “Setting Attributes” on page 90).
6. When you finish, select File > Save and check the Output window for validation errors.
You can then send your workflow template or job specification file to the TeamSite
server.
When you save a new workflow template, two files are created: a .wft file and a .wfb file
that contains the workflow diagram graphic.
85
Figure 28: Example of a WorkflowBuilder diagram
Placing Tasks on the Canvas

To place an object on the canvas, follow these steps:
1. Select an object from the Tasks toolbar.
When you move the pointer to the canvas, a graphic icon displays under it to
indicate that a mouse click will place an object on the canvas.
2. Click on the area of the canvas where you want to place the object.
If Sticky Mode is on (View > Sticky Mode), each click adds another of the same object
to the canvas until you right-click.
Drawing Transitions
Transitions indicate the flow from one task to the next. There are four types of transitions:
Successor, Timeout, Reset, and Inactivate (as described on page 60). You can qualify
transitions by using conditional activation elements such as AND, OR, or NOT.
When drawing transitions, use the Straight Transition button to draw straight lines and
the Segmented Transition button to draw a transition around other objects in your
diagram.
To draw a transition, follow these steps:

1. Using the Transition buttons in the Tasks toolbar, select the type of line you want to
draw (either straight or segmented). When you move the mouse arrow onto the canvas,
it changes to a plus sign ( ).

Getting Started
2. Click a connection point of the task you want to transition from. When you see the
cursor change to crosshairs ( ), you can click to anchor your transition line.
3. Click a connection point of the task you want to transition to.
A segmented transition provides two joints on the line between the anchor points. Use
these joints to position the line around other objects on the canvas.
4. When you finish drawing your transition, right-click to reset your mouse to the pointer.
When any task (other than the end task) is completed, the task owner is presented with
options for triggering one or more successor sets. In WorkflowBuilder, the ports on the task
icon represent successor sets. The maximum number of successor sets that a task can have
when created using WorkflowBuilder is eight (there are eight ports per icon). Each
successor set can have one or more tasks in them. Therefore, when a task is completed, the
user has the option of selecting a successor set. When a selection is made, all the tasks in that
successor set start.
In the following graphic, note that the transaction between the Review User Task and its
successor tasks (Submit to NJ and Submit to FR) originate from different points.
Submit (successor) tasks originate from Submit (successor) tasks originate from
different ports on the “Review” User Task. the same port on the “Review” User Task.
Result: the user chooses which one of the Result: both of the two successor tasks
two successor tasks gets started. get started.
Figure 29: Starting successor tasks
! In the graphic on the left (where tasks originate from different ports on the “Review”
User Task), when the “Review” User Task is completed, the task owner is given the
choice to select which of the two Submit successor tasks must be completed. The
selected task starts, but the task not selected does not start.
! In the graphic on the right (where tasks originate from the same point on the “Review”
User Task), when the “Review” User Task is completed, the task owner is given only
one choice. It differs from the other example in that Submit successor task is actually a
set of two tasks that must both complete. Therefore, when the task owner selects the
only option, both tasks are triggered.
87
In the workflow segment shown in the graphic, the User Task calls for a review of some
work done by an author. The reviewer (typically an Editor) has the choice of approving the
work and creating a nested job (Submit to NJ) or approving the work and submitting it for
final review (Submit to FR). There is a third option: the “Review” User Task has a Reject
arrow originating from the lower left port of the task icon but it is cropped out of the image.
Adding Conditions
The AND, OR, and NOT condition elements specify the conditions under which a task
becomes active. When a finishing task signals a successor task, the successor task notes that
the finishing task has signaled and then evaluates the logic of the element to determine if it
should become active.
To add a conditional element to a transition:

1. Select a condition element from the toolbar.
When you move the pointer to the canvas, a graphic icon appears under it to indicate
that a mouse click will place a graphic on the canvas.
2. Draw transition lines from predecessor tasks to the condition, and from the condition to
the successor task.
Adding Text Labels

You can add text labels to objects on the canvas. Text labels, unlike name and description
attributes, allow you to enter an unlimited number of characters. You can use labels to add a
descriptive name or explanatory notes.
To add text labels, follow these steps:

1. Click the text label button in the Tasks toolbar.
2. Click on the canvas where you want to place the text label.
A text area appears with selection boxes around it where you click.
3. To edit the text of the label, move your cursor into the boundaries of the text label and
double-click.
4. Right click when you finish placing text labels on the canvas.

Getting Started
Moving Objects
You can place objects anywhere on the canvas. You can also use the alignment buttons in the
toolbar to align objects on the canvas.
To move an object on the canvas, follow these steps:

1. Move the mouse pointer over the object you want to move. A multidirectional arrow
displays at the tip of your pointer.
2. Click and drag the object to where you want to place it.
Selecting Multiple Objects

To align objects on the canvas, you must select more than one object. You can also select
multiple objects and drag them around the canvas.
To select multiple objects, hold down the Shift key on your keyboard and click on the
objects you want to select. When an object is selected, selection boxes appear around the
object:
Figure 30: Object with selection boxes
Aligning Objects
You can align objects on the canvas by using the alignment buttons in the toolbar.
Option Description
Align Top Aligns the top of objects with the top of the last object
selected.
Align Horizontal Centers Aligns the horizontal center of objects with the center of
the last object selected.
Align Bottom Aligns the bottom of objects with the bottom of the last
object selected.
Align Left Aligns objects with the left side of the last object selected.
Align Vertical Centers Aligns the vertical center of objects with the center of the
last object selected.
Align Right Aligns objects with the left side of the last object selected.
89
To align objects, follow these steps:

1. Select two or more objects. The alignment buttons in the toolbar become active.
All objects selected are aligned relative to the object you select last.
2. Use the alignment buttons in the toolbar to align the objects.
Setting Attributes
To set attributes of a task or transition, follow these steps:
1. Select the arrow in the toolbar.
2. Click the task or transition whose attributes you want to select.
3. Click the Attributes tab in the left pane. The attributes for that task or transition
display in the Attributes window.
4. Click the Value column of the attribute you want to set. Some attributes can be set
using a pull-down menu (for example, AreaVPath). If you are connected to the
TeamSite server you can set some attributes using the ... button (for example,
AreaVPath or Owner). Other attributes must be typed (for example, Description).
If you want to use a variable for the value of this attribute, select its name from the
pull-down menu.
If you want to use information from the TeamSite server, click the ... button and select
the value you want from the list that appears.
If you want to type the value in directly, double-click on the Value column of the
attribute you want to set, and enter the value. Some attributes (for example,
AreaVPath) cannot be set this way.
All workflow templates must contain at least one Task with the Start attribute set to Yes. A
template can contain multiple Start attributes. For example, consider a job that, upon being
instantiated, needs to send different pieces of email to four different people and run a
process that generates one of the files to be manipulated during the workflow process. Since
none of these tasks have a dependence on the others, you can run them in parallel, each with
its own Start attribute.
Tasks with Start attributes are displayed using a green text box across the top of the task
icon:
Figure 31: Start attribute assigned to task
Each template must contain an End task.

Getting Started
Setting Variables
WorkflowBuilder allows you to set three types of variables: system, custom, and user. You
can use these variables to specify values of attributes.
Creating System Variables

To set a system variable, follow these steps:
1. Click the Variable tab in the Attributes window.
2. Double-click an entry in the Name column. Enter the name of your variable.
3. Double-click the corresponding entry in the Value column. Select System Variable
from the pull-down menu.
4. The Select System Variable window appears. Select the system variable you want to use.
Click OK.
When the workflow template is transferred to the TeamSite server, the variable is set to the
value you select (for example, if you named the variable userrole and selected iw-role as
the system variable, userrole is set to the role of the user who instantiates the job).
Creating Custom Variables

WorkflowBuilder includes a Perl Code Editor that enables you to add Perl code (including
custom variables) to workflow templates. This functionality is commonly used to control
the appearance of the forms associated with your template.
“Defining Custom Variables” on page 242 describes the creation a number of custom
variables within the context of the creation of an entire workflow template. To create
custom variables, follow these steps:
1. In the Variables window, click the Variables tab.

2. Double-click an empty cell in the Name column and enter a name for the new variable.
Custom variable names should begin with a lower-case “c”, for example cCustom.
Following this convention ensures that the variables you create do not conflict with
others included with future releases of WorkflowBuilder.
3. Double-click in the Value column and select Custom from the pull-down menu.
4. Select View > Perl Code Editor to open the Perl Code Editor.
5. In the Perl Code Editor, enter the corresponding Perl code to define the variable.
Creating User Variables

To create a user variable, follow these steps:
1. Click the Variable tab in the Attributes window.
2. Double-click an entry in the Name column.
91
3. Enter the name of your variable.

4. Double-click the corresponding entry in the Value column.
5. Select User Variable from the pull-down menu.
6. The Specify User Variable dialog displays:
Figure 32: Specify User Variable dialog box
7. In the Name of label field, enter the text you want to appear next to this variable in the
New Job template.
8. Optionally, enter the default value of this variable in the Default value field.
9. Optionally, click the Advanced button to display the following variable settings:
" In the Is this variable required? section, select Yes or No.
" In the Enter validation rules section, enter any rules you want to use to determine
valid input types. These rules must be specified using Perl regular expressions.
" In the Specify error message section, enter the error message you want to display
in the New Job template if the job creator enters an invalid value.
10. Click OK.
Configuring Templates to Include Preselected Files

You can configure workflow templates that enable job creators to attach files to jobs when
they set job parameters in the TeamSite GUI. These preselected files are automatically
attached to each task in the job as the job transitions from task to task.
To configure templates to include preselected files, follow these steps:

1. In the Attributes window, click the Workflow Attributes tab.
2. In the Attribute column, double-click Preselected Files and set the value to No.
3. On the canvas, select the task that you want to be the Start task.
4. In the Attribute window, click the Attributes tab.
5. In the Attribute column, double-click the Start attribute and set the value to Yes.
The File attribute of the Start task is automatically set with the Perl variable
$iw_selected_files [];. WorkflowBuilder prevents you from editing the value of
the File attribute of any other task in the template after the Preselected Files workflow
attribute has been set to Yes and a Start task has been specified.

Editing Existing Workflow Templates
Note: Set the value of the Preselected Files attribute to No if files will be added to the job
after it has been instantiated.
Editing Existing Workflow Templates

You can edit workflow templates that have been created using WorkflowBuilder. You cannot
use WorkflowBuilder to edit workflow templates that have not been created using
WorkflowBuilder because these files do not contain a workflow diagram.
To open a workflow template, follow these steps:

2. Navigate to the workflow template you want to edit, and click Open.
3. In the Login dialog box, enter your login information, or choose Offline Mode.
The file opens in WorkflowBuilder.
4. Edit the workflow template:
Select View > Attributes Window to display the Attributes window so you can set
attributes on the elements you place in your workflow template.
(Optional) Select View > Output Window to open the Output window to view
validation comments as you work.
5. Select elements from the toolbar and place them on the canvas in the order you want.
6. Set attribute values for each element.
7. When you finish, select File > Save and check the Output window to make sure there
are no validation errors. You can then send your workflow template or job to the
TeamSite server.
Sending Workflow Templates to the Server

After you create a workflow template, you must transfer its two associated files (the .wft
and the .wfb files) to the TeamSite server and decide what constraints (if any) to place on
the file to control access to it. When the file is transferred to the server, the
available_templates.cfg file is automatically updated to reflect that this new (or
modified) workflow file is available to specified TeamSite users. The files you send to your
TeamSite server are placed in iw-home/local/config/wft/wfb.
To transfer a workflow template to the TeamSite server, follow these steps:

1. Open WorkflowBuilder.
93
3. Locate and select the .wft file you want to send to your TeamSite server (note that
recently opened files are available on the File menu).
The Login dialog box displays.
4. Log in to your TeamSite server as a Master user (for details about the Login procedure,
see page 82).
The selected file displays in WorkflowBuilder.
5. Select File > Send to Server.
The Workflow Constraints dialog box displays with the WFT_Type tab activated.
Figure 33: Workflow Constraints dialog box
6. Click OK to accept the default constraint settings (by default, all users may use all
workflow templates on all branches) or define a constraint for the selected workflow
file as described in “Workflow Template Constraints” on page 95.
7. Choose the type of job your workflow template will create (New Job or Submit Job).
8. Click OK.
The available_templates.cfg configuration file is updated on your TeamSite server.
The transferred workflow template is available to users connecting to the server using
the TeamSite user interfaces.
Note: If you transfer a job specification file (a file that describes a particular job), the job is
instantiated immediately.

Workflow Template Constraints
WorkflowBuilder and available_templates.cfg

WorkflowBuilder contains a number of server-related features that make modifications to
the available_templates.cfg file. These features enable you to:
! Send and retrieve workflow templates from the server.
! Change the state of a workflow template on the server (valid states are active or
inactive).
! Delete files from the server.
! Define constraints that control access to each workflow template based on any
combination of user, role, branch, and type (how the workflow is instantiated, for
example, by starting a new job).
The available_templates.cfg is an XML file which can be modified in a text editor if

you prefer. Before making manual modifications to the file, ensure you understand the
structure and contents of the file as described in this chapter.
By default, the available_templates.cfg file is located in iw-home\local\config\wft.

TeamSite enables you to control access to specific workflow templates by setting constraints
on the workflow template files when they are published to the TeamSite server. A constraint
is constructed by selecting an entry from each of the following tabs in the Workflow
Constraints dialog box:
! Workflow Template Type (WFT_Type)
! Users
! Branch
The Workflow Constraints dialog box displays when you send your workflow template files
to your TeamSite server (see “Sending Workflow Templates to the Server” on page 93).
These constraint types are described in the following sections and the procedure for creating
workflow constraints begins on page 97.
Workflow Template Type Constraints

The WFT_Type tab of the Workflow Constraints dialog box enables you to determine how
each type of workflow template is invoked (for example, through the Submit or New Job
commands from the TeamSite GUI). By default, you can control access to the selected
workflow template file to following types:
! all—Valid for any type of job.
! assign—Valid only when you do an Assignment of a file to a user.
! iwcs_new_job—No longer valid.
! new_job—Valid when you select the New Job option from a TeamSite user interface
to start a new workflow.
95
! new_TFO_job—Valid when you select the New Job option in TeamSite Front-Office.
! submit—Valid when a Submit is performed from a TeamSite user interface.
! tt_data—Specifies this workflow file be invoked when closing a TeamSite
FormsPublisher data record in ContentCenter Standard (by default) or in
ContentCenter Professional (when configured in the UITK).
! tt_deletedcr—Specifies this workflow file be invoked when deleting a TeamSite
FormsPublisher data record in ContentCenter Standard only.
Note: You can add your own custom workflow types by clicking Add New Type and
entering a new type name in the window. The new type is added to the list when
you click OK.
The WFT_Type tab also enables you to assign a title to the workflow template file. The
Title field defaults to the file name given when the file was created or saved in
WorkflowBuilder, but can be changed by editing the name in the Workflow Constraints
dialog box. After sending the template to the server, this title displays in the list returned by
the New Job or Submit Job functionality of the TeamSite user interfaces.
Figure 34: Select a Workflow dialog box with a new workflow included
The WFT_Type tab also contains an Overwrite Existing File option that enables you to
overwrite workflow template files already on the server with updated versions of the same
file.
User Constraints
The Users tab of the Workflow Constraints dialog box enables you to specify which users
and types of users (defined by TeamSite roles) can access the workflow template file being
sent to your TeamSite server.
The Users tab displays the users stored in each of the four TeamSite Roles files (admin.uid,
author.uid, editors.uid, and master.uid). For more information about defining and
managing TeamSite Users, refer to the TeamSite Administration Guide.

Branch Constraints
The Branch tab of the Workflow Constraints dialog box enables you to specify from which
branches the workflow template can be accessed.
Note: If you do not specify a branch constraint, the template is available from all branches.
Defining a Workflow Constraint

To define a workflow constraint for a template file, follow these steps:
1. Open a completed workflow template file from within WorkflowBuilder.
2. Log in to the TeamSite server where you want to send the file.
The Workflow Constraints dialog box displays with the WFT_Type tab activated and
the file name used as the default title:
Figure 35: Workflow Constraints dialog box - WFT-Type tab
4. Select the type of template you are sending to the server (the default types are defined
on page 95).
This selection determines how the workflow template is invoked.
5. Optionally, enter a new title for the template in the Title field.
The entry in the Title field displays in the TeamSite user interface when the end-user
selects the “type” of activity associated with the selection made in the previous step.
6. Click the Users tab to make it active.
97
Figure 36: Workflow Constraints dialog box - Users tab
7. From the Role menu, select the Role of the individual user or group of users to whom
you want to allow access to this type (selected in step 4) of workflow file.
The Available Users list displays all the users with an entry in the Role file that
corresponds with your selection. In this example the Editor role is selected.
8. Click Select All or an individual user (you can use Shift+Click to select multiple users)
from the Available Users list.
9. Click >> to send the selected users to the Included Users list.
In this example, three editors (Bob, Jerry, and Phil) were added to the Included Users
list.
10. Click the Branch tab to make it active.
Figure 37: Workflow Constraints dialog box - Branch tab

11. In the Branch Expression field, type the name of the branch where you want this
template to be available, for example, main/PressRelease.
This branch must already exist on your TeamSite server. This procedure does not create
the branch.
12. Click Add Branch.
The branch you entered is displayed in the Branch List.
13. Repeat steps 11 and 12 for each branch where you want this template to be available.
14. In the Branch List, highlight all the branches where you want this template to be
available (you can use Shift+Click to select multiple branches).
15. Click OK to send the template to your TeamSite server with the constraints you just
defined.
To modify the constraints of a template, open it in WorkflowBuilder (either a local copy or

by doing File > Get From Server) and repeat this procedure; be sure the Overwrite
Existing File option is checked on the WFT_Type tab.
Effects on available_templates.cfg File

The use of constraints affects the available_templates.cfg file. The example illustrates a
number of points about the file’s structure and contents. It includes one of the default
workflow templates (author_submit.wft) and a template created using WorkflowBuilder
called custom.wft.
The following graphic shows the WorkflowBuilder’s Workflow Constraints settings that are
used to create these constraints.
Figure 38: Workflow Constraint Settings that will impact available_templates.cfg
99
Note the following:

! The title Custom is entered in the Title field of the WFT_Type tab. This title and the
actual file name (custom.wft) are both referenced in the available_templates.cfg
file.
! new_job is specified as the template type on the WFT_Type tab.
! The Users tab’s Role field is set to editor.
! Three users have been moved to the Included Users field. These three users must have
been previously added to the editor.uid file located in iw-home/TeamSite/conf/
roles.
! No branch constraints were defined on the Branch tab.

The following example shows how the data entered in the Workflow Constraints dialog box
is stored in the available_templates.cfg file.
<?xml version="1.0" standalone="no" ?>

<!DOCTYPE available_templates SYSTEM './available_templates.dtd'> Specifies the dtd
file used by this file
<available_templates> Begins a template file section (this
<template_file name='Author Submit Workflow' is one of the default templates)
path='default/author_submit.wft'>
<command_list> Specifies this workflow template
<command value='submit' /> can be invoked through Submit
<command value='all' include='no' /> Specifies this workflow template
</command_list> cannot be invoked by other means
<role_list>
Specifies Authors can use
<role value='author' include='yes' allusers='yes'/> this workflow template
<role value='all' include='no' allusers='yes'/>
Specifies other roles cannot
</role_list> use this workflow template
</template_file>
. Ends a template file section
.
.
Begins a template file section (this was created
<template_file active="yes" name="Custom" using WFB and stored in the wfb directory)
path="wfb/custom.wft">
<command_list> Specifies this workflow template
<command include="yes" value="new_job"> can be invoked through New Job
</command>
</command_list>
<role_list>
<role include="no" value="admin">
</role>
<role include="no" value="author"> Specifies this workflow
template can only be
</role>
invoked by Editors
<role include="no" value="master">
</role>
<role include="yes" value="editor">
</role>
</role_list>
<user_list>
<user include="yes" value="Bob"> Further specifies that this
</user> workflow template can
<user include="yes" value="Jerry"> only be invoked by the
</user> Editors Bob, Jerry, or Phil
<user include="yes" value="Phil">
</user>
</user_list>
</template_file>
</available_templates>
101
Retrieving Files from the Server

You can retrieve copies of workflow template files already transferred to your TeamSite
server using WorkflowBuilder. This functionality downloads a copy of both the .wft and the
.wfb files to any client machine with WorkflowBuilder installed. After opening one of these
files, you can modify it and repost it to the server or do a File > Save As to use it as the
foundation for creating a new workflow template.
Note: You can only retrieve active templates from the TeamSite server. If the file you
want to retrieve is not an active template, you must complete the procedure
described on page 103 to change the template’s state to active
To copy workflow templates from your TeamSite server, follow these steps:
1. Select File > New Workflow to display the Login dialog box.
2. Log in to the server where the workflow template you want to retrieve is stored.
3. Select File > Get From Server.
The Copy Template from Server dialog box is displayed:
Figure 39: Copy Template from Server dialog box
4. Select the template you want to copy to your client machine.

The path to the selected file and its title display next to the corresponding labels. The
file specifies the .wft extension but both the .wft and the .wfb files are downloaded.
5. Click Browse to display the Save As dialog box.
6. Enter a name for the files in the File name field.
The name selected in this step is used for both template files: one with a .wft extension
and one with a .wfb extension.
7. Select the location where you want to store the two template files.

Deleting Files from the Server
8. Click Save.
The path and the file name you selected are displayed in the Save As field of the Open
Selected Template dialog box.
9. Click OK.
Deleting Files from the Server

You can delete workflow templates from your TeamSite server from within
WorkflowBuilder. This functionality deletes both the .wft and the .wfb files from the
server. WorkflowBuilder’s Delete Templates dialog box also includes functionality for
undeleting files mistakenly deleted and changing the state of a workflow template on your
server (valid states are Active and Inactive).
State changes are written to the available_templates.cfg file, and are controlled by the
include attribute. Active workflow templates have the include attribute set to yes. Inactive
workflow templates are set to no. The following line from the available_templates.cfg
file shows the state of a file named LegalApproval.wft:
<template_file active=“yes” name=“LegalApproval” path=“wfb/
LegalApproval.wft”>
To either delete workflow template files from your TeamSite server or to change their
current state, follow these steps:
1. Select File > New Workflow to display the Login dialog box.
2. Log in to the server where the template files you want to delete are stored.
3. Select Tools > Delete Templates.
The Delete Templates dialog box displays.
Figure 40: Delete Templates dialog box
103
4. Delete a workflow template from the TeamSite server:

a. Set the Status field to correspond with the state of the file you want to delete
(either Active or Inactive).
The list of workflow templates displays all the files with the selected status. Note
that the list specifies the .wft extension but both the .wft and the .wfb files are
deleted.
b. Select the file you want to delete.
The path to the selected file and its title display next to the corresponding labels.
c. Check the Delete From Server box.
d. Click OK.
5. Change the state of a workflow template on the TeamSite server:
a. Set the Status field to correspond with the current state of the file you want to
change (either Active or Inactive).
The Templates list displays all the files with the selected status.
b. Select the file whose status you want to change.
The path to the selected file and its title display next to the corresponding labels.
c. Ensure the Delete From Server check box is cleared.
d. Click OK.
The selected workflow template’s entry in available_templates.cfg is updated
to reflect the change.
Note: Selecting Tools > Undelete Templates undoes either of these actions: it undeletes
the selected file if the Delete From Server check box is checked, or it reverts to the
previous state of the file if the check box is cleared.
WorkflowBuilder Error Codes

The following error codes are displayed by WorkflowBuilder under the specified condition.
Note: Double clicking on a WorkflowBuilder error message displays the task the error
occurred in if the error output window is docked (that is, not “floating”).
Condition Error Message

FAILURE Unknown Reason
WFB_SUCCESS Success
READ_ERROR Failed to read the complete file
WRITE_ERROR Failed to write the compete data to the file

WorkflowBuilder Error Codes
Condition Error Message

FILE_EXISTS File already exists
INVALID_FILEPATH Invalid file path
INSUFFICIENT_PERMISSION Permission Denied
LOGIN_FAILED Login failed
INVALID_SESSION Session invalid
USERDATA_NOT_AVAILABLE Username not set
HTTP_ERROR Communication Error
UNKNOWN Unknown Error
NO_FILE_NAME Invalid File Name
INVALID_ROLE Invalid Role
NOT_MASTER Not Master
OPEN_ROLE_FILE_FAILED Failed to open role files
CLOSE_SESSION_FAILED Close session failed
OFF_LINE Off Line
MEMORY_ALLOCATION_FAILED Memory allocation Failed
ACCESS_DENIED Access Denied
DISK_FULL Disk Full
WFB_EROFS TeamSite server is frozen
EMPTY_DIRECTORY Directory is empty
INVALID_ERROR_CODE Error code is invalid
XML_PARSE_ERROR XMl Parse Error
SERVER_NOT_INSTALLED Server Component of WFB is not installed
INVALID_SERVER_ID Invalid Server ID: TeamSite
FAILURE_GETTING_ARCHIVE_NAME Failure Getting Archive Name: TeamSite
FAILED_BRANCH_ITERATION Failed Branch Iteration: TeamSite
NO_BRANCH_NAME Branch Without A Name!!!: TeamSite
FAILED_WORKAREA_ITERATION Failed Workarea Iteration: TeamSite
NO_WFB_FILE The WFB for this template is not available
NO_WORKAREAS No Workareas
105

Chapter 6
Creating Workflow Template Files
This chapter describes the structure and contents of workflow template files. These files
include the sample workflow templates installed by the TeamSite installation program,
example files installed by the WorkflowBuilder installation program, and workflow
templates created with WorkflowBuilder.
The following sections contain 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 124.
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.
107
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",
],
);

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 122.
<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 the instantiator CGI 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 instantiator CGI.
! 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 “<normal>TAG_info Directive” on page 112).
! 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 CGI 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 111).
109
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... );
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:
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.
111
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'>",
};

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:
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(@_)',
]
)
113
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'>",
);
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.
115
Usage
__TAG__($tagname);
Description
When the instantiator CGI 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 programatically. 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.
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 120 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.
117
__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 120 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)
#
119
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 107, 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");
121
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 108; 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”.
! 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">
<areavpath v="__TAG__('iw_workarea');"/>
<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.">
.
.
.
123
Regular Expression Support

You can use regular expressions within workflow templates to search for a specified pattern
and specify what to do when matching patterns are found. For example, you can perform
regular expression searches for constraints on workflow templates.
Consider the following TeamSite structure:
/default/main
— administrator -a1
-a2
-a3
— marketing -m1
-m2
-m3
— sales -s1
-s2
-s3
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:
<branch_list>
<branch value="/default/main/administrator_1/a1" include="yes" />
<branch value="all" include="no" />
</branch_list>
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 following line:
Or you could modify the available templates.cfg file to use the following regular
expression and automate the constraints placed on the a4 branch:
<branch_list>
<branch value="/deault/main/administrator_1/.*" include="yes" />
<branch value="all" include="no" />
</branch_list>
This regular expression allows users from any branch under /deault/main/
administrator_1 to have access to the template.

Regular Expression Support
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 value="foo" include="yes"/>
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 value="^/default/main/foo" include="yes"/>
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 value="^/default/main/foo" include="yes"/>

<branch value="^\default\main\foo" include="yes"/>
<branch value="^\\default\\main\\foo" include="yes"/>
<branch value="^/default\main\\foo" include="yes"/>
125

Chapter 7
In addition to creating Job files in WorkflowBuilder (as described in Chapter 5, “Using

WorkflowBuilder”) or writing a .wft (as described in Chapter 6, “Creating Workflow
Template Files”), you can create a job by directly editing an XML job specification file. This job
specification file must:
! Reside in the TeamSite home directory
! Be structured as described in “Job Specification File” on page 127
! Use elements as described in “Job Specification DTD” on page 128
See “Sample Job Specification File” on page 165 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
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 165 for examples of files that use these
elements.
127
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?,

variables?)>
<!ATTLIST grouptask name ID #REQUIRED
start (t|f) "f"
lock (t|f) "f"
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, timeout?,

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, srcareavpath,

timeout?, files?, activation?, inactivate?, resets?,
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,

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?,
variables?)>
<!ATTLIST dummytask name ID #REQUIRED
start (t|f) "f"
129
<!ELEMENT locktask (description?, areavpath, success, failure,

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

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

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

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

<!ATTLIST wftfile v CDATA #REQUIRED>
<!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.
The workflow Element

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 132.
! variables—see page 132.
! usertask—see page 140.
! submittask—see page 150.
! updatetask—see page 151.
! externaltask—see page 145.
! cgitask—see page 148.
! endtask—see page 153.
131
! grouptask—see page 142.

! dummytask—see page 154.
! locktask—see page 155.
! wftask—see page 156.
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.
The description Element

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)>
The variables Element

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"
The areavpath Element

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"
The timeout Element

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 134.
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"
133
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"
The succ Subelement

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"
The files and file Elements
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>
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."
The activation Element

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.
The inactivate Element

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
135
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.
The resets Element

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

The eastartop Element

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
137
The eafinishop Element

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

The wfvarstartop Element

The wfvarstartop element defines how TeamSite variables 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 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.
The wfvarfinishop Element

The wfvarstartop element defines how TeamSite variables can be set, modified, or
deleted on the files contained by the task 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.
139
! name—specifies the key value of

the job variable.
! value—specifies the key value associated with the name attribute.
The usertask Element

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
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 133.
! successors—see page 141.
! timeout—see page 133.
! files—see page 134.
! activation—see page 135.
! inactivate—see page 135.
! resets—see page 136.
! eastartop—see page 137.
! eafinishop—see page 138.
! wfvarstartop—see page 139.
! wfvarfinishop—see page 139.
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.
The successors Element

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 134.
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.
141
The grouptask Element

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 143.
The following attributes are associated with the grouptask element:
name.


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.
or modifying files.
! 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.
The sharedby Element

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 144.
! group—see page 144.
143
The user Element

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"
The group Element

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"

The externaltask Element

The externaltask element defines an external task 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 146.
The following attributes are associated with the externaltask element:
name.
145
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.
or modifying files.
! 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.
The command Element

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:
<!ATTLIST command
v CDATA #REQUIRED>
The following attribute is associated with the command element:
! v—specifies the 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.
147
The cgitask Element

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*,
wfvarstartop*, wfvarfinishop*, variables?)>
<!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 146.


! variables—see page 132
The following attributes are associated with the cgitask element:
name.
! lock—when the lock attribute is set to t, the task acquires TeamSite locks on all the
of the files it contains, it releases any locks it has already acquired and try again every
a lock for a file, it checks first to see if that file is locked by some other task in its own
! 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 148 for more information on the useage of the immediate attribute.
or modifying files.
149
The submittask Element

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

The following attributes are associated with the submittask element:
name.
! 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.”
The updatetask Element

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, srcareavpath,
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" >
151
If the update task fails because of conflicts, it goes into a state like that of a failed submit
task. 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 141.
! scrareapath—see page 153.
The following attributes are associated with the updatetask element:
name.
! delete—propagates deleted files to the destination area.
! overwritemod—overwrites conflicting versions of files in the destination area.
of the files it contains, it releases any locks it has already acquired and tries again every
a lock for a file, it checks first to see if that file is locked by some other task in its own

The srcareapath Element

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 following attribute is associated with the srcareapath element:
! v—specifies the TeamSite path from which the files are copied. For example:
v="/default/main/WORKAREA/jdoe"
The endtask Element

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:
name.
153
The dummytask Element

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

The locktask Element

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*, wfvarstartop*,
wfvarfinishop*, variables?)>
<!ATTLIST locktask
name ID #REQUIRED
start (t|f) "f"
The following subelements are associated with the locktask element:
! success—see page 158.
! failure—see page 158.
The following attributes are associated with the locktask element:
name.
155
The wftask Element

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 owner CDATA #REQUIRED
name ID #REQUIRED
start (t|f) "f"
The following subelements are associated with the wftask element:
! jobfile—see page 157.
! wftfile—see page 157.

The following attributes are associated with the wftask element:
name.
The jobfile Element

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 following attribute is associated with the jobfile element:
! v—specifies the full path to the job specification file. For example:
v="__INSERT__($iwhome/local/jobs/nestedwftask_B.xml);"
The wftfile Element

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>
The v attribute is associated with the wftfile element. It specifies the full path to the
workflow template file. For example:
v="__INSERT__(iw-home/local/config/wft/devnet/nestedwftask_B.wft);"
157
The success Element

The success element defines the successor tasks that become active when the lock 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 134.
The failure Element

The failure element defines the successor tasks that become active when the lock task
fails.
DTD Definition
In the job specification DTD, the failure element is defined as:
<!ELEMENT failure (succ+)>
The succ subelement is associated with the failure element. For information, see
page 134.

Perl Modules
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.
GetActiveWorkflows() Returns an array of WFworkflow objects
corresponding to 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($spec) ,
CreateWorkflow($spec,$tmpfile) Creates a workflow instance from $spec (a
workflow specification in the form of a string).
Returns a TeamSite::WFworkflow. If the
$tmpfile arg is set, 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.
159
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_string) Sets the error message to $error_string and
returns the previous error 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, $task)=GetTaskByName($taskname)
TaskName should be specified in UTF-8 encoding.
Returns task in the workflow with name
$taskname. $task is a possibly invalid
TeamSite::WFtask object. $success is 1 if
successful.
GetDescription() Returns the description for this workflow.

Perl Modules
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($name) Gets the value of a workflow variable.
SetVariable($name, $value) Sets the value for a workflow variable. Returns
exit status of underlying CLT (non-zero indicates
an error occurred).
CreateVariable($name, $value) Creates a workflow variable. If the variable
already exists, this fails.
DeleteVariable($name) Deletes a workflow variable.
SetDescription($value) Value should be specified in UTF-8 encoding.
Changes the description 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.
161
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, \@groups) Returns the users and groups that share this task
as lists of strings. For example:
my @users;
my @groups;
$task->GetSharedBy(\@users, \@groups);
print "Users: ", join(", ", @users),
"\n";
print "Groups: ", join(", ", @groups),
"\n";
GetTimeout() Returns a string contain 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, $delta_format) Returns a string containing the task duration
formatted according to the 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, $comment) Adds a file with comment to a task.

Perl Modules
AddMultipleFiles(\@paths, $comment)
Adds one or more files with the same comment to
a task. Path and 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, $comment) Path and comment should be specified in UTF-8
encoding. Removes a 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, $value) Name and value should be specified in UTF-8
encoding. Set value of a task attribute. Returns
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
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
UntakeTask($user) Removes the current ownership of a shared
grouptask. Returns zero on error; non-zero on
success.
163
($success, $immediatetask) = SelectTransition($which, $comment)

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, $immediatetask) = CallBack($retcode, $comment)
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_and_c) Returns a (possibly empty) hash ref with file
names as the keys and 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, $felement)
Gets the file comments for the task. The result is
an array of hash refs, 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).

Sample Job Specification File
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, $value) Name and value should be specified in UTF-8
encoding. Set value of a task variables. Returns
an error occurred)
CreateVariable($name, $value) Name and value should be specified in UTF-8
encoding. Create a task variable. If the variable
already exists this will fail. Returns exit status of
occurred).
DeleteVariable($name) Name should be specified in UTF-8 encoding.
Delete a task variable. Returns exit status of
occurred).

The following job specification file could be created by direct editing (see “Running
Manually Created Jobs” on page 169) 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.
165


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

Running Manually Created Jobs
<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 Team-
Site 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.
169
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 8
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 not supported on non-English servers, remove the

VisualAnnotate functionality for these workflows if you are using a non-English
server (in TeamSite releases that support on non-English servers).
Users are prompted to install the VisualAnnotate client toolbar when they attempt to open a
file associated with either of the VisualAnnotate-enabled workflows.
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 174.
Task Checklist for Using VisualAnnotate

The following list provides an overview of the tasks that you must perform to install,
configure, and use VisualAnnotate successfully.
! Ensure that the server and client systems meet their respective system requirements.
! Install the VisualAnnotate as described in the TeamSite Installation Guide.
! Activate VisualAnnotate in configurable solutions workflows (recommended) or
integrate it into custom serial-review workflow templates. See “Configuring
VisualAnnotate” on page 175.
! Ensure that your VisualAnnotate-enabled workflow templates are available to TeamSite
users. See “Configuring VisualAnnotate” on page 175.
171
! Tell users how to install and use the VisualAnnotate toolbar on their client systems. See
the VisualAnnotate tutorial and online help.
! Ensure that you can log in to the TeamSite host system as a user having root (UNIX) or
Administrator (Windows) privileges.
! Ensure that no one is using the TeamSite system when you install VisualAnnotate
because the installation process restarts the TeamSite user interfaces.
! Familiarize yourself with the information about solutions workflows in Chapter 3.
VisualAnnotate Overview
VisualAnnotate is used in the context of TeamSite workflow. That is, VisualAnnotate tools
are activated when users view 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 My Tasks module in ContentCenter
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:
! The VisualAnnotate server is successfully installed on the TeamSite host.
! 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.

VisualAnnotate Overview
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 files are submitted to the staging area.
173
Installing the VisualAnnotate Client Toolbar

TeamSite prompts users to install the VisualAnnotate client toolbar when they attempt to
review a file associated with either of the VisualAnnotate-enabled workflows. The following
scenario describes the process leading up to the VisualAnnotate client toolbar installation:
4. After you log in to ContentCenter, you can display your assigned tasks.
Figure 41: Task List
In this example, both of the assigned tasks are part of VisualAnnotate-enabled workflow
jobs (specifically, the configurable_author_submit workflow).
5. Click one of the task numbers.
The Task Details display for the selected task.
Figure 42: Task Details

Configuring VisualAnnotate
6. Click File > Review link.

If the VisualAnnotate client toolbar is not installed, the following screen is displayed:
Figure 43: VisualAnnotate Toolbar installation screen
If it is not installed, you are prompted to install it.

7. Close all other browser windows—only one browser window can be open during the
installation.
8. Click Install.
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
175
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_reviewer.tpl
va_reviewer_email_body_template=/vannotate/templates/
va_mailbody_reviewer.tpl
va_reviewer_email_text_body_template=/vannotate/templates/text/
va_mailbody_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
177
The following table describes each variable:
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 on
active_user
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 the
active_user
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 can
one_per_cycle |
one_per_reviewer create.
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 176).
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.
179
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 when tasks are accessed through ContentCenter (as opposed
to accessed through VisualAnnotate email).

Chapter 9
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 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.
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
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.
181
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.
183
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="/usr/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 an id attribute whose value is the task ID.
! The element has a type attribute whose value is the name of the iwgetwfobj element
(usertask, externaltask, and so forth.)
185
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
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.
187
! 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.
! 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.
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
iw_solution_email.ipl Data Flow

The following graphic 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.
Job Header
Information Header
Template
Email Task Email Message HTML Email

Information Information Template HTML Part
Message
(XML)
Other Task Text

Plain Text Part
Information Template
Figure 44: Data flow for solution email
189

Chapter 10
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
instantiator CGI 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.
191
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:
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)
193
Workflow Tutorial
Task Symbols
The following graphic shows the task symbols used in the workflow diagrams in this
appendix.
User Task Group Task Lock Task
Dummy
Update Task Submit Task Task
External Task CGI Task Workflow Task
End Task
AND OR NOT
Figure 45: Task Symbols

Mapping Out Workflows
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.
Create New Job
externaltask externaltask externaltask
usertask usertask submittask
endtask
Figure 46: State Transition Diagram
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.
195
Workflow Tutorial
After you finish blocking out the diagram, go back and add descriptive titles, noting any
special attribute settings and variable usage to the various tasks.
Create New Job Job Author (Creator)

(creator) Author
Reviewer
(1) “NotifyAuthor” (3) (5)

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

“CreateDoc” “ReviewDoc” “SubmitWork”
[author] [reviewer] [reviewer]
(readonly) Approve
(7) “End”
Figure 47: Workflow diagram with descriptive titles
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

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 the following graphic, 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.
B1
Yes
No
A C
No
B2
Yes
Figure 48: Workflow diagram with logical conditions
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.”
When task A is activated, you want to not only inactivate B1 and B2, but also to ensure it
resets the table associated with task C, so that the next iteration through the concurrent
process will be treated identically to the first time through.
197
Workflow Tutorial
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 do 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 true.
Locks External to Workflow Engine

If you use a lock="t" attribute that exists for most tasks, this causes your workflow to
appear to go into limbo. The workflow engine attempts to get the lock on the files and fails
because the lock is outside of its control, and then it will sleep for a small amount of time
and try again indefinitely.
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 externaltask 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 it
is necessary to script some means of dumping the Audit Trail information (externaltask)
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.

Complex Tasks
externaltask
Scripts called from an externaltask 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. The new iw.cfg option external_task_add_filelist defaults to
true, but it is recommended that you set this to false and use the Perl method
TeamSite::WFtask::GetFiles() within your script rather than potentially exceeding the
operating systems command-line argument length limitations.
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, 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:
199
Workflow Tutorial
! The externaltask becomes active

! The externaltask 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.
! 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 TeamSite server process owner is in the iw-home/conf/roles/
master.uid file, 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 Techniques” on page 207.
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.

Complex Tasks
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.
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.
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 Techniques” on page 207.
Additional Information
All cgitask scripts must be located in: iw-home/httpd/iw-bin/.
201
Workflow Tutorial
If you need to pass parameters to the script on the command line, you can do so by adding
them as part of a query string to the command—using the encoded & for the “&”
character. For example:
<command v="mycgi.cgi?year=2001&month=6"/>
Alternatively, it can be more efficient to turn the parameters into task-level 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.

Complex Tasks
Retrieving File Comments

There are times, within either an externaltask or cgitask 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
203
Workflow Tutorial
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="tomato"/>
</successorset>
<successorset description="vegetable">
<succ v="broccoli"/>
</successorset>
</successors>
This collection of elements can be thought of as a Perl array:
my($fruit) = "tomato";
my($vegetable) = "broccoli";
my(@successors) = ("$fruit", "$vegetable");
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 the 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 and any subsequent email notification sent
with iwsend_mail.ipl will provide it for the recipient (see next section).

Complex Tasks
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 9, “Template-Based Email” for more information.
! Externaltask scripts for notification using iwsend_mail.ipl—Appendix C,
“iwsend_mail.ipl Script” for more information.
205
Workflow Tutorial
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 => "bgcolor='#COCOCO'
onLoad='top.resizeTo(600,400);'",
);
The parameters to resizeTo are the width and height respectively.

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.
207
Workflow Tutorial
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.
Message Explanation
Invalid workflow … This message may or may not contain more information.
Workflow xxx does not
exist It is usually an indication that an 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"/> in
for task xxx
the noted task which refers to a successor task by name
that does not exist. Check spelling of all successors very
carefully.
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 …/Mail/ This is usually an indication that the mail server and mail
Mailer.pm line xxx
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 job.
The workflow engine will continuously cycle through the attempt to obtain the lock
(approximately every 30 seconds). 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.

Designing a Workflow
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. Next, adjust the
available_templates.ipl script, and test it again. 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.
209
Workflow Tutorial
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.
Sample Workflows
This section contains two sample business process diagrams, and detailed steps by which one
might develop workflow templates within TeamSite to implement them.
Both workflows use the following methodology for building workflow templates:
1. Create generic workflow diagram

Draw (using flow-charting software) a generic business process diagram that represents
how users will need to interact with one another to do make changes to a Web site.
2. Note variables in workflow
Looking carefully at the workflow diagram, identify data points of the workflow that
will change depending on who is doing the work, such as the manager ID, the files to be
updated. Integrate the variables identified into another version of the workflow
diagram. Assign task names with each step or task in the workflow.
In order to be valid XML, task names must begin with either an underscore [_] or
alphabetic character [A-Za-z] and can only contain alphanumeric, underscore, and
hyphen characters [-_A-Za-z0-9]. Colons (:) are also legal, but have already been put
aside to have a special meaning. Avoid white space (<space>, <tab>) and dots (.).
3. Generate workflow template (.wft) code piece by piece:
a. CGI_info section
b. TAG_info section
c. Define Perl variables for use in various sections

d. Job specification XML

Sample Workflows
Both of the workflows include the diagrams one might generate for each of the above steps,
and also indicate for the reader's benefit the various features of the TeamSite workflow
engine featured in the workflow itself.
Sample Workflow 1: Serial Workflow with Deployment

This workflow is a content creation workflow with two approval steps:
1. The manager or job creator must approve changes.
2. A member of the QA group subsequently must approve the work performed.
Any rejection of changes returns the job back to the author for further modification. After
both parties have approved, the changes are submitted to the staging area.
Additionally, after content is submitted to staging, it needs to be queued for deployment to

a live production system. The queue time is specified by the job creator at instantiation
time.
The following TeamSite workflow features are implemented in this example:
! Task types: user, group, external, submit, dummy

! Dynamically generated workarea and author list box widgets
! Integration with an external deployment script
! Input form validation via regex pattern-matching
! Calculate timeout for dummy task based on form input
! Use of __TAG__, __VALUE__, __INSERT__ directives
! Debug mode option in input form
Create Generic Workflow Diagram

The following graphic shows a generic workflow diagram for this sample.
Reject
Author edits Manager QA Group

Manager content reviews member reviews
creates job Approve
Reject Approve
Deploy to Queue Submit to

production for staging
Job ends
deploy
Figure 49: Generic workflow diagram for serial workflow with deployment
211
Workflow Tutorial
Note Variables in Workflow

Make a note of the following variables in the workflow:
! Workarea for development
! Author
! Manager (implicitly, job creator)
! Number of days to queue deployment request
Redraw Workflow Diagram

Redraw the diagram, this time noting task “names,” variables, and significant attribute
settings. Also note the arrows. These indicate the state transition information. In workflow
terminology, this means the pred’s (predecessors) and succ’s (successors). Any time you
have more than one arrow leading into, or out of a task, it is in an indication that you will
need to accommodate multiple inputs or outputs in your coding.
The following graphic shows the EditContent task with three inputs. The first, “Manager
creates job” is handled by the attribute “(start)”, the second and third are the result of
another task further down the line sending control back to this task. This means that this
task will have multiple predecessors; you will see the code for this later.
Reject
“EditContent” “MgrReview” “QA-Review

Manager (start) (readonly) (readonly)
creates job [author] [iw_user] Approve
Reject Approve
“Deploy” “Delay” “Submit”

[iw_user] [iw_user]
“End”
<#-of-days>
Figure 50: Workflow diagram with tasks, variables, and attributes
Generate Workflow Template File

The accompanying workflow template files contain a significant amount of comments.
Much of the comments have been changed to text descriptions in this document to help
isolate the actual code snippets.

Sample Workflows
Write the XML Document Specification Information

In order for the workflow template to be considered well formed the first thing we do is
enter the XML doc specification tags (these are the same for every workflow template), then
start the workflow definition:
<workflow name="Sample1 - Serial Workflow"
owner="__TAG__('iw_user');"
creator="__TAG__('iw_user');"
description="__TAG__('iw_desc');">
Embedding Perl Code

The ability to embed Perl code within workflow templates is very powerful. Whether all in
one large block or split it into smaller blocks dispersed throughout the workflow template,
it is interpreted as if it were all one block of code.
Embedded Perl code must be enclosed within a template_script element and CDATA
tag. To begin this environment, use the following:
Define Appearance of Input Form with CGI_info Section

The built-in CGI_info subroutine section helps to determine the look (color, borders,
labels, and so forth) of the workflow instantiation form:
CGI_info(
valid_bgcolor => "#C0C0C0",
html_body_options => "bgcolor='#C0C0C0'",
submit_label => "Run Job" ,
cancel_label => "Cancel Job" ,
);
213
Workflow Tutorial
Define Perl Variables for TAG_info() Use

Just above the TAG_info function call, the HTML variables $workarea_html,
$author_html, and $archive_html are defined based on the pre-set branch (in this case,
"main/devnet") and the roles files:
use TeamSite::Config;
(my $iwhome = TeamSite::Config::iwgethome()) =~ tr|\\|/|;
Find our software
installation and set
eval("use Win32; $iwhome = Win32::GetShortPathName($iwhome);")
static variables
if ($Ô eq "MSWin32"); # Windows installation
my($BRANCH) = 'main/devnet'; # Hardwired for example
sub make_wapathlist {
Return HTML
my($branch) = @_;
selection box with
my(@pathlist) = map {
list of workareas.
s/^\s*(\S.*\S)\s*$/$1/s;
Input: a string
" <option>$_</option>\n"
containing the
} sort(`$iwhome/bin/iwlist "$branch/WORKAREA"`);
branch name (i.e.
return(join("", "<select size='3'>\n", @pathlist, "</select>\n"));
'main/www')
}
sub make_userlist {
my($usertype) = @_;
Return HTML return("<input type='text' value='== [r] $usertype.uid ($!) =='>")
selection box with if (!open(USER, "<$iwhome/conf/roles/$usertype.uid"));
list of users.
Input: one of my(@userlist) = map {
"author", "editor", s/^\s*(\S.*\S)\s*$/$1/s;
"admin", or " <option>$_</option>\n";
"master" } sort(<USER>);
return(join("", "<select size=5>\n", @userlist, "</select>\n"));
}
Generate HTML for
my($workarea_html) = make_wapathlist($BRANCH);
various tags that
my($author_html) = make_userlist('author');
are being used in
my($delay_html) = '<input type="text" value="60">';
the [TAG_info] form

Sample Workflows
Define Input Fields with TAG_info Section

In the following example, the built-in TAG_info subroutine defines the fields used in the
workflow instantiation input form. Multiple instances of the TAG_info section are
cumulative (one instance does not override another):
sub debug{
TAG_info(
iw_output_file =>
Comment out the "<input type='text' value='/tmp/foo.xml'>",
&debug; if you do iw_debug_mode =>
not want users to "<input type='radio' value='true'>True</input>" .
be able to debug "<input type='radio' value='false'>False</input>",
your WFT );
}
&debug;
TAG_info(
Note use of workarea =>
previously defined [ html => $workarea_html,
variable is_required => "true",
label => "Select a workarea",
error_msg => "<strong>Select a workarea.</strong>",
],
author =>
[ html => $author_html,
label => "Select an author",
error_msg => "<strong>Select an author.</strong>",
],
delay =>
[ html => $delay_html,
If value is entered, is_required => "true",
make sure it's a valid_input => '/^\d*$/',
number error_msg => "<strong>Invalid entry.</strong>",
label => "# of days to delay deployment",
],
);
215
Workflow Tutorial
Define Perl Variables for Task Use

Another thing you may need to write in Perl is any dynamically generated variables that will
be inserted, inline, into the job specification portion of the workflow template. In this
workflow, that includes the path to the workarea and staging area of the branch, the path to
the deployment script, and the timeout in +HHHHMM format:
Specify the
OpenDeploy my($iwperl) = ($Ô eq "MSWin32") ? "$iwhome/iw-perl/bin/iwperl" : "";
command. my($deploy_cmd) = "$iwperl $iwhome/local/bin/wft_deploy.ipl";
Calculate timeout
based on value of
input 'delay'. The my($timeout) = sprintf ("+%04d00", (24 * __VALUE__('delay')));
(delta) format of
timeout is:
"+HHHHMM"
End the Embedded Perl Section

In this example, one monolithic block is used for defining all of our Perl code. It must be
ended by closing both the CDATA tag and template_script elements:

Sample Workflows
Write the Job Specification XML

Now you can start entering the tasks. It is simpler for readability of the workflow template if
you write them in the order of the workflow as much as possible. Note the use of the
__INSERT__() directive for inserting previously defined Perl variables into the XML code.
Make heavy use of your workflow diagrams and comments. In the code examples here, the
comments have been moved to the side of the code.
<usertask name="EditContent"
Note: this is our owner="__TAG__('author');"
'start' task. description="Editing files for submission and deployment"
start="t">
<areavpath v="__INSERT__($work_area);"/>
<successors>
<successorset description="Submit for Mgr Review">
<succ v="ManagerReview"/>
</successorset>
</successors>
Note the use of the <activation>
<or> element to <or>
indicate that there <pred v="ManagerReview"/>
is more than one <pred v="QA-Review"/>
possible </or>
predecessor. </activation>
</usertask>
<usertask name="ManagerReview"
Note that this task owner="__TAG__('iw_user');"
is readonly. description="Reviewing files submitted by author"
readonly="t">
Note how each <successors>
successorset must <successorset description="Approve; send to QA">
have a description. <succ v="QA-Review"/>
This is what will </successorset>
show up in the <successorset description="Reject: send back to author">
menus for <succ v="EditContent"/>
transitioning </successorset>
interactive tasks. </successors>
<activation>
<pred v="EditContent"/>
</activation>
</usertask>
217
Workflow Tutorial
<grouptask name="QA-Review"
description="Reviewing files submitted by author"
readonly="t">
<successors>
<successorset description="Approve; submit to staging">
<succ v="Submit"/>
</successorset>
<successorset description="Reject: send back to author">
<succ v="EditContent"/>
</successorset>
Note that the
sharedby element </successors>
<sharedby>
can contain both
<group v='TeamSiteUsers'/>
group and individual

user names (though
</sharedby>
commented out
<activation>
here)
</activation>
</grouptask>
<submittask name="Submit"
Note that the
description="Submit files to staging">
submittask does not
have a
<successorset description="Deploy to external website">
<successors>
<succ v="Delay"/>
container for the
</successorset>
<successorset>
<activation>
element (there can
<pred v="QA Review"/>
be only one)
</activation>
</submittask>
<dummytask name="Delay"
Notice no description="Queue for deployment">
<successors> tag; <timeout v="__INSERT__($timeout);">
none required <succ v="Deploy"/>
because it isimplicit </timeout>
in the <timeout> <activation>
<pred v="Submit"/>
</activation>
</dummytask>
Note: The area here <externaltask name="Deploy"

is the staging area owner="__TAG__('iw_user');"
because we are description="Deploy content to production"
doing a content readonly="t">
push; this is <areavpath v="__INSERT__($staging_area);"/>
possible only <successors>
because this is a <successorset description="Done">
readonly task <succ v="End"/>
</successorset>
Insert previously </successors>
defined Perl <command v='__INSERT__($deploy_cmd);'/>
variable <activation>
$deploy_cmd <pred v="Delay"/>
</activation>
</externaltask>

Sample Workflows
<endtask name="End"
description="End Job">
<activation>
<pred v="Deploy"/>
</activation>
Note the end of the </endtask>
<workflow> element
here. This should
</workflow>
be the last item in
the workflow
template.
Miscellaneous Notes and Scripts

Particular to this workflow is an externaltask for content deployment. An exercise, examine
the following script and comments in for understanding how these scripts are called and
only preface with a couple of notes:
! Scripts are called by the workflow engine with the following syntax:
<path_to_script> <jobID> <taskID> <areavpath> <file1> <file2> ...
<fileN>
! Callbacks are necessary to indicate to the workflow engine when the script has finished
(and the task is thus ready to proceed to the next transition). The $retval (first
argument) to the iwcallback command (and TeamSite::WFtask::CallBack()
function) is an array index corresponding to the successor list of the task (array indices
begin at 0.
! Tip for testing: Disable the callback in the script until you are sure that it is working.
You can manually call the script using the syntax noted above from a shell/command
prompt to test its functionality (without transitioning from and thus deactivating the
associated task).
219
Workflow Tutorial
#!/usr/iw-home/iw-perl/bin/iwperl
######################################################################
# Copyright 1999, 2000, Interwoven Inc.
# All Rights Reserved.
#=====================================================================
# wft_deploy.ipl
#[...]
######################################################################
my($windows) = ($Ô eq "MSWin32") ? 1 : 0;
eval("use Win32::Process;use Win32;") if ($windows);
Determine the my($iwhome) = TeamSite::Config::iwgethome();

TeamSite home eval("$iwhome = Win32::GetShortPathName($iwhome);") if ($windows);
directory $iwhome =~ tr|\\|/|;
my($odhome);
if ($windows){
my($win32) = <<EOS;
Code like this,
use Win32::TieRegistry ( Delimiter=>"/", ArrayValues=>0 );
being 'eval'd, is
$Registry->Delimiter("/"); # Set delimiter to "/".
necessary to avoid
my($odKey) = $Registry->{"LMachine/Software/Interwoven/OpenDeploy/
problems trying to
"};
load platform-
$odhome = Win32::GetShortPathName($odKey->{'/od-home'});
specific Perl
EOS
module libraries.
eval("$win32");
}
else {
$odhome = "$iwhome/opendeploy";
die("Unable to determine OpenDeploy home directory")
if (! -d "$odhome");
}
my($iwmount) = TeamSite::Config::iwgetmount();
die("Unable to determine TeamSite mount point\n") if ($iwmount eq "");
my($ODCLIENT_CFGFILE) = "$odhome/conf/iwodclient.cfg";
Hard coded in this
my($ODCLIENT_DEPLOYMENT) = "wft_deploy";
example.
my($TMP) = $ENV{TMP} || $ENV{TEMP} || $ENV{TMPDIR} || "/tmp";
Open a log for my($LOGFILE) = "$TMP/wft_deploy.log";
debugging open (LOG, ">>$LOGFILE") || die ("[a] '$LOGFILE' ($!)\n");
information; $oldfh = select(LOG); $| = 1;
currently no way to
turn this off print "------------ begin wft_deploy.ipl ----------------------\n\n";

Sample Workflows
my($wfid, $taskid, $area) = (@ARGV[0..2]);

my($workflow) = new TeamSite::WFworkflow($wfid);
my($wfdescription) = $workflow->GetDescription();
my($wfowner) = $workflow->GetOwner();
Variables for later my($task) = new TeamSite::WFtask($taskid);
use. Note how my($taskowner) = $task->GetOwner();
they're filled in. my($taskdescription) = $task->GetDescription();
my(@taskfiles) = $task->GetFiles();
$area = "$iwmount$area";
my($branch);
print <<EOS;
AREA: $area
BRANCH: $branch
WORKFLOW_ID: $wfid
WFDESCRIPTION: $wfdescription
Debugging output
Task files:
EOS
for (my $i = 0; $i <= $#taskfiles; ++$i) {
print "\$taskfiles[$i] = $taskfiles[$i]\n";
}
my($deploylistfile) = "$TMP/wft_deploy_$$.tmp";
open(DEPLOYLIST, ">$deploylistfile") ||
die("[w] '$deploylistfile' ($!)\n");
Create temp file to for (my $i = 0; $i <=$#taskfiles; ++$i) {

hold deployment file my($f) = $taskfiles[$i];
list. $f =~ tr|\\|/|;
print DEPLOYLIST "/$f\n";
print "/$f\n";
}
close (DEPLOYLIST);
221
Workflow Tutorial
my($odcmd) = join(" ",

"$odhome/bin/iwdeploy",
Setup OpenDeploy "-fs $ODCLIENT_CFGFILE",
command with "-V 3 -events",
command line
"$ODCLIENT_DEPLOYMENT",
arguments. "area=$area",
"file_list=\"$deploylistfile\"");
if ($windows){
my($win32) = <<EOS;
unless(Win32::Process::Create($processObj,
"$odhome/bin/iwdeploy.exe",
$odcmd, 0, NORMAL_PRIORITY_CLASS, "." )){
$retval = Win32::GetLastError();
}
else {
Run the deployment print "Successful call... waiting for completion\n";
(Windows NT): $processObj->Wait(INFINITE);
If process creation $processObj->GetExitCode( $retval );
fails, signal error. unlink $deploylistfile;
Remove temp file }
only on success. if ($retval != 0) {
$message = Win32::FormatMessage($retval);
}
else {
$message = "Successfully deployed files.";
}
EOS
eval("$win32");
} #[end if($windows)]
else {
open(PIPE, "$odhome/bin/iwdeploy $odcmd 2>&1 |");
Run the deployment my(@text) = <PIPE>;
(UNIX): close(PIPE);
Capture output, $retval = $?;
check return code. $message = ($retval) ? join("", @text)
: "Successfully deployed files.";
}
Perform callback to $task->CallBack(0, $message);

workflow engine select($oldfh);
and exit. exit($retval);

Sample Workflows
Sample Workflow 2: Concurrent Workflow with Optional Task

This workflow implements a content contribution process where two phases of review and
approval are required: First, two managers must approve the changes; and then one of two
legal reviewers (pre-defined) must approve changes. If any of the users reject changes, the
job returns to the author for further changes. After both phases are passed, content is
submitted to staging. After that, the job is to stay in the system (rather than being purged) in
an archive state for 30 days.
During job creation, the user has the option of specifying whether to add specific files to the
job before passing it to the content contributor. If yes is specified, then an Add Files task
is inserted into the beginning of the job. Otherwise, the first task in the workflow is for the
author to modify (self-specified) content.
The following TeamSite workflow features are implemented in this example:

! Task types: user, group, dummy
! Dynamically generated workarea and author list box widgets
! Dynamically generated task XML (optional initial Add Files task)
! Use of __TAG__, __VALUE__, __INSERT__ elements
! Debug mode option in input form
223
Workflow Tutorial
Create Generic Workflow Diagram

The following graphic shows a generic diagram for this sample.
Manager
creates job
Manager
adds files
(optional)
Reject
Reject
Reviewer 1 Legal Review 1

Approve Approve
Author
edits Both
content approve
Reviewer 2 Legal Review 2
Approve Approve
Reject
Reject Either
approves
Archive
Submit
for
End 30
days
Figure 51: Workflow diagram with transition information and tasks
Note Variables in Workflow

Make a note of the following variables in the workflow:
! Workarea for development
! Author
! Approver 1, 2 (from editor file)
! Conditional processing (and/or)
! Option to provide task for manager to add files

Sample Workflows
Redraw Workflow Diagram Noting Task Names and Variables

As in the previous example, this time, when you draw (or augment) the diagram, note task
“names”, variables, and significant attribute settings.
Remember to note the arrows. These indicate the state transition information, the pred’s
(predecessors) and succ’s (successors). Any time you have more than one arrow leading
into, or out of a task, it is in an indication that you will need to accommodate multiple
inputs or outputs in your coding.
Manager
creates job
“AddFiles”
(start - optional)
Reject
Reject
“Review-Rev1” “Legal Bob”

(readonly) Approve (readonly) Approve
[appr1] [bob]
“EditContent”
(start-optional) Both
[author] approve
“Review-Rev2” “Legal Fred”

(readonly) (readonly)
[appr1] Approve [fred] Approve
Reject
Reject Either
approves
“Archive” “Submit”
[iw_user]
“End”
timeout
Figure 52: Workflow Diagram with task names and variables
225
Workflow Tutorial
Generate Workflow Template File (.wft) Code

The accompanying workflow template files contain a significant amount of comments, as it
should. Again, the comments have been turned into call-outs for the purposes of this
document.
Write the XML Document Specification Information

<workflow name="Sample2_Concurrent-Workflow"
creator="__TAG__('iw_user');"
description="__TAG__('iw_desc');">
Embed Perl Code

Begin the Perl code environment:
Define Appearance of Input Form with CGI_info Section
CGI_info(
valid_bgcolor => "#C0C0FF",
html_body_options => "bgcolor='#C0C0FF'",
submit_label => "Run Job" ,
cancel_label => "Cancel Job" ,
);

Sample Workflows
Define Perl Variables for TAG_info() Use

The following example shows how Perl variables for TAG_info() use can be defined.
my($BRANCH) = "main/devnet";
Hardcode branch. (my $iwhome = TeamSite::Config::iwgethome()) =~ tr|\\|/|;
Determine
TeamSite home my($TMP) = $ENV{TMP} || $ENV{TEMP} || $ENV{TMPDIR} || "/tmp";
directory. $TMP =~ tr|\\|/|;
etc. eval("use Win32; $iwhome = Win32::GetShortPathName($iwhome);")
if ($Ô eq "MSWin32"); # Windows installation
sub make_wapathlist {
my($branch) = @_;
my(@pathlist) = map {
Generate an HTML s/^\s*(\S.*\S)\s*$/$1/s;
formatted select list " <option>$_</option>\n"
from which to } sort(`"$iwhome/bin/iwlist" $branch/WORKAREA`);
choose a workarea. return(join("",
"<select size='1'>\n", @pathlist, "</select>\n"));
}
sub make_userlist {
my($usertype) = @_;
return("<input type='text' value='= $usertype.uid ($!) ='>")
if (!open(USER, "<$iwhome/conf/roles/$usertype.uid"));
Generate an HTML
formatted select list my(@userlist) = map {
from which to s/^\s*(\S.*\S)\s*$/$1/s;
choose a user. " <option>$_</option>\n";
} sort(<USER>);
return(join("",
"<select size='1'>\n", @userlist, "</select>\n"));
}
sub truefalse {
my($default) = @_;
my($true, $false) = ("", "");
if ($default eq "true"){
$true = "checked";
Generate HTML }
radio-buttons for else {
true/false response $false = "checked";
}
return(join("",
"<input type='radio' value='true' $true>yes</input>\n",
"<input type='radio' value='false' $false>no</input\n"));
}
Set some variables my($workarea_html) = make_wapathlist($BRANCH);

for use within my($author_html) = make_userlist('author');
TAG_info section my($editor_html) = make_userlist('editor');
my($truefalse_html) = truefalse("true");
227
Workflow Tutorial
Define Input Fields with TAG_info Section

The following example shows how input files with TAG_info can be defined.
TAG_info(
workarea =>
[ html => $workarea_html,
label => "Select a workarea",
error_msg => "<strong>Select a workarea.</strong>\n",
],
author =>
[ html => $author_html,
label => "Select an author",
error_msg => "<strong>Select an author.</strong>\n",
],
appr1 =>
[ html => $editor_html,
label => "Select mandatory approver #1",
error_msg => "<strong>Select an approver.</strong>\n",
],
appr2 =>
[ html => $editor_html,
label => "Select mandatory approver #2",
error_msg => "<strong>Select an approver.</strong>\n",
],
addfiles =>
Used to determine
[ html => &truefalse("true"),
whether the first
task is for adding
label => "Do you want to add files first?",
files
],
);
sub debug{
TAG_info(
iw_output_file =>
Comment out "<input type='text' value='/tmp/foo.xml'>",
&debug; to disable iw_debug_mode =>
debugging of "<input type='radio' value='true'>True</input>" .
workflow "<input type='radio' value='false'>False</input>",
);
}
&debug;

Sample Workflows
Define Perl Variables for Task Use

The following example shows how Perl variables for task use can be defined.
Vpath of user my($work_area) =

selected workarea. "/default/$BRANCH/WORKAREA/__TAG__('workarea');";
30 days expressed as my($timeout) = sprintf ("+%04d00", (30 * 24)); # days * hours/day

a delta (+HHHHMM)
my($edit_content_start_attrib) = "'t'";
my($add_files_predecessor) = "";
Set based on whether my($add_file_input) = __VALUE__('addfiles');
or not Add-Files is
desired as an initial if ($add_file_input eq "true") {
task. $edit_content_start_attrib = "f";
$add_files_predecessor = '<pred v="Add-Files"/>';
}
if ($add_file_input eq "true") {
my($addfilestask) = <<EOS;


<usertask name="Add-Files"
owner="__TAG__(iw_user);"
description="Adding files for author"
start="t">
Task specification
added only if job
<areavpath v="$work_area"/>
creator requested the
<successors>
Add-Files option.
<successorset description="Submit for editing">
<succ v="Edit-Content"/>
</successorset>
</successors>
</usertask>
EOS
__INSERT__("$addfilestask");
}
End the Embedded Perl Section

The Perl code block must be ended by closing both the CDATA tag and template_script
elements:
229
Workflow Tutorial
Write the Job Specification XML

The following example shows how the job specification XML can be written.
<usertask name="Edit-Content"
Note use of previously
owner="__TAG__('author');"
defined variable for
start="__INSERT__($edit_content_start_attrib);"
condition start
description="Edit files for submission and deployment">
attribute.
<successors>
<successorset description="Submit for review ">
<succ v="Review-1-__TAG__('appr1');"/>
<succ v="Review-2-__TAG__('appr2');"/>
</successorset>
</successors>
<activation>
Note all the possible <or>
predecessors to this <pred v="Review-1-__TAG__('appr1');"/>
task. <pred v="Review-2-__TAG__('appr2');"/>
<pred v="Legal-jcochrane"/>
Note use of previously <pred v="Legal-cdarrow"/>
defined variable for __INSERT__("$add_files_predecessor");
conditional <pred/> </or>
</activation>
</usertask>
Note personalization <usertask name="Review-1-__TAG__('appr1');"

of task names owner="__TAG__('appr1');"
description="Review files from __TAG__('author');"
readonly="t">
<successors>
<successorset description="Approve; send to Legal">
Note spawning of
<succ v="Legal-jcochrane"/>
multiple, concurrent
<succ v="Legal-cdarrow"/>
successors
</successorset>
</successorset>
</successors>
<activation>
<pred v="Edit-Content"/>
</activation>
</usertask>

Sample Workflows
<usertask name="Review-2-__TAG__('appr2');"
owner="__TAG__('appr2');"
description="Review files from __TAG__('author');"
readonly="t">
<successors>
<successorset description="Approve; send to Legal">
Same as previous <succ v="Legal-jcochrane"/>
task module 'name' <succ v="Legal-cdarrow"/>
and 'owner' attributes </successorset>
</successorset>
</successors>
<activation>
<pred v="Edit-Content"/>
</activation>
</usertask>
<usertask name="Legal-jcochrane"
owner="jcochrane"
description="Legal review, files by __TAG__('author');"
readonly="t">
<successors>
<successorset description="Approve">
<succ v="Submit"/>
</successorset>
</successorset>
</successors>
<activation>
Note activated only if <and>
both previous <pred v="Review-1-__TAG__('appr1');"/>
reviewers approved. <pred v="Review-2-__TAG__('appr2');"/>
</and>
</activation>
</usertask>
231
Workflow Tutorial
<usertask name="Legal-cdarrow"
owner="cdarrow"
description="Legal review, files by __TAG__('author');"
readonly="t">
<successors>
<successorset description="Approve">
<succ v="Submit"/>
Same as previous </successorset>
task module 'name' <successorset description="Reject: send back to author">
and 'owner' attributes <succ v="Edit-Content"/>
</successorset>
</successors>
<activation>
<and>
<pred v="Review-1-__TAG__('appr1');"/>
<pred v="Review-2-__TAG__('appr2');"/>
</and>
</activation>
</usertask>
<submittask name="Submit"
description="Submit files to staging">
<successorset description="Archive">
<succ v="Archive"/>
</successorset>
<activation>
Note activation based <or>
on either of the <pred v="Legal-ghoti"/>
previous reviewers' <pred v="Legal-Administrator"/>
approval </or>
</activation>
</submittask>
<dummytask name="Archive"
description="Archive Job">
<timeout> takes place <timeout v="__INSERT__($timeout);">
of <successor> <succ v="End"/>
element </timeout>
<activation>
<pred v="Submit"/>
</activation>
</dummytask>
<endtask name="End" description="End Job">

<activation>
<pred v="Archive"/>
</activation>
</endtask>
End of workflow
</workflow>

Appendix B
WorkflowBuilder Tutorial
This tutorial shows you how to create a workflow template and make it available to end-
users logged in to your TeamSite server. Use this tutorial to learn the basic skills you will
need to develop workflow templates and job specification files, and to learn about some of
the features available in WorkflowBuilder.
For more information about workflow templates and job specification files, see Chapter 6,
“Creating Workflow Template Files” and Chapter 7, “Job Specification Files”.
By the end of this tutorial, you will learn how to perform the following tasks:
! Create variables and specify attributes.
! Use custom variables.
! Control the appearance of the New Job form associated with your template.
! Make your workflow template available to job creators.
! Specify where your templates are invoked and who can invoke them.
The concepts and procedures included in this tutorial are designed to get you through the
creation of your first actual workflow template. Some features that are not specific to the
creation of this project are not explained. These options—and other advanced
WorkflowBuilder features—are described in detail in other chapters of this book.
Prerequisites
This tutorial assumes the following:
! TeamSite and WorkflowBuilder Server are installed and configured as described in the
TeamSite Installation Guide, and in this manual on a system dedicated for
WorkflowBuilder training. See “Installation” on page 76 for more information.
! WorkflowBuilder client is installed as described in this manual. See “Installation” on
page 76 for more information.
! You have Master privileges in TeamSite on the system dedicated for WorkflowBuilder
training.
! You have the TeamSite server name and the Interwoven Web daemon (iwwebd) port
number available.
! You are familiar with basic TeamSite administration tasks (or have access to the TeamSite
documentation).
233
Setting up the Tutorial Environment

To set up the WorkflowBuilder tutorial environment, follow these steps:
1. Add yourself and a fictional user to the Master role file in TeamSite.
Refer to the TeamSite Administration Guide for instructions about adding users to
TeamSite.
2. Establish two branches: main/WFB_training1 and main/WFB_training2.
Refer to the ContentCenter Professional online help for instructions about creating
branches.
3. In each branch, create workareas for yourself and the fictional user.
Refer to the ContentCenter Professional online help for instructions about creating
workareas.
4. In your workarea on the main/WFB_training1 branch, create a file.
This file can be any file format and does not need to contain content. It will be used
later in the tutorial to show how workflow developers can enable job creators to specify,
when a job is created, which files they want attached to all of the tasks in the job.
Tutorial Overview
In a real-world implementation, the development and use of WorkflowBuilder workflow
templates follows this pattern:
! Development—A workflow developer creates a workflow template that describe the
flow of tasks in a particular job.
! Deployment—The workflow developer makes the workflow template available to job
creators by adding the template to the TeamSite server.
! Job Instantiation—In ContentCenter Professional, a job creator selects the template
that describes the job to be created. A dialog box displays into which the job creator
enters data specific to that job.
Although this tutorial only covers the development and deployment phases, the following
sections use the tutorial project to describe the three phases of workflow development and
use so that you can gain a broad understanding of this process.
Development
In this tutorial you, the workflow developer, will develop a template that describes a job
composed of these tasks:
! Unlock—If files have been attached to the job by the job creator, they are unlocked.
! Author Work—A task to edit files appears in an Author’s Task list in the TeamSite. The
Author completes the requested task and marks it Done.

Tutorial Overview
! Review—The job transitions to a reviewer who chooses to either:

"Reject the Author’s changes and return the job back to the Author.
" Approve the Author’s changes.
! Submit to New Job or Submit to Final Review—Upon approval of the Author’s
changes, the reviewer chooses to either:
" Submit the changes and transition the job to a nested workflow. For details about
nested workflows, see “Nested Workflow” on page 74.
" Submit the changes and transition the job directly to a final reviewer.
! Final Review—Depending on the action taken by the first reviewer, one of two things
happens:
" The job described in the nested workflow starts. After that subworkflow ends, the
job transitions to the final reviewer.
" The job transitions directly to the final reviewer.
! EndTask—The job ends upon approval by the final reviewer.
The following graphic shows how the completed tutorial project should appear:
Perl Code
Editor
Canvas
Attributes window with

Variables tab selected Output window
Figure 53: Completed tutorial project
235
Deployment
When the Author Assignment with Nested Job template is complete, you will send it to the
TeamSite server and specify:
! Title of the workflow
! Type of workflow it is
! Which users can access the template
! Branches where the workflow can be run
Instantiation
When job creators initiate a new job, the creator first selects a template in a TeamSite GUI,
then fills in the required job parameters (such as job description, task owner, and so on) in
the form.
You will configure the tutorial workflow template in such a way that some job parameters
are extracted automatically by the template, and others must be supplied by the job creator.
Additionally, your workflow template will contain a custom variable that changes the
appearance of the new job form under certain conditions.
! If the job creator has attached pre-selected files to the job, the variable automatically
extracts the vpath to the end user’s workarea. In this case, the new job form does not
contain input fields for branch and workarea information.
! If files were not attached, this information cannot be automatically extracted, so the job
creator must specify branch and workarea information in the new job form.
These two input fields are

conditional. That is, they appear only
when a certain condition is met; in
this case it is when the job creator
has not attached files to the job.
Figure 54: New job form with conditional input fields
You can control such aspects of new job forms as:

! The conditions under which a form element displays.
! The type of form element that displays for any given line of input (a text area, for
instance, instead of a text field).
! The label that displays for each form element.

Creating a New Workflow
Creating a New Workflow

To complete this tutorial, you must work in Online mode. For details about Online and
Offline mode, “Sending Workflow Templates to the Server” on page 93.
To open the tutorial and begin your project, follow these steps:
1. Launch WorkflowBuilder.
Select Start > Program Files > Interwoven > WorkflowBuilder.
The Login dialog box is displayed.
2. Enter the following information in the Login dialog box:
" User Name—Your TeamSite user name.
" Password—Your TeamSite password.
" Domain—The domain where the TeamSite sever you are accessing resides. Contact
your TeamSite administrator if you do not know the domain where your TeamSite
server resides.
" Server Name—The name of the TeamSite server.
" Port Number—The Interwoven Web daemon (iwwebd) port number.
3. Click OK.
4. Select File > New Workflow.
The attributes window displays on the left and the canvas on the right.
237
5. Place these tasks and transitions on the canvas so that your workflow diagram is identical
to the one in the following graphic:
Figure 55: Creating a new workflow
" Task 1—External task

" Task 2—User task
" Task 4—Submit task
" Task 5—Submit task
" Task 7—NWF (New Workflow) task
" EndTask
See “Placing Tasks on the Canvas” on page 86 for information about placing objects on
the canvas.

Variables Overview
Variables Overview
The variables you create in this section are used to specify task and workflow attributes in
the following sections. Create these variables in the Variables tab of the Attributes window
(see “Specifying Workflow Attributes” on page 243.)
! sOwner—System variable. Specifies the owner of the job by automatically extracting
the user name of the job creator from the job creator’s system.
! uDescription—User variable. Creates an input field in the new job form where the job
creator can enter a description of the job.
! cArea_VPath— Custom variable. Extracts the vpath information if pre-selected files
are attached to the job. Also affects the appearance of the new job form.
! cUnlockFile—Custom variable. If files are attached to the job, this variable unlocks
them.
! uAuthor—User variable. Specifies the owner of the Author_Work task.
! cNested_Job—Custom variable. Specifies which .wft file to run within the
encapsulating job.
! cTextArea—Custom variable. Changes the new job form so that a text area is
displayed as the input field for a user variable rather than the default input field.
Naming Conventions
Each variable begins with a lower-case letter that corresponds to the type of variable it is (“s”
for System, “u” for User, and “c” for Custom). It is recommended that you use this
convention when naming the variables you create. You should also avoid giving variables
names identical to attribute names.
Custom Variables
WorkflowBuilder enables you to add Perl code to workflow templates so that you can
enhance them with custom variables. “Defining Custom Variables” on page 242 includes the
Perl code needed to define the custom variables in this tutorial.
For more information, see “Variables” on page 73.
Creating the sOwner Variable

To create the sOwner variable, follow these steps:
1. In the Attributes window, click the Variables tab.
2. In the Name column, double-click in an empty cell.
3. Enter sOwner.
4. Click in the corresponding row in the Value column.
239
5. Select System Variable from the drop-down menu.

The Specify System Variable dialog box displays.
6. In the Specify System Variable dialog box, select iw_user.
7. Click OK.
Creating the uDescription Variable

To create the uDescription variable, follow these steps:
1. In the Attributes window, ensure the Variables tab is selected.
3. Enter uDescription.
5. Select User Variable from the drop-down menu.
The Specify User Variable dialog box displays.
6. In the Specify User Variable dialog box, enter Description in the Name of label field.
7. In the Default value field, enter $cTextArea.
The cTextArea variable is used to customize the type of form element that displays for
the uDescription user variable in the New Job form. It is not used to specify task or
workflow attributes. You will define this variable, along with the other custom
variables, in the “Defining Custom Variables” section.
8. Click OK.
Creating the cArea_VPath Variable

To create the cArea_VPath variable, follow these steps:
1. In the Attributes window, ensure that the Variables tab is selected.
3. Enter cArea_VPath.
5. Select Custom variable from the drop-down menu.

Variables Overview
Creating the cUnlockFile Variable

To create the cUnlockFile variable, follow these steps:
3. Enter cUnlockFile.
Creating the uAuthor Variable

To create the uAuthor variable, follow these steps:
3. Enter uAuthor.
5. Select User Variable from the drop-down menu.
The Specify User Variable dialog box displays.
6. In the Specify User Variable dialog box, enter Enter user in the Name of label field.
7. In the Default value field, select $authors from the drop-down menu.
8. Click OK.
Creating the cNested_Job Variable

To create the cNested_Job variable, follow these steps:
Figure 56: Attributes window - Variables tab
241
3. Enter cNested_Job.
In the next section you will define the custom variables you just created.
Defining Custom Variables

WorkflowBuilder enables you to you to add custom Perl code. In this section you will add
Perl code that defines the custom variables that you created in the previous section:
! cArea_VPath
! cUnlockFile
! cNested_Job
! cTextArea
To add the Perl code that defines your custom variables, follow these steps:
1. Select View > Perl Code Editor.
2. In the Perl Code Editor, select the following text:
# Put your addition to the Workflow Template here.

Specifying Workflow Attributes
3. Enter a definition for each of your custom variables as follows:
For this variable: Enter this:

cArea_VPath use TeamSite::Usertask qw(
cleanup_paths
get_names_from_file
get_mail_cmd
make_branchpathlist
);
sub set_area{
my($btag, $watag) = @_;
my($avpath, $bpath, $wapath, $skip);
my($iwbpath, $iwwapath) =(__VALUE__("iw_branch"),
__VALUE__("iw_workarea"));
if ((length($iwbpath)) > 0 && (length($iwwapath)) > 0){

$bpath = $iwbpath;
($wapath = $iwwapath) =~ s|^\s*/.*:||;
$wapath =~ s|/\s*$||;
return("$wapath", "$iwbpath", "$wapath", "TRUE");
}
($bpath, $wapath, $avpath) =
cleanup_paths(__VALUE__("$btag"),
__VALUE__("$watag"));
return("$avpath", "$bpath", "$wapath", "FALSE");

}
my($cArea_VPath, $branch_path, $work_area, $skip_branch) =

set_area("branch_path", "work_area");
cUnlockFile my $cUnlockFile = "$iwhome/iw-perl/bin/iwperl $iwhome/local/

bin/unlock.ipl";
cNested_Job my $cNested_Job = "$iwhome/local/config/wft/default/
author_assignment.wft";
cTextArea my $cTextArea = "<textarea rows='5' cols='40'></textarea>";
Continue the tutorial by specifying the workflow attributes of this template.
Specifying Workflow Attributes

In this section you will specify four workflow attributes:
! Name—Specifies the name that displays in the list of available templates in the TeamSite
user interfaces.
! DebugMode—Specifies whether DebugMode is on or off.
! Description—Allows the job creator to enter a description of the new job.
! Owner—Specifies the owner of the new job as the current user.
These attributes specify the general parameters of the job. For details about workflow
attributes, see “Workflow Attributes” on page 68.
243
To specify the workflow attributes, follow these steps:

1. In the Attributes window, click the Workflow Attributes tab.
2. In the Attribute column, select the attribute you want to specify.
3. Click in the corresponding cell in the Value column.
4. Enter the values as described in the following table:
To specify this attribute: Do this:

Name Enter a name, for example, MyTutorialProject.
DebugMode Select Yes from the drop-down menu.
Preselected Files Select Yes from the drop-down menu.
Variables Do not specify this attribute because you will not use
Activity variables in this tutorial.
Description Select $uDescription from the drop-down menu.
Owner Select $sOwner from the drop-down menu.
Continue the tutorial by specifying the attributes of each task on the canvas.
Specifying Task Attributes

In this section you will specify the attributes of each task. Each kind of task has a different set
of attributes. For details about task attributes, see “Task Attributes” on page 61.
To specify the task attributes:
1. In the Attributes window, click the Attributes tab.

2. On the canvas, select Task 1.
3. Specify the attributes by selecting the one you want in the Attribute column, then
clicking in the corresponding cell in the Value column. Specify each attribute as fol-
lows:

Name Enter Unlock.
Description Enter Unlock attached files.
Lock Select No from the drop-down menu.
Retry Select Yes from the drop-down menu.

Specifying Task Attributes

Start Select No from the drop-down menu.
Note: Set this attribute to No so that in a later section you

can see how the Validate Template feature works. In that
section you will reset the value of this attribute to what is
should be—Yes.
AreaVpath Select $cArea_VPath from the drop-down menu.
Command Select $cUnlockFile from the drop-down menu.
Files You cannot set this attribute because the workflow
attribute, PreselectedFiles is set to Yes. It will be set
automatically when you complete the section “Saving Your
Template” on page 249.
Variables Do not specify this attribute because you will not use
Activity variables in this tutorial.
4. On the canvas, select Task 2 and specify these attributes as follows.:

Name Enter Author_Work.
Description Select $uDescription from the drop-down menu.
Owner Select $uAuthor from the drop-down menu.
Lock Select Yes from the drop-down menu.
Readonly Select No from the drop-down menu.
5. On the canvas, select the Task 3 and specify these attributes as follows:

Name Enter Review.
Description Enter Review.
Lock Select Yes from the drop-down menu.
Readonly Select Yes from the drop-down menu.
245

Name Enter Submit_to_NJ. Submit_to_New_Job is too long to
display as task name, thus the abbreviation “NJ” for “New
Job.”
Description Enter ContentApproved_StartNewJob.
Skip Conflicts Select No from the drop-down menu.
Skip Locked Select No from the drop-down menu.
Override Select No from the drop-down menu.
Unlock Select Yes from the drop-down menu.
SaveComments Select Yes from the drop-down menu.
7. On the canvas, select the Task 5 and specify the attributes as you did for the
Submit_to_NJ task in step 9 on page 246, with the following changes:

Name Enter Submit_to_FR. Submit_to_Final_Review is too
long to display as a task name, thus the abbreviation “NJ”
for “New Job.”
Description Enter ContentApproved_StartFinalReview.

Name Enter Nested_Job.
Description Enter Nested_Author_Assignment_Workflow.
AreaVPath Select $cArea_VPath from the drop-down menu.
Wffile To set the Wffile attribute, follow these steps:
2. Click .... A dialog box displays.
3. In the dialog box, select $cNested_Job from the drop-
down menu.
4. Select WF Template.
5. Click OK.

Specifying Transitions
9. On the canvas, select the last Task 6 and specify these attributes as follows:

Name Enter Final_Review.
Description Enter Final_Review.
Lock Select No from the drop-down menu.
ReadOnly Select Yes from the drop-down menu.
AreaVPath Select $cArea_VPath from the drop-down menu.
Continue the tutorial by specifying the transitions between the tasks.
Specifying Transitions
The types of transitions are:
! Successor (default)
! Timeout
! Inactivate
! Resets
! Failure
Successor transitions are not listed with the other types in the drop-down menu because they
are applied automatically when no other type is selected. For details about transitions, see
“Transitions” on page 60.
All of the transitions in this tutorial are successor transitions. However, you will specify a
name for each transition.
To specify a name for a transition:

1. On the canvas, select a transition arrow.
2. In the Attributes window, click the Attributes tab.
3. In the Attributes column, select Type.
5. Enter a name for the transition.
Continue the tutorial by printing your template.
247
Printing Your Template

In this section, you will learn how to view page bounds, set the page size, and print your
template.
Select View > Page to view page bounds:
The dashed line

indicates a page
boundary.
Figure 57: WorkflowBuilder canvas with a page boundary
Note that the three task icons on the right flow over the boundary of the first page. For this
tutorial, you will want to fit everything onto one page.
To fit all the icons onto one page, follow these steps:
1. Hold down the Shift key and select the Nested_Job, Final_Review, and EndTask tasks.
2. Drag them to the left, into the boundary of the first page.
To set the page size of the canvas, follow these steps:

1. Select View > Set Canvas Size.
2. In the Set Canvas Size dialog box, set the Horizontal and the Vertical page limits to 1.
3. Click OK.
To print the workflow diagram, follow these steps:

1. Select File > Print.
2. In the Print dialog box, click Print.
Continue the tutorial by saving your work.

Saving Your Template
Saving Your Template

In this section you will save your workflow file and use the Verify Template feature to find
and correct an error in the template.
When you save a workflow file, WorkflowBuilder checks for errors. If errors exist, the
Output window opens and displays information about each error. You can validate your
workflow file at any time by selecting Tools > Verify Template.
The error in this tutorial is that no task is identified as a Start task. To fix this, reset the value
for the Start attribute of the Unlock task to Yes.
1. Save your Template:

a. Select File > Save As.
b. In the Save As dialog box, navigate to the WorkflowBuilder-home\examples
directory.
c. Name the file completed_tutorial.wft.
d. Click Save.
The Output window opens to display an error.
2. Fix the error:
a. On the canvas, select the Unlock task.
b. In the Attributes window, click the Attributes tab.
c. In the Attributes column, double-click Start.
d. In the corresponding cell of the Value column, select Yes from the drop-down
menu.
3. Select File > Save.
The Output window lists no errors.
Now that you have verified your template and saved it, you are ready to send it to the
TeamSite server.
249
Sending Your Template to the TeamSite Server

When you are ready to make a template available to TeamSite users, you must transfer its
two associated files (the .wft and the .wfb files) to the TeamSite server and decide what
constraints (if any) to place on the file to control access to it. For more information about
controlling access using constraints, see “Workflow Template Constraints” on page 95.
In this section you learn how to:

! Specify a title for your template. The title displays in the list of available templates in the
TeamSite user interfaces, and can be different than the file name and the Name
workflow attribute.
! Specify yourself as the only user permitted to access the template.
! Specify that the template can be accessed only from the main/
WorkflowBuilder_Tutorial branch.
To send the template to the server, you must be in online mode. If you are not already in
online mode, Select File > New to access the Login dialog box.
To send your template to the server, follow these steps:

The Workflow Constraints dialog box displays with the WFT_Type tab activated.
2. In the Title field, enter Tutorial Template.
3. In the Type of WFT field, select all. This makes the template accessible only through
the New Job link.
4. Click the Users tab.
5. From the Role drop-down menu, select master.
All users with an entry in the Master role file display in the Available Users field.
6. Select your user name from the list and click >> to add yourself to the list of Included
Users.
Do not include the fictional TeamSite user you created when you established the tutorial
environment (see “Setting up the Tutorial Environment” on page 234).
7. Click the Branch tab.
8. Enter main/WFB_training1. This restricts access to your template to this branch.
Your template is not accessible from main/WFB_training2.
9. Click OK to send your template to the server.
Finish the tutorial by testing your work. In the next section, you will invoke your template
from a TeamSite user interface and create a new job with it.

Testing Your Work
Testing Your Work

Test your work by creating a new job with your template in TeamSite.
1. Open a browser and log in to TeamSite.
2. Navigate to your workarea on the main/WFB_training2 branch.
3. Select the file you created there (see “Setting up the Tutorial Environment” on
page 234) to attach it to the job.
4. Navigate to your Task list.
5. Select New Job.
The Select Workflow window displays with the Tutorial Template included in the list of
available templates.
6. Select Tutorial Template and enter a description (such as, test1.)
7. Click Next.
A new job form displays. Notice that you do not need to enter branch or workarea data
because you preselected a file that will be attached to the job. Notice also that the form
element for Description is a text area and not a text field.
8. Enter a description and specify yourself as the task owner.
9. Click Run Job.
10. Navigate to the Task list screen.
The job you just created has placed a task in your Task list. Notice that the file you
preselected is included in the task.
Try to access your template from the other branch, or log out and log back in to TeamSite as
the fictional user and try to invoke the Tutorial Template as that user. If you followed the
steps in this tutorial correctly, your template is inaccessible.
Congratulations! You successfully completed the WorkflowBuilder tutorial.
251

Appendix C
iwsend_mail.ipl Script
The Perl script iwsend_mail.ipl was 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.
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
! 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:
253
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 253. 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.
255
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.
257
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 260.
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 260.
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" />
259
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>
261
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
----------------------------------------------------------------------
263
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>
shared/deploy.ipl>
shared/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 the following example:

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
Figure 58: Sample email message using HTML mode
265

Appendix D
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.
267
CGI Task Example
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.
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 rename 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 com-
plete.
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
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 from the Tasks list in ContentCenter.

! A user finishes a user or group 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 TeamSite server executes the specified program 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 request that started the 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 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.
269
CGI Task Example
! 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.
The Sample CGI Program

The sample CGI program produces an HTML page with the simple form. 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 59: 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.

The Sample CGI Program
! 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 will include information that may be useful during
development or troubleshooting.
Figure 60: 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.
271
CGI Task Example
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 61: 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.

The 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 is quite simple:
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.
273
CGI Task Example
The job instantiation form has a Write job spec to: input field (iw_output_file):
Figure 62: 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 value should be used for the “command” attribute on a CGI task?
The command is the name of a CGI program. The program must reside in the following
location:
iw-home/httpd/iw-bin/
It cannot be in a subdirectory. Give the name of the file, including its extension. For
example:
command="sample_cgi_task.ipl"
The actual request URL will appear to be something like
http://hostname/iw-bin/iw_cgi_wrapper.cgi/sample_cgi_task.ipl
A fully qualified path or a URL cannot be used for the command. The system will not be
able to find the program.
Developers are encouraged to name their programs with a prefix that easily identifies the
program as belonging to a customer, as opposed to those that are part of the standard, out-
of-the-box TeamSite installation.
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 as 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
275
CGI Task Example
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 ACTION?

The recommended value for your form’s action is simply the name of a CGI program in
iw-home/httpd/iw-bin/ (usually the same as the command on the CGI task). If your
HTML does not override the default base URL, this relative URL will go back through the
iw_cgi_wrapper.cgi, and the wrapper will execute the CGI program.
If your request does not go through the wrapper (for example, if you used
action="/iw-bin/my_program.cgi"), then impersonation will not be used, and the
program must have the extension .cgi. The .cgi extension is not needed when the
wrapper is used because the wrapper executes the program.
On a Windows server, you cannot simply rename a Perl script from .ipl to .cgi; you will
need to create a CGI wrapper. On Windows these CGI wrappers should be unique within
the first six characters to avoid conflicts in the long-to-short filename mappings.
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.

Troubleshooting
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).
277
CGI Task Example

Appendix E
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. You can use these files as a simple
demonstration of a workflow with an external task, or you can make a copy of
sample_external_task.ipl and use it to start development of your own external task.
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.
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>
279
If you intend to make significant changes to the example code to develop your own program
or workflow, it is recommended that you rename 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 press the Refresh button 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. Press Refresh 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
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).
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 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).
281
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.n
! Each file attached to the task (as an area relative path). The order of the files is the same
as in 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.
The 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 finished, 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 halts. 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.

Logging
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.
283
The 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.

The Sample Program
[START 2003-02-06 17:36:57 /usr/iw-home/local/config/wft/examples/

sample_ext
ernal_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]
285

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 is quite simple:
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 has a Write job spec to: input field (iw_output_file):
Figure 63: 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.
287

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.
From an external program, where do STDOUT and STDERR go?
Unless the program redirects the output, standard output is recorded in iwtrace.log on
UNIX or in iwserver.log on Windows when an external program is invoked by the
workflow system. Output sent to standard error will be recorded in iwtrace.log. The
Troubleshooting section describes this in more detail.

Troubleshooting
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
289
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 lock (cgitask) 149
__ELEM__ directive 115 lock (externaltask) 146
__INSERT__ directive 118 lock (grouptask) 143
syntax 120 lock (updatetask) 152
__TAG__ directive 115 lock (usertask) 141
syntax 120 lock task 65
__VALUE__ directive 119 name (cgitask) 149
name (dummytask) 154
A name (eafinishop) 138
activation element 135 name (eastartop) 137
AND condition 61 name (endtask) 153
areavpath element 133 name (externaltask) 145
array validators 113 name (grouptask) 142
ask_va_enabled 177 name (locktask) 155
attaching files 57 name (submittask) 151
attributes name (updatetask) 152
about 61 name (usertask) 140
CGI task 62 name (wftask) 157
comment 135 name (wfvarfinishop) 140
creator 132 name (wfvarstartop) 139
delete 152 name (workflow) 132
description (cgitask) 149 nested 65
description (dummytask) 154 of jobs 61
description (endtask) 153 of tasks 61
description (externaltask) 145 of transitions 61
description (grouptask) 143 op (eafinishop) 138
description (locktask) 155 op (eastartop) 137
description (submittask) 151 op (wfvarfinishop) 139
description (successorset) 141 op (wfvarstartop) 139
description (updatetask) 152 override 151
description (usertask) 141 overwritemode 152
description (wftask) 157 owner (cgitask) 149
description (workflow) 132 owner (externaltask) 145
dummy task 62 owner (locktask) 155
dynamic 68 owner (submittask) 151
dynamically modifying 69, 72 owner (updatetask) 152
email task 63 owner (usertask) 140
end task 63 owner (wftask) 157
external task 64 owner (workflow) 132
group task 64 path 134
immediate 149 readonly (cgitask) 149
key 133 readonly (externaltask) 146
291
readonly (grouptask) 143 available_templates.cfg file 95
readonly (usertask) 141 branch_list element 30
retainowner 143 command_list element 29
retry 146 modifying 99
savecomments 151 role_list element 29
setting 90 structure 28
skipconflicts (submittask) 151 user_list element 30
skiplocked 151 available_templates.dtd file 32
start (cgitask) 149 available_templates.ipl file 33
start (dummytask) 154
start (externaltask) 145 B
start (grouptask) 142 branch constraints 97
start (locktask) 155 branch_list element 30
start (submittask) 151 buffer limit, task and job variables 281
start (updatetask) 152
start (usertask) 140 C
start (wftask) 157 callbacks 203
submit task 66 iwcallback 204
task 61, 244 TeamSiteCGI_liteiwcallback 205
transferonly (cgitask) 149 TeamSiteWFtaskCallBack() 204
transferonly (externaltask) 146 cArea_VPath variable 240
transferonly (grouptask) 143 cgi task 60, 201
transferonly (updatetask) 152 areaVPath attribute 62
transferonly (usertask) 141 attributes 62
unlock 151 background 269
update task 67 command attribute 62
user task 67 debugging 201
v (command) 147 description attribute 62
v (group) 144 enhancements 272
v (jobfile) 157 example 267
v (reset) 136 files attribute 62
v (srcareapath) 153 immediate attribute 62
v (succ) 134 lock attribute 62
v (timeout) 133 name attribute 62
v (user) 144 owner attribute 62
value 133 start attribute 62
variables 62 troubleshooting 277
workflow 68, 243 CGI_info directive 111
WorkflowBuilder 68 error_data_bgcolor property 111
audit trail 198 error_label_bgcolor property 111
Author Submit with Deploy 40 error_text_color property 111
Author Submit with Email 41 html_body_options property 111
Author Submit with Metadata 42 post_tagtable_html property 111
author_assignment.wft template file 22 pre_tagtable_html property 111
author_submit_with_deploy.wft file 40 tag_table_options property 111
author_submit_with_email.wft file 41 title property 111
author_submit_with_metadata.wft file 42 valid_bgcolor property 111
cgitask element 148
used with command 147

cNested_Job variable 241 D
command element 146 debugging
used with cgitask 147 iw_debug_mode key 191
used with external task 146 iw_output_file key 191
command_list element 29 techniques 207
comment attribute 135 workflow 191
conditions 61, 88 workflow log file 192
AND 61 default_submit.wft template file 22
NOT 61 delete attribute 152
OR 61 delete_jobs_on_completion 34
Configurable Author Assignment 43 deployment settings 54
Configurable Author Submit 44 description (cgitask) attribute 149
Configurable Default Submit 45 description (dummytask) attribute 154
configurable workflows 171, 172, 175 description (endtask) attribute 153
configurable_author_assignment.cfg file 50 description (externaltask) attribute 145
configurable_author_assignment.wft file 43, 49 description (grouptask) attribute 143
configurable_author_submit.cfg file 49 description (locktask) attribute 155
configurable_author_submit.wft file 44, 49 description (submittask) attribute 151
configurable_default_submit.cfg file 50 description (successorset) attribute 141
configurable_default_submit.wft file 45, 49 description (updatetask) attribute 152
configuration 171 description (usertask) attribute 141
files 176 description (wftask) attribute 157
workflows 172 description (workflow) attribute 132
configuration files 27 description element 132
.cfg 49 design 209
.properties 50 directives
available_templates.cfg 95 __INSERT__ 118
available_templates.dtd 32 __TAG__ 115
available_templates.ipl 33 __VALUE__ 119
configurable_author_assignment.cfg 50 _ELEM__ 115
configurable_author_submit.cfg 49 CGI_info 111
configurable_default_submit.cfg file 50 TAG_info 112
email_map.cfg 262 disable VisualAnnotate 179
iw.cfg 34, 262 dummy task 60
wft_opendeploy.cfg 26 attributes 62
wft_opendeploy.ipl 26 description attribute 62
wft_opendeploy.xml 26 files attribute 62
workflow 49 name attribute 62
constraints 95 start attribute 62
branch 97 variables attribute 63
template type 95 dummytask element 154
user 96 dynamic attributes 68
conventions
notation 11
path name 12
creator attribute 132
cUnlockFile variable 241
custom variables 74
creating 91
293
E email 172
eafinishop element 138 customizing 177
eastartop element 137 debugging 188
elements from workflow 184
activation 135 header 182
areavpath 133 HTML and plain text combination 183
branch_list 30 html part 183
cgitask 148 plain text part 183
command 146 settings 51
command_list 29 tasks 60
description 132 template-based 181
dummytask 154 templates 176
eafinishop 138 email task
eastartop 137 areaVPath attribute 63
endtask 153 attributes 63
externaltask 145 description attribute 63
failure 158 email attribute 63
file 134, 136 files attribute 63
files 134, 136 lock attribute 63
group 144 name attribute 63
grouptask 142 owner attribute 63
inactivate 135, 197 retry attribute 63
jobfile 157 start attribute 63
locktask 155 variables attribute 63
reset 136 email_map.cfg file 262
resets 197 end task 60
role_list 29 attributes 63
sharedby 143 description attribute 63
srcareapath 153 name attribute 63
submittask 150 endtask element 153
succ 134 error codes, WorkflowBuilder 104
success 158 error messages 208
successors 141 error_data_bgcolor property 111
successorset 141 error_label_bgcolor property 111
template_script 109 error_msg property 113
timeout 133 example files 176
updatetask 151 example use case 172
user 144 extended attributes
user_list 30 annotations 50
usertask 140 external task 60, 199
variable 132 areaVPath attribute 64
variables 132 attributes 64
wftask 156 background 281
wftfile 157 callback 282
wfvarfinishop 139 command attribute 64
wfvarstartop 139 command line arguments 282
workflow 131 debugging 199
workflowinformation 185 description attribute 64
example 279

files attribute 64 I
lock attribute 64 immediate attribute 149
logging 283 inactivate element 135, 197
name attribute 64 installation
owner attribute 64 prerequisites 76
retry attribute 64 Solaris 77
start attribute 64 Windows 77
troubleshooting 289 instantiation window, size 206
variables attribute 64 instantiator CGI 20
external_task_add_filelist 34 integrating
external_task_retry_wait 34 with OpenDeploy 26
externaltask element 145 is_required property 113
used with command 146 iw.cfg file 34, 180, 262
iwsend_mail parameter 34
F workflow parameter 34
failure element 158 iw_debug_mode key 191
file comments, retrieving 203 iw_output_file key 191
file element 134, 136 iw_setwfarg 114
files iw_solution_email.ipl
configuration 176 data flow illustrated 189
ReadMe 177 iwcallback 204
workflow properties 178 iwsend_mail.ipl script 253
worklow 171, 175 command line 254
files element 134, 136 composing email message body 257
email addresses 255
G email sender 256
group element 144 email subject line 257
group task 59 error capturing 260
areaVPath attribute 65 example 262
attributes 64 HTML formatting 259
description attribute 64, 65 messages, constructing 254
files attribute 65 multiple email recipients 256
lock attribute 64 next task 260
name attribute 64 parameters 253
owner attribute 65 task variable usage 254
readonly attribute 64 URL formatting 259
retainOwner attribute 64
shareby attribute 65 J
start attribute 65 job specification 16
variables attribute 65 job specification DTD 128
grouptask element 142 job specification files 17, 127
sample 165
H job variable buffer limit 281
html property 113 jobfile element 157
html_body_options property 111 jobs 16
running 169
295
K nested workflow 74
key attribute 133 NOT condition 61
notation conventions 11
L notifications 205
label property 113
localization 58 O
lock (cgitask) attribute 149 objects
lock (externaltask) attribute 146 aligning 89
lock (grouptask) attribute 143 moving 89
lock (updatetask) attribute 152 selecting 89
lock (usertask) attribute 141 op (eafinishop) attribute 138
lock task 60 op (eastartop) attribute 137
attributes 65 op (wfvarfinishop) attribute 139
name attribute 65 op (wfvarstartop) attribute 139
locks 198 OpenDeploy
external to workflow engine 198 integration 26
locktask element 155 solutions workflows 26
OR condition 61
M override attribute 151
metadata capture 53 overwritemode attribute 152
settings 53 owner (cgitask) attribute 149
models 15 owner (externaltask) attribute 145
owner (locktask) attribute 155
N owner (submittask) attribute 151
name (cgitask) attribute 149 owner (updatetask) attribute 152
name (dummytask) attribute 154 owner (usertask) attribute 140
name (eafinishop) attribute 138 owner (wftask) attribute 157
name (eastartop) attribute 137 owner (workflow) attribute 132
name (endtask) attribute 153
name (externaltask) attribute 145 P
name (grouptask) attribute 142 parameters
name (locktask) attribute 155 iwsend_mail 34
name (submittask) attribute 151 workflow 34
name (updatetask) attribute 152 path attribute 134
name (usertask) attribute 140 path name conventions 12
name (wftask) attribute 157 Perl modules 159
name (wfvarfinishop) attribute 140 TeamSiteWFsystem 159
name (wfvarstartop) attribute 139 TeamSiteWFtask 161
name (workflow) attribute 132 TeamSiteWFworkflow 160
nested job task Perl scripts
attributes 65 iwsend_mail.ipl 253
description attribute 65 permit_add_locked_files_to_locking_tasks 34
files attribute 66 ports 180
name attribute 65 VisualAnnotate 180
owner attribute 65 post_tagtable_html property 111
start attribute 66 pre_tagtable_html property 111
variables attribute 66 presubmit_check 34
wffile attribute 66 properties
error_data_bgcolor 111

error_label_bgcolor 111 deployment 54
error_message 113 email notification 51
error_text_color 111 enabling 21
html 113 localization 58
html_body_options 111 metadata capture 53
is_required 113 OpenDeploy, integrating 26
label 113 review 55
post_tagtble_html 111 settings 51
pre_tagtable_html 111 solutions workflows 171
tag_table_options 111 sOwner variable 239
title 111 srcareapath element 153
valid_bgcolor 111 start (cgitask) attribute 149
valid_input 113 start (dummytask) attribute 154
start (externaltask) attribute 145
R start (grouptask) attribute 142
ReadMe files 177 start (locktask) attribute 155
readonly (cgitask) attribute 149 start (submittask) attribute 151
readonly (externaltask) attribute 146 start (updatetask) attribute 152
readonly (grouptask) attribute 143 start (usertask) attribute 140
readonly (usertask) attribute 141 start (wftask) attribute 157
regular expressions 124 submit task 60
path separators 125 areaVPath attribute 66
requirements, system 171 attributes 66
reset element 136 description attribute 66
resets element 197 files attribute 66
retainowner attribute 143 name attribute 66
retry attribute 146 override attribute 66
review cycles 177 owner attribute 66
review settings 55 saveComments attribute 66
review_cycles 177 skip conflicts attribute 66
role_list element 29 skip locked attribute 66
start attribute 66
S unlock attribute 66
savecomments attribute 151 variables attribute 66
serial_approval.wft file 23 submittask element 150
server-side workflow subsystem 20 succ elements 134
sharedby element 143 success element 158
show_save_button 178 successors element 141
skipconflicts (submittask) attribute 151 successorset element 141
skiplocked attribute 151 system requirements 171
solutions workflows 21 system variables 73
activating 23 creating 91
attaching files 57 iw_areaowner 73
author_submit_with_deploy.wft file 40 iw_branch 73
author_submit_with_email.wft file 41 iw_desc 73
author_submit_with_metadata.wft file 42 iw_home 73
configurable_author_assignment.wft file 43, 49 iw_role 73
configurable_author_submit.wft file 44, 49 iw_session 73
configurable_default_submit.wft file 45, 49 iw_template_file 73
297
iw_template_name 73 terminology, workflow 15
iw_use_default 73 test VisualAnnotate 180
iw_user 73 text labels, adding 88
iw_workarea 73 timeout element 133
title property 111
T toolbar 172
TAG_info directive 112 activation of 172
array validators 113 toolbars
error_msg property 113 task 79
html property 113 transferonly (cgitask) attribute 149
is_required property 113 transferonly (externaltask) attribute 146
iw_setwfarg_ 114 transferonly (grouptask) attribute 143
label property 113 transferonly (updatetask) attribute 152
valid_input property 113 transferonly (usertask) attribute 141
tag_table_options property 111 transitions 60
task toolbar 79 adding 85
task variable buffer limit 281 drawing 86
task_areavpath_file_access_check 34 inactivate 61
tasks 15 reset 61
adding 85 specifying 247
attributes 61 successor 61
cgi 60, 267 timeout 61
dummy 60 tutorials
email 60 workflow 193
end 60 WorkflowBuilder 233
external 60, 279
group 59 U
lock 60 uAuthor variable 241
placing, WorkflowBuilder 86 uDescription variable 240
submit 60 unlock attribute 151
update 60 update task 60
user 59 areaVPath attribute 67
workflow 59 attributes 67
TeamSite GUI 172 delete attribute 67
TeamSite server, logging in 83 description attribute 67
TeamSiteWFtask module 161 files attribute 67
TeamSiteWFtaskCallBack() 204 lock attribute 67
TeamSiteWFworkflow module 160 name attribute 67
template type constraints 95 overwrite attribute 67
template_script element 109 owner attribute 67
template-based email 181 srcAreaVPath attribute 67
templates start attribute 67
printing 248 variables attribute 67
saving 249 updatetask element 151
TeamSite server 250 use case 172
testing 251 user constraints 96
workflow 17 user element 144

user task 59 review_cycles 177
areaVPath attribute 67 setting 91
attributes 67 show_save_button 178
description attribute 67 sOwner 239
files attribute 68 system 73, 91
lock attribute 67 uAuthor 241
name attribute 67 uDescription 240
owner attribute 67 user 73, 91
readonly attribute 67 va_create_snapshots 178
start attribute 67 va_default_page 178
variables attribute 68 va_enabled 177
user variables 73 va_show_cycles 178
creating 91 va_show_live_option 178
user_list element 30 va_show_reviewers 178
usertask element 140 va_show_snapshots 178
which_snapshot 178
V variables attribute 62
v (command) attribute 147 variables element 132
v (group) attribute 144 VisualAnnotate 50
v (jobfile) attribute 157 disable 179
v (reset) attribute 136 extended attributes 50
v (srcareapath) attribute 153 introduced 50
v (succ) attribute 134 ports 180
v (timeout) attribute 133 test 180
v (user) attribute 144 variables 177
va_create_snapshots 178 workflow settings 176
va_default_page 178
va_enabled 177 W
va_show_cycles 178 WFsystem module 159
va_show_live_option 178 wft_opendeploy.cfg file 26
va_show_reviewers 178 wft_opendeploy.ipl file 26
va_show_snapshots 178 wft_opendeploy.xml file 26
valid_bgcolor property 111 wftask element 156
valid_input property 113 wftask_nesting_depth_allowed 34
value (eafinishop) attribute 138 wftfile element 157
value (eastartop) attribute 137 wfvarfinishop element 139
value (wfvarfinishop) attribute 140 wfvarstartop element 139
value (wfvarstartop) attribute 139 which_snapshot 178
value attribute 133 workflow 172, 176
variable element 132 attributes 68
variables 61, 73 components 17
ask_va_enabled 177 conditions 61, 88
buffer limit 281 configuration files 27, 49
cArea_VPath 240 constraints 95
cNested_Job 241 debugging 191
cUnlockFile 241 description attribute 68
custom 74, 91, 239, 242 designing 209
naming conventions 239 elements 59
overview 239 email task 184
299
enabling solution workflows 23 instantiation window 206
job specification 16 locks 198
job specification files 17, 127 mapping workflows 195
jobs 16 notifications 205
model 15 requirements 209
name attribute 68 resets 197
nested 74 samples 210
owner attribute 68 task symbols 194
properties files 178 terms 193
requirements 209 WorkflowBuilder 75
sample 210 alignment toolbar 80
schematic of 18 attributes 68
solutions 21 attributes, setting 90
tasks 15, 59 available_templates.cfg file, modifying 99
template file 108 client installation 78
template files 107 components 75
terminology 15 constraints 95
terms 193 debugMode attribute 68
transitions 60 error codes 104
variables 73, 176 files, deleting from server 103
variables attribute 68 files, retrieving from server 102
VisualAnnotate 50 graphical user interface 79
WorkflowBuilder 75 installation 76
workflow element 131 logging in 82
workflow log file 192 menu toolbar 79
workflow template files 19, 107 objects, aligning 89
workflow templates 17 objects, moving 89
author_assignment.wft 22 objects, selecting 89
default 22 preselectedFiles attribute 68
default_submit.wft 22 tasks toolbar 79
editing existing 93 tasks, placing 86
examples 22 templates 92, 93
preselected files 92 templates, viewing 83
regular expressions 124 text labels, adding 88
sample 21 toolbars 79
sending to server 93 transitions, drawing 86
serial_approval.wft file 23 tutorial 233
structure 107 uninstallation 78
viewing 83 variables, setting 91
workflow tutorial 193, 209 view menu 81
audit trail 198 zoom toolbar 80
callbacks 203 WorkflowBuilder Server 75
cgi task 201 WorkflowBuilder tutorial
debugging techniques 207 cArea_VPath variable 240
error messages 208 cNested_Job variable 241
external task 199 cUnlockFile variable 241
file comments, retrieving 203 deployment 236
inactivate 197 development 234
information, prompting for 206 environment 234

instantiation 236
overview 234
prerequisites 233
sOwner variable 239
task attributes 244
templates 250, 251
templates, printing 248
templates, saving 249
transitions, specifying 247
uAuthor variable 241
uDescription variable 240
variable naming conventions 239
variables overview 239
variables, custom 239, 242
workflow attributes 243
workflow, creating 237
301

Teamsite Workflow Dev Guide ts.650.wf

Diunggah oleh

Informasi Dokumen

Deskripsi Asli:

Judul Asli

Hak Cipta

Format Tersedia

Bagikan dokumen Ini

Bagikan atau Tanam Dokumen

Opsi Berbagi

Apakah menurut Anda dokumen ini bermanfaat?

Apakah konten ini tidak pantas?

Hak Cipta:

Format Tersedia

Teamsite Workflow Dev Guide ts.650.wf

Diunggah oleh

Hak Cipta:

Format Tersedia

TeamSite®

Interwoven, TeamSite, Content Networks, OpenDeploy, MetaTagger, DataDeploy, DeskSite, iManage,

Chapter 2: Using Workflows 21

Chapter 3: Using Solution Workflows 39

Chapter 4: Workflow Components 59

4 Workflow Developer’s Guide

Chapter 7: Job Specification Files 127

6 Workflow Developer’s Guide

Chapter 8: Using VisualAnnotate 171

Chapter 9: Template-Based Email 181

Chapter 10: Debugging Techniques 191

Appendix B: WorkflowBuilder Tutorial 233

8 Workflow Developer’s Guide

Appendix C: iwsend_mail.ipl Script 253

Appendix D: CGI Task Example 267

10 Workflow Developer’s Guide

Convention Definition and Usage

Click Edit File in the Button Bar.

The iwextattr command-line tool allows you to set and look up

iwckrole role user

>iwextattr -s project=proj1 //IWSERVER/default/main/dev/

means that you must insert the values of projectname and

Notation of iw-home on UNIX and Windows Systems

Windows Path Name Conventions

For example, instead of:

you can try:

12 Workflow Developer’s Guide

What’s In This Manual

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

Note: A workflow task cannot have more than 512 predecessors.

Editor Task: Task: Task:

Reject Task: Approve Task:

Figure 1: Workflow model

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

16 Workflow Developer’s Guide

Reject Task: Approve Task:

Figure 2: Workflow with assigned users

Job Specification Files

Figure 3: Workflow Components

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

18 Workflow Developer’s Guide

4. An end-user using TeamSite ContentCenter Professional enters information in the

Workflow Template File

Browser Interface (GUI)

Job Specification File

Server-Side Workflow Subsystem

20 Workflow Developer’s Guide

Default Template Descriptions

Template Name Description

Example Template Descriptions

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

22 Workflow Developer’s Guide

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

Template Name Description

5. Save and close the available_templates.cfg file.

24 Workflow Developer’s Guide

8. If you are using Metadata Capture functionality:

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

9. If you are using Deployment functionality:

b. Edit solutions/wft_opendeploy.cfg file to specify the mapping from branch

Integrating with OpenDeploy

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