This document was uploaded by user and they confirmed that they have the permission to share
it. If you are author or own the copyright of this book, please report to us by using this DMCA
report form. Report DMCA
Interwoven, Inc. 803 11th Ave. Sunnyvale, CA 94089 http://www.interwoven.com Printed in the United States of America Release 6.7.0 Part #90-11-00-670-210 March 2006
About This Book The Workflow Developer’s Guide is a guide to configuring and using TeamSite workflows. This document is primarily intended for TeamSite Administrators and Master users, and workflow developers.
Notation Conventions This manual uses the following notation conventions: 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
Monospaced
Monospaced italic
Book titles appear in italics. Terms are italicized the first time they are introduced. Important information may be italicized for emphasis. 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 italics are used for command-line variables. For example: iwckrole role user
Monospaced bold
Means you must replace role and user with actual role and user values. Monospaced bold represents user input. The > character that appears before a line of user input represents the command prompt and should not be typed. For example: >iwextattr -s project=proj1 //IWSERVER/default/main/dev/ WORKAREA/andre/products/index.html
9
Convention
Definition and Usage
Monospaced bold italic
Monospaced bold italic text is used to indicate a variable in user input. For example: >iwextattr -s project=projectname workareavpath
means that you must insert the values of projectname and workareavpath when you enter this command. Square brackets surrounding a command-line argument mean that the argument is optional. Vertical bars separating command-line arguments mean that only one of the arguments can be used.
[] |
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.
10
Workflow Developer’s Guide
Chapter 1
Introduction Workflow encompasses the procedures, tasks, people, and equipment that define business practices and processes within an organization. Using TeamSite to define and automate workflow ensures that the business practices associated with your content are performed in a logical and consistent manner leading to better organization and increased productivity. This chapter provides a high-level overview of workflows. Later chapters examine workflow components and various methods of creating workflows.
Workflow Terminology This section defines workflow terminology as it relates to TeamSite. Many of these terms have more general definitions outside of the context of TeamSite. Workflow Models A workflow model is a general description of a recurring business process. Each workflow model describes a process consisting of a series of tasks, or units of work, and can be represented by a flow diagram, illustrating the task sequences and decisions involved. Figure 1 shows a simple assign-edit-approve workflow model. Email is sent to the participants at each stage of the process, and an automated content deployment task is performed at the end.
Editor initiates job
Task: Email sent to Author
Task: Author edits files
Task: Email sent to Editor
Reject Task: Email sent to Author
Task: Approve Editor Task: Email sent reviews to Author Author’s work
Task: Content submitted to staging area
Task: Automated deployment
Figure 1: Workflow model of an Author Assignment business process
11
Introduction
The people involved in this description are not actual people, but are abstractly represented as an editor and an author. Similarly, no specific files are mentioned. This is an important distinction between the generalized workflow model, representing a recurring business process, and a specific instance of this process. Jobs A job is a specific instance of a workflow model. One example of a TeamSite job is the set of tasks needed to prepare a new section in a marketing Web site to support a new product launch. Figure 2 shows the workflow model depicted in the previous section being used for the marketing Web site’s new product launch. This job instance now includes specific TeamSite users: Andre (the editor) and Pat (the author), and specific files that need to be edited: index.html and banner.gif.
Andre initiates job
Task: Email sent to Pat
Task: Pat edits index.html and banner.gif
Task: Email sent to Andre
Reject Task: Email sent to Pat
Task: Approve Andre Task: Email sent reviews to Pat Pat’s work
Task: Content submitted to the staging area
Task: Automated deployment
Figure 2: Workflow with assigned users
Note: You may find it helpful to refer to Chapter 3, “Using Solution Workflows,” for
diagrams showing actual solution workflows provided with TeamSite. Because jobs follow predefined workflow models, tasks cannot be added to or removed from individual jobs. In TeamSite, a description of a workflow model is called a workflow template. When a job is created, the job creator supplies all the specific information for that job, effectively “filling out” the workflow template to create a job specification. When a job specification is then loaded into the workflow subsystem it becomes a job instance. Each job is a specific instance of a workflow model.
12
Workflow Developer’s Guide
Workflow Terminology
Workflow Templates Workflow templates are XML files, with a .wft extension, that describe a particular workflow model. You can create these files and then transfer them to your TeamSite server where they can be instantiated by users, as needed, to become specific jobs. The configuration file available_templates.cfg lists all the workflow templates available to users to be instantiated. Job Specifications Job specifications are XML files that describe a specific job instance. You can create these files either directly or by invoking the instantiation of a workflow template through a TeamSite GUI. Tasks A task is a both a logical unit of work, when describing business processes, and an actual unit of work performed by a single user or process during the execution of a specific job. Each task is associated with a TeamSite branch and workarea and, possibly, one or more files. The user or process owning a task can modify, add files to, or remove files from the task (provided the task is not a read-only task for content approval). Tasks have two possible states: active and inactive. A task becomes active when its predecessor task signals it to do so (predecessor tasks and conditions for activation are all configured as part of the workflow model). After the task has been activated, users or external programs can work on it. For example, after a user task has been activated, the user can work on the files contained in that task. After an external task has been activated, the appropriate external program can run on the files contained in that task. Inactive tasks are tasks that have been completed, or that have not been activated yet. Transitions When one task is finished in a workflow, a transition to the next task (if any) occurs. For example, when an external task program makes a callback to the workflow engine to say that it is done and has succeeded, that callback is making a task transition. In an approval workflow, when the reviewer approves or rejects something, a transition to the subsequent task occurs. A workflow can have a maximum of 1000 transitions.
13
Introduction
Workflow Illustrated This section includes a detailed illustration that focuses primarily on the server processes and the interaction with the end-user (job creators and authors). It introduces the Instantiator CGI and depicts the four other main components involved in using workflow templates to create jobs: Workflow template—Defines the workflow rules through a set of workflow markups and a set of general workflow configuration instructions. Instantiator CGI—Interprets the workflow rules and data from end users, produces browser graphics and prompts, generates a job specification, and instantiates the job. Instantiator CLT (iwwft_compile.ipl)—An alternative to the Instantiator CGI, this Command Line Tool interprets the workflow rules and data from end users, generates a job specification, and instantiates the job. TeamSite browser-based GUI—Displays forms that prompt end-users for input. Job specification file—Generated by the workflow instantiator (CGI or CLT). Server-side workflow subsystem—Provides a framework for controlling processes involved with these. Figure 3 shows how these components work together. Sections after the diagram explain each diagram step and component in detail. The diagram key is displayed following the illustration.
14
Workflow Developer’s Guide
Workflow Illustrated
Workflow Template File Workflow markup General workflow configuration instructions
2
Browser End user selects template from GUI End user fills in WF form
1 3 4
5
Instantiator CGI or CLT Reads workflow markups Generates forms (not CLT) Compares data with WF rules Combines data with WF instructions Generates job specification and instantiates job
6
Job Specification Job-specific rules Can optionally be written to an XML file
7
Server-Side Workflow Subsystem Runs jobs
Figure 3: Workflow Components
1. In TeamSite ContentCenter Professional, an end user selects a workflow template from the Actions > New Job menu item. The workflow instantiator (the CGI, in this case) reads the file available_templates.cfg to determine which workflow template files are available for that given TeamSite area, file content, or user’s role. 2. The workflow instantiator goes to the specified workflow template file and iteratively reads and processes all of the workflow’s markup, which consists of Perl instructions residing in the workflow template file’s template_script element. (See “ Element” on page 63 for details about syntax and usage.) 3. Based on the workflow markup, the instantiator CGI (only) creates one or more workflow forms into which an end user can enter specific job information. 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 workflow instantiator (see Step 6). If the data does not meet all necessary criteria, the interface re-prompts the end user so that data can be reentered (default notification is the invalid field turning red in the workflow form).
15
Introduction
6. After determining that the workflow form contains valid data, the workflow instantiator combines the data with the general instructions from the workflow template file to create a job specification (and optionally a job specification file) for this specific job. If a job specification file is created, it is equivalent to the file you would create manually if you defined a job as described in Chapter 5, “Job Specification Files.” When a job specification file is not created (which is typically the case), the workflow instantiator performs the functional equivalent of writing a job specification file to disk and then invoking the iwjobc and iwinvokejob commands to instantiate and execute the job instance. For an explanation of workflow template file structure and supported element syntax, see “Workflow Template File Structure” on page 61. For an example of a job specification file, see “Sample Job Specification File” on page 118. 7. The job is instantiated on the server and started. These actions could be done manually (using iwjobc and iwinvokejob) as described in “Running Manually Created Jobs” on page 122. The following sections provide more details about each diagram component. Workflow Templates A workflow template is an XML file that can contain any or all of the elements that are valid in a job specification file. These elements form the set of general workflow configuration instructions shown in the diagram in “Workflow Illustrated” on page 14. See “Workflow Template File Structure” on page 61 for details about these elements. In addition, the workflow template file can contain elements and a set of directives to define the workflow markups also shown in the diagram on Figure 3. All instructions residing within a element are interpreted by the workflow instantiator as Perl code. See “Workflow Template File Structure” on page 61 for details and a sample file illustrating these concepts.
16
Workflow Developer’s Guide
Workflow Illustrated
Instantiator CGI TeamSite includes a standard instantiator CGI, iwwft_instantiator.cgi, to perform the following functions: Create and display the workflow information form based on information in the workflow template file. Evaluate data entered by end users based on the workflow rules in the workflow template file. Combine user-entered data with general workflow configuration instructions to create a job specification. Instantiate the job specification on the TeamSite server and start the job. Note: The CLT iwwft_compile.ipl can be used instead, to perform all but the first of
these functions. Browser Interface (GUI) End users interact with the workflow subsystem through several different user interfaces and forms. Within the ContentCenter user interfaces, users can view active job and task lists and detailed information on a specific task or job. Users can also attach, remove, or edit files attached to a task. All instructions in this manual refer to the ContentCenter interfaces. When a user initiates a new job, a workflow selection list may appear (if more than one workflow is available to that user in that user’s current TeamSite folder, workarea, or branch), allowing a user to select which workflow should be instantiated. Once a workflow has been selected, the workflow information form is then displayed to gather information from the end user for the specific job being initiated. Workflows may also trigger external tasks, which, in turn, may create forms or display other visual elements with which end users may interact. Job Specification For an explanation of file structure and supported element syntax, see “Job Specification File” on page 79. See “Sample Job Specification File” on page 118 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.
17
Introduction
Workflow Development Workflow development conceptually consists of three sequential phases: Design: understanding the business process being modeled and breaking it down into logical tasks. The output from the design phase is a workflow model. Development: turning a workflow model into a workflow template by writing a workflow template file. Alternatively, a job specification file could be written. Execution: instantiating and executing a workflow template file or executing a job specification file. In practice, the phases will typically occur iteratively as the underlying business process is better understood and as development and testing occurs.
18
Workflow Developer’s Guide
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 20.
These templates are described in “Example Template Descriptions” on page 20.
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.”
19
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. 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.wft
author_submit_dcr.wft
default_assign.wft
default_submit.wft
default_TFO_submit.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. 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. In addition to submitting the files, provides support for presubmit activities including approval, file type recognition, and user-specific destinations. Submits content to the staging area. This workflow can be configured for use by Front-Office users when they submit files from the TeamSite Briefcase or from a Microsoft Office application, such as Word.
Example Template Descriptions The templates in iw-home/local/config/wft/examples are included as reference examples that are applicable to some installations. The functionality provided by these examples is included in a more generalized form in the work_order.wft template. The templates in the examples directory are provided as shorter, more modular examples of how you can develop custom workflow templates. To make the example files available to end-users, you must edit available_templates.cfg as described in “available_templates.cfg” on page 25.
20
Workflow Developer’s Guide
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. Same as serial_approval.wft, except the reviewers review content in parallel. Example workflow template that demonstrates the functionality of a cgitask. Uses iw-home/local/config/wft/examples/
concurrent_approval.wft external_task_test.wft
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 61.
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 25).
21
Using Workflows
3. Add an entry for each new workflow. For example, to add the Author
Submit Workflow
workflow, add the following entry:
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 53. 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.
22
Workflow Developer’s Guide
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 corresponding item name values in the datacapture.cfg file. e. Optionally, test your metadata capture configuration from a custom menu item before you try it from a workflow. 9. If you are using Deployment functionality: a. Copy the deployment configuration file (solutions/wft_opendeploy.xml) to the od-home/conf directory. b. Edit solutions/wft_opendeploy.cfg file to specify the mapping from branch names to the corresponding destination nodes and paths. See “Integrating with OpenDeploy” on page 24 for detailed information about these entries.
23
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 or comment out the last three lines of the wft_opendeploy.cfg file to reflect the mapping between the branch names containing the files to be deployed and their destinations. If content from only one branch are being deployed, edit one line and comment out the other two lines. If content from more than three branches are being deployed, add lines as appropriate. branchName=/default/main/br3/,dst=/space/vijay/odreceive2,useNode=INTERNET branchName=/default/main/br2/,dst=/space/vijay/odreceive1,useNode=INTERNET branchName=/default/main/br1/,dst=/space/vijay/odreceive,useNode=INTERNET
source branch
destination path
destination node name
Note:
24
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 Developer’s Guide
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.
Workflow Configuration Files The TeamSite workflow functionality uses three configuration files to store information about the availability of workflow templates on your TeamSite server. These files apply regardless of the type of workflow you are using. These files are:
available_templates.cfg—XML file installed as part of the TeamSite installation
procedure that stores information about the conditions under which users can access workflow templates. available_templates.dtd—File used by available_templates.cfg that contains a collection of declarations (elements and attributes) that describe the expected document structure. Additionally, workflow configuration settings must be made in the main TeamSite configuration file: iw.cfg. These files are described in detail in the sections that following. Information specific to each of the workflows that are installed with TeamSite are described in Chapter 4, “Creating Workflow Template Files.” available_templates.cfg The available_templates.cfg file is an XML configuration file that lists all of the workflow templates that are available for use on the TeamSite server. For each workflow, this file indicates the name of workflow, the location of the workflow template file, and the conditions under which the workflow is available. By default, the available_templates.cfg file is located in:
Note: If available_templates.cfg is edited and contains non-ASCII text, it must be
saved in UTF-8 encoding. The available_templates element is the container element for the file. This element contains the following attribute:
— specify whether (true) or not (false) workflow templates selection screen will include a branch/workarea chooser if workarea context is not present. Most of the out of the box workflow template examples require this to be enabled (require_workarea="true") to work properly. Default value is false. require_workarea
Within the available_templates element is the template_file element: ...
The template_file element has the following attributes:
name
— specify the title of the workflow, for example:
name="Author Submit Workflow"
— indicate whether (yes) or not (no) the workflow template is enabled. Default value is yes. path — specify the path where the template file resides. Template files must reside in one of the following locations:
26
active
iw-home/local/config/wft/default
iw-home/local/config/wft/examples
iw-home/local/config/wft/solutions
Workflow Developer’s Guide
Workflow Configuration Files
The value you specify is relative to the iw-home/local/config/wft directory, so if the template file resided in the following absolute path: iw-home/local/config/wft/default/author_submit.wft
then you would specify the value: path="default/author_submit.wft"
Specifying Template Access
You can configure access to each template listed in the available_templates.cfg file by using any combination of the following categories: Command Role Group User Branch The categories can be combined using boolean terms such as AND, OR, and NOT to include and exclude those that meet the inclusion or exclusion criteria you configure. Template access is configured within the allowed element, which is a subelement of template_file: Within the template_file element is the allowed element, where you can configure user access by matching workflow commands with user roles: ...
Command Access Workflow commands are specified by the command element. The command element specifies the user-activity that starts the corresponding workflow. For example, the following configuration:
specifies that the associated workflow is started when performing a Submit and that it cannot be invoked by other means. The valid command values that you can associate with a workflow are:
submit (submitting
files) assign (assign button or menu item) new_job (new job) new_TFO_job (new job, in TeamSite FrontOffice) 27
Using Workflows
(saving FormsPublisher data records) tt_deletedcr (deleting FormsPublisher data records in ContentCenter Standard only) all (all possible values from this list) tt_data
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 Access Access based on TeamSite roles is specified by the role element’s name attribute. For example, the following configuration:
specifies that if the user is logged in as an Author.
Group Access Access based on user groups is specified by the group element:
User Access Access based on individual user name is specified by the user element: <user name="jdoe"/>
Branch Access Access based on TeamSite branch is specified by the branch element:
Combining Access Categories Pairings of individual or multiple access elements can be included or excluded using the and, or, and not elements within the allowed element. You can use boolean logic to create combinations of categories that can either have access to a specific template, or be excluded from it.
28
Workflow Developer’s Guide
Workflow Configuration Files
In the following example: <not> <user name="jdoe"/>
the following individuals have access to the Author Submit workflow:
Those who are authorized to perform submit commands. Those who have the author or editor role. Those who are members of the marketing group. Those who have the admin role, with the exception of the user jdoe. If no access category is specified, it is assumed that category has full access to the workflow template. Regular Expression Support
You can use regular expressions when specifying branch element constraints within available_templates.cfg to search for a specified pattern and specify what to do when matching patterns are found. Using regular expressions allows a greater level of flexibility when adding items. For example, if you want only the users in the three administration_1 branches (a1, a2, and a3) to access a workflow template, you can set the following constraint: ...
29
Using Workflows
If a new branch called a4 is added to /default/main/administrator_1 you could manually update the available_templates.cfg file to allow access for users in the new branch by adding the branch element to the existing ones:
Or you could modify the available templates.cfg file to use the following regular expression and, thus, automate the constraints placed on the a4 branch: ...
This regular expression allows users from any branch under /deault/main/ administrator_1 to have access to the template.
Path Separators When using regular expressions, the path-separators (“\”, “\\”, “/”) are all translated to “/” in both the pattern and the string to match against before attempting the match. In the following example:
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:
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/...
30
Workflow Developer’s Guide
Workflow Configuration Files
The following examples are all treated as identical on both Windows and UNIX.
name="^/default/main/foo" include="yes"/> name="^\default\main\foo" include="yes"/> name="^\\default\\main\\foo" include="yes"/> name="^/default\main\\foo" include="yes"/>
available_templates.dtd The available_templates.cfg file begins with the following prolog:
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:
The following available_templates.dtd defines the default behavior of the available_templates.cfg file:
iw.cfg The iw.cfg file is the main TeamSite server configuration file. It includes configuration settings for the way TeamSite looks and responds to various requests. By default, the file is located in /etc (Solaris) or iw-home/etc (Windows). This section includes information about workflow-related settings in three parts of the iw.cfg file:
[iwserver] [iwsend_mail] [workflow]
For details about TeamSite configuration issues that do not concern workflow, refer to the TeamSite Administration Guide for your server platform (Windows or UNIX).
32
Workflow Developer’s Guide
iw.cfg
[iwsend_mail] Parameters The Perl script iwsend_mail.ipl was specifically designed for use within TeamSite workflows to simplify the creation of external task scripts for email notification. Modify the [iwsend_mail] section of your iw.cfg file to include the following lines: [iwsend_mail] maildomain=interwoven.com mailserver=mail1.interwoven.com use_mapping_file=true email_mapping_file=c:/iw-home/local/config/wft/email_map.cfg debug_output=c:/tmp/iwsend_mail.log
For detailed information about the iwsend_mail.ipl script, refer to Appendix B, “iwsend_mail.ipl Script.” [workflow] Parameters The [workflow] section of iw.cfg contains by default these commented parameters and their corresponding default values:
Each of these parameters also contains a commented description. To activate any of the parameters, remove the single pound sign (#) that precedes the line. You can also change the default setting. Ensure the double pound signs (##) preceding the description are not removed. [workflow] ## Set 'external_task_add_filelist' to false if you want to prevent ## TeamSite from adding files to the command line of external task ## command callouts (recommended on WinNT/2K). Defaults to true. #external_task_add_filelist=false ## ## The maximum depth of nesting allowed for nested jobs (wftask); ## defaults to 3. Values less than 1 are ignored. #wftask_nesting_depth_allowed=3 ## ## Set external_task_retry_wait to the number of minutes you want the ## workflow engine to wait before it re-attempts to run an external ## task after failing. Defaults to 1 minute. #external_task_retry_wait=1 ## ## Causes the submittask to check for possible locking & conflict ## issues with files before attempting the submit. This provides ## a greater likelihood that the submittask files will be submitted ## all at once, or none at all. Defaults to false if not specified.
33
Using Workflows
#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. The syntax for the iwquerytasks CLT is: iwquerytasks [-h] [-v] [-x] [-o offset] [-m max] [-l locale] [-s servername]
34
Print this message. Print version. Output result in XML. Use servername as the TeamSite server. Skip the first offset results. The number of results specified are skipped before results are returned. Maximum number of results to return. Locale for server-side sorting. The query is read from stdin.
Workflow Developer’s Guide
Querying Workflows
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):
Then call the iwquerytasks CLT as follows: iwquerytasks < myquery.xml>
The attributes of tasks that may currently be queried against are: active job active job owner workflow id needsattention task type sharedby (that is, all group tasks shared by a specific user) undoableby (that is, all tasks undoable by a specific user) tryingtolock readonly task areavpath task activationtime task file (that is, all tasks with a specific file in their file lists) Query results may also be sorted and/or filtered by job or task description and variables. In addition to specifying the field to sort by, you can also specify case sensitivity, descending order, and primary sort fields. For example, the previous query, with results sorted by areavpath in descending order, would be: <sortby>
To construct more complex queries, refer to the DTDs.
35
Using Workflows
The syntax for the iwqueryjobs CLT is: iwqueryjobs [-h] [-v] [-x] [-o offset] [-m max] [-l locale] [-s servername]
-l locale
Print this message. Print version. Output result in XML. Use servername as the TeamSite server. Skip the first offset results. The number of results specified are skipped before results are returned. Maximum number of results to return. Locale for server-side sorting.
The query is read from stdin.
-v -x -s servername -o offset -m max
The attributes of jobs which may currently be queried against are: job owner active job activationtime
External Task Commands Using URLs You can configure an external task to run a URL command on your TeamSite server host, or on a remote host. This remote host must be running Java to use this feature. Configuration is similar to that of other external task workflows. When the external task is executed, the URL is checked for validity. If it is valid, it is executed in the manner described in this section. Otherwise, it is treated as a conventional external task. Note that only HTTP URL commands are supported. To configure an external task with URL workflow in a workflow template, follow these steps: 1. Specify the external task URL command using the following format:
where servername is the local host on which the workflow is being run, and param=value are the user-defined parameters.
36
Workflow Developer’s Guide
Demonstrating the Workflow CGI Task
2. Add the value ClassName as a variable to the external task, for example:
3. Create a Java class that implements the following interface: com.interwoven.cssdk.workflow.CSURLExternalTask
4. Place the Java class in the appropriate location relative to the following directory: iw-home/local/config/lib/content_center/customer_src
For example, if you created the following class” com.corp.custom.URLExternalTaskTest
then the full path would be: iw-home/local/config/lib/content_center/customer_src/com/corp/ custom/URLExternalTaskTest.java
5. Rebuild the Web applications. 6. Add that workflow template to the available_templates.cfg file. See “available_templates.cfg” on page 25 for more information. Sample Files The following sample files are provided for use with this feature. Workflow template file — iw-home/local/config/wft/examples/ url_external_task_test.wft
Java class — iw-home/local/config/lib/content_center/ customer_samples_src/src/com/corp/custom/URLExternalTaskTest.java
Demonstrating the Workflow CGI Task A file named cgi_task_test.wft in iw-home/local/config/wft/examples can be used to test a workflow CGI program. The workflow has two tasks. The first task is a CGI task that can transition either to the end of the workflow or to the second task. The second task is a user task that transitions back to the first task (to re-run the CGI). This workflow can be modified to use the Convert CGI task by performing the following steps: 1. Make of copy of the WFT with a different name. 2. Edit the new file. a. Change the $cgi_command to /iw-cc/converttask (line 31). b. Change the readonly flag on the CGI task from "t" to "f" (line 117).
37
Using Workflows
c. Optionally, change the description of the CGI task to something like Convert Attached Documents (line 114). 3. Add this workflow to iw-home/local/config/wft/available_templates.cfg for the desired command, branches, etc. For example:
Alternatively, this task can be added into an existing workflow by simply adding a CGI task with the command /iw-cc/converttask and readonly="f". For example: <areavpath v="__TAG__('iw_workarea');"/> <successors> <successorset description="NEXT TASK"> <succ v="Done"/>
Roles Considerations As a workflow developer, you need to aware of the role constrains. If you allow some users with certain roles to do some workflow tasks, you need to make sure those users have the privileges to perform their tasks, such as preview, compare, merge, and so forth. Otherwise, those users will not be able to complete their tasks. To workaround these role constraints, you can choose to use external task scripts. External scripts run in master mode and ignore role constrains. The following sections describe issues related to the use of flexroles in TeamSite workflows. Specifying Reviewer Roles in Workflow Templates It is recommended that you write workflow templates that allow only users with roles that have permission to preview files to be the reviewers, or the reviewers will not be able to see the content when reviewing and approving the task. For example, in the configurable_author_assignment.cfg solutions workflow template residing in the following location: iw-home/local/config/wft/solutions
38
Workflow Developer’s Guide
Roles Considerations
use either of the following lines to specify who can be the reviewer: review_type=serial[select[role:admin,role:master,role:editor], select[role:admin,role:master,role:editor]]
or review_type=areaowner
The value areaowner is a special value specifying that only the workarea owner needs to be reviewing the task. Only set review_type to roles that have preview access to the workarea. Configuring Callout Buttons In order for flexroles to work in this release, it is recommended that you use the following examples when making callout buttons: use TeamSite::Flexroles qw(get_users_having_roles); $vpath = "a_branch_vpath_to_get_roles_and_users_from"; my @users = get_users_having_roles($vpath, ("author", "editor"));
Using the above code section, a list of users is returned from the call to get_users_having_roles in Flexroles.pm. You can then use this list of users to construct any kind of HTML list as you want in their workflow template files.
39
Using Workflows
40
Workflow Developer’s Guide
Chapter 3
Using Solution Workflows The solution workflows are designed to incorporate functionality that was commonly being implemented either by modifying the Interwoven-provided workflow template files (wft) or by modifying the Perl code. They have features and supporting files that make them easier to use. It is recommended that you use or revise these workflows when possible. Three of these workflows are variations on the author_submit default workflow included with earlier TeamSite releases. The other three workflows are configurable alternatives to the previous default workflows included with earlier versions of TeamSite.
Solutions Workflows Illustrated This section shows diagrams and descriptions of workflows in the solutions directory, located in iw-home/local/config/wft. These workflows are available for your use and also illustrate the tasks and transitions included in workflows. The configurable steps are marked as “optional”.
41
Using Solution Workflows
Author Submit with Deploy Figure 4 illustrates an author submit combined with a deployment.
1. Author clicks Submit to submit modified files, which initiates a new Job and prompts the author for the following information: Submit comment (required) Information comment (optional) Individual file comments (optional)
Submit
Author Work iw_author
reject
Review iw_areaowner
2. Author-submitted content is sent to a reviewer. The reviewer is defined as the owner of the workarea from which the files are submitted.
approve
Submit iw_areaowner
failure Resolve Deployment Problem
Deploy retry
3. The reviewer either: Approves the work. Rejects the work (which is sent back, as a task, to the author who modifies the work, and resubmits it for approval by clicking Finish on that task).
End
4. When approved, the files are submitted to the staging area. 5. The files are then deployed to the location specified in the wft_opendeploy.cfg file. Note: wft_opendeploy.cfg must be configured before this OOTB solution can be used. Figure 4: Diagram of the Author Submit with Deploy solution workflow
42
Workflow Developer’s Guide
Solutions Workflows Illustrated
Author Submit with Email Figure 5 illustrates an author submit combined with an email.
Submit
Author Work iw_author
1. Author clicks Submit to submit modified files, which initiates a new Job and prompts the author for the following information: Submit comment (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 owner of the workarea to which the files are submitted.
Review iw_areaowner
3. The reviewer either: Approves the work. Rejects the work (which is sent back, as a task, to the author who modifies the work, and resubmits it for approval by clicking Finish on that task). When resubmitted, another email is sent to the reviewer).
reject
approve
Submit iw_areaowner
End
4. When approved, the files are submitted to the staging area. Figure 5: Diagram of the Author Submit with Email solution workflow
43
Using Solution Workflows
Author Submit with Metadata Figure 6 illustrates an author submit with metadata capture.
Submit
Author Work iw_author
Metadata Capture iw_user
reject
Review iw_areaowner approve
Submit
iw_areaowner
End
1. Author clicks Submit to submit modified files, which initiates a new Job and prompts the author for the following information: Submit comment (required) Information comment (optional) Individual file comments (optional) 2. Author-submitted content is then processed for metadata capture (by either the TeamSite Tagger GUI or through MetaTagger integration). 3. Author-submitted content is sent to a reviewer. The reviewer is defined as the owner of the workarea from which the files are submitted. 3. The reviewer either: Approves the work. Rejects the work (which is sent back, as a task, to the author who modifies the work, and resubmits it for metadata capture and approval by clicking Finish on that task). 4. When approved, the files are submitted to the staging area.
Figure 6: Diagram of the Author Submit with Metadata solution workflow
44
Workflow Developer’s Guide
Solutions Workflows Illustrated
Configurable Author Assignment Figure 7 illustrates a configurable author assignment.
1. A new job is initiated, typically by an editor; the initiator may have already selected files to be worked on by the author (prior to initiating the job) or may attach them to the job.
New Job
(optional) Add Files to Job
2. (Optional) Email notification of the assigned work and any associated files is sent to the author.
(optional) Email to Author
3. Author completes assigned work and marks the task as Done by clicking Finish on that task.
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
reject
5. Work is submitted to the review subflow for approval or rejection. See “Review Subflows” on page 47 for more information.
Review Subflow (See “Review Subflows” on page 47 for more information.)
approve (optional) Email Notification of Deployment Problem
6. The reviewer either: Approves the work, in which case the files are submitted to the staging area. Rejects the work, in which case the job is returned to step 2. 7. (Optional) The file is deployed to the location specified in the wft_opendeploy.cfg file (email is sent to the initiator if there is a deployment problem).
Figure 7: Diagram of the Configurable Author Assignment solution workflow
45
Using Solution Workflows
Configurable Author Submit Figure 8 illustrates a configurable author submit.
Submit
(optional) Add Files to Job (optional) Email to Author
Author Work iw_author
(optional) reject
Metadata Capture iw_user
4. Work is submitted to the review subflow for approval or rejection. See “Review Subflows” on page 47 for more information.
Review Subflow (See “Review Subflows” on page 47 for more information.) approve (optional) Email Notification of Deployment Problem
1. Author clicks Submit to submit modified files, which initiates a new Job and prompts the author for the following information: Submit comment (required) Information comment (optional) Individual file comments (optional) 2. (Optional) The author selects additional files to be submitted. 3. (Optional) Author-submitted content is then processed for metadata capture (by either the TeamSite Tagger GUI or MetaTagger integration).
Resolve Deployment Problem iw_areaowner
cancel job
5. The reviewer either: Approves the work and the files are submitted to the staging area. Rejects the work, in which case optional email requesting revisions is generated and a revision task occurs. 6. (Optional) The file is deployed to the location specified in the wft_opendeploy.cfg file (email is sent to the initiator if there is a deployment problem).
Figure 8: Diagram of the Configurable Author Submit solution workflow
46
Workflow Developer’s Guide
Review Subflows
Configurable Default Submit Figure 9 illustrates a configurable default submit. 1. A user—whose work does not need review—submits a file.
Submit
2. (Optional) Content is processed for metadata capture (either in the TeamSite Tagger GUI or through MetaTagger integration), then submitted to the staging area.
(optional) Metadata Capture iw_user
(optional) Email Notification of Deployment Problem
Submit iw_user failure (optional) Deploy retry
End
3. (Optional) The file is deployed to the location specified in the wft_opendeploy.cfg file (email is sent to the initiator if there is a deployment problem).
Resolve Deployment Problem iw_areaowner
cancel job
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, it is a part of the configurable author submit
and assignment workflows. This review subflow process is shown in as a single box in the overall workflow illustrations. This section contains an illustration detailing this subflow process. Serial Review Serial reviews provide for tiers of reviewers. If the first reviewer approves the work, it is forwarded to the next reviewer. Depending on the type of serial review, a rejection either automatically sends the work back to an author for revision (“return on first reject”), or passes the work to the next reviewer (“all at once”). 47
Using Solution Workflows
Return on First Reject
Figure 10 illustrates a return on first reject. This serial review allows for a sequential review of the work. If any of the reviewers reject the work, the work is automatically sent back to an author for revisions, and no further reviewing is done until the work is resubmitted.
Start Review
(optional) Start Review Cycle
(optional) Email Reviewer 1
Review 1 (reviewer 1 or group 1) approve (optional) Email Review 2
Reviewer 2 (reviewer 2 or group 2)
1.(Optional) Email notification is sent to first reviewer configured in the workflow configuration file. 2. The reviewer either: Approves the work. Rejects the work. 3. One of the following actions occurs: If approved, the workflow (optionally) emails the next reviewer (if any) configured in the workflow configuration file. The work is then forwarded to the next reviewer. If rejected, an email is triggered to the author for modification.
approve (optional) Email Reviewer n
4. The review procedure is repeated for each reviewer of 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
48
Workflow Developer’s Guide
Review Subflows
All At Once
Figure 11 illustrates an all-at-once. This serial review permits each reviewer to approve or reject the work. If the work is rejected, it is still forwarded to the next reviewer. This way the author can receive input from all reviewers, even if there is a rejection. After all reviews are complete, a selection criterion is applied to the work based on the cumulative approvals and rejections to determine the work’s status. All-at-once serial reviews are typically used in conjunction with VisualAnnotate.
1.(Optional) Email notification is sent to first reviewer configured in the workflow configuration file.
Start Review
(optional) Start Review Cycle
2. The reviewer either: Approves the work. Rejects the work.
(optional) Email Reviewer 1
3. The work is forwarded to the next reviewer configured in the workflow configuration file. An email can optionally be sent to the next reviewer.
Review 1 (reviewer 1 or group 1) reject
4. The review procedure is repeated for each reviewer until all the reviewers have reviewed the work.
approve (optional) Email Review 2
5.After the last reviewer finishes, a selection criterion, based on all the cumulative approvals and rejections, is applied to the work to determine if the work has passed review.
Reviewer 2 (reviewer 2 or group 2) reject
approve (optional) Email Reviewer n
Review n (reviewer n or group n) reject
Reject
approve (optional) End Review Cycle
Approve
Figure 11: Diagram of the All-at-once Review workflow
49
Using Solution Workflows
Concurrent Review Figure 12 illustrates a concurrent review. This provides for a simultaneous distribution of the work to all the reviewers. This differs from the serial review where the work is seen by only one reviewer at a time. At the end of the concurrent review, the reviewers’ decisions and comments are tallied, and a decision is made on whether the work has passed review.
1. (Optional) Email notifications are sent to all reviewers configured in the workflow configuration.
Start Review
(optional) Start Review Cycle
2. Each reviewer either: Approves the work. Rejects the work. (optional) Email Reviewer 1
Review 1 (reviewer 1 or group 1)
approve
3. If any reviewer rejects the work, the review is immediately terminated. Otherwise, the review is passed when every reviewer has approved the work.
reject
(optional) Email Review 2
Reviewer 2 (reviewer 2 or group 2)
approve reject
(optional) Email Reviewer n
Review n (reviewer n or group n)
approve reject
OR
AND
Review rejection
Review approval
Reject
Approve
Figure 12: Diagram of the Concurrent review workflow
50
Workflow Developer’s Guide
Configurable Workflow Overview
Configurable Workflow Overview The following three solutions workflows are activated by default and are configurable:
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 51 and the properties files in “Workflow.properties File Overview” on page 52. Note: To activate any of the optional (non-default) workflows, complete the procedure
described in “Enabling Workflows” on page 21.
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 51 for an overview of a specific workflow or “Configurable Workflow Settings” on page 53 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
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 60.
VisualAnnotate and Configurable Workflows VisualAnnotate is a review tool that is installed by the TeamSite installation program. It enables users to annotate HTML pages from within their browser window. Reviewers can draw, change text, and add “sticky notes” directly on the pages they are viewing. These annotations are stored separately from the file as extended attributes. VisualAnnotate reviews are implemented within the following solution workflows:
Using or adapting these solutions eliminates the need to build separate VisualAnnotate workflows. Refer to Chapter 6, “Using VisualAnnotate,” for more information about VisualAnnotate and its configuration.
52
Workflow Developer’s Guide
Configurable Workflow Settings
Note: Because VisualAnnotate is not supported on non-English servers, remove the
VisualAnnotate functionality from these workflows before using them on a nonEnglish server.
Configurable Workflow Settings All three configurable workflows share the following functionality:
Email Notification Metadata Capture Deployment The configurable_author_assignment and configurable_author_submit workflows also add the functionality to have submitted files reviewed by a configurable reviewer. The reviewer section of these workflow configuration (.cfg) files is where the email notification system obtains instructions to determine the email address of the reviewer. Note: The configurable_author_assignment workflow also adds the functionality to
attach files to a workflow task. The general procedure for configuring these options is the same for each of the configurable workflows: 1. Open the workflow_name.cfg file that corresponds with the configurable workflow you want to implement. By default, these files are located in iw-home/local/config/wft/solutions. 2. Edit the entries that correspond with the functionality you want to enable. 3. Save and close the file. 4. Ensure the workflow is activated as described in “Enabling Workflows” on page 21. The following sections describe each of these options in detail. Email Notification Settings All configurable workflows have the ability to send email notifications to alert the user of work assignments, requests for review of completed work, or problems deploying files. ## Email Notification ## # Should an email notification be sent to an Author when a task # is pending? email_notification_to_author=no
Change this entry to email_notification_to_author=yes if you want the email sent to authors who have either had work assigned to them by an assignment workflow or by having 53
Using Solution Workflows
submitted work rejected by a reviewer. If set to yes, email is sent to the author to whom the work is assigned (author_assignment workflows) or to the author who performs the submit (author_submit workflows). # Should an email notification be sent to a reviewer when a task # is pending? email_notification_to_reviewer=no
Change this entry to email_notification_to_reviewer=yes if you want to email sent to reviewers who have had work assigned to them for review (that is, the status of the task is pending). If set to yes, you must configure the reviewer in the reviewer section of the configurable_author_assignment.cfg or configurable_author_submit.cfg files. # Should an email notification be sent if a deploy task fails? email_no_deploy=no
Change this entry to email_no_deploy=yes if you want to email sent to the job initiator when a deploy task fails. # Should the initiator be prompted to confirm or change these # choices when initiating a job? # If yes, the values of email_notification_to_author, # email_notification_to_reviewer, and email_no_deploy will serve # as the defaults. ask_email_notification_to_author=no ask_email_notification_to_reviewer=no ask_email_no_deploy=no
Change these entries to ask_email_...=yes if you want the person initiating the job to be prompted to override (on a job-by-job basis) whether email should be sent for any of the three situations. # Templates for the headers and bodies of email messages. reviewer_email_header_template=reviewer_iwmailheader.tpl reviewer_email_body_template=reviewer_iwmailbody.tpl author_email_header_template=author_iwmailheader.tpl author_email_body_template=author_iwmailbody.tpl no_deploy_email_header_template=no_deploy_iwmailheader.tpl no_deploy_email_body_template=no_deploy_iwmailbody.tpl
If you want to replace the Interwoven logo file (ts_logo.gif) with a graphic file containing your organization’s logo:
Copy the file into iw-home/httpd/iw-icons/solutions directory. Open the appropriate _mailbody.tpl file in a text editor. Replace the ts_logo.gif reference in the section with a reference to the new graphic file.
54
Workflow Developer’s Guide
Configurable Workflow Settings
Figure 13 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 marked as Done, the workflow will display either the MetaTagger capture screen (requires that the MetaTagger product is installed) or the default TeamSite metadata capture screen depending on a setting later in this file. # Should the initiator be prompted to confirm or change this # choice when initiating a job? # If yes, the value of metadata_capture will serve as the default. ask_metadata_capture=no
Change this entry to ask_metadata_capture=yes if you want the person initiating the job to be prompted to override (on a job-by-job basis) whether the submitter is required to enter metadata. # If there is a task to capture metadata, which UI should be presented? # iwmetadata.cgi is the TeamSite metadata capture UI. metadata_capture_ui=iwmetadata.cgi # mtmetaproxy.cgi is the MetaTagger metadata capture UI (requires MetaTagger). #metadata_capture_ui=mtmetaproxy.cgi
55
Using Solution Workflows
If a metadata task is included in the workflow, the default metadata capture interface displayed to the submitter is the TeamSite metadata capture form (iwmetadata.cgi). If you have installed MetaTagger 3.1 or later, and would like to have it displayed by the workflow, comment out the metadata_capture_ui=iwmetadata.cgi line (add a # at the beginning of the line) and uncomment the #metadata_capture_ui=mtmetaproxy.cgi line (remove the #). For more information about capturing metadata, refer to the:
TeamSite Administration Guide for information about iwmetadata.cgi.
MetaTagger user documentation for information about mtmetaproxy.cgi.
Deployment Settings The workflow_name.cfg files contain the following deployment entries. They use a question-and-answer format with the question commented out (preceded by #) followed on the next line by the answer. The answer is set to no by default and may be followed by additional settings. ## Deployment ## # Should there be a Deploy task at the end of a job to deploy files # after they have been submitted? deploy_task=no
Change this entry to deploy_task=yes if you want the files being submitted to be deployed by the workflow using OpenDeploy. # Should the initiator be prompted to confirm or change this # choice when initiating a job? # If yes, the value of deploy_task will serve as the default. ask_deploy_task=no
Change this entry to ask_deploy_task=yes if you want the person initiating the job to be prompted to override (on a job-by-job basis) whether the files associated with this job should be deployed when submitted. # Should the job form include an info field? ask_for_info=yes
By default, the job form presented to the submitter includes a field where details about the submission can be included. Any information entered by the submitter is stored in a submit-info variable of the submit task and, as such, can be queried or displayed.
56
Workflow Developer’s Guide
Configurable Workflow Settings
Review Settings The configurable_author_submit.cfg and configurable_author_assignment.cfg workflows contain functionality that requires files be reviewed before they are submitted. The configuration involves defining who the reviewer is. The default reviewer for these workflows is the owner of the workarea to which the file is being submitted. The following commented section from these files summarize how reviewers can be specified: ## Review ## # Who should review the Author's work? The format of the review_type is: # # "review_type=" | <serial> | # = "areaowner"|"job_initiator"|<user>||<select> # <user> ::= "user:" # ::= "grouptask[" (|<user>) ("," (|<user>))* "]" # ::= "group:" # <select> ::= "select[" ("," )* "]" # ::= "role:" ( "author"|"editor"|"admin"|"master"| etc. ) # <serial> ::= "serial[" ("," )* "]" # ::= "concurrent[" ("," )* "]"
The following sections describe simple examples (those that use as the review_type value), and advanced examples (those that use <serial> or 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). Note: In the second example, the domain is specified for Windows only; on a UNIX
system, it would be simply the username (andre). In the third example, the review task is a grouptask that is shared by the specified users and groups. In the fourth example, the review task is a usertask, and the owner of that task will be selected by the job initiator from a selection list of those users who are authors or editors.
57
Using Solution Workflows
The configurable_author_submit workflow uses areaowner by default.To specify one of the following reviewers, comment out (with #) the line review_type=areaowner and:
Job initiator—Uncomment the line # review_type=job_initiator Specified user—Uncomment the line # review_type=user:worldcorp\andre, and replace worldcorp\andre with the username and (Windows only) domain. Specified group—Uncomment the line # review_type=grouptask[group:demomaster,user:jsmith], and replace demomaster with one or more groups, defined in the operating system, and replace jsmith with one or more user names (and, on Windows, their domains). Separate each group and user name with a comma. You can include groups and users in any number and combination. Selection list from which to choose a reviewer or group of reviewers and respective roles —Uncomment the line # review_type=select[role:editor,role:author] and specify the desired reviewer roles in any number or combination. The users whose roles match one or more of the reviewer roles specified will be displayed in a selection list to the job initiator. For example, the file configurable_author_assignment.cfg has a commented out line review_type=select[role:editor]. If this were specified, then the selection list would contain all users with the Editor role. Figure 13 shows an example of an email sent to a reviewer. Advanced Examples review_type=serial[select[role:editor],areaowner,select[role:master,role:admin]]
This example specifies a review process with three review tasks that are executed in a serial manner. The first review task is assigned to a user selected from among the Editors. The second review task is assigned to the area owner. The third task is assigned to a user selected from among the Masters and Administrators. review_type=concurrent[select[role:editor],select[role:editor],select[role:editor]]
This example specifies a review process with three concurrent review tasks. Each task is assigned to a selected editor. Use with VisualAnnotate
For workflows that employ VisualAnnotate, it is recommended that a serial review process be in place. For example: review_type=serial[select[role:admin,role:master,role:editor],select[role :admin,role:master,role:editor]] Return on First Reject?
In a serial review process, you must decide whether the workflow will return to the author as soon as a single reviewer rejects, bypassing all remaining reviewers. return_on_first_reject=yes
58
Workflow Developer’s Guide
Configurable Workflow Settings
If you decide no, the workflow will reach all reviewers before deciding whether to return to the author. Minimum Number of Reviewers
You must also determine the minimum number of reviewers that the job initiator must specify. min_reviewers=3
This indicates the minimum number of reviewer selections that are required. For example, if review_type indicates a serial review with three tasks, with one reviewer type specified and two to be chosen from selection lists, and min_reviewers=1, then one reviewer selection will be required and one will be optional. If you do not specify a minimum, the job initiator must select a reviewer for every review task that specifies a selection list. Automatically Forward to Next Reviewer?
You must decide whether the job should automatically forward the review task on to the next reviewer (or to the author) if a certain amount of time elapses. review_timeouts=yes
Note: Depending on the workflow’s specified selection criteria, based on cumulative
approvals and rejections, to determine if the work being reviewed has passed review, such automatic forwarding may result in the work not passing review. If you choose yes, you must specify how long in hours and minutes the amount of time will be, using the +HHHHMM format. review_timeout_duration=+004800
When using the +HHHHMM format, you must use all six digits, including leading zeros if necessary.
59
Using Solution Workflows
Add Files Settings The configurable_author_assignment.cfg and configurable_author_submit.cfg workflows contain functionality for the initiator to attach files to a job. When a new job is created by selecting Assign, Submit, or New Job, all of the selected files are attached to the job. The configuration specifies whether the workflow will begin with a user task for the initiator to add additional files (the default is no for both of the following options). ## Add Files ## # Should there be an "Add Files" task at the beginning of the job # to permit additional files to be added? include_add_files=yes # Should the initiator be asked if an "Add Files" task is desired # when initiating a job? # If yes, the value of include_add_files will serve as the default. ask_include_add_files=yes
Configurable Workflows and Localization In addition to the workflow_name.cfg file and workflow_name.properties files installed by the TeamSite installation program, there are additional properties files that have been localized in TeamSite versions that support localization: workflow_name_de.properties (German) workflow_name_en.properties (English) workflow_name_fr.properties (French) workflow_name_ja.properties (Japanese) workflow_name_ko.properties (Korean) workflow_name_zh_CN.properties (Simplified Chinese) These files contain the localized text strings that display in the ContentCenter interfaces if the user’s browser is operating in a locale that matches one of these files. If the locale of the browser does not match one of the locales, the default workflow_name.properties file (the one without a locale specified) is used to provide the text strings. Note: The contents of these files use Latin-1 encoding, therefore multibyte characters are
represented using Unicode characters.
60
Workflow Developer’s Guide
Chapter 4
Creating Workflow Template Files This chapter describes the structure and contents of workflow template files. It contains an introduction to the components used in workflow templates; an excerpt from a basic sample workflow template file; an explanation of all file components (some of which are not included in the basic sample file); and a second, more sophisticated sample file (which shows how to use more of these file components). The actual ready-to-use workflow templates installed with TeamSite are described beginning on page 77.
Workflow Template File Structure Workflow template files are installed by default in three subdirectories in iw-home/local/ and end with a .wft extension. Workflow template files may contain the following components: 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.
config/wft
61
Creating Workflow Template Files
Simple Workflow Template File The following is a fragment from a simple workflow template file that fills in blank fields (indicated by __TAG__ directives) with HTML-encoded CGI data. ", job_name
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 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 job_name
=> "", => [ html => "", label => "Job Name", ],
);
62
Workflow Developer’s Guide
Workflow Template File Structure
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... ...another_attribute... ... and so on... ],
=> =>
...a_value..., ...another_value...,
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 76. Element A workflow template file can contain any number of elements. Each element contains arbitrary Perl code that can perform the following actions: Define the rules that a workflow instantiator (either the CGI or CLT) employs to combine user-entered data with: hardcoded workflow XML from the workflow template file. programmatically generated workflow XML produced within elements. Programmatically generate a job specification (and/or intersperse hard-coded XML job specification information with programmatically generated XML). Optionally send the job specification to a file in addition to, or instead of, instantiating it into the workflow subsystem. This can be helpful if you need to see exactly what XML is being produced by the workflow template file and a workflow instantiator. Define the rules that validate user-entered data. Define the custom error messages displayed when the template's data validation rules are not satisfied (see “<normal>TAG_info Directive” on page 66). Inspect incoming POST/GET data, and (under certain conditions) execute code on the basis of this data. For example, rules in a element can tell the instantiator to generate different job specifications depending on what a user’s name is. For example, if the an Author “Andre” needs three approvers for his work, but the Author “Jerome” needs only one approver, you can define rules in a 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 65). 63
Creating Workflow Template Files
Because TeamSite workflow templates must be valid XML documents, all content in a element must be declared as CDATA to protect it from interpretation by an XML parser. For example:
Together, all of the elements in a workflow template file form a single Perl program. If a workflow template file contains more than one element, all variables, functions, and libraries set in one element are available in the others. For example: <...hard-coded workflow XML...> <...hard-coded workflow XML...>
64
Workflow Developer’s Guide
Workflow Template File Structure
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 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"). Label field background color displayed if an end user enters invalid data in the data field. Error message text color. Background color displayed if an end user enters valid data. Browser window title. Sets the options for the element of the instantiator CGI. For general information about elements, see
error_label_bgcolor error_text_color valid_bgcolor title html_body_options
element of the instantiator CGI. For general information about
elements, see http://www.w3.org/TR/REC-html40/struct/ tables.html#h-11.2.1
pre_tagtable_html post_tagtable_html
Defines what is displayed in a workflow form between the banner and tag table areas. 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.
65
Creating Workflow Template Files
Example CGI_info( error_bgcolor valid_bgcolor title html_body_options tag_table_options
", 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 =>
that collects data for tagname...", expression...", label...", 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 => "", );
The internal representation of the resulting HTML code is: ""
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 => "", };
66
Workflow Developer’s Guide
Workflow Template File Structure
then name='drink' gets removed and automatically replaced by name='beverage'. The TAG_info directive may appear only within a 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. Whether end-user input in the tag is required. Defaults to true if not set. Rules to check input validity. Default is to check for an empty string if not set. An HTML message returned if end-user input is invalid. Default message is Valid input required if not set. The HTML label displayed beside the HTML input field for this tag. Defaults to the value of tagname if not set.
is_required valid_input error_msg label
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 => "", 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(@_)', ] )
67
Creating Workflow Template Files
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 => "", beverage => [ html => "", is_required => 'true', label => '<strong>Enter beverage choice', valid_input => '/^Beverage:/', error_msg => ' <strong>'. 'ERROR: input must begin with "Beverage:"'. '', ], music => "", );
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 = "", );
68
Workflow Developer’s Guide
Workflow Template File Structure
And the person who creates an instance of this job fills in the prompt for “Title” with “Technical Writer,” the generated workflow contains:
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 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>" "