Workflow Extensions User Guide. StarTeam 12.0

Transcription

1 Workflow Extesios User Guide StarTeam 12.0

2 Micro Focus 575 Ato Blvd., Suite 510 Costa Mesa, CA Copyright 2011 Micro Focus IP Developmet Limited. All Rights Reserved. StarTeam cotais derivative works of Borlad Software Corporatio, Copyright Borlad Software Corporatio (a Micro Focus compay). MICRO FOCUS, the Micro Focus logo, ad Micro Focus product ames are trademarks or registered trademarks of Micro Focus IP Developmet Limited or its subsidiaries or affiliated compaies i the Uited States, Uited Kigdom, ad other coutries. All other marks are the property of their respective owers. BORLAND, the Borlad logo, StarTeam, ad Borlad product ames are trademarks or registered trademarks of Borlad Software Corporatio or its subsidiaries or affiliated compaies i the Uited States, Uited Kigdom, ad other coutries. All other marks are the property of their respective owers. ST12.0-EXT December 2011 PDF

3 Cotets Chapter 1 Preface 7 Documetatio Documetatio Covetios Micro Focus Support Chapter 2 Uderstadig StarTeam Workflow Extesios Features 9 What Is Workflow? About StarTeam Workflow Extesios StarTeam Extesios StarTeam Workflow Desiger StarTeam Notificatio Aget Related StarTeam Features StarTeam Repository Customizatio StarTeam SDK Workflow Roadmap Chapter 3 Usig StarTeam Extesios 13 About StarTeam Extesios Creatig ad Cofigurig the StarFlow Extesios Project Creatig StarFlow Extesios Projects Addig Access to a Server Cofiguratio Addig Files to the StarFlow Extesios Project. 15 Uderstadig Locator Addig Folders to the StarFlow Extesios Project17 Settig Access Rights Creatig ad Deployig APEs Usig Modal or Embedded APEs Uderstadig Property Editors Sample Chage Request APEs WorkFlow Status Property Sample Requiremet APEs Cofigurig JBuilder to Use StarTeam JavaBeas 21 Usig JBuilder Persoal Editio Editig StarTeam APEs Cofigurig StarTeam Projects to Use APEs Usig the propertyeditor.xml File Usig a Property Other Tha Usr_StarFlowStatus 25 Usig the Form Server Usig the Custom Toolbar Advaced Topics Usig the JavaBeas i guicompoets.jar Subclassig the ItemWrapper Class Kow Issues Custom Fields ot Recogized Thigs to Check Use of Process Items Chapter 4 Usig StarTeam Workflow Desiger 33 About StarTeam Workflow Desiger Plaig a Workflow Geeral Workflow Iformatio Workflow Cotrol Property Workflow Resposibility Property Multiple Workflows for the Same Item Type.. 35 Uderstadig Steps Step Names Time Limits Form Cotrol Who s Who Uderstadig Liks Startig Workflow Desiger Usig the Meu Bar The File Meu The Edit Meu The Layout Meu Displayig a Workflow i the Workspace Creatig a Workflow Uderstadig the 0. Etered Etry Step.. 42 Opeig a Workflow Stored i a Server Cofiguratio 42 Importig a Workflow File Viewig ad Editig Workflow Properties Creatig ad Likig Steps Creatig Steps Likig Two Steps Maually Creatig ad Likig Steps Automatically Coditioally Likig Steps Whe Editig a Item Editig a Lik Displayig Lik Coditios as Text Aligig Steps Resizig Steps Repositioig Liks Chagig the Default Lik Colors Chagig the Color of Idividual Liks Cotrollig the Cotets of the APE Form Cotrollig What Properties the Form Displays. 55 Cotrollig Dyamic Chages to Forms Limitig the Selectios i a Eumerated Field Based o the Value i aother Field Limitig the Users Listed i a User Selectio Field 58 Cotrollig the Behavior of a Item i a Step Listig the Participats Specifyig a Notificatio Message ad Iterval. 61 Uderstadig Notificatio List Operatio Limitig the Time Allowed to Complete the Task. 63 Specifyig a Iitial Value for a Empty Text Field 64 Moitorig a Item s Status Maagig Exceptios Extedig the Workflow s XML Addig ad Modifyig Custom Properties iii

4 Creatig a New Eumerated Property Addig a Value to a Eumerated Property Chagig the Name of the Step Checkig for Errors Savig ad Exportig Workflows Savig a Workflow Disablig a Workflow Exportig a Workflow Chagig Workflow Cotrol Property Values Automatically Chapter 5 Walkig Through a Workflow 73 Workflow Roadmap Settig Up Projects ad Files Settig Up Users ad Groups Uderstadig the Example Use Case Decidig Which Properties to Use Numberig the Example Steps Creatig a Custom Property to be the Workflow Cotrol Property Creatig the Custom APE Form Creatig a Workflow Creatig the Steps ad Liks Drawig the 1. New Step Likig the Two Steps Maually Editig the 0. Etered Step Editig the 1. New Step Creatig Next Steps for 1. New Drawig the Rest of the Steps Summary of Other Step Properties PM Evaluatio EM Processig a. R ad D Implemetatio b. Maiteace Fix Testig a. Not Implemeted b. Completed c. Reopeed Customer Letter Testig the Workflow Deployig the Workflow Chapter 6 Usig StarTeam Notificatio Aget 97 About StarTeam Notificatio Aget Gettig Ready to Use Notificatio Aget Settig Access Rights for Notificatio Aget Startig Notificatio Aget ad Notificatio Setup. 101 Idetifyig a Server Cofiguratio Settig Up Notificatio Aget to Moitor a Server Cofiguratio Ruig Notificatio Aget Ruig Notificatio Aget Maually Ruig Notificatio Aget as a Service Chagig the Http Server Port Number Message Sedig ad Exceptio Processig Files Created by Notificatio Aget Kow Issues for Notificatio Aget Revisio Assumptios Oly Notificatio Aget Should Chage Resposibility Field Out-of-Memory Errors from Java Appedix A StarTeam Extesios Samples 113 Sample APEs Sample Workflows Sample Utility Sample Tools Appedix B Notificatio Tags ad Messages117 Tag Sytax Overview Tag Referece {{lik-base}} Attributes Examples {{part-boudary}} Attributes Examples {{project-ame}} Attributes Examples {{property}} Attributes Examples {{property-style}} Attributes Examples {{property-table}} Attributes Examples {{request-timig}} Attributes Examples {{resposibility-assigmet}} Attributes Examples {{step-timig}} Attributes Examples {{type-ame}} Attributes Examples {{view-ame}} Attributes Examples {{url-view}} Attributes Examples {{url-folder}} Attributes Examples {{url-item}} Attributes Examples iv

5 Default Notificatio Messages Status Notificatio Message Subject Lie Body Resposibility Request Message Subject Lie for Default Message that All Messages Body of Default Message that Expects a Respose Body of Default Message that Expects a HTTP Server Respose Body of Default Message that Expects No Respose Cofirmatio Messages Subject Lie Body Request Exceptio Message Subject Lie Body Step Exceptio Message Subject Lie Body Idex 135 v

6 vi

7 Chapter Chapter 1Preface This maual cotais iformatio for StarTeam admiistrators ad project leaders. It provides istructios o settig up workflows ad Alterate Property Editors (APEs) for use with StarTeam Server ad its cliets. Importat The olie mauals are distributed i Adobe Acrobat (.pdf) format ad require the use of Adobe Reader i order to display them. The reader is available from the Adobe web site at: Documetatio The documetatio provided for StarTeam Workflow Extesios is listed below. You ca access the documets usig the Widows Start Meu (Start > Programs > Borlad StarTeam > StarTeam Workflow Extesios compoet> Documetatio). Table 1.1 Documet StarTeam Workflow Extesios Documetatio Set StarTeam Workflow Extesios User s Guide (this maual) StarTeam Release Notes (readme_e.html) StarTeam Istallatio Guide i the chapter titled Istallig StarTeam Workflow Extesios Cotais A overview of StarTeam Workflow Extesios ad its compoets How to use StarTeam Extesios, Workflow Desiger, ad Notificatio Aget Walkig through a workflow Workflow samples Notificatio tags ad messages System requiremets Kow Issues Limitatios Cotactig Micro Focus support Istallatio istructios for all compoets of StarTeam Workflow Extesios Preface 7

8 Micro Focus Support Documetatio Covetios The followig table lists the documetatio covetios that this guide uses. Covetio Choose File > Exit to... Fixed-Space Fot italics Object Idicated, Idetified, or Represeted A meu selectio that precedes a submeu selectio. The right agle bracket ( > ) separates the commads to be selected from subsequet meus. For example, the phrase Choose File > Exit meas to choose File from the meu bar ad the to choose Exit from the resultig drop-dow meu. Code, file ames, parameters, iformatio that you eed to type, ad messages from the system. Iformatio that you replace with the ames of your files, child folders, ad so forth. Italics also emphasize words ad idetify the ames of books. Bold UI cotrols ad iformatio that oe must use exactly as show. [ ] Optioal sytax. Mutually exclusive choices. Note Supplemetal iformatio. Tip Iformatio about alterative procedures or other helpful but oessetial iformatio. Importat Iformatio that is essetial to the completio of a task. Cautio Actios that might result i a loss of data, or procedures that oe must follow to avoid losig data. Micro Focus Support Micro Focus is committed to providig world-class services i the areas of cosultig ad techical support. We have more tha 30 years of experiece i supportig developers ad eterprise customers. Qualified techical-support egieers are prepared to hadle your support eeds o a case-by-case basis or i a ogoig partership. Micro Focus provides worldwide support, deliverig timely, reliable service to esure every customer's busiess success. For more iformatio about support services at Micro Focus, go to From the Web site, you ca also access may ewsgroups where users exchage iformatio, tips, ad techiques. This Micro Focus Commuity, available at commuity.microfocus.com, provides access to product specific iformatio, articles, code examples, ad ews. Whe cotactig support, be prepared to provide complete iformatio about your eviromet, the versio of the product you are usig, ad a detailed descriptio of the problem. For support o third-party tools or documetatio, cotact the vedor of the tool. 8 StarTeam Workflow Extesios User s Guide

9 Chapter 2Uderstadig StarTeam Chapter Workflow Extesios Features What Is Workflow? This chapter describes workflow, the StarTeam Workflow Extesios ad its compoets, ad gives you a road map for implemetig workflow i your orgaizatio. Workflow is a comprehesive term to explai a process by which members of a orgaizatio complete complex tasks. Whether your orgaizatio uses formalized or ad hoc workflows, there is a process or patter by which work is accomplished. Oe employee begis a task ad passes it alog to someoe else for review. That perso gives the project to yet a third perso to fialize ad the it goes back to perso umber two for fial review, ad so o. Workflow software ca automate workflow by providig automatic otificatio of resposibility, by presetig oly appropriate optios at each step i the process, ad by assurig that items are acted upo i a timely maer. The most difficult part of desigig a workflow process is decidig what you wat to cotrol ad how you wat to cotrol it. Oce you have determied your eeds, StarTeam Workflow Extesios alog with StarTeam give you all the tools you eed to create customized workflow models that meet the uique requiremets of your orgaizatio. I this guide, the term workflow is used to deote a.workflow.xml file that idicates step-by-step how items of a particular type will be processed. You ca create a workflow to cotrol ay item type withi StarTeam, such as files, chage requests, requiremets, tasks, or topics. Because teams commoly cotrol processes usig chage request statuses, the chage request maagemet system offers a simple, built-i workflow patter based o the Status property. It requires a chage request to proceed sequetially through a specific umber of ordered steps ad otifies team members of their resposibilities at each stage of the chage request Uderstadig StarTeam Workflow Extesios Features 9

10 About StarTeam Workflow Extesios life cycle. This workflow patter meets the eeds of may orgaizatios. (For complete iformatio o the built-i workflow capabilities of StarTeam, see the StarTeam Help.) For some orgaizatios, however, the built-i workflow model is too much. Their workflow models do ot require that may steps or that may choices. For other orgaizatios, the built-i workflow model is ot eough. They have requiremets for complex workflow patters that may iclude a time-depedet respose from the team member who is resposible for a specific step or may require redirectio of the workflow based o specific coditios. About StarTeam Workflow Extesios The products, tools, ad features i StarTeam Workflow Extesios that are used to set up ad maitai workflow processes are described i the followig sectios. StarTeam Extesios StarTeam Extesios icludes: Alterate Property Editors (APEs) ad the Java beas that make them easy to create. APEs, which are forms writte i a stadard programmig laguage such as Java, replace the stadard properties dialogs that come with each compoet of StarTeam. A workflow egie that reads the appropriate.workflow.xml file ad populates the APEs. A toolbar that ca be used with the Cross-Platform cliet to start applicatios that add ew features to StarTeam. Various other utilities ad libraries writte i Java. The default istallatio folder is C:\Program Files\Borlad\ StarFlow Extesios, but Micro Focus recommeds copyig these files to a differet folder for each server cofiguratio that rus o the same Server. For example, you might use C:\cofig_ame\StarFlow Extesios. I this way, you ca esure that each cofiguratio s StarFlow Extesios project has differet workig folders. Eve if you curretly ru oly oe server cofiguratio, it is wise to pla ahead. This also esures that, whe you upgrade or reistall for some other reaso, you are ulikely to overwrite ay StarTeam Extesios files that you are usig. See Usig StarTeam Extesios o page 13. StarTeam Workflow Desiger You must use Workflow Desiger to develop custom workflows. Workflow Desiger outputs.xml files that formalize the steps i a workflow, specifies who will be otified about each step ad about exceptios, ad so o. Each file is amed item_type.workflow.xml ad ca be used for a etire project or idividual views withi that project. The StarTeam Extesios workflow egie ad Notificatio Aget read from these files. Workflow Desiger ca be istalled separately o ay workstatio. See Usig StarTeam Workflow Desiger o page 33. StarTeam Notificatio Aget Notificatio Aget moitors server cofiguratios to determie who eeds to be otified about work to be performed ad about exceptios that occur i the workflow process. 10 StarTeam Workflow Extesios User s Guide

11 Workflow Roadmap It must be istalled ad set up separately. It is usually istalled o the computer that rus the Server, but it ca be istalled aywhere. Whe Notificatio Aget is ot o the same computer as the Server, the two computers clocks must be sychroized. Notificatio Aget s time caot be ahead of the Server s time. See Usig StarTeam Notificatio Aget o page 97. Related StarTeam Features StarTeam Repository Customizatio StarTeam allows you to create custom fields to meet the eeds of a workflow process. Oe eumerated property field cotrols the workflow process for the item type. The selected field usually requires some customizatio eve whe it is a existig applicatio property field. You ca customize the property fields i a server cofiguratio for a item type by usig StarTeam ad, to some degree, by usig Workflow Desiger. See the customizatio chapter i StarTeam Help or the Admiisterig ad Usig StarTeam PDF to lear more about creatig custom fields from StarTeam. For iformatio about customizig eumerated property fields usig Workflow Desiger, see Addig ad Modifyig Custom Properties o page 67. StarTeam SDK Workflow Roadmap The APEs ad the applicatios that ru from the StarTeam Workflow Extesios toolbar (i the Cross-Platform cliet) are StarTeam SDK applicatios. See the olie documetatio for APEs (that ca be istalled with StarTeam Workflow Extesios) ad the olie documetatio that comes with the SDK for more details. I geeral, the steps required to implemet a custom workflow i StarTeam are: 1 Istall StarTeam Server, StarTeam Workflow Extesios (StarTeam Extesios, Workflow Desiger, ad Notificatio Aget), ad the Cross-Platform cliet i appropriate places. See the StarTeam Istallatio Guide. 2 Create the ecessary projects ad folders. See Creatig ad Cofigurig the StarFlow Extesios Project o page Pla your ew workflow. As you begi to pla the ew workflow, you ll fid pecil ad paper to be oe of your most useful tools. Oce you have sketched the basic workflow model, flowchartig software such as Microsoft Visio may help you develop your workflow model. The flow diagram for the example workflow model explaied i this chapter was desiged usig flowchartig software. See Plaig a Workflow o page 34 for more iformatio. 4 Create a custom eumerated property ad values o which the workflow is based. (See Addig ad Modifyig Custom Properties o page 67 ad the StarTeam Help PDF for more iformatio.) 5 Create ay other custom properties to be used. 6 Pla your custom form. You eed to decide: What properties to use. Where to place them o the form. Which properties will be eeded, required, hidde, ad disabled for each step. Uderstadig StarTeam Workflow Extesios Features 11

12 Workflow Roadmap Which properties will chage dyamically as the user edits the chage request at each step. 7 Create a custom workflow usig Workflow Desiger to specify the steps ad actios of the workflow. See Usig StarTeam Workflow Desiger o page 33 for more iformatio. I additio to the graphical represetatio, each step has a properties dialog for optios that ca be set at each step. 8 Create a custom form that will display all the properties you have decided that you eed. See Creatig ad Deployig APEs o page 18 for more iformatio. 9 Test the workflow to esure that it performs as iteded. Store the workflow i the Test folder of the StarFlow Extesios project so that it ca be used i a applicatio project amed Test. (The project ame does ot have to be Test; this is just a example.) See Addig Folders to the StarFlow Extesios Project o page 17, Uderstadig Locator o page 16, ad Savig a Workflow o page 70. Use the Test butto i JBuilder to test the form with the workflow. This butto is o the sample forms ad ca be added to others. The Test butto is set up i the sample so that it is visible oly i JBuilder. Activate the workflow i the Test project by settig the appropriate APE settigs i that project. See Cofigurig StarTeam Projects to Use APEs o page 24. Setup ad start Notificatio Aget to moitor the Test project for the correct item type. Notificatio Aget otifies appropriate users about pedig work, item statuses, ad exceptios that occur i the process. See Gettig Ready to Use Notificatio Aget o page 98 ad Startig Notificatio Aget ad Notificatio Setup o page 101. Use Notificatio Aget s Ru Now butto to simulate movemet from step to step. Correct the workflow if ecessary. 10 Deploy the workflow. Store the workflow i the appropriate subfolders of the StarFlow Extesios project. This makes the workflow available for activatio. See Addig Folders to the StarFlow Extesios Project o page 17, Uderstadig Locator o page 16, ad Savig a Workflow o page 70. Activate the workflow for the appropriate projects by settig the appropriate APE settigs for those projects. See Cofigurig StarTeam Projects to Use APEs o page 24. Setup ad start Notificatio Aget to moitor the project, views, ad item types uder workflow cotrol. Notificatio Aget otifies appropriate users about pedig work, item statuses, ad exceptios that occur i the process. See Gettig Ready to Use Notificatio Aget o page 98 ad Startig Notificatio Aget ad Notificatio Setup o page 101. Whe users ope items uder workflow cotrol, StarTeam Extesios displays the APE form. The APE calls the workflow egie that examies the item ad, based o the iformatio cotaied i the workflow cofiguratio, displays the relevat workflow iformatio to the user. Users perform various workflow-related operatios o the items ad evets are stored i the audit log. The user completes a assiged step by selectig a appropriate ext step. 12 StarTeam Workflow Extesios User s Guide

13 Chapter 3Usig StarTeam Extesios Chapter This chapter explais: How to create ad cofigure a StarFlow Extesios project for each server cofiguratio. How to create ad deploy APEs. How to use various utilities icluded with StarTeam Extesios. About StarTeam Extesios Note: StarTeam Extesios, a key compoet of StarTeam Workflow Extesios, cosist of: Sample Alterate Property Editors (APEs) ad the JavaBeas that make them easy to create. APEs, which are forms writte i stadard programmig laguages such as Java, replace the stadard properties dialogs that come with each compoet of StarTeam. A workflow egie that applies user-defied workflow rules to the processig of items. The egie ca process ay item type. Various other utilities ad libraries writte i Java. A custom toolbar that ca be used with the Cross-Platform Cliet to start applicatios that add ew features to StarTeam. Custom toolbars ca be implemeted with the help of Micro Focus cosultats. Creatig ad Cofigurig the StarFlow Extesios Project The StarFlow Extesios project is used to store the customized workflows ad APEs, as well as the workflow egie ad other Java utilities ad libraries. Locator, a program used to distribute code ad XML updates to cliet workstatios for some cliets, will look for a project with the ame StarFlow Extesios ad use the latest revisio it fids for the required workflow elemets for the APE. The cliets Usig StarTeam Extesios 13

14 Creatig ad Cofigurig the StarFlow Extesios Project Importat provide users with the latest revisio of these files wheever the APE is requested. The followig procedure explais how to create this project. You eed oe for each server cofiguratio that will use APEs. Because of the StarFlow Extesios project: You, as the admiistrator, are guarateed that the user has coectivity to these files sice they reside o StarTeam Server that the user is curretly accessig. You ca revert to a previous revisio of a workflow or APE if ecessary. Do ot chage the ame of this project. The cliets look for this project whe doig aythig regardig APEs ad workflow. If this project is reamed or missig, StarTeam Extesios fuctioality will fail. All users eed read access to the files i the StarFlow Extesios project or they will ot be able to use the workflows ad APE files. The ability to chage the files i this project, however, should be limited to the few users who will be creatig or modifyig workflows, APEs or custom tools. Creatig StarFlow Extesios Projects Every server cofiguratio that uses APEs or tools must have a StarFlow Extesios project. To create the StarFlow Extesios project: 1 For each server cofiguratio, copy the StarFlow Extesios folder from the locatio where it was istalled (by default C:\Program Files\Borlad\StarFlow Extesios) to a uique locatio for each server cofiguratio, for example, C:\cofig_ame\ StarFlow Extesios. 2 Start the Server with the server cofiguratios that will be usig workflow. 3 Start the StarTeam Cross-Platform cliet. 4 Create a StarTeam project amed StarFlow Extesios i each server cofiguratio, usig the uique locatio for the StarFlow Extesios folder as its workig folder: a From My Computer or Widows Explorer, select the folders to be icluded i your project. b Drag the folders to a empty spot i the StarTeam Cross-Platform Cliet widow ad release the mouse butto. The New Project Wizard dialog appears. If you drag the folders to a ope view widow, the StarTeam Cross-Platform Cliet adds the folders to that project view as childre of the selected folder. This is ot your goal. You wat to create a ew project. c Do oe of the followig: Select a server o which you wat to store your project (from the server list), ad click Next to cotiue. Click Add Server to add access to aother server ad follow the steps i Addig Access to a Server Cofiguratio o page 15, ad the cotiue with this procedure. After you log o or if you are logged o already, the New Project Wizard: Project Name dialog appears. d Eter StarFlow Extesios i the Project Name text box. e f Eter a descriptio of the project ad click Next to cotiue. The New Project Wizard: Workig Folder dialog appears. Click Next. The New Project Wizard: Child Folders dialog appears. 14 StarTeam Workflow Extesios User s Guide

15 Creatig ad Cofigurig the StarFlow Extesios Project g Do ot exclude ay folders. h Click Fiish to ope the project. 5 Repeat step 4 for ay other server cofiguratios. You ca add more folders after a project has bee created. Addig Access to a Server Cofiguratio You ca access oe or more server cofiguratios from StarTeam Cross-Platform Cliet. Whe addig access to a server cofiguratio, you must provide the domai ame (DNS) or IP address ad appropriate edpoit for that server cofiguratio. After the server cofiguratio is added, users ca access whatever projects are available for that server cofiguratio. You ca add server cofiguratio access as part of creatig a project or as part of opeig a existig project. 1 From the New Project Wizard dialog, click Add Server. The StarTeam Server dialog appears. 2 Eter a descriptio i the Server Descriptio text box. This is a uique descriptive ame for the server. It is ot case-sesitive ad caot cotai colos (:). It ca be ay ame you wat. 3 Eter or browse for the address i the Server Address text box. The address is the computer ame or IP address. 4 Eter the correct TCP/IP edpoit i the Edpoit text box. The edpoit is the port umber associated with the protocol. 5 (Optioal) Select the Compress Trasferred Data check box to compress data trasferred betwee your workstatio ad the server. 6 (Optioal) Select a miimum ecryptio type check box to ecrypt data trasferred betwee your workstatio ad the server. Ecryptio protects files ad other project iformatio from beig read by uauthorized parties over usecured etwork lies (like the Iteret). The ecryptio types are ordered (top to bottom) based o speed ad security. Each ecryptio type is slower, but safer, tha the type that precedes it i the list. For more iformatio about ecryptig data, see the StarTeam Help. 7 Click OK to retur to the New Project Wizard dialog. Addig Files to the StarFlow Extesios Project After you create the StarFlow Extesios project, you must add the files that are Not i View. To add files: 1 I StarTeam Cross-Platform Cliet, ope the StarFlow Extesios project if it is ot already ope. 2 Select the root folder (amed StarFlow Extesios). 3 Select the File tab from the upper pae. 4 Click the All Descedats ico o the toolbar to display all the files that are located i the project s folders. 5 Select the <All Files By Status> or Files Not I View filter from the filter list box o the toolbar. If you selected the <All Files By Status> filter, click the butto i frot of the Not I View group to display the files. Usig StarTeam Extesios 15

16 Creatig ad Cofigurig the StarFlow Extesios Project Note The Not I View status is assiged to each file i a workig folder that is ot already added to the project (ad, therefore, ot yet uder versio cotrol). 1 Choose Select > Select All from the File or cotext meu to select all the files simultaeously. 2 Do oe of the followig: To quickly add all the files, click the Add Files ico o the toolbar to add files without usig the Add Files dialog. Choose Add Files from the File or cotext meu. The Add Files dialog appears. 1 Eter a geeric descriptio for all files i the File Descriptio text box. 2 From the Lock Status group box, make sure that the Ulocked optio butto is selected so that the files are ulocked. 3 Make sure that the Delete Workig Files check box is cleared so that you keep the workig files i the workig folder as well as i the repository. 4 Clear the Lik Ad Pi Process Item check box uless you have set up this project to use process items. If so, see the StarTeam Help for more details about selectig a process item while addig files. 5 (Optioal) If you are usig the Cross-Platform Cliet, click Advaced to set advaced features. See the StarTeam Help for more details. 6 Click OK. As you add ew files to StarTeam Cross-Platform Cliet, their statuses chage from Not I View to Curret. Depedig o the filter you select, the ames of the selected files may o loger o the upper pae. For example, if you use the filter Files Not I View, you ca see your files agai if you select the Files I View filter. Uderstadig Locator To use APEs, you eter Locator before the ame of the APE i the StarTeam Project Properties dialog. See Cofigurig StarTeam Projects to Use APEs o page 24 for more details. Some cliets use a tool called Locator; others, such as the Cross-Platform cliet, use this word as a sigal to check the StarFlow Extesios project. The cliets ope the StarFlow Extesios project, fid the correct files automatically, load them ito memory ad execute the mai etry poit for the APE.jar file. The resources required by the APE are specified i the.propertyeditor.xml file. With the StarTeam Visual Studio.NET itegratio, you ca user Locator ad display a cosole log file durig iitializatio. This cosole log provides details about the executio ad, if a exceptio occurs durig iitializatio, LocatorDebug displays the locatio of the exceptio ad its code. Whe you upgrade StarTeam Extesios to a ew release, you must check i ew files to the StarFlow Extesios project. 16 StarTeam Workflow Extesios User s Guide

17 Creatig ad Cofigurig the StarFlow Extesios Project Addig Folders to the StarFlow Extesios Project If you pla to use differet APEs ad/or differet workflows for differet projects ad/or views i a give server cofiguratio, you eed to place those workflows ad APE files i differet places withi the StarFlow Extesios project. If you store workflow ad APE files i the Projects folder, they ca be used by all projects o the server uless overridde by files at a lower level. If you create a myproject folder uder Projects, all workflow ad APE files stored withi this folder are used for the project amed myproject that reside i the same server cofiguratio as the StarFlow Extesios project. If you create a myview folder uder myproject, the workflow ad APE files stored withi it are used i the myview view for the specified project. The files that must be checked i to the Projects folder or a appropriate subfolder i the StarFlow Extesios project are ame.jar, ame.propertyeditor.xml ad item_type.workflow.xml. If projects ad views will use differet APEs ad/or workflows, the you eed to add folders to the StarFlow Extesios project. After you create the folders that you eed, you will add workflows ad APE files to those folders. Use the Projects folder for workflows ad APEs to be used as the default for all projects ad views. Use a folder with the ame of a specific project (such as StarDraw) to store workflows ad APEs to be used by the views i that project uless a folder ad files exists for a specific view. Use a folder with the ame of a specific view, such as Beta Release, to store workflows ad APEs to be used by that specific view. The cliet uses the folder hierarchy to search for resources. If for example, a view i the StarDraw sample cofiguratio is beig processed, the cliet checks for workflows ad APEs i StarFlow Extesios\Projects\ StarDraw\Release 1.0 Maiteace. If it does ot fid all of the files it eeds, it looks i the StarFlow Extesios\Projects\ StarDraw folder ad the the StarFlow Extesios\Projects folder. If it still has ot located the files it eeds, a error message is displayed. To add a folder to a view usig StarTeam Cross-Platform Cliet: 1 Choose New from the Folder Tree or cotext meu. The New Folder Wizard dialog appears. 2 Select a folder from the folder tree to be the paret of the ew folder. 3 Click Next. The New Folder Wizard: Folder Name dialog appears. 4 Eter a ame for the child folder i the Folder Name text box. Use a maximum of 254 characters. 5 Leave the Workig Folder text box blak. The applicatio creates the workig folder usig the ame of the ew folder ad the path to its paret s workig folder. 6 I the Folder Descriptio text box, eter a descriptio of up to 254 characters for the ew folder. 7 Click Next. The New Folder Wizard: Child Folders dialog displays the ew folder i the New Folder s Child Folders box. If the workig folder has child folders, StarTeam Cross-Platform Cliet adds a applicatio folder for each of them. 8 Do oe of the followig: To exclude a child folder from your project, select the folder ad click Exclude. Usig StarTeam Extesios 17

18 Creatig ad Deployig APEs To exclude all child folders, click Exclude All. To redisplay folders you have excluded, click Reset Folders. 9 Click Next. The New Folder Wizard: StarTeam Folders dialog displays the view s folder tree with the ew child folder. 10 Click Fiish. Settig Access Rights This sectio explais the miimum access rights to the StarFlow Extesios project required for users of StarTeam alterate property editors. It is best to set the access rights o the StarFlow Extesios project at the project level. Usig the Project Access Rights dialog, esure that the All Users group has the followig rights: O the Project ode, users eed to be grated the See project ad its properties right. O the View ode, users eed to be grated the See view ad its properties right. O the Child Folders ode, users eed to be grated the See folder ad its properties right. O the File ode, users eed to be grated the See file ad its properties right, the See history right, ad the Check out files right. O the remaiig odes, (Chage Request, Requiremet, Task, ad Topic), the Admiistrator should dey access to casual users. Creatig ad Deployig APEs Alterate property editors (APEs) are custom forms created specifically for your compay i support of a corporate process. Workflow processes are created for use with the forms. They ca be customized easily because they ca be implemeted i Java. Sample property editors for all applicatio compoets are icluded. However, a APE is ot just a form. It is a StarTeam SDK applicatio that is executed istead of the default properties dialog for the item type. The files you must check i to the StarFlow Extesios project or a APE are ame.propertyeditor.xml ad a ame.jar file. StarTeam Extesios provide the workflow egie, form customizatio capability ad distributio architecture. You are ot required to use this software for APEs because ay applicatio ca be executed as a APE, allowig maximum flexibility i tailorig the StarTeam Cross-Platform Cliet to work i a maer required by your process eeds. You must defie a APE for ay project that will use workflows. You ca use APEs: Without workflow. For example, if you do ot like the stadard properties dialog for a item type, you ca replace it with a APE of your ow desig. I this way, you ca hide properties o the stadard properties dialog from view ad put all custom properties i easily accessible locatios o the form, istead of o the Custom tab. To use a APE without workflow, you select a APE for the item type i the project ad check i a disabled workflow. See Disablig a Workflow o page 71. With workflow but without otificatio. For example, if the workflow is well uderstood ad everyoe kows exactly who will be resposible for the ext step, otificatio is uecessary. Everyoe ca sort items based o resposibility ad creatio or etry time, ad work o the items for which they are resposible i the order i which they etered the system. 18 StarTeam Workflow Extesios User s Guide

19 Creatig ad Deployig APEs To use a APE with workflow but without otificatio, you select a APE for the item type i the project ad check i a workflow that has o otificatio lists. With workflow ad otificatio. For example, if you use otificatio, you ca ask several people, i tur, to take resposibility for a item at a give step. You ca also otify supervisors if o oe accepts resposibility, or if a step is takig loger tha expected. To use a APE with workflow ad otificatio, you select a APE for the item type i the project ad check i a workflow that has otificatio lists. See Cotrollig the Behavior of a Item i a Step o page 58. While a APE is for a specific compoet, you do ot have to use the same APE for all the projects or views i a server cofiguratio. You ca create differet forms perproject or per-view. StarTeam Extesios simplifies the process of creatig custom forms i JBuilder or aother Java developmet eviromet by providig a variety of JavaBeas. The StarTeam JavaBeas allow you to customize the APEs usig a graphical form desiger. I additio, Java code ca be added to the form to access the Server with the StarTeam SDK. Such code ca provide additios to the form ad eforce workflow side-effects as required. Usig Modal or Embedded APEs A sigle APE form ca be used i a cotext dialog (as i pre-5.3 releases) ad i a embedded cotext such as i the StarTeam JBuilder itegratio, where the form is implated i a documet widow, rather tha i a modal dialog. Prior to 5.3, APEs cosisted of a subclass of com.starbase.starteam.starflow.abstractlaucher, which lauched the form ad placed it i a dialog, ad a subclass of javax.swig.jpael which implemeted the form UI. APEs ow subclass com.starbase.starteam.starflow.basiclaucher istead of AbstractLaucher. BasicLaucher serves a similar fuctio but works with embedded forms as well. A ew subclass of AbstractItemEditor was added to 5.3 also. Whereas the BasicLaucher subclass is the etry poit for lauchig the editor i a dialog, this subclass becomes the etry poit for lauchig editors embedded i a widow. The form still subclasses JPael (typically), but the Navigator compoet, which supplies the Next, Previous, OK, Cacel, Apply, ad Reset buttos, is o loger added directly to the form. Istead, BasicLaucher adds the form to a dialog that already cotais the Navigator compoet, while the AbstractItemEditor subclass merely istatiates the form with o Navigator compoet. No Navigator compoet is used i the embedded cotext because StarTeam Cross-Platform Cliet, rather tha the form, has the resposibility of hadlig those fuctios. The followig optioal elemet has bee added to the.propertyeditor.xml for a APE: <itemeditor class="com.starbase.starteam.chagerequest.chagerequesteditor"> <jar ame="chagerequest.jar"/> <jar ame="guicompoets.jar"/> <jar ame="starflow-extesios.jar"/> </itemeditor> The jar elemets serve the same fuctio as i the javaclass elemet, ad the class attribute of the itemeditor elemet serves a similar fuctio as i the javaclass elemet. It idetifies the ame of the etry poit for the APE as a embedded form (it must idetify a subclass of AbstractItemEditor). Usig StarTeam Extesios 19

20 Creatig ad Deployig APEs Uderstadig Property Editors I additio to supportig files as part of its Software Cofiguratio Maagemet (SCM) features, StarTeam Cross-Platform Cliet also supports chage requests, requiremets, tasks, ad topics. Collectively these are kow as item types, ad the part of the applicatio that supports a particular item type is kow as a compoet. Each item type is surfaced i the StarTeam Cross-Platform Cliet as a separate tab with the compoet ame. To edit a particular item s properties, the user selects the item ad the chooses item_type > Properties from the meu bar. The user ca also double-click the item uless the item is a file. (Double-clickig a file displays its cotets rather tha its properties; select a file ad press Alt+Eter to display the property editor.) By default, the applicatio displays the stadard property dialog. May customers do ot use all of the stadard properties for a item type, ad ted to create custom properties for iformatio importat to their orgaizatio s iteral processes. If a customer creates custom properties, they appear as fields o the Custom tab of the stadard property dialog. May customers would prefer to locate fields for the properties that are most importat to them o the first tab ad hide the properties that are irrelevat to their process by ot havig fields for these properties o the form. The applicatio s alterate property editors (APEs) make this possible. With APEs, the properties ca be cotrolled by a workflow that fits the customer s eeds ad allows differet properties to be displayed, required, or eabled o the form depedig o the step i the workflow that is beig performed. StarTeam Extesios icludes sample forms that you ca use immediately or customize usig your favorite Java compiler ad form desig product. These forms make use of custom JavaBeas that itegrate with the StarTeam SDK ad the StarTeam Extesios workflow egie. These JavaBeas allow you to drag a ew field oto the form ad assig a applicatio field ame to the JavaBea. All of the access to the field through the StarTeam SDK ad the workflow behavior is the hadled by the JavaBea. There are several sample forms icluded i the StarTeam Extesios istallatio. These are located i the Samples folder of the StarTeam Extesios istallatio folder (by default, C:\Program Files\Borlad\ StarFlow Extesios\Samples). See Appedix A, StarTeam Extesios Samples o page 113 for more iformatio. Uder this folder is a copy of the StarTeam Rutime.jar file for use by the sample applicatio s JBuilder projects. This is required so that StarTeam Extesios ca iclude a precofigured project ad make it easier for you to get started with customizig the various forms. Documetatio o the StarTeam Extesios API is foud i the Program Files\Borlad\ StarFlow Extesios\Documetatio folder. Sample Chage Request APEs A sample chage request APE is foud i the Samples\ChageRequest folder uder the StarTeam Extesios istallatio folder. I the JBuilder project amed ChageRequest.jpx, required fields (i this case, Priority, Syopsis, ad Resposibility) are idicated i red. The tab ame (i this case Syopsis) is i red to idicate that the tab has required property fields o it. The chage request caot be saved util a valid value is supplied for all required fields. The source code for the sample form is provided so you ca use this form as a startig poit for creatig your ow custom form. Aother such sample chage request APE is foud i the Samples\LikTypeChageRequest folder uder the StarTeam Extesios istallatio folder. This sample is foud i the JBuilder project amed LikTypeChageRequest.jpx. 20 StarTeam Workflow Extesios User s Guide

21 Creatig ad Deployig APEs I additio to the capabilities of the previous chage request APE, this APE ca display a corporate logo ad access the items to which the chage request is liked. Some properties are displayed at all times. Clickig tabs chages oly the lower part of the form. Whe usig StarTeam Extesios for workflow maagemet, the existig Status field foud i the chage request is ot used as the workflow cotrol property. The reasos for this are: Existig chage requests ad the built-i property editor dialog rely o specific status values beig used for a chage request. Chagig this status value causes specific side effects. To isolate these side effects from the implemetatio of a custom workflow, a separate custom property is used. I geeral, you should try to keep the Status property i the state that most closely matches the correspodig Workflow Status. You should also chage the public filters to iclude the Workflow Status field istead of the default Status field. WorkFlow Status Property The ChageRequest.Workflow.xml that ships with the product expects that you have a custom property field ame WorkFlow Status with the iteral ame Usr_StarFlowStatus. Sample Requiremet APEs StarTeam Extesios icludes sample requiremets APEs. These APEs display the selected requiremet. If this requiremet was origially exported from CaliberRM, it will be displayed i a read-oly mode. However, clickig the CaliberRM butto or the Lauch CaliberRM butto starts the CaliberRMViewer, ad if the user has a licese to CaliberRM, allows the user to start CaliberRM ad, usig CaliberRM, edit the requiremet. The APE ad laucher for the viewer are foud i the JBuilder project amed Requiremet.jpx. Cofigurig JBuilder to Use StarTeam JavaBeas Note While you ca use ay full featured Java developmet eviromet with StarTeam Extesios, the samples icluded were created with Borlad JBuilder Eterprise Editio. These samples may also be maitaied with later releases of JBuilder. To use the StarTeam JavaBeas i JBuilder you must cofigure your libraries ad palette. To use the JavaBeas: 1 Cofigure the JBuilder libraries to iclude the starflow-extesios.jar, starteamxx.jar ad guicompoets.jar files. a Choose Tools > Cofigure Libraries from JBuilder s meu bar. b From the resultig Cofigure Libraries dialog, select the User Home folder. c Click New to create a StarTeam Extesios folder (uder the User Home folder) that cotais the starflow-extesios.jar ad guicompoets.jar files. I earlier editios of this maual, users created a StarFlow folder uder the User Home folder. You might already have this set up, but you eed to chage it. d I the resultig New Library Wizard dialog, eter StarTeam Extesios i the Name text box. e Click Add. Usig StarTeam Extesios 21

22 Creatig ad Deployig APEs Note f From the resultig Select Oe or More Directories dialog, select the starflowextesios.jar ad guicompoets.jar files from the StarFlowExtesios\Projects folder at C:\cofig_ame\StarFlow Extesios\ Projects). g Click OK to retur to the New Library Wizard dialog. h Click OK to retur to the Cofigure Libraries dialog. i j k Click Add agai. From the resultig Cofigure Libraries dialog, select the User Home folder agai. Click New to create a StarTeam folder (uder the User Home folder) that cotais the starteamxx.jar file. I earlier editios of this maual, users created a StarGate folder uder the User Home folder. You may already have this set up, but you eed to chage it. l I the resultig New Library Wizard dialog, eter StarTeam i the Name text box. m Click Add. From the resultig Select Oe or More Directories dialog, select the starteamxx.jar file (usually located at C:\Program Files\Borlad\ StarTeam SDK x.x\lib\starteamxx.jar). o Click OK to retur to the New Library Wizard dialog where this file ow appears i the Library Paths list. p Click OK to retur to the Cofigure Libraries dialog. q Click New to create a StarTeam folder (uder the User Home folder) that cotais the starteam-gui.jar file. r s t I the resultig New Library Wizard dialog, eter GUI SDK i the Name text box. Click Add. From the resultig Select Oe or More Directories dialog, select the starteamgui.jar file from the StarFlowExtesios\Projects folder (for example, at C:\ cofig_ame\starflow Extesios\ Projects). u Click OK to retur to the New Library Wizard dialog where this file ow appears i the Library Paths list. v Click OK to retur to the Cofigure Libraries dialog. User Home should ow have subfolders amed StarTeam Extesios, StarTeam, ad GUI SDK. 2 Add a ew palette by choosig Tools > Cofigure Palette from JBuilder s meu bar. a I the resultig Palette Properties dialog, click Add. b If the resultig Add Page dialog, eter StarTeam Extesios. c Click OK to retur to the Palette Properties dialog. d Select StarTeam Extesios. e f Click Move Up util StarTeam Extesios is at the top of the list i this tab. Click the Add Compoets tab. g Click Select Library. h From the resultig Select a Differet Library dialog, select the StarTeam Extesios library. i j Click OK to retur to the Palette Properties dialog. From the Palette Page list, select the StarTeam Extesio palette page. 22 StarTeam Workflow Extesios User s Guide

23 Creatig ad Deployig APEs k l Click Add From Selected Library at the bottom of the dialog. As the JavaBeas are added, they are listed i the Results dialog. Click OK, ad you are ready to use the StarTeam JavaBea compoets. m Click OK agai to retur to the mai widow. 3 I JBuilder, ope a sample project to be modified for use with StarTeam. 4 Double-click the.java file to be modified. 5 Click the Desig tab. The StarTeam Extesios JavaBeas should appear o the StarTeam Extesios page of the toolbar. Usig JBuilder Persoal Editio JBuilder Persoal does ot iclude IDE-based support for buildig Jar files. Buildig the Jar file is a ecessary step for use as a APE. For your coveiece, we have icluded MakeitemtypeJar.bat i the base of each respective sample project. After you have compiled the project i JBuilder, you ca ru the batch file to create the Jar file, which will be placed i the Projects folder by default, where it will be ready for check i to the StarFlow Extesios project i the Projects folder. You may eed to edit the batch file if JBuilder is ot istalled i the C:\jbuilderx folder. Note Editig StarTeam APEs You ca add ew fields to or edit the existig fields of a StarTeam Extesios form usig your favorite Java developmet tool. These forms are called alterate property editors (APEs). Whe you use a StarTeam JavaBea compoet, you will eed to select the correct compoet that matches the type of field you are usig, ad after the compoet is placed o the form, you will eed to set the propertyname attribute. The propertyname attribute should have the applicatio field ame that you wish to display i this compoet i the form. I desig mode the label o the field will be the value foud i the propertyname attribute of the JavaBea, but whe executed the label will be the StarTeam Display Name for the field. Where applicable, the JavaBeas are composed of a editor compoet ad a text label showig the ame of the property beig edited. By default, the text show by the label is the display ame of the StarTeam property associated with the JavaBea (set via the "propertyname" JavaBea property). Whe you edit the JavaBea i a visual form desiger such as JBuilder, the label's text will be the iteral idetifier for the property, that is, the value of the propertyname property of the JavaBea. Whe the form is ru, that text is replaced with the display ame of the property (defied by StarTeam metadata about the property). For example, the StarTeam Status field has the same display ame ad iteral idetifier. However, the custom status field used i the chage request samples has the display ame Workflow Status ad the iteral idetifier Usr_StarFlowStatus. I the latter case, you see Usr_StarFlowStatus i JBuilder ad Workflow Status whe the form rus. You ca cotrol the behavior of this label by doig ay of the followig: Supplyig alterate text for the label To do this, set the labeltextoverride property of the JavaBea. The text you supply will be see i JBuilder ad whe the form rus. Turig the label off so that it is ot see at ay time. To do this, set the showlabel property to false. To tur the label back o later, you would set the showlabel property to true. Usig StarTeam Extesios 23

24 Creatig ad Deployig APEs Cofigurig StarTeam Projects to Use APEs Importat By default, every project uses the stadard property dialogs. Whe a APE is ready for use, you must chage the project properties so that all the views i a project will use the APEs. Oce set, every view i the project must use a APE istead of the stadard dialog. However, each view ca use a differet APE that you have checked ito the appropriate view-specific subfolder i the Projects folder of StarFlow Extesios project. See Addig Folders to the StarFlow Extesios Project o page 17 ad Uderstadig Locator o page 16. Take care whe settig the APE for a project that is i productio because the ew settig takes effect immediately. It is importat to test ay chages that are made to a APE prior to makig this editor available to a wide audiece. To use a APE with a StarTeam item type: 1 I the applicatio, choose Project > Properties from the meu bar. The Project Properties dialog appears. 2 Select the Editors tab. 3 Select the Use Alterate Property Editor For <item> check box. 4 Eter or browse for the correct APE. You eter the word Locator followed by the ame of the APE. Depedig o the cliet, Locator is either a program or a sigal to distribute resources, such as.jar ad.xml files to cliet workstatios. If specified here, wheever the applicatio requests the APE, the cliet looks for the StarFlow Extesios project maaged by the server cofiguratio. If that project exists ad cotais a.propertyeditor.xml file with the specified ame i either the Projects folder or a appropriate child folder, the cliet copies the tip revisio of that resources refereced i that file to the cliet workstatio (if they are ot already there). The the user edits items usig the APE istead of the applicatio s stadard properties dialog for the specified type of item. Usig the propertyeditor.xml File The cliet obtais the details about the resources to load ad ru from the.propertyeditor.xml file. For example, if you use the APE Locator ChageRequest, the file ChageRequest.propertyeditor.xml is read by the cliet to determie which resources are deployed for the APE. While the samples icluded i the StarFlow Extesios are writte i Java, the Locator was desiged to also distribute applicatios writte i other laguages. The format of the.propertyeditor.xml file is geeric i this sese, ad icludes parameters for specifyig the target operatig system ad multiple resources that should be located ad checked out to the cliet workstatio for the APE. Below is a copy of the sample ChageRequest.propertyeditor.xml file icluded with the StarTeam Extesios: <?xml versio="1.0" ecodig="utf-8"?> <propertyeditor ame="chage Request Editor" versio="1.1"> <itemeditor class="com.starbase.starteam.chagerequest. ChageRequestEditor"> <jar ame="chagerequest.jar"/> <jar ame="guicompoets.jar"/> <jar ame="starflow-extesios.jar"/> 24 StarTeam Workflow Extesios User s Guide

25 Creatig ad Deployig APEs </itemeditor> <javaclass ame="com.starbase.starteam.chagerequest. ChageRequestLaucher"> <jar ame="chagerequest.jar"/> <jar ame="guicompoets.jar"/> <jar ame="starflow-extesios.jar"/> </javaclass> </propertyeditor> The ame of the.propertyeditor.xml file is passed to the cliet i the Project Properties dialog, for example, Locator ChageRequest. The cliet fids this.propertyeditor.xml file ad determies which resources are eeded for this APE. The <javaclass> elemet idetifies the Java class that acts as the etry poit for the APE. The ame attribute ames the class ad the <jar> subelemets ame the jar files that implemet the editor. The amed jar files are located i the StarFlow Extesios project i the same maer as the.propertyeditor.xml itself, allowig for overridig i a similar maer. These jars are checked out of StarTeam ad loaded ito the Java Virtual Machie before the mai method of the amed etry poit class is called. The <exteral> elemet cotais the default commad ad ay operatig specific commads that may be eeded. The <commad> elemet icludes a platform optio that ames the operatig system ad a call optio to idicate the executable to call o the target platform. Withi the <commad> elemet are the parameters to pass to the executable specified o the call optio. The format ${resource:<file>} is used to tell the cliet that the <file> is to be located by usig the stadard logic for locatig a resource i the StarFlow Extesios project, that is by searchig for a folder with the view ame ad the the project ame ad, if ot foud, fially usig the default files foud i the Projects folder. Usig a Property Other Tha Usr_StarFlowStatus Usr_StarFlowStatus (with Workflow Status as its usual display ame) is the property the workflow egie expects to fid as the workflow cotrol property for ay item. This is easy to chage. To use a property other tha Usr_StarFlowStatus: 1 I JBuilder, ope the APEproject.jpx file for the project (for example, LikTypeChageRequest.jpx or ChageRequest.jpx). This may be i oe of the Samples folders or perhaps you have the source code for this java project i the workig folder for a appropriate StarTeam folder i the StarTeam project amed StarFlow Extesios. 2 Double-click the item_typelaucher.java file to ope it for editig. 3 After the file opes, search for Usr_StarFlowStatus: public Strig getworkflowstatuspropertyname() { retur "Usr_StarFlowStatus"; 4 Replace Usr_StarFlowStatus with the iteral ame for the workflow cotrol property to be used with this item_type. For example, you might be usig a existig field such as Status property field for Topics or a Usr_MyStatus for ay item type. The oly field that should ot be used is the Status property field for chage requests as the applicatio s built-i workflow ivolves the use of that property field. 5 Save the file. 6 Recompile the.jar (for example, LikTypeChageRequest.jar or ChageRequest.jar). Usig StarTeam Extesios 25

26 Usig the Form Server Usig the Form Server 7 Check the.jar file ito the applicatio s StarFlow Extesios project. Use a appropriate folder. For example, if this APE will be used by a specific project view, you might check it ito the StarFlow Extesios\Projects\Big Project\ Big Project\Web Stuff folder. I this example, there is a project amed Big Project with a root view ame Big Project ad a child view amed Web Stuff. The StarTeam form server is a backgroud applicatio that improves the performace ad resposiveess of the APE feature i the StarTeam Visual Studio.NET itegratio. Oce loaded, it keeps i memory the resources that are expesive to reload, so that subsequet access to those resources is faster. Uder ormal operatio, the user eed ot do aythig to receive the beefit of the form server. It automatically starts the first time the user opes a APE. Note that the first time a APE is lauched (if the form server is ot already ruig), it may take a exteded period of time to iitialize ad display the form. A ico represetig the form server appears i the user s system tray idicatig that the server is ruig. The form server may be shut dow by double-clickig the ico ad respodig Yes to the cofirmatio dialog. However, the form server does ot stop whe you exit the applicatio. To stop the form server: 1 Double-click the form server ico i the system tray. A message box asks whether or ot you wat to shut dow the form server. 2 Click Yes. Usig the Custom Toolbar The custom toolbar ca be used with the Cross-Platform Cliet. Buttos o the toolbar start tool applicatios that are usually writte for your orgaizatio by Micro Focus cosultats. The tools are ofte time-savig applicatios that access the StarTeam Server ad perform multi-step operatios that you do routiely. The toolbar buttos ca be displayed at the view level or per-compoet. For example, you might see buttos while usig the chage request compoet but ot whe usig the file compoet. Whe you see a compoet-level butto, the tool it represets may also appear o the item meu for that compoet. For example, if a tool amed MyTool appears o the custom toolbar whe you use the chage request compoet, the Chage Request meu usually has a submeu amed Tools with MyTool as oe of its meu commads. Some tools have represetatios that are oly appropriate i the toolbar ad ot the meu. Which users ca see these toolbar buttos is cotrolled by the access rights o the.tool.xml files (for example, mytool.tool.xml) that are checked i to applicatio folders located i the server cofiguratio s StarFlow Extesios project. The folders use the same folder scheme as the workflow ad APE form files. If chages are made to the tools or the cotets of the toolbar, you are uaware of those chages util you reope the project view i which they are used. If a error occurs as a tool is placed o the toolbar, a error-message toolbar butto appears o the toolbar. Clickig the butto displays the errors ecoutered by the toolbar o startup. 26 StarTeam Workflow Extesios User s Guide

27 Advaced Topics Advaced Topics The followig sectios explai: All the JavaBeas i the guicompoets.jar file Passig parameters to a APE Usig the.propertyeditor.xml file How to subclass the ItemWrapper class to support more complex workflow eeds Usig the JavaBeas i guicompoets.jar The JavaBeas icluded i the guicompoets.jar are: AddAdLikButto This butto lauches a property editor that adds a ew item to the repository ad automatically liks the ew item to the item curretly displayed by the form i which this butto resides. Add this butto withi the scope of a PropogatigPael ad set the itemtype ad locatorkey properties to the ame of the item type ad the ame of the form to use, respectively. Optioally, set the addtosamefolder property (which defaults to true) ad/or the createpiedlik property (which defaults to false). AttachmetsEditor This compoet displays, adds, ad removes attachmets to a item. Add this compoet withi the scope of a PropogatigPael. Nothig else eeds to be doe to make this compoet fuctio. The propertyname is fixed, so settig this property has o effect. BooleaEditor This compoet edits properties of type Property.Types.INT32 or Property.Types.ENUMERATED as boolea values. Add this compoet withi the scope of a PropogatigPael ad set the propertyname property to the ame of the property to be edited. Optioally, set the truevalue ad falsevalue properties to the iteger values that represet true ad false. I the case of Property.Types.INT32 properties, this is a pair of arbitrarily desigated values. I the case of Property.Types.ENUMERATED properties, this pair correspods to the code values of the eumerated values that represet true ad false. ComboEditor This compoet edits properties of type Property.Types.ENUMERATED. Add this compoet withi the scope of a PropogatigPael ad set the propertyname property to the ame of the property to be edited. Optioally, set the sortorderig property to make the list of values be sorted i ASCENDING, DESCENDING, or NONE sort order. DateEditor This compoet edits properties of type Property.Types.TIME. Add this compoet withi the scope of a PropogatigPael ad set the propertyname property to the ame of the property to be edited. Optioally, set the displaytimeportio property (which defaults to true) to display the date oly or date ad time. Optioally set the allownull property (which defaults to true) to allow or disallow blak values. ItemDisplayListeer Usig StarTeam Extesios 27

28 Advaced Topics This is ot a JavaBea; it is a iterface that some of the JavaBeas support. It is the listeer iterface for receivig otificatios of a ew item to be displayed ad to refresh the display of the curretly displayed item. ItemsPaeCompoet Displays requiremets, tasks, or topics i a folder i tree form. Whe a item is displayed i this compoet, the tree will be expaded so that the item is visible ad the item ca be selected. Most of the ormal applicatio item-level fuctioality is available via the cotext meu for the selected Item. The ItemsPaeCompoet depeds o a StarTeam library that requires a StarTeam Server 5.3 or higher. O older releases, the compoet displays a placeholder istead of the compoet. The placeholder idicates that the compoet caot fid a 5.3 or higher licese. This compoet ca be used i oe of three ways: If the actasitemdisplaylisteer property is set to false (default), the you may set the likscompoet property to create a relatioship such that whe a Item selected i the LiksCompoet, it will be displayed i this compoet. If the actasitemdisplaylisteer property is set to false (default), the you may leave the likscompoet property empty ad call the showitem(item) or setitem(itemwrapper) methods directly. If the actasitemdisplaylisteer property is set to true, the the compoet will display the ItemWrapper set by the setitem method of the ItemDisplayListeer iterface. Add this compoet withi the scope of a PropogatigPael, ad it will automatically display the Item i the curret scope accordig to the PropogatigPael. Nothig else must be doe to make this compoet fuctio. ItemPropertyEditor This is ot a JavaBea; it is the superclass of most the JavaBeas. This abstract base class is for property editor compoets. Subclasses of this class allow the display or editig of idividual item properties. This class hooks listeers to evet sources, such as PropogatigPael, that cotrol which item to display. ItemPropertyLabel This compoet displays a property s display ame, optioally allowig a arbitrary ame to override the default display ame. Add this compoet withi the scope of a PropogatigPael ad set the propertyname property to the ame of the property. Optioally, set the text property to override the display ame of the property. Optioally, set the prefix ad suffix properties. LiksCompoet This compoet displays items liked to a item. Add this compoet withi the scope of a PropogatigPael. Nothig else must be doe to make this compoet fuctio. The propertyname is fixed, so settig this property has o effect. Optioally, set the typefilter property to the ame of a item type to limit the displayed items to items of that type. Navigator This compoet cotrols the avigatio through a list of ItemWrapper. Add a ActioListeer to liste for butto evets (ok, cacel, apply, ad reset), or add a PropertyChageListeer to liste for curretitem evets idicatig that the curretly selected item has chaged, ad items evets idicatig that the uderlyig list of ItemWrappers has chaged. Optioally, set the refreshitems property to 28 StarTeam Workflow Extesios User s Guide

29 Advaced Topics idicate whether or ot the item data should be fetched from the server every time the item selectio chages. The refreshitems property defaults to true. NumberEditor This compoet edits properties of type Property.Types.INT32 or Property.Types.FLOAT64. Add this compoet withi the scope of a PropogatigPael ad set the propertyname property to the ame of the property to be edited. The compoet automatically detects the differece betwee iteger ad floatig poit umbers ad behaves appropriately. OpeLikedItemButto This butto lauches a property editor to display a item selected i a LiksCompoet. Add this butto to the form ad set the LiksCompoet property with a referece to the LiksCompoet to fid the selected lik i. Clickig the butto performs the same actio o the selected item as double-clickig the item i the LiksCompoet. PropogatigPael This compoet recursively propagates the curretitem property chage evets to all the PropogatigPael, ItemPropertyEditor, ad ItemDisplayListeer objects cotaied i this pael. It provides a coveiet way to hook all property editors to the Navigator so that they ca liste for ew curret item selectios. As a side effect, this compoet sets tabbed pae tab titles red if the tab cotais ay required properties. Micro Focus recommeds usig a istace of this class at the top level somewhere ad addig it as a PropertyChageListeer to the Navigator. RevisioCommetEditor This compoet displays ad edits the revisio commet for a item. Add this compoet withi the scope of a PropogatigPael. Nothig else eeds to be doe to make this compoet fuctio. The propertyname is fixed, so settig this property has o effect. StaticTextEditor This compoet displays ay type of property as read-oly static text. Add this compoet withi the scope of a PropogatigPael ad set the propertyname property to the ame of the property to be displayed. TaskDepedeciesCompoet This compoet displays the predecessor ad successor relatioships for a task. Add this compoet withi the scope of a PropogatigPael. Nothig else eeds to be doe to make this compoet fuctio. The propertyname is fixed, so settig this property has o effect. TaskWorkEditor This compoet displays, adds, edits, ad removes Work Records for a task. Add this compoet withi the scope of a PropogatigPael. Nothig else eeds to be doe to make this compoet fuctio. The propertyname is fixed, so settig this property has o effect. TestButto This butto populates a form with live data for testig coveiece. This butto is ot iteded to be visible o productio forms, but may be added to the form so that, durig developmet, live data may be used i the form without requirig that the form be lauched from the applicatio. The butto should be hidde or removed Usig StarTeam Extesios 29

30 Advaced Topics whe used i a productio eviromet. The samples provided with StarTeam Extesios use this butto i JBuilder ad hide i whe APEs are displayed to users. Add this butto to your form ad hook the Navigator compoet to liste for items PropertyChageEvets from this butto. The evet cotais as its ewvalue a ItemWrapper[ ] cotaiig the data retrieved from the server. Optioally, set the URL property to idetify the source of the data, the type property to idetify the Item type to operate o, the locatorkey to idetify the workflow to be used (locatorkey + ".Workflow.xml"), ad the workflowstatuspropertyname property to idetify the item property that cotais the workflow status property. TextAreaEditor This compoet edits properties of type Property.Types.TEXT i a multilie editor. Add this compoet withi the scope of a PropogatigPael ad set the propertyname property to the ame of the property to be edited. TextFieldEditor This compoet edits properties of type Property.Types.TEXT i a sigle lie editor. Add this compoet withi the scope of a PropogatigPael ad set the propertyname property to the ame of the property to be edited. UserListEditor This compoet edits property groups that cotai lists of User IDs. Add this compoet withi the scope of a PropogatigPael ad set the propertyname property to the ame of the primary property of the property group that cotais the list of users, the coutpropertyname property to the ame of the property group s property that idetifies the umber of IDs i the list, ad the IDsPropertyName property to the ame of the property group s property that idetifies the IDs i the list. Lists of users require implemetig a special group of three properties. You must set the property ame for all three members of the group. Subclassig the ItemWrapper Class The ItemWrapper class is the core of the StarTeam Extesios workflow logic. There may be situatios where the StarTeam Extesios workflow egie caot support a complex workflow requiremet, ad i these cases the ItemWrapper ca be subclassed ad special logic ca be implemeted by overridig specific class members. The StarTeam Extesios Samples iclude a Customizatio Sample that illustrates how to do this. To subclass the ItemWrapper class: 1 Create your ow class to exted ItemWrapper. 2 Override the methods that you eed to alter. 3 Chage the code i the forms that make use of ItemWrapper to create a istace of your class istead of directly creatig ItemWrapper istaces. 4 If you cotiue usig the provided Laucher framework, you ca simply exted AbstractLaucher or oe of its subclasses (like ChageRequestLaucher), ad override the createitemwrapper method. The framework uses this factory method to create ItemWrapper istaces, so oce you ve overridde that oe method, your subclass will be created wherever a ItemWrapper would have bee created. The methods of ItemWrapper are either public or protected so that they ca be overridde. There are just a few methods that you ll be likely to wat to override, 30 StarTeam Workflow Extesios User s Guide

31 Advaced Topics however. Followig is a brief descriptio of the likely cadidate methods to be overridde: put method This method is used to set the value of ay property (except the additio of attachmets) of a applicatio Item (ChageRequest, Requiremet, etc.). You should ot replace this method uless you have a i-depth uderstadig of the implicatios. Rather, this is a good place to put pre- ad post-processig logic. If you just wat to be otified of a property chage, you do t eed to subclass ItemWrapper at all; you ca add a PropertyChageListeer to the ItemWrapper istace. If you wat to block certai values from beig put, you will wat to override the checkvalue method istead. checkvalue method This method is called withi put after checks are made to see that the user is authorized to call put i the first place, that the Item is ot read-oly, ad that the value beig put is differet tha the existig value. Oce these coditios are met, checkvalue is called with the ame of the property ad the value that is beig set. The default implemetatio always returs true, but you ca override this method to perform ay special validatio that you wat. getallowedvalues method This method returs lists of values that are valid ext values for a particular property. For istace, this method supplies the values for the drop-dow lists used to select values for Resposibility, LastBuildTested, Priority, Severity, etc. Geerally speakig, you will most likely wat to simply limit the set of values retured by the default implemetatio based o your ow rules, so it would be best to call the superclass method first ad the rework that list before returig it. ispropertyrequired, ispropertyhidde, ad ispropertydisabled methods These methods determie whether a particular property requires a o-ull value before the Item may be saved, or whether the property s represetatio o the form should be hidde or disabled. You might override these if you have special logic that depeds o other elemets of the Item s state. isauthorized method This method determies if the user is allowed to edit the Item. You might override these if you have special logic that depeds o other elemets of the Item s state. update method This method causes the chages to the Item to be saved i the repository. The same warigs apply as with put. Similar to put, if you wat to perform some validatio before allowig the chages to be saved, you will wat to override the validateproperties method istead. validateproperties method This method is called withi the update call to validate that all requiremets are met before the chages are saved. If a requiremet is ot met, the method throws a RequiremetNotFulfilledExceptio. dyamicdefaults method This method is called with the ame of the property that has just bee put ad the sets the default values of other properties based o the workflow rules. You may override this method if you have special logic that caot be expressed by the workflow rules. The sematics of dyamic defaults is such that dyamic defaults are oly set i respose to a user chagig a property value directly. Therefore, dyamic defaults should ot be triggered by the settig of a acillary property durig dyamic defaults processig. I order to allow you to put a property value without triggerig dyamic defaults processig, there is a protected, overloaded put method that takes a additioal Boolea parameter idicatig whether or ot to Usig StarTeam Extesios 31

32 Kow Issues Kow Issues perform dyamic defaults processig. You should use this overloaded method to put property values if you override dyamicdefaults. Custom Fields ot Recogized The cachig of server coectios improves the form server s performace, but chages to customizable properties ad ew properties are ot automatically recogized by APEs. Use oe of the followig workarouds: You ca force-log-off all users after makig the property customizatio. This causes the cached server coectio to be recreated with the ew iformatio. You ca perform the modificatio after hours if everyoe logs off as they leave. Tell all users to shut dow their form servers. Whe the APE is restarted, the coectio is reestablished with the ew iformatio. Thigs to Check Make sure that the server descriptio s computer ame or IP address ad edpoit are correct. Also be sure that your userame ad password are correct. The StarFlow Extesios project caot be reamed. StarTeam Extesios looks for this project whe doig aythig regardig APEs ad workflow. If this project is reamed or missig, StarTeam Extesios fuctioality will fail. Java requires a miimum of 256 colors to start ay AWT or Swig-based graphical user iterface. Whe you try to start the StarTeam Server from the Start meu o a computer with too few colors, you see a DOS box blik o the scree the go away. Use of Process Items Markig process items as fixed, fiished or completed as part of the check-i process chages the value of the iteral property field amed Status for the item type. It works well for users of the stadard property dialogs. However, if the item type uses a custom workflow process, this ca cause problems ad should be avoided. For example, if you mark a chage request as fixed as part of check i, the Addressed I property is automatically set to Next Build. However, the workflow cotrol property for a chage request is ever the Status field (because of the applicatio s built-i workflow). The value of the workflow cotrol property is ot chaged by this check-i process ad the ext build label ca become attached to the process item erroeously. 32 StarTeam Workflow Extesios User s Guide

33 Chapter 4Usig StarTeam Workflow Chapter Desiger This chapter provides a overview of the StarTeam Workflow Desiger ad describes: Issues that you eed to cosider while plaig a workflow. Startig Workflow Desiger. The purpose of the commads o the meu bar ad the buttos o the toolbar. Displayig a workflow i the Workflow Desiger workspace, set its properties, ad save it. Cotrollig a workflow at the step level. Extedig the XML for a step. For users who are ot ew to StarTeam or to the StarTeam s workflow features, this chapter provides iformatio about updatig items that were created before you used the StarTeam s workflow features so that they ca be used with a workflow ad Notificatio Aget. See Chagig Workflow Cotrol Property Values Automatically o page 72. About StarTeam Workflow Desiger StarTeam Workflow Desiger allows you to create workflows usig a graphical eviromet i which you draw boxes that represet the steps of the workflow ad coect those boxes with directed lies or arrows (called liks). The steps ad liks represet the paths that a item ca take through the workflow. Workflow Desiger meets both the simplest ad most complex workflow eeds. Usig Workflow Desiger, you ca: Create workflow models with ay umber of sequeced steps. Create steps that must begi or be completed before a specific amout of time has elapsed. Create steps that redirect workflow based o certai coditios. Usig StarTeam Workflow Desiger 33

34 Plaig a Workflow Note Idicate how the APE will display fields for a step: what fields will be required, disabled, or hidde. Set the list of users or user groups to be asked to accept resposibility for a item while that item is i a specific workflow step. Set the list of authorized users or user groups for a workflow step. Oly authorized team members ca edit a item that is at this step i the workflow. Specify who will be otified about the status of a item ad ay exceptios that occur while the item is beig processed. Defie the format of otificatios. Create eumerated properties or add values to the workflow cotrol property if ecessary. As Workflow Desiger looks for server descriptios i the ServerList.st file. The StarTeam Cross-Platform cliets use the ew starteam-servers.xml file. If you update a server descriptio i Workflow Desiger, it will ot be recogized by the Cross-Platform cliets ad vice-versa. The followig figure shows the graphical depictio of the ChageRequest.Workflow.xml that comes with StarTeam Extesios. The figure shows the workflow as it would appear i the Workflow Desiger widow whe the grid is ot show. Plaig a Workflow Before you create a workflow, you should have a pla for the etire workflow. Before you modify a workflow, you should have a clear uderstadig of what your modificatio eeds to do ad how it will fit with what is curretly i the workflow. Walk through the workflow by creatig a paper map, otig ay coditios that might chage the directio of the item through the workflow ad ay time costraits that must be applied to items as they progress throughout the workflow. The steps ad liks represet the paths that a item ca take through the workflow. Both have limitatios. 34 StarTeam Workflow Extesios User s Guide

35 Plaig a Workflow The ext few sectios cover those limitatios ad defie the terms you eed to uderstad as you create workflows. Geeral Workflow Iformatio The more time you sped plaig a workflow, the fewer problems you will have durig its executio. This sectio explais issues that you should be aware of durig the plaig phase. Workflow Cotrol Property Each workflow is based o oe eumerated property, called the workflow cotrol property. You choose this property from those already available for the item type or create a ew property. For example, the sample StarDraw server cofiguratio uses the custom property Usr_StarFlowStatus i its sample workflows for chage requests. If you use a existig property, it will probably eed some modificatios. I StarTeam, to review the properties for a item type that are available for customizatio, select item > Advaced > Customize. The Customize dialog lists the properties. Some of the applicatio s eumerated properties are more customizable tha others: A property with the red ad yellow ico is a applicatio field. It is always a eumerated type ad is fully customizable. You ca add to, disable, reame, ad reorder the eumerated type s values. A field with the white ad blue ico is a restricted eumerated type. You ca chage oly the ames the applicatio displays for the eumerated type s values. Usually these fields have built-i workflow characteristics. I most cases you will decide to create your ow eumerated property for the item. Each step i your workflow takes the ame of a value i the workflow cotrol property. Micro Focus recommeds you create the workflow first to fid out what steps you eed, assig ames to them, ad create the property to have those ames as values. Workflow Resposibility Property You must also select oe of the item type s properties to be used as the workflow resposibility property. This ca be a custom property. It must be a user ID property, oe that accepts user ames as its values. Notificatio Aget seds messages askig users to accept resposibility for each item at each step i the workflow. The Notificatio Aget sets the workflow resposibility property to the ame of the user who accepts resposibility. Multiple Workflows for the Same Item Type Withi a server cofiguratio, all projects ad views have the same properties for their item types. Whe you create a property for a item type, that property becomes available i all items of that type i the server cofiguratio, regardless of where the items reside. This is what makes it easy to share ad move items, but it ca complicate workflow is some circumstaces. For example, suppose that you have two projects, oe that uses a APE ad oe that uses the stadard properties dialog for the item type. The stadard properties dialog has a Custom tab that will show ay fields you have created for the other project s workflow. If ay of these properties were created as required fields, the users i the project usig the stadard properties dialog must provide a value for them. The users i the project with the workflow do ot eed to be aware of this property. It does ot have to appear o the form that they use, ad whether or ot it was created as a required property does ot affect them. Usig StarTeam Workflow Desiger 35

36 Plaig a Workflow Now suppose that the two projects both use workflow for the same item type, but that the workflows are differet. Suppose that the first project s workflow uses all the values for the workflow cotrol property, but the other workflow uses oly a subset of those values. If a item is moved or shared from the first project to the secod while it is i a state that is ot recogized i the secod project, that item is straded i the secod project util its state is chaged. You would probably wat that chage to cause the item to brach. If you are aware of possible pitfalls, you ca elimiate or compesate for them before they occur. Uderstadig Steps Each step has properties that ca be set. These properties cotrol what happes to a item uder workflow cotrol while it i that step. Step Names Each step represets a value i the workflow cotrol property. That value becomes the ame of the step. Time Limits A step usually idicates the completio of some umber of activities. For example, whe a developer sets the status of a chage request to fixed, team members recogize that, as a result of some defect, that developer has writte code, compiled it, tested the fix i debug mode, ad checked i oe or more files. These activities are ot usually reflected i the workflow, but they require some time to complete. You ca allot time for the activities that must be performed at a give step by settig a umber of days, hours, or miutes for the step to complete. This time ca be relative to the time the steps starts or the time betwee some previous step ad this step. Exceptio message are set whe deadlies are missed. Form Cotrol At each step, you have some cotrol over the APE form. You ca: Hide property fields. Require property fields. Disable property fields. Limit the values that are displayed i the list box for the workflow cotrol property. This cotrols what ext steps are available to the user editig the APE. Dyamically set values i fields based o the value set i aother You set dyamic defaults so that, if a user selects oe value i oe field, oe or more other fields chage their values. For example, if you are familiar with the applicatio s built-i workflow for chage requests, you have oticed that whe you chage the Status to fixed, two dyamic defaults take place: The Resposibility field automatically becomes set to the ame of the user who created the defect (the value of the Etered By property). The value of the Addressed I field is automatically set to Next Build. A dyamic default happes i real time ad is triggered by some actio o the user s part. It is oly a default. The user ca chage the values i either of these fields. 36 StarTeam Workflow Extesios User s Guide

37 Plaig a Workflow You caot use a date/time property as the triggerig field for a dyamic default. Who s Who At each step, you create lists of users ad groups: Those who will be asked to accept resposibility for the work to be doe for the step. Those who ca edit the item at this step. This should iclude: The previous list of people or at least the oe to whom the Notificatio Aget has assiged to the workflow resposibility property field. Some admiistrators who eed access to the item at all times. Some supervisors who may ot be resposible for ay items but who will assist those who are. Those who will eed to be otified whe items reach a specific step. Those who eed to be otified about exceptios. Exceptios iclude missed deadlies, the failure of ay user to accept resposibility for a item at this step, ad so o. For the participats, those who are asked to accept resposibility for the step, you ca tailor the step otificatio message s cotets. It ca also be set to users simultaeously or i a specific or radom order. Notificatio Aget seds status ad exceptio messages to everyoe i the lists simultaeously. You ca tailor the status message, but the exceptios messages are uder Notificatio Aget s cotrol. If you do ot wat to otify ayoe, the otificatio list should be empty. Uderstadig Liks Liks are directed lies coectig pairs of steps. They show the routig possibilities withi a workflow. Liks ca be ucoditioal or coditioal. Whe a lik is ucoditioal, users ca select the secod step from the first, regardless of the settigs of ay other properties. Coditioal liks limit the possible ext steps based o the value of some property other tha the workflow cotrol property ad other tha a date/time property. Keep i mid that: O paper, you ca draw several liks betwee ay two specific steps, but i the Workflow Desiger, you see oly oe lik coectig two steps i the workspace. O paper you ca write ay umber of simple ad complex coditios o a lik, but i Workflow Desiger, oly oe property ca appear i a coditioal lik. The coditioal property caot be the workflow cotrol property or a date/time property. The coditioal property ca be set to oe, more tha oe, or all the values, icludig the <otherwise> value with varyig cosequeces depedig o each listed value. All of the cosequeces are moves to other workflow steps. I most cases, whe the user eters the workflow step, the coditioal property should be displayed ad eabled. It may eve be required. I most cases, whe the user eters the workflow step, the workflow cotrol property must be displayed ad eabled. Usig StarTeam Workflow Desiger 37

38 Startig Workflow Desiger The value of the coditioal property dictates which values (steps) ca be selected from the workflow cotrol property s list. For example, suppose a lik s coditio is equivalet to Whe Severity is High ad has the possible ext steps of 1. New ad 2a. Ope. The the oly values the user ca select from the workflow cotrol property s list are 1. New ad 2a. Ope whe the coditio is true. Startig Workflow Desiger Usig the Meu Bar If you istalled Workflow Desiger o a Widows platform, Workflow Desiger is o your Start meu: Start > Programs > Borlad StarTeam > Workflow Desiger. With cosultig work, a butto for Workflow Desiger ca be added to the custom toolbar provided with the Cross-Platform cliet. Cotact Professioal Services at Workflow Desiger meu bar offers commads that allow you to create, modify ad save workflows. The File Meu The optios o the File meu are: New Creates a ew workflow o the Server of your choosig. If you are ot already logged o to the server cofiguratio that will store this ew workflow, you must select the server cofiguratio ad provide logo iformatio. Ope Opes a existig workflow file. If you are ot already logged o to the server cofiguratio that stores the workflow, you must select the server cofiguratio ad provide logo iformatio. Close Closes the curret workflow file. Save Saves the curret workflow file ad checks i a ew revisio. There is o workig file. This is equivalet to a force check-i. Save As Saves the curret workflow file, allowig you to specify a ew ame or locatio, ad checks i a ew revisio. If the applicatio already has a file with this ame at this repository locatio, you are asked if you wat to overwrite the existig file. If you agree, a force check-i is performed. No workig file is affected. Save As Disabled Deletes everythig i the workflow file, savig a sigle <Disabled/> XML tag i its place. This tag disables workflow processig. To restore the workflow to its predisabled coditio, check out a previous revisio, import it ito Workflow Desiger, ad save it. Why do you disable workflows? Suppose you have created a workflow ad APE for chage requests for a etire project. However, you wat oe view to have o workflow. I the folder for that oe view i the StarFlow Extesios project, you would place a disabled workflow. Whe the applicatio sees that the workflow has bee disabled, it uses the APE without workflow. 38 StarTeam Workflow Extesios User s Guide

39 Usig the Meu Bar Import Loads a previously exported.workflow.xml file ito Workflow Desiger. Export Saves the workflow documet as a local.workflow.xml file. Does ot check i a ew revisio. This feature allows you to save a workflow that cotais errors. Check For Errors Examies the workflow for errors that could prevet it from ruig ad displays the results. Fidig o errors does ot mea that the workflow will ru correctly, but it should ru oce the errors are corrected. New Workflow Step Allows you to draw a ew step i the workspace. Prit Prits the curret workflow, reducig the diagram to fit o a sigle page. Exit Closes Workflow Desiger. The Edit Meu The optios o the Edit meu are: Udo <edit actio> Reverses the last edit made to the curret workflow. Redo <edit actio> Restores a previously udoe edit. Normal Zoom, Zoom I, Zoom Out, Zoom To Fit, Zoom To Box Adjusts the zoom level of the displayed workflow. Overview Creates a thumbail view of the workflow s graphical represetatio withi the Workflow Desiger widow. Workflow Properties Displays ad allows you to edit the properties of the curret workflow. Step Properties Displays ad allows you to edit the properties of the curretly selected step. Delete Removes the curret selectio from the workspace. Create All Steps Creates a step for each of the values of the workflow cotrol property that do ot already have steps. Select All Selects all elemets i the curret workflow. Select All Steps Selects all steps i the curret workflow. Lik Optios Allows you to specify colors for the liks betwee steps ad to display lik text (the properties ad values that drive the liks). By default, the lik text is cleared wheever you ope a workflow. You have to tur it o if you wat to see the coditioal text for a lik. Most customers prefer to hover over the lik to display the coditioal text as a tool tip. Usig StarTeam Workflow Desiger 39

40 Displayig a Workflow i the Workspace The Layout Meu The optios o the Layout meu are: Alig Lies up two or more selected steps vertically or horizotally. Optios iclude Top ad Left. Make Same Size Adjusts the size of two or more selected steps. Optios iclude Height, Width, ad Both. Show Grid Displays a grid o which to alig steps. Sap To Grid Automatically aligs a step o a gridlie whe you move the step ear the lie. The gridlies do ot have to be displayed. Set Grid Size Allows you to adjust the size of the grid. Automatic Layout Arrages the workflow steps ad liks, usually i ladscape orietatio. Apply FLW Imports the layout istructios for workflows that were created i the Outlook-based versios of this product (Workflow Desiger 5.2 was the first release that was ot Outlook-based.) Displayig a Workflow i the Workspace Cautio To display a workflow i the Workflow Desiger workspace, you ca: Create a ew workflow from scratch. Ope a workflow from the server cofiguratio i which it resides. Import a.workflow.xml file from your workstatio or a etwork locatio. Every workflow has properties that specify: The type of item that the workflow cotrols. Oe of the item type s properties as the field that will idicate who is curretly resposible for a item. This field is called the workflow resposibility property. Oe of the item type s properties as the workflow cotrol property o which the workflow is based. This field is called the workflow cotrol property because its values become the ames of the steps i the workflow. The etry step for the workflow. Workflow properties must be established whe the workflow is created but ca be chaged at ay time. Editig or chagig the workflow cotrol property or workflow resposibility property after a workflow is deployed whe items are already uder workflow cotrol may yield udesirable results. For more iformatio about workflow properties, see Viewig ad Editig Workflow Properties o page 43. You ca create custom properties for a item type or add values to a existig property usig either Workflow Desiger or StarTeam. See Addig ad Modifyig Custom Properties o page 67 or the customizatio chapter i the StarTeam Admiistrator s Guide. 40 StarTeam Workflow Extesios User s Guide

41 Displayig a Workflow i the Workspace Creatig a Workflow Note Whe you create a ew workflow, Workflow Desiger asks you to select (ad, if ecessary, log o to) the server cofiguratio that will store the ew workflow. Workflow Desiger displays the Workflow Properties dialog so you ca set properties for the ew workflow. After you provide the required iformatio, Workflow Desiger automatically creates the etry step i the top left corer of the Workflow Desiger workspace. To create a workflow: 1 Do oe of the followig: Select File > New from the Workflow Desiger meu bar. Click the New Workflow toolbar butto. 2 From the resultig New dialog: a Select a server cofiguratio. b If the Log O dialog appears, log o usig a valid user ame ad password. c Click New. 3 From the resultig New Workflow Properties dialog: a I the Item Type list, select the item type o which the workflow is based. You ca create a workflow for the followig item types: file, chage request, requiremet, task, ad topic. b I the Workflow Resposibility list, select the item property that idicates resposibility for a step. If you are creatig a workflow for chage requests, the default is Resposibility. You may chage this, for example, if you have created a custom property to track resposibility or choose to use aother user ID field. c From the Workflow Cotrol Property list, select the item type s property that will cotrol the workflow. This property is always a eumerated type. It may be a custom property or a existig applicatio property that is customizable. If you are creatig a workflow for chage requests ad have created a custom property with the iteral ame Usr_StarFlowStatus, the list defaults to that property s display ame (usually Workflow Status). d From the Etry Step list, select the ame of the eumerated value from the workflow cotrol property that will be the ame of the etry step, the step at which each item eters the workflow. The etry step is usually amed 0. Etered. Steps with that specific ame defie the costraits for a item as it is iitially created. e Click OK. Workflow Desiger displays the workspace ad the etry step. That step, represeted i the workspace by a rectagle has the ame of the eumerated value you selected from the Etry Step list. The ame is i gree. Other step s ames will be black. This makes it easy to distiguish the etry step. All liks created from the etry step must be directed towards other steps. No liks ca be directed to the etry step. Normally, there is oly oe ucoditioal lik from the etry step to the secod step. If ad whe you save the ew workflow, it will be checked ito the selected server cofiguratio s StarFlow Extesios project. The New dialog has its ow toolbar allowig you to add/edit server iformatio ad select folders. Usig StarTeam Workflow Desiger 41

42 Displayig a Workflow i the Workspace Uderstadig the 0. Etered Etry Step The etry step is a special pass-through step. As a user creates a item, the APE uses the step properties for the 0. Etered status to cotrol: The iitial optios for form fields (that is required, hidde, or disabled). The values that ca be selected for the workflow cotrol property at the time that the item is created. (These values are equivalet to steps i the workflow process.) For example, as a user creates a chage request, the oly values that ca be selected for the workflow cotrol property are those specified for the O. Etered step o its Next Steps tab. 0. Etered is ever used as a Next Step for ay workflow step. That meas that users caot select 0. Etered as the value for the workflow cotrol property. 0. Etered ca have o liks directed to it oly from it. Because o item ever displays this status, there is o reaso to set otificatios, participats, dyamic defaults, or a duratio for this step. They will ever be eforced. While 0. Etered is ever the selected value for the workflow cotrol property i the APE, there always is a selected value. This ca cause some iitial desig cofusio. As you create the settigs for steps that correspod to values of the workflow cotrol property, be aware that, whe a user creates a item, settigs assiged to both 0. Etered ad the step that correspods to the curretly selected value of the workflow cotrol property affect the workflow. For example, suppose that the oly Next Step for 0. Etered is 1. New. As the user creates a ew chage request, the default value (i fact the oly possible value) for the workflow cotrol property is 1. New. However, the form field settigs assiged to both the 0. Etered ad the 1. New steps affect the APE. If 0. Etered requires the Type field ad the 1. New step requires the Platform field, both Type ad Platform will be required. Notificatios, participats, dyamic defaults, ad duratio come oly from the 1. New step. Opeig a Workflow Stored i a Server Cofiguratio Workflow files must be stored i the StarFlow Extesios project of ay server cofiguratio i which workflows are used. You may have several server cofiguratios, ay or all of which may have a StarFlow Extesios project, although the paths to their workig folders should be differet. See Creatig ad Cofigurig the StarFlow Extesios Project o page 13 for more iformatio. To ope a existig workflow file i a StarFlow Extesios project: 1 Do oe of the followig: Select File > Ope from the Workflow Desiger meu bar. Click the Ope Workflow toolbar butto. 2 If you have ot already logged o to a server cofiguratio, the Ope dialog displays a list of servers. If you have previously logged o to a server cofiguratio, the Ope dialog displays ay.workflow.xml files foud i the Projects folder of the StarFlow Extesio project o that server. If you wat to select a differet server cofiguratio to log o to, you ca ope the Look I list, ad select oe from the tree it displays. You ca also avigate to other projects, views, the Projects folder s child folders, ad so o. a If the dialog displays a list of server cofiguratios or if you wat to log o to a differet server cofiguratio, select oe. b If the Log O dialog appears, log o usig a valid user ame ad password. 42 StarTeam Workflow Extesios User s Guide

43 Viewig ad Editig Workflow Properties Note c The Ope dialog replaces the list of server cofiguratios with the list of item_type.workflow.xml files i the selected cofiguratio s StarFlow Extesios project s Projects folder. If you had previously logged o to a server cofiguratio durig this sessio, the Ope dialog showed these files iitially. Locate the file to be worked o. You may have several project ad view folders to choose from, may of which have workflow files. d Click Ope. Workflow Desiger displays the workflow steps from the selected file i the workspace. The Ope dialog has its ow toolbar: If this workflow was created usig a release of Workflow Desiger prior to 5.2, a pile of liked steps appears i the upper left corer of the workspace. Withi secods, Workflow Desiger applies its automatic layout routie, but you will probably prefer to apply a appropriate.flw file to this workflow so that it has the same look as i the old Workflow Desiger. Importig a Workflow File Note You ca export workflow files from oe server cofiguratio ad the import them ito aother. You ca also import a workflow file that has bee checked out to your workstatio or a accessible etwork locatio. To import a workflow file: 1 Select File > Import from the meu bar. 2 From the resultig Import Workflow Documet dialog: a Locate a.workflow.xml file. b Click OK. 3 From the resultig Select Server dialog: a Select the server cofiguratio that will store this workflow file. b If the Log O dialog appears, log o usig a valid user ame ad password. c Click Select. Workflow Desiger displays the workflow steps from the selected file i the workspace. The Ope dialog has its ow toolbar: If this workflow was created usig a release of Workflow Desiger prior to 5.2, a pile of liked steps appears i the upper left corer of the workspace. Withi secods, Workflow Desiger applies its automatic layout routie, but you will probably prefer to apply a appropriate.flw file to this workflow so that it has the same look as i the old Workflow Desiger Viewig ad Editig Workflow Properties Cautio Wheever you ope a workflow, Workflow Desiger lets you kow if the workflow properties eed to be specified. Eve whe they are already specified, you may choose to chage them. Editig or chagig the workflow cotrol property or workflow resposibility property after a workflow is deployed ad there are items uder workflow cotrol may yield udesirable results. Usig StarTeam Workflow Desiger 43

44 Creatig ad Likig Steps Note To specify workflow properties: 1 Do oe of the followig: Select Edit > Workflow Properties from the Workflow Desiger meu bar. Click the View/Edit Workflow Properties toolbar butto. 2 From the resultig Workflow Properties dialog: a From the Item Type list, select the item type o which the workflow is based. You ca create a workflow for the followig applicatio item types: file, chage request, requiremet, task ad topic. b From the Workflow Resposibility list, select the item property that idicates resposibility for a step. If you are creatig a workflow for chage requests, the default is Resposibility. You may chage this, for example, if you have created a custom property to track resposibility or choose to use aother user ID field. c From the Workflow Cotrol Property list, select the item type s property that will cotrol the workflow. This property is always a eumerated type. It may be a custom property or a existig applicatio property that is customizable. If you are creatig a workflow for chage requests ad have created a custom property with the iteral ame Usr_StarFlowStatus, the list defaults to that property s display ame (usually Workflow Status). d From the Etry Step list, select the ame of the value from the workflow cotrol property that will be the ame of the etry step, the step at which each item eters the workflow. The etry step is usually amed 0. Etered. Steps with that ame defie the costraits for a item as it is iitially created. e Click OK. You ca create a custom eumerated property from the Workflow Properties dialog. You ca also add values to that property or ay other eumerated property that is either a custom property or a customizable applicatio property. For more iformatio about custom ad customizable fields, see the StarTeam Admiistrator s Guide. For iformatio about creatig ad modifyig custom fields from Workflow Desiger, see Addig ad Modifyig Custom Properties o page 67. Creatig ad Likig Steps The steps i a workflow ad the liks betwee those steps idicate all the possible paths tha a item ca take through a workflow. Every step i a workflow has the same ame as a eumerated value i the workflow cotrol property. Normally every eabled eumerated value appears as a step i the workflow, but this is ot eforced. You ca: Create steps maually by drawig them i the workspace Create steps automatically by listig them i the Next Steps tab of the Edit Step dialog Use stadard graphical features such as aligig, resizig, ad repositioig to give steps a acceptable look 44 StarTeam Workflow Extesios User s Guide

45 Creatig ad Likig Steps You lik two steps to show that items ca trasitio from the first step to the secod i the directio of the lik. Whe a item s workflow cotrol property is set to the value represeted by the first step, the user who is editig the item ca select the value represeted by the secod step. For example, suppose the workflow cotrol property cotais steps amed 1. New ad 2a. Ope. If you lik the step 1. New to the step 2a. Ope, the whe a item has the value 1. New, the user ca select 2a. Ope as the ext value. You ca: Create liks from a etry step to other steps. You caot reeter the step desigated as the etry step. Create liks betwee ay two o-etry steps i either directio. Chage the step to which the lik poits. Delete the lik. Repositio the lik so that you ca more easily see its path i the workspace. This icludes adjustig the locatio where the eds of the lik cotact the steps as well as addig lik poits to bed the lik as it travels from oe step to the other. Apply a color to the lik. There are o aligmet ad sizig features available for liks. Creatig Steps You ca draw steps maually i the workspace. Micro Focus recommeds drawig all of your steps maually as you start your workflow. You ca positio the steps i a appropriate maer. This makes it easier to create liks, either maually or automatically. Workflow Desiger draws the etry step for you whe you create a ew workflow. The rest of the steps ca be created automatically all at oe or maually step-by-step. To create all the steps at oce: 1 Select Edit > Create All Steps from the meu bar. Usig StarTeam Workflow Desiger 45

46 Creatig ad Likig Steps Workflow Desiger draws oe step for each of the values i the workflow cotrol property as a cascade. To create oe step at a time: 1 I the workspace, do oe of the followig: Select File > New Workflow Step from the meu bar. Click the Add New Workflow Step toolbar butto. The mouse poiter chages to a cross-hair. 2 Usig the mouse, click ad drag i the workspace to defie a rectagle. Whe you release the mouse butto, the New Step dialog opes. 3 From the New Step dialog: a Use the Step Name list to select the ame of oe of the workflow cotrol property s eumerated values as the ame of this step. b Click OK. A ew step with the selected ame appears i the workspace. You ca resize ad alig the step at ay time. You ca also use the Add Value butto to add values to the workflow cotrol property from this dialog. See Addig a Value to a Eumerated Property o page 69. You ca copy a previously created step except for its liks (the iformatio o the Next Steps tab). To copy a step: 1 Right-click the step. 2 Select Copy Step from the right-click meu. 3 Positio the mouse where you wat the ew step to be located ad right-click. 46 StarTeam Workflow Extesios User s Guide

47 Creatig ad Likig Steps 4 Select Paste Step from the right-click meu. 5 Add liks (Next Steps) out of this step as appropriate. 6 Be sure to create at least oe lik ito this step from aother step as well. Whe you copy a step, you ca paste what you copied just oce. To paste the step a secod time, you must recopy it. Likig Two Steps Maually Whe you draw liks maually i the workspace with your mouse, you ca start ad ed the lik at a variety of locatios o ay edges of the steps. Maually addig a lik from oe step to aother automatically affects the iformatio i the Next Steps tab of the Edit Step dialog for the step beig trasitioed from. The ame of the step beig trasitioed to is added to the list of steps for the <otherwise> value. The <otherwise> value specifies the steps to which the item is liked (ad, therefore, the values to which the item ca trasitio) whe o coditios exist or o coditios are met. Whe the lik betwee two steps is created solely because the ext step is available oly as a settig for <otherwise>, the lik is ot dotted. That trasitio is ucoditioal, eve if there are coditioal liks also origiatig from the first of the two steps. To maually create a lik from oe step to aother, do oe of the followig i the workspace: Click the edge of a step. This immediately liks the selected step with the step closest to it uless that step is the etry step. Click-ad-drag a lik from the edge of oe step to the edge of the ext. Whe you release the mouse butto, the lik appears. Agai, you caot drag a lik to the etry step. Creatig ad Likig Steps Automatically After you select a step, you ca automatically create all the liks from it to other steps usig the Next Step tab of the Edit Step dialog. If the coected steps have ot already bee draw, this procedure draws them as well. The followig figure shows what the workspace might have looked like prior to opeig the Edit Step dialog. Usig StarTeam Workflow Desiger 47

48 Creatig ad Likig Steps The ext figure shows a example of a workflow i which the 2a. Ope step will be automatically liked ucoditioally to several other steps. Whe you click OK to close the Edit Step dialog, the ew steps ad/or liks appear at the top left corer of the workspace. Use the mouse to drag the steps to more appropriate positios, or use the Layout > Automatic Layout commad to arrage the steps. 48 StarTeam Workflow Extesios User s Guide

49 Creatig ad Likig Steps The ext figure shows these steps ad liks after automatic layout has bee applied to the workspace. If the steps were already draw maually, but you defied liks usig the Next Step tab of the Edit Step dialog, Workflow Desiger draws the arrow from the first step s left edge to the secod step s right edge, regardless of their locatios i the workspace. This procedure is ot recommeded iitially because the rearragig may be as much work as drawig the steps ad liks maually, but it ca be used to make a few chages automatically afterwards. Coditioal liks ca be created oly by usig the Next Steps tab of the Edit Step dialog. See Coditioally Likig Steps o page 50 for details. To create ad lik steps automatically: 1 Do oe of the followig to select the step from which the ew steps will be liked, ad ope the Edit Step dialog: Double-click a existig step. Select a existig step ad the select the View/Edit Step Properties toolbar butto. Right-click iside a existig step ad select Step Properties from the cotext meu. Select a existig step ad the select Edit > Step Properties from the meu bar. 2 From the resultig Edit Step dialog, click the Next Steps tab. 3 Select <otherwise> i the Coditios colum to specify liks for this step that do ot have coditios. 4 Click Add Steps. 5 From the resultig Select Next Steps dialog: a Select the steps to trasitio to from the list of values. Usig StarTeam Workflow Desiger 49

50 Creatig ad Likig Steps Tip b Click OK. If you chage your mid about some of the steps selected, highlight the uwated steps ad click Remove Steps. Coditioally Likig Steps A lik ca idicate that a trasitio from oe step (or eumerated value) to aother is valid oly whe a item property other tha the workflow cotrol property has specific values. For example, suppose you have two steps amed 1. New ad 2h. Suggestio Review. Suppose that the user ca select 2h. Suggestio Review as the ext value for a item s workflow cotrol property oly whe the Type property has the value Suggestio. To show this i the workflow, you coect the two steps with a coditioal lik. A coditioal lik is a dotted arrow poitig to the step that is available oly whe the coditio is true. The followig figure shows the workspace with the 0. Etered, 1. New, ad 2h. Suggestio Review steps, but o lik has yet bee created betwee the 1. New ad 2h. Suggestio Review steps. The ext figure shows how this coditioal trasitio would be displayed i the Next Steps tab of the Edit Step dialog. You must use this dialog to create coditioal liks. They caot be created maually withi the workspace. 50 StarTeam Workflow Extesios User s Guide

51 Creatig ad Likig Steps Whe you specify a coditio, you select a property ad oe or more values. For each value, you select oe or more steps that are appropriate trasitios for a item whose property is set to that value a item that meets that coditio. I this example, the coditioal property is Type. Whe the value of that property is Suggestio, the user ca select 2h. Suggestio Review as the ext value of the workflow cotrol property. If the steps ad liks have ot already bee draw maually, Workflow Desiger creates a step for each step listed i the Next Steps list. It also creates liks from the selected steps to those steps. The steps ad liks are draw automatically ad layered i the upper left corer of the workspace. Use Automatic Layout to repositio the steps or drag each step to a appropriate locatio usig the mouse. Hoverig over the lik displays these values. They ca also be displayed as text i the workspace. As you ope existig workflows, this text is o by default. The ext figure shows these steps ad liks after the mouse has hovered over the ew coditioal lik log eough to display the coditioal iformatio. If the steps were already draw maually, but ot the liks, Workflow Desiger draws the liks. I each case, the lik starts from the first step s left edge ad eds at the secod step s right edge, regardless of the locatios of these steps i the workspace. If the liks were already draw, there already are steps listed as possible trasitios for <otherwise>. If you add a coditio, they remai i place but they become coditioal liks as well as <otherwise> liks. Oly oe lik is ever draw betwee two steps, although the lik may have more tha oe value (icludig <otherwise>) for the coditioal property. If all the possible values for the coditioal property appear i the Next Steps tab, the <otherwise> coditio may be left blak. Micro Focus does ot recommed this because if a additioal value is added to the coditioal property, a item with that ew value as its settig becomes straded. It has o ext step to go to. To coditioally lik steps: 1 I the workspace, double-click a existig step. 2 From the resultig Edit Step dialog, click the Next Steps tab. 3 From the Properties list, select the property o which to base the coditio (for example, the Type property). 4 Click Add Value. 5 From the resultig Select a Value dialog: a Do oe of the followig: Select a value for the coditio (for example, Suggestio), the click OK. The value appears i the Values list ad is selected. Select a property from the Value of Property list so that the coditio becomes depedet upo the value of that property. For example, suppose the property i the Properties list is Etered By. You ca select aother property of the same type, such as Locked By from the Usig StarTeam Workflow Desiger 51

52 Creatig ad Likig Steps Value of Property list. Your coditio is equivalet to Whe the value of these two properties is the same. b Click OK to retur to the Next Steps tab of the Edit Step dialog. 6 Click Add Steps. 7 From the resultig Select Next Steps dialog: a Select oe or more ext steps. b Click OK. 8 (Optioal.) Repeat steps 4 through 7 of this procedure to select additioal values of the specified coditioal property ad the steps available for trasitio whe the coditioal property has those values. 9 Select <otherwise> to specify the workflow steps to which the item is liked (ad, therefore, the values of the workflow cotrol property to which the user ca trasitio) whe o coditios exist or o coditios are met. Repeat steps 6 ad 7 of this procedure to select those workflow steps. 10 (Optioal) Use the Edit Value, Remove Value, ad Remove Steps buttos to make correctios as eeded. 11 Whe you click OK to close the Edit Step dialog, ay steps that were specified as ext steps ad were ot yet draw appear i the upper left corer of the Desiger widow. Note that the lik appearace is differet whe the lik is coditioal. Whe Editig a Item Suppose that you are editig a item at 1. New step ad the item s Severity is High. Further suppose that, i the workflow, the step 1. New has a coditioal lik to the step 2a. Ope ad aother coditioal lik to the step 2b. Emergecy. The coditio attached to the lik betwee 1. New ad 2b. Emergecy is equivalet to Whe Severity is High. The coditio attached to the lik betwee 1. New ad 2a. Ope is equivalet to Whe Severity is Low. The the oly value you ca choose for the workflow cotrol property at this step is 2b. Emergecy. If you chage the value of Severity to Low, the APE chages the value (step) that ca be selected from the workflow cotrol property s list to 2a. Ope. Editig a Lik You ca edit the liks for a step by double-clickig oe of the liks that origiates from that step. To edit a lik, double-click the lik. Workflow Desiger displays the Edit Step dialog for the step from which the lik origiates. The dialog is ope to the Next Step tab so you ca easily chage the lik s destiatio step or the coditios required for a trasitio to that or other destiatio steps. Displayig Lik Coditios as Text You ca display a lik s coditios as text i the workspace. Whe you do ot display the text i the workspace, it appears as a tip whe you hover the mouse poiter over a lik. Wheever you ope a workflow, the lik text is tured off. You must tur it o or use the tooltip. To display or hide the coditios i the workspace, select Edit > Lik Optios > Display Lik Text. 52 StarTeam Workflow Extesios User s Guide

53 Creatig ad Likig Steps Aligig Steps You ca alig two or more selected steps horizotally or vertically. To alig steps: 1 I the workspace, select the step that the other steps must match. 2 Select oe or more additioal steps. The selectio marks for the additioal steps are a differet color: light blue istead of gree. 3 Select Layout > Alig > Top for vertical aligmet, or select Layout > Alig > Left for horizotal aligmet. Resizig Steps You ca resize steps by draggig a edge or corer of the steps. You ca make oe step s size the same as aother s i height, width, or both usig meu commads. To resize steps: 1 I the workspace, select the step that the other steps must match. 2 Select oe or more additioal steps. The selectio marks for the additioal steps are a differet color: light blue istead of gree. 3 Select oe of the followig: Layout > Make Same Size > Height Layout > Make Same Size > Width Layout > Make Same Size > Both Repositioig Liks Whe selected, each lik has at least two lik poits. The iitial two lik poits mark each ed of the lik. To repositio a lik i the workspace: Drag the lik poit earest the arrow to repositio it o the curret step. Drag the lik poit earest the arrow to chage the step to which the lik poits. Drag the lik poit farthest from the arrow to a ew positio o the same step oly. You caot chage the step from which the lik is draw. Add beds ad turs to the lik by addig lik poits ad draggig them to appropriate spots i the workspace. To add a lik poit: 1 I the workspace, right-click the locatio o the lik where you wat to create a ew lik poit. 2 From the resultig right-click meu, select Add Lik Poit. A ew lik poit appears o the lik. Chagig the Default Lik Colors Liks are color-coded, oe color for liks with o coditios ad aother color for liks with coditios. By default, Workflow Desiger displays ucoditioal liks i dark blue Usig StarTeam Workflow Desiger 53

54 Cotrollig the Cotets of the APE Form ad coditioal liks i cya. Coditioal liks are dotted lies. You ca easily chage the default colors. You caot chage the default lie style. To chage the default lik color: 1 Choose Edit > Lik Optios > Default Lik Colors from the meu. A color selectio dialog opes. 2 Select the ew default lik color by selectig a color swatch or eterig RGB or HSB values, the click OK. To chage the default coditioal lik color: 1 Choose Edit > Lik Optios > Default Coditioal Lik Colors from the meu. A color selectio dialog opes. 2 Choose the ew default lik color by selectig a color swatch or eterig RGB or HSB values, the click OK. Chagig the Color of Idividual Liks I complicated workflows, too may overlappig liks ca make it difficult to follow a lik from its source to its destiatio. You ca chage the color of idividual liks withi a workflow to make it easier to see where the lik lies start ad ed. To chage the color of a idividual lik: 1 I the workspace, poit to the lik for which you wat to chage the color ad rightclick to display the cotext meu. 2 From the resultig right-click meu, select oe of the followig: Select Edit Lik Color > Use Default to retur to the default color for the type of lik. Select Edit Lik Color > Customize. From the resultig color selectio dialog, select the ew color for the lik lie by selectig a color swatch or eterig RGB or HSB values, the click OK. Cotrollig the Cotets of the APE Form Whe a APE is created, it is a composite of all the fields that will be eeded to perform ay of the steps i the workflow. You ca specify: What properties ca be viewed/edited from the APE by the user modifyig a item that is at a specific step. What values ca be listed for the workflow cotrol property usig the Next Steps. For a explaatio of this feature, see Coditioally Likig Steps o page 50. Dyamic chages to the item s properties that occur while the user modifies the item at that step. 54 StarTeam Workflow Extesios User s Guide

55 Cotrollig the Cotets of the APE Form Cotrollig What Properties the Form Displays Importat Use the Form Optios tab of the Edit Step dialog to specify which property fields, if ay, are required, disabled, or hidde o the item s custom form at a give step i the workflow process. These field attributes are mutually exclusive; each field may be assiged oly a sigle attribute per step. By default, oe of the fields are required, disabled, or hidde. Click the colum header to sort the fields based o that colum header. For example, clickig Required results i listig required fields first, the the fields that are ot required. Use Shift+click to reverse the sort. Be aware that as soo as a user selects a ew value for the workflow cotrol property, the o-form fields chage based o the required, disabled, ad hidde settigs for the ewly selected status. This happes regardless of whether the user is authorized to edit a item with the ew status. Authorized participatio is eforced oly whe a user opes a item. The Form Optios tab lists every possible property for the item type. The APE form usually does ot display all these properties. Be careful ot to desigate a field as required that is ot available o the APE form. To specify required, disabled, or hidde fields: 1 I the workspace, double-click a existig step. 2 From the resultig Edit Step dialog, click the Form Optios tab. 3 I the Field Name colum, locate the ame of the property field that eeds to have its attributes chaged. This colum lists all of the fields that a item of the selected type ca have. Igore fields that are ot o the form. 4 Do oe of the followig: Select the Required check box to desigate the field as required at this step i the process. If your APE form is based o a sample form that comes with the product, required fields probably appear i red (although the color ca be chaged programatically). Select the Disabled check box to prevet iput to this field at this step i the workflow. Disabled fields are usually dimmed i appearace. Select the Hidde check box to stop the APE form from displayig the field at this step i the process. The area that the field occupies o the form is left blak. 5 Click OK or aother tab. Cotrollig Dyamic Chages to Forms Use the Dyamic Defaults tab of the Edit Step dialog to set the value of oe property based o the value the user selects for aother property. For example, usig dyamic defaults, if the user sets the Severity of a chage request to High, the value of Resposibility ca be set to Jack automatically. For each property i the property list, you ca place oe or more of its values i the Whe Equals Value list. The value <otherwise> substitutes for ay values ot explicitly specified i the Whe Equals Values list. For each value i the list, you ca specify oe or more other properties ad the values to which they should be set. For example, suppose you add Severity to the Property list. While it is selected, you add High ad Low to the Whe Equals Value List. While High is selected, you add Resposibility/Jack as the property/value pair to the Assig Values To Other Properties list; while Low is selected, you add Resposibility/Jill ad a Short Commet As time permits to the Assig Values To Other Properties list. Usig StarTeam Workflow Desiger 55

56 Cotrollig the Cotets of the APE Form The result is that whe a user sets the Severity set to High, the Resposibility property is automatically set to Jack; whe the user sets the Severity to Low, the resposibility is automatically set to Jill ad the Short Commet property becomes As time permits. A commo use of dyamic defaults is to set a revisio commet for the revisio created at each step. For example, whe the workflow cotrol property for a chage request is set to 1. New, the commet ca be set to Status: 1. New. Users ca the see the steps i the history pae whe they select the item i the applicatio ad review the revisio commets. The user ca chage the settigs created by dyamic defaults. The idea is that, ormally, these are chages that the user would be makig ad, therefore, settig them dyamically saves the user time. You caot use a date/time property as the triggerig field for a dyamic default. To set properties based o the user s chages to other properties: 1 I the workspace, double-click a existig step. 2 From the resultig Edit Step dialog, click the Dyamic Defaults tab. 3 Select a property that the user would be expected to chage at this step: a Click the Add butto beeath the Property list. b From the resultig Select Property dialog, select the property. c Click OK to retur to the Dyamic Defaults tab. d Select the property from the Property list. The <otherwise> value appears i the Whe Equals Value list. 4 Select a value to which the user might set the selected property. a Click the Add butto beeath the Whe Equals Value list. b From the resultig Select Coditio Value dialog (which ca vary depedig o the type of the selected property), select oe of the followig: c A specific value for this property from the Value list. For example, if the property is Severity, you might select High. If the user chages Severity to High, dyamic chages will occur. Aother property of the same type from the Value Of Property list. If the user chages the selected property so that it matches the value of this property, dyamic chages will occur. For example, if the selected property is Severity, a eumerated field, oly eumerated properties appear i the Value Of Property list. If the user selects High for the Severity property ad this property, for example, the Priority property, is also set to High, the the dyamic chages will occur. These same chages would also occur if the both the Severity ad Priority properties were set to Low. The curret user (available for user ID properties). Noe (available for eumerated types that have a empty value). Click OK to retur to the Dyamic Defaults tab. The selected value or the property to be matched appears i the Whe Value Equals list. 5 Specify a dyamic chage: a Select the value i the Whe Value Equals list. b Click the Add butto beeath the Assig Values To Other Properties list. c From the resultig Select Property ad Value to Assig dialog, select a property (such as Resposibility) to be chaged ad the value (such as Jack) to which it should be set. 56 StarTeam Workflow Extesios User s Guide

57 Cotrollig the Cotets of the APE Form Tips This dialog varies depedig o the type of the property. The property types are User ID, Date/Time ad Eumerated. d Click OK to retur to the Dyamic Defaults tab. The property to be chaged ad its value appear i the Property ad Value colums of the Assig Values To Other Properties list. 6 Optioal) Repeat step 5 for other dyamic chages to be made if the property selected from the Property list has the value selected from the Whe Value Equals list. 7 (Optioal) Repeat steps 4 through 5 for other values of the property selected from the Property list. 8 (Optioal) Repeat steps 3 through 5 for other properties. 9 Click OK or aother tab. Use the Edit ad Remove buttos to chage ad delete properties ad values. If you use the workflow cotrol property i the Dyamic Defaults tab, avoid cofusio by ever usig it as a property to be chaged. That is, avoid placig the workflow cotrol property i the colums etitled Assig values to other properties. Whe you use the workflow cotrol property i the leftmost colum (the Property colum), always set it to the value that correspods to the step. Otherwise it will be igored. For example, i the step 5. Testig, you ca set dyamic defaults for the workflow cotrol property whe it has the value 5. Testig. If your dyamic defaults specifies a chage to the Commet field (for example to Workflow Status is 5. Testig ), that commet would appear i the history for the item ad idicate which revisios had that status. Limitig the Selectios i a Eumerated Field Based o the Value i aother Field To limit the selectios i a eumerated field based o the value i aother field i a step: 1 Uder "Property" o the Dyamic Defaults tab of the Edit Step dialog, select the property whose value will limit the selectios i a eumerated field. 2 Uder "Whe equals value", select the value that will limit the selectios i a eumerated field. 3 Uder "Assig values to other properties", click the Limits tab. 4 Click the Add butto. The Select Property dialog will appear. 5 From the drop-dow list, select the Property for which you wat to limit the list of available selectios based o the value i the field specified above. 6 Click OK. 7 Select the ewly added property ad click the Add Values butto. 8 Select a subset of the available values. Use the Ctrl or Shift key to make multiple selectios. 9 Do oe of the followig: Leave the "Iclude selected value" check box selected to retai the field's previously selected value if it does ot appear i the curret available selectios for the field. Clear the "Iclude selected value" check box to remove the field's previously selected value if it does ot appear i the curret available selectios for the field. Usig StarTeam Workflow Desiger 57

58 Cotrollig the Behavior of a Item i a Step 10 Click OK twice. 11 Save the workflow. Limitig the Users Listed i a User Selectio Field Note Note To limit the users associated with a project or view that will be listed i a user selectio field i a step: 1 O the Cotext Limits tab of the Edit Step dialog, clear the "Use global workflow cotext limits for this step" check box if it is selected. 2 From the Cotext tree view, select the project or view for which you wat to limit the associated users listed i a user selectio field. The Add butto becomes available. 3 Click the Add butto. The Select Property dialog will appear. 4 From the drop-dow list, select the Property for which you wat to limit the list of available users. 5 Click OK. 6 Select the same user selectio field uder Property o the Cotext Limits tab of the Edit Step dialog. 7 Do oe or both of the followig: Click the Add Users butto to select the user(s) to be listed i the user selectio field. Use the Ctrl or Shift key to make multiple selectios. Click the Add Groups butto to select the group(s) to be listed i the user selectio field. Use the Ctrl or Shift key to make multiple selectios. Clickig the All Users butto will remove all previous selectios ad list all the users associated with the selected project or view i the user selectio field. 8 Optioally, click the Add Refereces butto to select the user selectio field(s) for which you wat the same list of available users. Use the Ctrl or Shift key to make multiple selectios. 9 Optioally, select the "Use global workflow cotext limits for this step" check box to set the same user selectios for every step i the workflow. User selectios are automatically set globally o the Cotext Limits tab of the Workflow Properties dialog. 10 Click OK. 11 Save the workflow. Cotrollig the Behavior of a Item i a Step Workflow Desiger allows you to cotrol the behavior of a item at a particular step. You ca specify: Who will be asked to accept resposibility for a item that has reached a particular step. Who will be allowed to modify that item. For example, while everyoe who is asked to accept resposibility for a item must be allowed to edit it, you might wat additioal persoel, such as admiistrators or team leaders, to be able to edit that item at this step. 58 StarTeam Workflow Extesios User s Guide

59 Cotrollig the Behavior of a Item i a Step How log a user will have to accept resposibility for a item at a give step. For example, if this step is a critical oe ad the first user does ot accept resposibility i a specified amout of time, aother user will be asked to accept resposibility. How log a user will have to perform the tasks ecessary at a give step before editig the item. For example, source code may eed to be modified before a chage request ca be marked fixed. Who moitors the progress of a item as it reaches a particular step. Who is otified whe exceptios occur i the workflow process. For example, a item at a particular step may exceed the time allowed for the step to complete or all participats may declie to accept resposibility for the item at that step. You specify these settigs usig Workflow Desiger, but Notificatio Aget must be ruig to eforce your otificatio settigs i real time. Listig the Participats Each step has its ow set of participats. For example, someoe i developmet may have to address a chage request durig the implemetatio step while someoe i QA may have to address that same chage request durig the testig step. You idetify the team members who are allowed to modify the item at a give step i the workflow. You also determie whether they are asked simultaeously or oe-at-a-time to accept resposibility for a particular item as it reaches a particular step. The Participats tab o the Edit Step dialog has two lists. The Step Notificatio List specifies team members who will receive otificatio that the workflow has trasitioed to the curret step. Members of these lists receive the message defied o the Step Notificatio tab or a default message from Notificatio Aget if o message is provided. See Usig StarTeam Notificatio Aget o page 97. The Authorized List specifies team members who are authorized to modify a item at this step i the workflow. For example, suppose you are authorized to edit chage requests with the Ope status but ot with the Fixed status. If you select a Ope chage request ad chage its status to Fixed, you ca still click OK because the authorizatio for Fixed does ot go ito effect util a ew revisio is created with that status. After you click OK, you caot reope the chage request because you are ot authorized to modify a item that is fixed. For proper operatio of the workflow, everyoe o the Step Notificatio List must also be o the Authorized List. I additio, you might wat to add some supervisory team members to the Authorized List. For example, a QA team leader might ot be assiged items to test, but might eed to assist other testers as they perform their jobs. Havig the ability to edit items durig the testig steps may make both persos jobs easier. To specify who ca edit a item at a particular step: 1 I the workspace, double-click a existig step. 2 From the resultig Edit Step dialog, click the Participats tab. 3 Select oe of the followig types of otificatio from the Notificatio Type list. Blast istructs the Notificatio Aget to otify everyoe o the list at oce. If a step is critical ad must be doe i a very short time period, you might prefer that everyoe be otified immediately. If Notificatio Aget will be sedig a resposibility otificatio message that requires o respose, the Blast optio is recommeded. Otherwise, after the amout of time set for users to accept resposibility passes, the ext participat will receive the message. This goes o util all participats receive the message, ad the a exceptio otificatio is set. Ordered, the default, istructs the Notificatio Aget to otify users oe-at-a-time i the order they appear i the list. By default, users i a group are listed Usig StarTeam Workflow Desiger 59

60 Cotrollig the Behavior of a Item i a Step Importat Tip alphabetically by their logo ames. If certai users are better equipped to perform this step tha others, you might wat the users asked to accept resposibility for a item at this step to be listed i a differet order. Radom istructs the Notificatio Aget to radomize the list ad the otify users oe-at-a-time i the radomized order. If ayoe i the list ca perform this step, you may ot wat the first perso is the list to be bombarded with requests while a user at the bottom of the list is rarely asked to perform this step. If this is the case, radom comes closest to balacig each user s workload. 4 Before you create the Step Notificatio List, select the Use Same Names As Step Notificatio List check box. This esures that all the users ad groups i the Step Notificatio List also appear i the Authorized List. 5 Add ay umber of idividual users, user groups, ad refereces to the Step Notificatio List. Specifyig a referece adds to the list oe or more user ID fields. The user whose ID appears i the refereced field at the time a item eters this step will be added to the list. These users ad groups are from the server cofiguratio. To add oe or more users: a Click the Add Users butto ext to the Step Notificatio List to add users to the list. b From the resultig Select Notified Users dialog, select oe or more users. c Click OK to retur to the Participats tab. The selected users appear i both the Step Notificatio List ad the Authorized List. To add oe or more user groups: d Click the Add Groups butto ext to the Step Notificatio List to add a group to the list. e From the resultig Select Notified Groups dialog, select oe or more groups. f Click OK to retur to the Participats tab. The selected groups appear i both the Step Notificatio List ad the Authorized List. To add oe or more users by referece: g Click the Add Refereces butto ext to the Step Notificatio List to add users to the list. h From the resultig Select Refereced Fields dialog, select oe or more user ID fields. i Click OK to retur to the Participats tab. The refereced user ID fields appear i both the Step Notificatio List ad the Authorized List. 6 (Optioal) If you wat to add additioal users or groups to the Authorized List so that those users ca also edit items at this step, clear the Use Same Names As Step Notificatio List check box. The users, groups ad refereces curretly i the Authorized List remai there, but the Add Users, Add Groups, ad Add Refereces buttos beside the list become eabled. Use these buttos to add ay umber of additioal idividual users, user groups, ad refereces to the Authorized List. It is commo to add a referece to the resposibility field to esure that ayoe who has bee assiged resposibility to the item at this step, for whatever reaso, ca edit the item. 7 Click OK or aother tab. 60 StarTeam Workflow Extesios User s Guide

61 Cotrollig the Behavior of a Item i a Step Tips You ca use drag-ad-drop to rearrage users, groups ad refereces i the Step Notificatio List if you are usig Ordered otificatio. Use the Remove buttos to delete users, groups or refereces from either list. Specifyig a Notificatio Message ad Iterval Note Use the Step Notificatio tab to: Specify the message that asks users to accept resposibility for a give step Limit the amout of time a user has to accept that resposibility Idicate what importace should be attached to the message Settig itervals ca result i time limits that ed durig the ight, over the weeked, or o holidays. That meas that a exceptio message may be set if o oe accepts resposibility for a item whe o oe was at work to make such a acceptace. Settig a 24-hour or greater iterval should allow the users decisios to accept or declie resposibility to cotrol whe the ext user is otified i most cases. Exceptio otificatios would usually occur oly whe o oe accepted resposibility. Whe otificatio is ordered or radom, if a participat seds a I declie... respose or does ot respod withi the iterval set o this tab, the message is set to the ext ame o the Step Notificatio List. If o participat accepts resposibility for the item, Notificatio Aget geerates a exceptio otificatio message. To specify a otificatio message ad the iterval at which it is set to team members listed i the Step Notificatio List: 1 I the workspace, double-click a existig step. 2 From the resultig Edit Step dialog, click the Step Notificatio tab. 3 From the Set The Importace To list, select Low, Normal (the default), or High. This determies what importace a mail message has attached to it. For example, a message of high importace would have a exclamatio poit i frot of it i a Outlook ibox. 4 Specify the time iterval betwee otificatio messages i miutes, hours, or days usig the Notificatio Iterval text ad list boxes. The default is oe hour. Notificatio Aget uses this iterval both to determie whe to sed the ext message ad, fially, whe everyoe has bee cotacted, to determie that a exceptio message eeds to be set because o participat has accepted resposibility for a specific item at this step. Settig this iterval is importat eve whe the message is blasted simultaeously to everyoe, because at the ed of the iterval, a exceptio message is set if o oe has accepted resposibility. 5 (Optioal) If you prefer ot to use the default step otificatio message subject lie, eter a subject for the otificatio message. Leave the Subject text box blak to use the default subject lie for step otificatio messages (see Default Notificatio Messages o page 128). 6 (Optioal) If you prefer ot to use the default step otificatio message body, specify the body of the otificatio message. The body of the message may be i plai text or HTML format. If you do ot specify the message body, Notificatio Aget seds the default body for step otificatio messages (see Notificatio Tags ad Messages o page 117). This message is set to team members listed o the Participats tab i the Step Notificatio List. Usig StarTeam Workflow Desiger 61

62 Cotrollig the Behavior of a Item i a Step 7 (Optioal) Add the curret values of specific item property fields to the subject lie or message body usig the appropriate Isert Referece butto. a Click Isert Referece. b From the resultig Select a Referece dialog, select oe or more property field ames. c Click OK to retur to the Step Notificatio tab. For each property field you selected, a referece appears i the subject lie or message body. For example, if you selected the Etered By field, the referece toke {{property ame="eteredby"}} appears. (EteredBy is the iteral ame for the Etered By property.) Whe the message is set, the toke is replaced with the ame of the team member who etered the item. 8 (Optioal) Click Preview HTML to see how the body of your message would appear i a browser widow. 9 Click OK or aother tab. Uderstadig Notificatio List Operatio Notificatio Aget is resposible for processig the Step Notificatio List ad sedig otificatio messages appropriately. Names o the otificatio list are processed as follows: Leavig the otificatio list blak creates a silet step; o otificatio is set. This is useful whe: The workflow cotais a umber of cosecutive steps for which the same user is resposible. There is oly oe user who performs this step ad that user prefers ot to get wheever a item eters this step. For example, the user may perform the tasks associated with this step oly oce a moth ad prefers to use a query i the applicatio to locate the items that eed to be processed. Eterig a sigle ame o the otificatio list results i the otificatio of: The oe user who always completes this step. A sigle user who maually assigs resposibility for the step to oe of several appropriate users i order to balace their workloads. Note that all these appropriate users must be etered o the Authorized List for that step. Eterig two or more idividual ames or a group ame o the Step Notificatio list istructs Notificatio Aget to sed messages as specified i the Notificatio Type field. If Blast is selected, the system otifies everyoe o the participats list at oce. If either Radom or Ordered are specified, the system seds otificatio messages to oe idividual at a time. If a otified user accepts the task, o other messages are set. If a otified user declies a task or does ot respod before the otificatio iterval expires, a otificatio message is set to the ext ame o the list. Users may maually assume resposibility for a task after the otificatio iterval has expired as log as o other user has already accepted the task. Users may ot, however, use the automated accept/declie liks withi a otificatio message after the iterval has expired; the system iforms the user that the message was tardy ad discards these messages without processig them. If there is a mixture of users ad groups i the list, Notificatio Aget resolves duplicate ames so that users are otified oly oce, the first time they appear o the list. For example: 62 StarTeam Workflow Extesios User s Guide

63 Cotrollig the Behavior of a Item i a Step Elle, Joh, Mary, ad Scott are i Egieerig Elle, Joa, ad Tom are i Maagemet Elizabeth ad Scott are i Marketig The table below illustrates otificatio resolutio for a mixed list that is set to Ordered ad uses the above ames ad groups. Step Notificatio List Mary Egieerig Tom Marketig Maagemet Resolutio A sigle message is set to Mary. If she accepts, the otificatio process is over; o additioal messages are set. If she declies or fails to respod before the otificatio iterval expires, the aget moves o to the ext etry i the list. Elle, Joh, Mary, ad Scott are i Egieerig. Mary has already received a message, so messages are set sequetially to the remaiig members of the group, amely Elle, Joh, ad Scott. Each team member is give the legth of the otificatio iterval (set o the Step Notificatio tab of the Edit Step dialog) to respod before the ext message is set. Oly the active team member, that is, the oe with the most recet otificatio message, may respod usig the automatic liks withi the otificatio message. If o oe i Egieerig accepts before their otificatio iterval expires, Notificatio Aget moves o to the ext etry i the list. A sigle message is set to Tom. If Tom declies or does ot reply before the otificatio iterval expires, the aget moves o to the ext etry i the list. Elizabeth ad Scott are i Marketig. Scott has already received otificatio as a member of Egieerig, so a sigle message is set to Elizabeth. If Elizabeth declies or does ot reply before the otificatio iterval expires, the aget moves o to the ext etry i the list. Elle, Joa, ad Tom are i Maagemet. Elle has already received otificatio as a member of Egieerig ad Tom has already received otificatio idividually, so a sigle message is set to Joa. If Joa declies or does ot reply before the otificatio iterval expires, the aget geerates a exceptio, followig the istructios o the Exceptios tab. Whe a user accepts resposibility for a item at a particular step, Notificatio Aget sets the workflow resposibility property to that user s ame. Limitig the Time Allowed to Complete the Task Whe you create a timed step, you specify a duratio for the step ad a base step for the duratio. The base step for the duratio may be the step for which the duratio is specified or ay precedig step. For example, if you wat to specify that a step be accomplished i 24 hours, you set a duratio of either 24 hours or 1 day for the step ad base the duratio o othig or o the step itself. If, however, you require that step 3 ed withi 3 days after step 0 started, you would set a duratio of 72 hours or 3 days o step 3, based o step 0. If a step is ot accomplished withi the specified duratio, a exceptio occurs. The Exceptios tab of the Edit Step dialog allows you to specify recipiets for exceptio messages that are geerated at this step. Exceptio messages are geerated by Notificatio Aget ad caot be chaged. Note Settig duratios ca cause problems uless your orgaizatio operates 24-7 because the duratio time cotiues to be calculated overight, durig the weeked, ad o holidays. That meas that steps will expire ad exceptio messages will be set earlier tha aticipated. For example, if o a Friday, a step has 24 more hours before it expires, exceptio messages may be set o Saturday. Usig StarTeam Workflow Desiger 63

64 Cotrollig the Behavior of a Item i a Step To create a timed step: 1 I the workspace, double-click a existig step. 2 From the resultig Edit Step dialog, click the Geeral tab. 3 I the Step Duratio group, select the Limit Step Duratio check box. 4 Specify a duratio for the step by typig a iteger value i the Duratio text box ad selectig days, hours, or miutes from the list. 5 From the Relative To list, select the step o which the duratio is based. To specify a duratio for the step from its begiig to its ed, set Relative To to the curret step or leave it blak. Settig a duratio relative to othig (blak) or the curret step specifies that the curret step must be performed i the specified time, idepedet of other steps i the process. To specify a duratio for a task that spas two or more steps, set Relative To to the first step i the task. Settig a duratio relative to a precedig step specifies that the duratio begis whe the relative step begis ad eds whe the curret step eds, o matter how may steps itervee. The Relative To list cotais the ames of all the steps i the workspace. Be sure to select a step that precedes the curret step i the workflow. 6 Click OK or aother tab. Specifyig a Iitial Value for a Empty Text Field Note To specify a iitial value for a empty text field i a step: 1 Uder Iitialize Values o the Geeral tab of the Edit Step dialog, click the Add butto. The Select Property ad Value to Assig dialog will appear. 2 Select the Property from the drop-dow list. 3 Do oe of the followig: Select the Value radio butto to type a ew value i the associated text field. Select the Value of property radio butto to select the value from the associated drop-dow list of curretly available values. 4 Click OK twice. 5 Save the workflow. Use the Edit butto to update or the Remove butto to delete a selected Property/ Value combiatio. Moitorig a Item s Status Use the Status Notificatio tab o the Edit Step dialog to specify recipiets ad a message for otificatio of a item s trasitio to this step i the process. Status otificatio messages are iformatioal i ature ad recipiets are usually team members other tha those listed o the Participats tab for the step. For example, Customer Support supervisors might eed to be aware that a chage request has reached a escalatio step. Notificatio Aget seds oe message to all the users i the status otificatio list simultaeously. 64 StarTeam Workflow Extesios User s Guide

65 Cotrollig the Behavior of a Item i a Step To create a status otificatio list ad message: 1 I the workspace, double-click a existig step. 2 From the resultig Edit Step dialog, click the Status Notificatio tab. 3 Add ay umber of idividual users, user groups, ad refereces to the Status Notificatio List. Specifyig a referece adds to the list oe or more user ID fields. The user whose ID appears i the refereced field at the time a item eters this step will be added to the list. These users ad groups are from the server cofiguratio. a To add all users simultaeously: 1 Click the All Users butto to add all users to the list. 2 Click OK to cofirm this decisio because it will empty ay curret etries i the Status Notificatio List. 3 The word Everyoe appear i the Status Notificatio List. There is o eed to add idividual users, groups, or refereces. b To add oe or more users: c 1 Click the Add Users butto ext to the Status Notificatio List to add users to the list. 2 From the resultig Select Notified Users dialog, select oe or more users. 3 Click OK to retur to the Status Notificatio tab. The selected users appear i the Status Notificatio List. To add oe or more user groups: 1 Click the Add Groups butto to add groups to the list. 2 From the resultig Select Notified Groups dialog, select oe or more groups. 3 Click OK to retur to the Status Notificatio tab. The selected groups appear i the Status Notificatio List. d To add oe or more users by referece: 1 Click the Add Refereces butto to add users to the list. 2 From the resultig Select Refereced Fields dialog, select oe or more user ID fields. 3 Click OK to retur to the Status Notificatio tab. The refereced user ID fields appear i the Status Notificatio List. Use the Remove butto to delete users, groups or refereces from the list. 4 (Optioal) If you prefer ot to use the default status otificatio message subject lie, eter a subject for the otificatio message. Leave the Subject text box blak to sed a message with the default subject lie for status otificatio messages (see Default Notificatio Messages o page 128). 5 (Optioal) If you prefer ot to use the default status otificatio message body, specify the body of the otificatio message. The body of the message may be i plai text or HTML format. If you do ot specify the message body, Notificatio Aget seds the default body for status otificatio messages (see Default Notificatio Messages o page 128). 6 (Optioal) Add the curret values of specific item property fields to the subject lie or message body usig the appropriate Isert Referece butto. a Click Isert Referece. b From the resultig Select a Referece dialog, select oe or more property field ames. Usig StarTeam Workflow Desiger 65

66 Cotrollig the Behavior of a Item i a Step c Click OK to retur to the Status Notificatio tab. For each property field you selected, a referece appears i the subject lie or message body. For example, if you selected the Etered By field, the referece toke {{property ame="eteredby"}} appears. (EteredBy is the iteral ame for the Etered By property.) Whe the message is set, the toke is replaced with the ame of the team member who etered the item. 7 (Optioal) Click Preview HTML to see how the body of your message would appear i a browser widow. 8 Click OK or aother tab. Maagig Exceptios Use the Exceptio Notificatio tab o the Edit Step dialog to specify the recipiets for otificatio messages to be set if: The curret step does ot reach completio as expected (for example, if a timed step is ot fiished withi the specified duratio). No oe accepts resposibility for a item at a particular step. The exceptio messages are geerated by Notificatio Aget based o the above ad o system errors. These messages vary accordig to the exceptio that occurred, ad caot be modified. Notificatio Aget seds oe message to all the users i the exceptio otificatio list simultaeously. See Default Notificatio Messages o page 128 for more iformatio. To create a exceptio otificatio list: 1 I the workspace, double-click a existig step. 2 From the resultig Edit Step dialog, click the Exceptio Notificatio tab. 3 Add ay umber of idividual users, user groups, ad refereces to the Exceptio Notificatio List. Specifyig a referece adds to the list oe or more user ID fields. The user whose ID appears i the refereced field at the time a item eters this step will be added to the list. These users ad groups are from the server cofiguratio. a To add all users simultaeously: 1 Click the All Users butto to add all users to the list. 2 Click OK to cofirm this decisio because it will empty ay curret etries i the Exceptio Notificatio List. 3 The word Everyoe appear i the Exceptio Notificatio List. There is o eed to add idividual users, groups, or refereces. b To add oe or more users: c 1 Click the Add Users butto ext to the Exceptio Notificatio List to add users to the list. 2 From the resultig Select Notified Users dialog, select oe or more users. 3 Click OK to retur to the Exceptio Notificatio tab. The selected users appear i the Exceptio Notificatio List. To add oe or more user groups: 1 Click the Add Groups butto to add groups to the list. 2 From the resultig Select Notified Groups dialog, select oe or more groups. 3 Click OK to retur to the Exceptio Notificatio tab. The selected groups appear i the Exceptio Notificatio List. 66 StarTeam Workflow Extesios User s Guide

67 Extedig the Workflow s XML Tip d To add oe or more users by referece: 1 Click the Add Refereces butto to add users to the list. 2 From the resultig Select Refereced Fields dialog, select oe or more user ID fields. 3 Click OK to retur to the Exceptio Notificatio tab. The refereced user ID fields appear i the Exceptio Notificatio List. 4 Click OK or aother tab. Use the Remove butto to delete users, groups or refereces from the list. Extedig the Workflow s XML The Workflow Extesios tab allows you or Micro Focus cosultats to exted the workflow with complex logic for ay of the followig: The etire workflow usig the Workflow Extesios tab i the Workflow Properties dialog A particular step usig the Workflow Extesios tab i the Edit Step dialog For example, you might add features that are ot directly supported by Workflow Desiger. This XML is iserted ito the XML output for the workflow. With additioal codig, the ew XML elemets ca be used by StarTeam Extesios features ad the custom APE forms. Ay XML tags you add will ot coflict with those beig used by the applicatio. Your tags are scoped withi the Workflow Extesios XML elemet so there is o chace of a coflict. To add XML elemets: for a step 1 Do oe of the followig: For a step: I the workspace, double-click a existig step. For the etire workflow: Select Edit > Workflow Properties. 2 From the resultig Workflow Properties or Edit Step dialog, click the Workflow Extesios tab. 3 Type the ew elemets i the text box. 4 Click OK to check the ew XML for errors. Addig ad Modifyig Custom Properties Note Ofte the workflow cotrol property is a custom property that has bee desiged to fit your orgaizatio s process. You ca create ad modify custom properties from Workflow Desiger if you have the correct access rights. It is easier to create custom properties whe you are usig the applicatio because they ca be edited while you create them. See the StarTeam Admiistrator s Guide for more iformatio about creatig custom property fields. Addig a custom property field or makig chages to a existig property field ca cause cofusio for users who do ot use APEs. For example, APEs ad your workflows cotrol what property fields users see ad what workflow property values (ext steps) they ca select, but users of the stadard property dialogs see every field ad every possible value for that field. The iitial default that you set for a ew workflow cotrol property is very importat if you have existig items to be put uder workflow cotrol. For example, if you have Usig StarTeam Workflow Desiger 67

68 Addig ad Modifyig Custom Properties bee usig the applicatio, but without its workflow features, you may have hudreds of items that have ot previously bee uder workflow cotrol. As you create a ew property, these existig items acquire the iitial default value for that ew property. See Chagig Workflow Cotrol Property Values Automatically o page 72 for more iformatio. You ca create a custom eumerated property from the New Workflow Properties dialog ad the Workflow Properties dialog. These dialogs appear as part of the process of creatig a ew workflow or editig a existig workflow s properties. You ca add a value to a eumerated property from the followig dialogs: New Workflow Properties dialog (displayed by selectig File > New). Workflow Properties dialog (displayed by selectig Edit > Workflow Properties). New Step dialog (displayed by selectig File > New Workflow Step). Edit Step dialog s Geeral tab (displayed by double-clickig a step i the workspace). Creatig a New Eumerated Property Cautio Tips After you have diagrammed a ew workflow, you may eed to add a eumerated property to the item type. Usually, the ew property is the workflow cotrol property. For coveiece, Workflow Desiger allows you to create it from withi the desiger. Before you click OK, be sure that the field ame ad codes you select are the oes that you wat. They caot be chaged after you exit this dialog. The display ame ad the values ca be chaged from StarTeam, but ot from Workflow Desiger. To create a eumerated custom field: 1 From the New Workflow Properties dialog or the Workflow Properties dialog, click Add Property. 2 I the resultig Add Eumerated Property dialog, eter the ame for the userdefied field to be used by the database i the Field Name text box. Use oly alphaumeric characters ad o spaces i this ame. The ame should be fewer tha 31 ASCII characters (icludig the Usr_) ad ot cotai these followig characters that are ot accepted by oe or more of the databases that the applicatio supports: = \\.^$@,;!:#*&<>?-//% [](())+" 3 Type the ame that StarTeam will display to users i the Display Name text box. 4 Click Add to eter the first value for this eumerated type. The Add Value dialog appears. The applicatio reserves the umeric codes from 0 to 99, so this dialog shows umbers startig with Use the displayed code or eter aother i the Code text box. 6 Type the ame for this eumerated value i the Name text box. 7 Click OK. 8 Repeat Steps 4-7 to add additioal values. If you create a eumerated code or value icorrectly, click Edit to repair or Delete to remove that value from the list. Whe you are fiished addig values, you ca use drag-ad-drop to rearrage the values i the Possible Values list box. 68 StarTeam Workflow Extesios User s Guide

69 Addig ad Modifyig Custom Properties 9 Select oe of the eumerated values as a default from the Default Value list box. This value automatically becomes the value for this field i all existig items for which this field is a property. It does ot become the default value for ewly created items uless they are created whe APEs are disabled or a APE is used with a disabled workflow. See Chagig Workflow Cotrol Property Values Automatically o page 72 for more iformatio about the importace of the iitial default settig for this ew field. 10 Click OK. Addig a Value to a Eumerated Property Cautio Occasioally, you eed to add a value to a eumerated property. Usually, the ew value is a additio to the workflow cotrol property. For coveiece, Workflow Desiger allows you to add that value from withi the desiger. To add a eumerated value to a custom field: 1 From the Workflow Properties dialog, New Step dialog or Edit Step dialog s Geeral tab, click Add Value. 2 I the resultig Add Eumerated Value dialog, click Add. The Add Value dialog appears. 3 Use the displayed code or eter aother i the Code text box. 4 Type the ame for this eumerated value i the Name text box. 5 Click OK. Before you click OK, be sure that the code ad value are correct. You caot chage them from Workflow Desiger after you exit this dialog. The value ca be chaged from the applicatio. Chagig the Name of the Step Use the Geeral tab to chage the ame of the step, that is, to chage the value of the workflow cotrol property that the step represets. For example, if you have just added a ew value to the workflow cotrol property, you might wat chage the ame of a existig step to match the ew property ame. To chage a workflow step s ame: 1 I the workspace, double-click a existig step. 2 From the resultig Edit Step dialog, click the Geeral tab. 3 From the Step Name list, select aother value as the ame of this step. 4 Click OK or aother tab. Usig StarTeam Workflow Desiger 69

70 Checkig for Errors Whe you ope a workflow that cotais errors or whe you select File > Check For Errors from the meu bar, Workflow Desiger checks for ay ad all errors that could prevet the workflow from executig. First it checks that all of the workflow properties are set ad valid. The it checks each step to verify that all properties are valid. A message box lists the errors ad red questios marks are used to guide you to the problems i specific property dialogs. For example, if you import a workflow that specifies a workflow cotrol property that does ot exist for the curret server cofiguratio, it places a red questio mark o the Form Optios tab of the Edit Step dialog. Specific fields display questio marks whe they are i error i the Workflow Properties dialog. The Edit Step dialog displays questio marks o idividual tabs as well as specific fields. Savig ad Exportig Workflows Savig a workflow to the Projects folder or oe of its subfolders i the server cofiguratio s StarFlow Extesios project is equivalet to deployig that workflow. Micro Focus recommeds that you save workflows to a Test folder i a Test project util it is ready for geeral use. Savig the workflow to the Projects folder or oe of its subfolders makes that workflow available for deploymet, so log as: The ame of its paret folder is the ame of a applicatio project or view The path from the Projects folder to the paret folder represets the project/view hierarchy withi the server cofiguratio. Makig a workflow available for deploymet ca provide workflow steps or stop the use of the workflow. If the workflow was disabled via Workflow Desiger, the the APE will appear but o workflow will be eforced. Usig both eabled ad disabled workflows makes it possible to tur o workflow for a etire project but stop it for specific views. Exportig a workflow allows you to use it i aother server cofiguratio. This feature also allows you to save a workflow that cotais errors. For more iformatio about deployig workflows, see Deployig the Workflow o page 95. Savig a Workflow Whe you save a workflow for deploymet, it is output as item_type.workflow.xml ad checked i to the server cofiguratio you select. You must store it i that cofiguratio s StarFlow Extesios project. The default locatio for workflows is the Projects folder, but you ca select aother folder. No workig file is created for a.workflow.xml file. The file is checked directly ito the applicatio repository. To save a ew revisio of a existig workflow: 1 Do oe of the followig: Select File > Save from the meu bar. Click the Save Workflow toolbar butto. No Save dialog appears as the locatio of this workflow was specified whe you opeed it. 70 StarTeam Workflow Extesios User s Guide

71 2 I the resultig Revisio Commet dialog, eter a commet for this workflow that will appear i the ew revisio s commet field. 3 Click OK. This causes a forced check-i. To save a workflow to a ew locatio: 1 Select File > Save As from the meu bar. 2 I the resultig Save As dialog: a Type a ame for this workflow. b Select a appropriate folder to store it i. 3 Click OK. 4 I the resultig Revisio Commet dialog, eter a descriptio for this workflow. Your descriptio/commet appears i both the descriptio ad commet fields of the saved revisio if this revisio is the first revisio of a ew file. It appears oly i the commet field of the saved revisio of this workflow file is ot a ew file. 5 Click OK agai. If a workflow with that ame already exists i that locatio, you are asked whether the existig file ca be overwritte. Clickig yes causes a forced check-i. Disablig a Workflow Whe you disable a workflow, it is emptied of all XML tags except for a sigle <Disabled/> tag. A disabled workflow turs off the workflow for a specific view whe workflow has bee eabled for the project i which the view resides ad whe the disabled workflow is checked i to that view s folder i the StarFlow Extesios project. If you reope a disabled workflow, you must cofirm that you wat to create a ew workflow i this ow empty.workflow.xml file. To create a disabled workflow: 1 Select File > Save As Disabled from the meu bar. 2 Click Yes whe a message asks you to cofirm. 3 I the resultig Save As dialog: a Type a ame for this workflow. b Select a appropriate folder to store it i. 4 Click OK. 5 I the resultig Revisio Commet dialog, eter a descriptio for this workflow. Your descriptio/commet appears i both the descriptio ad commet fields of the saved revisio if this revisio is the first revisio of a ew file. It appears oly i the commet field of the saved revisio of this workflow file is ot a ew file. 6 Click OK agai. If a workflow with that ame already exists i that locatio, you are asked whether the existig file ca be overwritte. Clickig yes causes a forced check-i. Usig StarTeam Workflow Desiger 71

72 Exportig a Workflow You ca export a file to use with aother server cofiguratio. This feature also allows you to save a workflow that cotais errors. To export a workflow: 1 Select File > Export. 2 I the resultig Export Workflow Documet dialog, select a file ame ad locatio. 3 Click OK. Chagig Workflow Cotrol Property Values Automatically You ca covert items, such as chage requests, that existed prior to your use of the applicatio s custom workflow features for use with the ew workflow ad Notificatio Aget by writig a StarTeam SDK script or havig the Professioal Services Orgaizatio from Micro Focus create a script for you. Usig chage requests as a example, such a script would determie the value of the Status property for each chage request ad, based o that value, assig a appropriate value to the ew workflow cotrol property. 72 StarTeam Workflow Extesios User s Guide

73 Chapter 5Walkig Through a Workflow Chapter Workflow Roadmap Workflow Desiger provides a graphical eviromet i which to create ad modify workflows. Workflow Desiger allows you to quickly ad easily create complex customized workflows for your orgaizatio. This chapter walks you through the creatio of a workflow for chage requests. The example illustrates a workflow that deals with iformatio captured from a feedback form o a compay s web site. It is writte primarily for ew users of the applicatio who have o items that were created prior to the use of workflows ad Notificatio Aget. If you are addig the use of these features, see Chagig Workflow Cotrol Property Values Automatically o page 72. For this example, it is assumed that you have istalled or have access to a Starteam Server, a server cofiguratio with a StarFlow Extesios project, StarTeam cliet, Workflow Desiger, ad Notificatio Aget. 1 Create the ecessary StarTeam projects ad folders. 2 Set up appropriate users ad groups for the Server. 3 Pla your ew workflow. 4 Create a custom eumerated property ad values o which the workflow is based. 5 Pla ad create your custom APE form. 6 Create a custom workflow usig Workflow Desiger to specify the steps ad actios of the workflow. 7 Test the workflow to esure that it performs as iteded: Use the Test butto i JBuilder to test the form with the workflow. Use the Ru Test butto i Notificatio Aget to check the otificatios. Walkig Through a Workflow 73

74 Settig Up Projects ad Files Settig Up Projects ad Files Whe you store custom forms ad workflows i the applicatio repository, they must be stored i specific projects ad folders. The cliet locates these projects ad folders ad uses the appropriate files to apply your customizatios to the appropriate items. I this example, you create a Test project ad a Test folder i the StarFlow Extesios project to store the Test project s workflow ad APE files. To create a StarTeam project amed Example: 1 Use the ew project wizard to create the Example project i your server cofiguratio. To create a Example folder i the StarFlow Extesios project: 1 Ope the StarFlow Extesios project. 2 Create a Example folder as a child of the Projects folder. You will store the custom forms ad workflows to be used i the Example project here. The project i which the workflows ad APE forms are to be used ad the folder i which they are stored must have the same ame. Settig Up Users ad Groups For this example, you will eed some specific group ad user ames. You ca create users of your choice to populate the ew groups; however, all of them must have a resolvable address. If you eed more details about creatig users ad groups, see the StarTeam Help. Sice you probably have oly oe address at your disposal, all of these users will eed to have your address. You will be able to idetify who has bee otified because their full ames will appear i the . Create the followig users ad groups i User Maager: 1 From StarTeam or its Admiistratio Tool, ope the User Maager dialog. 2 Create the followig groups ad users: Groups: Customer Support group Marketig group Product Maiteace group Product Maagemet group 74 StarTeam Workflow Extesios User s Guide

75 Settig Up Users ad Groups Research ad Developmet group Testig group Users with the followig full ames: Put these users i the groups that match their ames. Customer Support Perso 1 Marketig Perso 1 Product Maiteace Perso 1 Product Maagemet Perso 1 Research ad Developmet Perso 1 Testig Perso 1 Testig Perso 2 Additioal users with the followig full ames: Do ot put these users i ay group other tha All Users. Customer Liaiso EM Geeral Maager Notificatio Aget PM QA Maager The example illustrates a workflow to deal with iformatio captured from a feedback form o a compay s web site. Whe feedback comes i, team leaders must be otified that ew feedback has etered the system. If the feedback is a suggestio, it is forwarded to the product maager (PM) for review. The PM decides whether to implemet the suggestio. If yes, the feedback is forwarded to the egieerig maager (EM) for assigmet. If the feedback is to report a defect i the product, it is forwarded to the EM for assigmet. The EM assigs the feedback to a egieer. If the egieer does ot ackowledge the assigmet withi 24 hours, the feedback must be assiged to a differet egieer. Whe the egieer is fiished with the assigmet, the EM is otified ad the product chage is set to quality assurace (QA) for testig. If the chage does ot pass testig, it is set back to the egieer. If the ehacemet passes QA testig, the customer, egieerig, ad marketig are otified ad the chage request is closed. Walkig Through a Workflow 75

76 Uderstadig the Example Use Case Uderstadig the Example Use Case Customer geerates feedback Customer Liaiso respods & assigs Is it a suggestio? yes Product maager evaluates o Egieerig maager schedules & assigs yes Should we implemet? Implemet chage Test chage o o Did it pass the test? yes Close the chage request 76 StarTeam Workflow Extesios User s Guide

77 Decidig Which Properties to Use The example workflow process cotrols a chage request (CR) item ad has several possible steps: 1 New. The customer geerates feedback, which is etered ito the system. The team must be otified that a CR has etered the system. The CR is assiged to the Customer Liaiso for review. The Customer Liaiso respods to the customer ad evaluates the CR. 2 PM Evaluatio. If the CR is a suggestio for product ehacemet, it is forwarded to the PM for review. If the PM decides to implemet the suggestio, the CR is set to the EM for schedulig ad assigmet. Otherwise, the CR is closed. 3 EM Processig. All CRs that are to be acted upo must go to the EM for schedulig ad assigmet. 4 Implemetatio. This step has two possible solutios. a Product ehacemets proceed to the research ad developmet (R ad D) group for implemetatio b Defect reports go to Product Maiteace to be fixed. 5 Testig. All chages to the product must be tested by the QA departmet. If the chage does ot pass testig, it s retured to the egieer for more work; otherwise, the CR is closed. 6 Closed. There are three possible states for closed CRs. a If the CR is a suggestio that has ot bee implemeted, the team is otified that the CR is closed ad the customer is set a appropriate thak you ote. b If the CR is a suggestio that has bee implemeted, the team is otified that the CR is closed, the customer is set a appropriate thak you ote, ad Marketig is otified of the product s ew feature. c If the CR is a defect that is fixed, the team is otified that the CR is closed, Customer Support is otified that the problem has bee fixed, ad the customer is set a appropriate thak you ote. 7 Customer Letter. After the Customer Liaiso has set the appropriate thak you letters, the item s workflow cotrol property (Workflow Status) is set to Customer Letter. I additio to these steps, a special etry step must be created for use durig the creatig of ew items. This step is usually amed 0. Etered. For ewly created items, the etry step cotrols what user sees ad ca do. I this example, all ew chage requests will automatically start with a Workflow Status of 1. New because that is what the 0. Etered step will dictate. Decidig Which Properties to Use Before startig a ew workflow, you eed to decide which properties will be required to process chage requests usig your workflow. Directly tied to the workflow are a workflow cotrol property ad a workflow resposibility property. The workflow cotrol property has your workflow steps as its values. Workflow cotrol properties are always eumerated properties. This property ca be created from the applicatio or as part of the process of creatig a ew workflow i Workflow Desiger. The workflow resposibility property cotais user IDs ad allows the work to progress from perso to perso through the workflow. Walkig Through a Workflow 77

78 Numberig the Example Steps Note The Status property for chage requests most closely matches our workflow steps. However, that property cotrols the applicatio s built-i workflow for chage requests, ad caot be used for a custom workflow. A sample chage request APE uses Usr_StarFlowStatus, which has the display ame Workflow Status. For this example, we will use a similar property. It will have the same ame but differet values. The Resposibility property for chage requests most closely fits the eeds of the workflow resposibility property, ad it is ot part of the applicatio s built-i workflow for chage requests. It is the property to use. Whe you create a workflow for the chage request item type, the sample APEs that come with StarTeam Extesios expect the workflow cotrol property to be a custom property amed Usr_StarFlowStatus. You ca use other properties for chage requests, but it requires additioal APEs or additioal customizatio of a sample APE. Numberig the Example Steps To customize the chage request item i the applicatio, add a custom chage request property with the ame Usr_StarFlowStatus, which has the followig values: 0. Etered 1. New 2. PM Evaluatio 3. EM Processig 4a.R ad D Implemetatio 4b.Maiteace Fix 5. Testig 6a.Not Implemeted 6b.Completed 6c.Reopeed 7. Customer Letter While umberig the values that drive the process i this way is ot ecessary, it improves the readability ad maitaiability of the workflows you desig. Creatig a Custom Property to be the Workflow Cotrol Property Importat The workflow cotrol property must be a eumerated property. I this example, it is a custom property which is substitutig for the Status property. You ca create a custom property i StarTeam or i Workflow Desiger. You are more likely to create the property from StarTeam because it offers more support for creatig custom properties. The iitial default that you set for a ew workflow cotrol property is very importat if you have existig items to be put uder workflow cotrol. For example, if you have bee usig the applicatio, but without its workflow features, you may have hudreds of items that have ot previously bee uder workflow cotrol. As you create a ew property, these existig items acquire the iitial default value for that ew property. See Chagig Workflow Cotrol Property Values Automatically o page 72 for more iformatio. 78 StarTeam Workflow Extesios User s Guide

79 Creatig the Custom APE Form Cautio To create a workflow cotrol property: 1 I StarTeam, ope a project i the server cofiguratio. 2 Select the Chage Request tab. 3 Select Chage Request > Advaced > Customize. The Customize dialog lists the fields that ca be customized: 4 Click Add. The Add Field dialog appears. 5 Type StarFlowStatus to create a custom field with the ame Usr_StarFlowStatus. 6 Type Workflow Status, the ame that StarTeam ad Workflow Desiger will display to users i the Display Name text box. 7 Click Add to eter the first value for this eumerated type. The Add Value dialog appears. The applicatio reserves the umeric codes from 0 to 99, so this dialog shows umbers startig with Use the displayed code. 9 Type 0. Etered i the Name text box. 10 Click OK to retur to the Add Field dialog. 11 Repeat steps 7 10 usig the followig code ad ame combiatios: New PM Evaluatio EM Processig 140 4a. R ad D Implemetatio 150 4b. Maiteace Fix Testig 170 6a. Not Implemeted 180 6b. Completed 190 6c. Reopeed Customer Letter 12 Select 0. Etered as a default from the Default Value list box. This value automatically becomes the value for this field i all existig items for which this field is a property. It does ot become the default value for ewly created items uless they are created whe APEs are disabled or a APE is used with a disabled workflow. 13 Click OK. Before you click OK, be sure that the field ame ad code umbers are the oes that you wat. They caot be chaged after you exit this dialog. Later, you ca chage oly the display ame ad the ames of the eumerated values. Creatig the Custom APE Form This sectio provides a overview of the procedure for creatig the form used i the example workflow. Before you begi, verify that JBuilder (or the Java developmet eviromet of your choice) is istalled ad properly cofigured to work with the applicatio. See Cofigurig JBuilder to Use StarTeam JavaBeas o page 21 for more iformatio o usig JBuilder to customize applicatio forms. To create a form: 1 Copy the files located i C:\Program Files\Borlad\ StarFlow Extesios\ Samples\ ChageRequest folder o your workstatio to the workig folder for the StarFlow Extesios\Projects\Example folder (for example, C:\cofig_ame\StarFlow Extesios\Projects\Example). Walkig Through a Workflow 79

80 Creatig a Workflow Creatig a Workflow 2 Start JBuilder ad ope the ChageRequest.jpx JBuilder project file ow located i the Example folder. View ChageRequestForm.java (double-click the file ame i the pae o the upper left of the widow). 3 Click the Desig tab at the bottom of the cetral pae. A sample Chage Request form appears i the Desig widow. 4 Experimet with addig oe property that is ot already there. 5 Choose File > Save from the meu ad save the form with the same ame (ChageRequestForm.java) 6 Create the.jar file by selectig the Project > Make project_ame commad usig the meu bar. 7 If you are usig JBuilder Professioal Editio, ru the Makeproject_amejar.bat file to complete the creatio of the.jar file. 8 Check i the ew form.jar ad.propertyeditor.xml to the StarFlow Extesios\ Projects\Example folder. Now that you have the form, groups, users, ad properties that you eed, you are ready to create the workflow. To create the workflow: 1 Start the Workflow Desiger by choosig Start > Programs > StarTeam > Workflow Desiger from the Start meu. 2 I the Workflow Desiger widow, choose File > New from the meu bar. 3 From the resultig New dialog: a Select a server cofiguratio. b From the Log O dialog, log o usig a valid user ame ad password. c Click New. 4 From the resultig New Workflow Properties dialog: a From the Item Type list, select ChageRequest. b From the Workflow Resposibility list, select Resposibility, which is the default. c I the Workflow Cotrol Property list, select Workflow Status, which is the default. 5 From the Etry Step list, select 0. Etered. 6 Click OK. The 0. Etered step has bee draw for you i the upper left corer of the workspace, but you must set properties for that step. 80 StarTeam Workflow Extesios User s Guide

81 Creatig a Workflow Creatig the Steps ad Liks I the ext few sectios, you create the steps of your workflow ad lik them. The followig table summarizes the step properties for the 0. Etered step. Because the etry step is umbered ad amed appropriately, the item will be automatically forwarded to the ext step i the workflow by the workflow egie. No participat list or otificatio list is ecessary. I geeral, you will oly set form optios ad specify the ext step for the etry step. You may also set dyamic defaults i the etry step. Tips Drawig the 1. New Step You ca draw steps maually i the workspace. I the followig procedure, you draw the 1. New step. To create a step: 1 I the workspace, do oe of the followig: Choose File > New Workflow Step from the meu bar. Click the Add New Workflow Step toolbar butto. The mouse poiter chages to a cross-hair. 2 Usig the mouse, click ad drag i the workspace to defie a rectagle. Whe you release the mouse butto, the New Step dialog opes. 3 From the New Step dialog: a Use the Step Name list to select the ame of oe of the workflow cotrol property s eumerated values as the ame of this step. I this case, you select 1. New. b Click OK. A ew step with the ame 1. New appears i the workspace. You ca resize ad alig the step at ay time. To draw a step for each value i the workflow cotrol property all at oce, use Edit > Create All Steps. The steps form a cascade i your workspace. You ca also copy a existig step (except for its liks) by right-clickig the step to display a right-click meu ad selectig Copy Step. To place the ew step, rightclick a locatio i the workspace ad select Paste Step from the right-click meu. Likig the Two Steps Maually Whe you draw liks maually i the workspace with your mouse, you ca start ad ed the lik at a variety of locatios o ay edges of the steps. Maually addig a lik from oe step to aother automatically affects the iformatio i the Next Steps tab of the Edit Step dialog for the step beig trasitioed from. The ame of the step beig trasitioed to is added to the list of steps for the <otherwise> value. The <otherwise> value specifies the steps to which the item is liked (ad, therefore, the values to which the item ca trasitio) whe o coditios exist or o coditios are met. Walkig Through a Workflow 81

82 Creatig a Workflow Whe oly a <otherwise> value exists i the Next Steps tab, the lik is ot dotted because the lik is ot coditioal. To maually create a lik from oe step to aother i the workspace, do oe of the followig: Click the edge of the 0. Etered step. This immediately liks the selected step with the step closest to it uless that step is the etry step. I this case, it creates a lik to 1. New. Click-ad-drag a lik from the edge of the 0. Etered step to the edge of 1. New. Whe you release the mouse butto, the lik appears. Agai, you caot drag a lik to the etry step. Editig the 0. Etered Step The etry step is the poit at which the item to be cotrolled eters the workflow. Each workflow must cotai a etry step; ad the etry step should be amed 0. Etered to be processed properly by the workflow egie. Like the ames of all steps, this step s ame is oe of the possible values for the workflow cotrol property. The etry step is a special pass-through step. That is, as a user creates a item, the APE uses the step properties for the 0. Etered status to cotrol: The iitial optios for form fields (that is required, hidde, or disabled). The values that ca be selected for the workflow cotrol property at the time that the item is created. For example, as a user creates a chage request, the oly values that ca be selected for the workflow cotrol property are those specified for the O. Etered step o its Next Steps tab. 0. Etered is ever used as a Next Step for ay workflow step. That meas that users caot select 0. Etered as the value for the workflow cotrol property. 0. Etered ca have o liks directed to it oly from it. Because o item ever displays this status, there is o reaso to set otificatios, participats, dyamic defaults, or a duratio for this step. They will ever be eforced. While 0. Etered is ever the selected value for the workflow cotrol property i the APE, there always is a selected value. This ca cause some iitial desig cofusio. As you create the settigs for steps that correspod to values of the workflow cotrol property, be aware that, whe a user creates a item, settigs assiged to both 0. Etered ad the step that correspods to the curretly selected value of the workflow cotrol property affect the workflow. For example, suppose that the oly Next Step for 0. Etered is 1. New. As the user creates a ew chage request, the default value (i fact the oly possible value) for the workflow cotrol property is 1. New. However, the form field settigs assiged to both the 0. Etered ad the 1. New steps affect the APE. If 0. Etered requires the Syopsis, Severity, ad Type fields ad the 1. New step requires the Platform field, all four fields will be required as the user creates a ew chage request. Notificatios, participats, dyamic defaults, ad duratio come oly from the 1. New step. 82 StarTeam Workflow Extesios User s Guide

83 Creatig a Workflow Because this is a ucoditioal lik from 0. Etered to 1. New, you ca draw the lik maually i Workflow Desiger. Creatig the lik maually automatically sets the <otherwise> value to have the ext step of 1. New. Table Etered Field Geeral Tab Step Name Limit Step Duratio Participats Tab To Exceptio Notificatio Tab To Step Notificatios Tab To Form Optios Tab Field Name Settig Field Name Settig Field Name Settig Status Notificatio Tab To Next Steps Tab* Coditio Next Step Dyamic Defaults Tab Workflow Extesios Tab Workflow Extesios Value/Notes 0. Etered cleared <leave blak> <leave blak> <leave blak> Severity Required Syopsis Required Type Required <leave blak> <otherwise> 1.New <leave blak> (ot available with iitial step; the Workflow Status field is ever set to 0. Etered; Dyamic Defaults apply oly to the curretly selected status i the Workflow Status field) <leave blak> To edit the step: 1 Double-click i the iterior of the step. The Edit Step dialog opes. 2 Click the Form Optios tab ad set the Severity ad Type fields to Required by activatig the check box i the Required colum for each field. 3 Click the Next Steps tab ad set the <otherwise> coditio to step 1.New. a Select <otherwise> i the Values list. b Click Add Steps. The Select Next Steps dialog opes. c Select 1. New ad click OK. 4 Click the Dyamic Defaults tab ad specify that if the Severity property is set to High, the the value of the Priority property should be set to Yes. a I the Property list, click Add. The Select Property dialog opes. b Select Severity from the list of properties ad click OK. c Select Severity i the Property colum. d I the Whe Equals Value colum, click Add. The Select Coditio Value dialog opes. Walkig Through a Workflow 83

84 Creatig a Workflow e f Select High as the value ad click OK. Select High i the Whe Equals Value list. g I the Assig Values To Other Properties colum, click Add. The Select Property ad Value to Assig dialog opes. h Select Priority as the property ad Yes as the value, the click OK. 5 Click OK to close the dialog whe you are doe. Notice that the 1. New step ad the lik betwee 0. Etered ad 1. New have bee draw for you. You could have draw the two steps ad liked them by clickig the edge of the 0. Etered step ad draggig the lik to the 1. New step because the two are liked ucoditioally. However, coditioal liks must be created i the Next Steps tab of the Edit Step dialog. Editig the 1. New Step Step 1. New is always processed by someoe i the product maagemet group. The user who accepts resposibility at this step must set the Type to either suggestio or defect. From step 1. New, there are two possible trasitios: defects go directly to the egieerig maager (EM) for assigmet, while suggestios go to the product maager (PM) for evaluatio first. I this example, the trasitio to step 2. PM Evaluatio is coditioal, based o Type = Suggestio ad usig the default <otherwise> coditio for the trasitio to step 3. EM Processig. Implemetig a <otherwise> coditio assures that a item ca always trasitio to some ext step. At rutime, the user will be preseted with a sigle choice for the ext step. If the item is a suggestio, the oly choice will be to proceed to step 2; if the item is aythig other tha a suggestio (a defect), the oly choice will be to proceed to step 3. Try editig this step o your ow from the followig summary. Table New Field Geeral Tab Step Name Limit Step Duratio Duratio Relative To Participats Tab Notificatio Type To Authorized Exceptio Notificatio Tab To Step Notificatio Tab Importace Notificatio Iterval Subject Body Value 1. New Selected 4 days <leave blak> Radom Product Maagemet group Product Maagemet group PM Admiistrators group Referece to curret value of Resposibility property PM Normal 12 hours Use the default step otificatio message. Use the default step otificatio message. 84 StarTeam Workflow Extesios User s Guide

85 Creatig a Workflow Table New (cotiued) Field Value Form Optios Tab Field Name Platform Settig Required Status Notificatio Tab To <leave blak> Next Steps Tab Coditio Type Value Suggestio Next Steps 2. PM Evaluatio Coditio <otherwise> Next Steps 3. EM Processig Dyamic Defaults Tab Property Severity Whe equals value High Assig Property: Value: Priority Yes Property Severity Whe equals value <otherwise> Assig Property: Value: Priority No Property Workflow Status Whe equals value 1. New Assig Property: Value: Commet Status is 1. New Workflow Extesios Tab Workflow Extesios <leave blak> Creatig Next Steps for 1. New Use the Next Steps tab to specify oe or more steps to follow the curret step i the workflow ad the coditios that gover the movemet of the item from this step to the ext. Specifyig coditios for a step s trasitio govers the choices that appear to users whe they complete the step. For example, the example workflow specifies that all suggestios are to be reviewed by the product maager before they are set to egieerig, while all defects are set directly to the egieerig maager. The logic for the Next Steps dialog is: If Type = Suggestio the Next Step = 2. PM Evaluatio <otherwise> Next Step = 3. EM Processig If the Type is set to Suggestio, the oly possible ext step, ad the oly choice preseted to the user, is step 2. For all other values of Type, the oly possible ext step is step 3. I this simple example, the ext steps could just as easily be specified as: If Type = Suggestio the Next Step = 2. PM Evaluatio If Type = Defect the Next Step = 3. EM Processig yieldig the same result from the user s perspective. However, if values are ever added to the Type property ad correspodig coditios are ot added to the workflow step, a item with the ew value for Type will ot be able to trasitio from this step to ay other. Walkig Through a Workflow 85

86 Drawig the Rest of the Steps So, it is ot ecessary to specify a <otherwise>, or default, coditio for the trasitio if the values of the coditioal property are accouted for. However, specifyig a <otherwise> coditio safeguards agaist the possibility of a item becomig straded i a step. Micro Focus recommeds that you specify a ext step for the <otherwise> coditio. If you do ot specify a <otherwise> coditio, Micro Focus recommeds that you set a duratio limit for the step so that a exceptio will be raised if the step does ot trasitio withi the specified duratio. Duratio is set o the Geeral tab. If the steps specified as ext steps have ot yet bee draw, Workflow Desiger draws rectagular objects i the workspace to represet these steps automatically. Workflow Desiger deposits the graphical steps i the upper left corer of the workspace, oe o top of aother. You ca move the steps maually or select Layout > Automatic Layout to rearrage them. Drawig the Rest of the Steps As you progress through the assigmet, rearragig automatically geerated steps becomes tedious. It is best to draw a step for each value ow, before proceedig with the rest of the Example exercises. See Drawig the 1. New Step o page 81 for the directios to draw a step. Summary of Other Step Properties The followig sectios cotai tables that summarize the properties for all the other steps i this example. While the workflow cotrol property is amed Usr_StarFlowStatus, its display ame Workflow Status is what you see i property lists. Exceptio otificatio should be set up at every step that has participats, so that someoe is otified whe o oe takes resposibility for a item at a particular step. A exceptio is also geerated if a step does ot trasitio to the ext step i the set time limit (duratio). Try editig these steps etirely o your ow. Some steps are give differet properties to suggest alterate ways of doig the same thig, depedig o your eeds. 86 StarTeam Workflow Extesios User s Guide

87 Summary of Other Step Properties 2. PM Evaluatio Note that either of the two possible trasitios from step 2 are coditioal. The PM will always be preseted with the same two choices for the ext step. Table PM Evaluatio Field Geeral Tab Step Name Limit Step Duratio Duratio Relative To Participats Tab Notificatio Type To Authorized Exceptio Notificatio Tab To Step Notificatio Tab Importace Notificatio Iterval Subject Body Form Optios Tab Status Notificatio Tab To Next Steps Tab Coditio Next Steps Dyamic Defaults Tab Property Whe equals value Assig Property: Value: Workflow Extesios Tab Workflow Extesios Value 2. PM Evaluatio selected 7 days <leave blak> Ordered (does ot matter because there is oly oe participat) PM PM Admiistrators group Referece to curret value of Resposibility property value PM Geeral Maager Normal 4 days <leave blak> to use the default step otificatio message. <leave blak> to use the default step otificatio message. <leave blak> <leave blak> <otherwise> 3. EM Processig 6a. Not Implemeted Workflow Status 2. PM Evaluatio Commet Status is 2. PM Evaluatio <leave blak> 3. EM Processig Both of the trasitios from step 3 are coditioal. If the chage request is a suggestio, the EM s oly optio is to forward the item to R ad D; if the chage request is a defect, the oly optio is to forward the item to maiteace. I this case, the EM ca either set oly the ext step or both set the ext step ad directly assig resposibility to a specific team member. If this is commo practice, you might wat to tur off otificatio. Walkig Through a Workflow 87

88 Summary of Other Step Properties Table EM Processig Field Geeral Tab Step Name Limit Step Duratio Duratio Relative To Participats Tab Notificatio Type To Authorized Exceptio Notificatio Tab To Step Notificatio Tab Importace Notificatio Iterval Subject Body Form Optios Tab Status Notificatio Tab To Next Steps Tab Coditio Value Next Steps Coditio Next Steps Dyamic Defaults Tab Property Whe equals value Assig Property: Value: Workflow Extesios Tab Workflow Extesios Value 3. EM Processig selected 7 days <leave blak> Ordered (does ot matter because there is oly oe participat) EM EM Research ad Developmet group Product Maiteace group Admiistrators group Referece to curret value of Resposibility property EM PM Normal 4 days <leave blak> to use the default step otificatio message. <leave blak> to use the default step otificatio message. <leave blak> <leave blak> Type Suggestio 4a. R ad D Implemetatio <otherwise> 4b. Maiteace Fix Workflow Status 3. EM Processig Commet Status is 3. EM Processig <leave blak> 88 StarTeam Workflow Extesios User s Guide

89 Summary of Other Step Properties 4a. R ad D Implemetatio Whe completed, the user would select Testig as the ext step. Table 5.5 Field Geeral Tab Step Name Limit Step Duratio Duratio Relative To Participats Tab Notificatio Type To Authorized 4a. R&D Implemetatio Exceptio Notificatio Tab To Step Notificatio Tab Importace Notificatio Iterval Subject Body Form Optios Tab Status Notificatio Tab To Next Steps Tab Coditio Next Steps Dyamic Defaults Tab Property Whe equals value Assig Property: Value: Workflow Extesios Tab Workflow Extesios Value 4a. R ad D Implemetatio Selected 10 day <leave blak> Ordered Referece to curret value of Resposibility property Research ad Developmet group Referece to curret value of Resposibility property Research ad Developmet group Admiistrators group EM Normal 24 hours <leave blak> to use the default step otificatio message. <leave blak> to use the default step otificatio message. <leave blak> <leave blak> <otherwise> 5. Testig Workflow Status 4a. R&D Implemetatio Commet Status is 4a. R&D Implemetatio <leave blak> 4b. Maiteace Fix Whe completed, the user would select Testig as the ext step. Table 5.6 4b. Maiteace Fix Field Value Geeral Tab Step Name 4b. Maiteace Fix Limit Step Duratio Selected Duratio 5 day Relative To <leave blak> Walkig Through a Workflow 89

90 Summary of Other Step Properties Table 5.6 4b. Maiteace Fix (cotiued) Field Value Participats Tab Notificatio Type Ordered To Referece to curret value of Resposibility property Product Maiteace group Authorized Referece to curret value of Resposibility property Product Maiteace group Admiistrators group Exceptio Notificatio Tab To EM Step Notificatio Tab Importace Normal Notificatio Iterval 24 hours Subject <leave blak> to use the default step otificatio message. Body <leave blak> to use the default step otificatio message. Form Optios Tab <leave blak> Status Notificatio Tab To <leave blak> Next Steps Tab Coditio <otherwise> Next Steps 5. Testig Dyamic Defaults Tab Property Workflow Status Whe equals value 4b. Maiteace Fix Assig Property: Commet Value: Status is 4b. Maiteace Fix Workflow Extesios Tab Workflow Extesios <leave blak> 5. Testig All of the trasitios from step 5. Testig are coditioal. If the item is a suggestio, the user may either close the item or sed it back to Research ad Developmet for additioal work. If the item is a defect, the user may either close the item or sed it back to maiteace for additioal work. Dyamic defaults are used to direct a faulty implemetatio or fix back to the egieer who set it to test. This is aother case i which users would prefer to have otificatio tured off to avoid redudat messages. Table Testig Field Geeral Tab Step Name Limit Step Duratio Duratio Relative to Participats Tab Value 5. Testig Selected 2 days <leave blak> 90 StarTeam Workflow Extesios User s Guide

91 Summary of Other Step Properties Table 5.7 Field Notificatio Type To Authorized Exceptio Notificatio Tab To Step Notificatio Tab Importace Notificatio Iterval Subject Body Form Optios tab 5. Testig (cotiued) Status Notificatio Tab To Next Steps Tab Coditio Next Steps Dyamic Defaults Tab Property Whe equals value Assig Property: Value: Assig Property: Value: Workflow Extesios Tab Workflow Extesios 6a. Not Implemeted Value Radom Testig group Testig group Admiistrators group Referece to curret value of Resposibility property QA Maager EM Normal 12 hours <leave blak> to use the default step otificatio message. <leave blak> to use the default step otificatio message. <leave blak> QA Maager <otherwise> 6b. Completed 6c. Reopeed Workflow Status 5. Testig Commet Status returs to 5. Testig Addressed By Curret User <leave blak> If a suggested chage request has ot bee implemeted, the appropriate users ad groups are otified that the chage request is closed ad the customer is set a appropriate thak you ote. Letters to be geerated to customers are ot set from the applicatio, although the templates for them may be stored i the applicatio. The Customer Liaiso otices this step s completio ad is expected to sed the appropriate letter ad move to the fial step, which is Customer Letter. Table 5.8 6a. Not Implemeted Field Value Geeral Tab Step Name 6a. Not Implemeted Duratio 2 days Relative to <leave blak> Participats Tab Notificatio Type <leave blak> Walkig Through a Workflow 91

92 Summary of Other Step Properties Table 5.8 Field To Authorized Exceptio Notificatio Tab To Step Notificatio Tab To Form Optios Tab 6a. Not Implemeted (cotiued) Status Notificatio Tab To Subject Body Next Steps Tab Coditio Value Dyamic Defaults Tab Property Whe equals value Assig Property: Value: Assig Property: Value: Workflow Extesios Tab Workflow Extesios 6b. Completed Value <leave blak> Customer Liaiso Admiistrators group Referece to curret value of Resposibility property PM Geeral Maager <leave blak> <leave blak> Research ad Developmet group EM Product Maagemet group PM Customer Liaiso <leave blak> to use the default step otificatio message. <leave blak> to use the default step otificatio message. <otherwise> 7. Customer Letter Workflow Status 6a. Not Implemeted Commet Status is 6a. Not Implemeted Resposibility Customer Liaiso <leave blak> If a chage request has bee successfully fixed or implemeted, the appropriate users ad groups are otified that the chage request is closed, the customer is set a appropriate thak you ote, ad Marketig is otified of the product s ew feature. Letters to be geerated to customers are ot set from the applicatio, although the templates for them may be stored i the applicatio. The Customer Liaiso is otified about this step s completio ad is expected to sed the appropriate letter ad move to the fial step, which is Customer Letter. Table 5.9 6b. Completed Field Geeral Tab Step Name Duratio Relative to Participats Tab Value 6b. Completed 2 days <leave blak> 92 StarTeam Workflow Extesios User s Guide

93 Summary of Other Step Properties Table 5.9 Field Notificatio Type To Authorized Exceptio Notificatio Tab To Step Notificatio Tab To Form Optios Tab Status Notificatio Tab To Subject Body Next Steps Tab Coditio Value Dyamic Defaults Tab Property Whe equals value Assig Property: Value: Assig Property: Value Workflow Extesios Tab Workflow Extesios 6c. Reopeed 6b. Completed (cotiued) Value <leave blak> <leave blak> Customer Liaiso Admiistrators group Referece to curret value of Resposibility property value PM EM Geeral Maager <leave blak> <leave blak> Research ad Developmet group EM Product Maagemet group PM Customer Liaiso Marketig group <leave blak> to use the default step otificatio message. <leave blak> to use the default step otificatio message. <otherwise> 7. Customer Letter Workflow Status 6b. Completed Commet Status is 6b. Completed Resposibility Customer Liaiso <leave blak> If a defect has ot bee fixed or implemeted correctly, the chage request must be reopeed. The appropriate users ad groups are otified. Resposibility is reassiged to the perso who addressed the problem previously. Table 0.1 6c. Reopeed Field Geeral Tab Step Name Duratio Relative to Value 6c. Reopeed 2 days <leave blak> Walkig Through a Workflow 93

94 Summary of Other Step Properties Table 0.1 6c. Reopeed (cotiued) Field Value Participats Tab Notificatio Type <leave blak> To <leave blak> Authorized referece to Resposibility property s curret value Research ad Developmet group Admiistrators group Exceptio Notificatio Tab To EM QA Maager Step Notificatio Tab To <leave blak> Form Optios Tab <leave blak> Status Notificatio Tab To Product Maiteace group Product Maagemet group Subject <leave blak> to use the default step otificatio message. Body <leave blak> to use the default step otificatio message. Next Steps Tab Coditio <otherwise> Value 5. Testig Dyamic Defaults Tab Property Workflow Status Whe equals value 6c. Reopeed Assig Property: Commet Value: Status is 6c. Reopeed Assig Property: Resposibility Value: referece to Addressed By property s curret value Workflow Extesios Tab Workflow Extesios <leave blak> 7. Customer Letter This is the fial step. The Geeral Maager (who is Customer Liaiso s supervisor) is otified whe a item moves to this step. Table Customer Letter Field Geeral Tab Step Name Participats Tab To Exceptio Notificatio Tab To Step Notificatio Tab To Form Optios Tab Status Notificatio Tab Value 7. Customer Letter <leave blak> <leave blak> <leave blak> <leave blak> 94 StarTeam Workflow Extesios User s Guide

95 Testig the Workflow Table Customer Letter (cotiued) Field To Next Steps Dyamic Defaults Tab Property Whe equals value Assig Property: Value Workflow Extesios Tab Workflow Extesios Value Geeral Maager <leave blak> Workflow Status 7. Customer Letter Commet Status is 7. Customer Letter <leave blak> Testig the Workflow To test a workflow, you eed to: 1 I StarTeam, create a Test project i your server cofiguratio. (The project ame does ot have to be Test; this is just a example.) 2 Create a Test folder as a child of the Projects folder i the StarFlow Extesios project. See Addig Folders to the StarFlow Extesios Project o page 17, Uderstadig Locator o page 16, ad Savig a Workflow o page Copy the ChageRequest.Workflow.xml, ChageRequest.jar ad ChageRequest.propertyeditor.xml files to the Test folder s workig folder. 4 Check them i. 5 Activate the APE form: a I StarTeam, ope the Test project ad choose Project > Properties from the meu. b From the resultig Project Properties dialog, click the Editors tab. c Select the Use Alterate Property Editor For Chage Requests check box. d Type Locator ChageRequest i the text box uder the check box. e Click OK. 6 Setup ad start Notificatio Aget to moitor the Test project for the correct item type. See Gettig Ready to Use Notificatio Aget o page Use Notificatio Aget s Ru Now butto to simulate movemet from step to step. 8 Correct the workflow if ecessary. Deployig the Workflow Perform the followig steps to activate your workflow i the Example project ow that it has bee tested: 1 I StarTeam, copy the ChageRequest.Workflow.xml, ChageRequest.jar ad ChageRequest.propertyeditor.xml files to the StarFlow Extesios project s Example folder s workig folder. 2 Check them i. Walkig Through a Workflow 95

96 Deployig the Workflow 3 Activate the APE form for the Example project usig the Project Properties dialog. 4 Setup ad start Notificatio Aget to moitor the Example project for the correct item type. Notificatio Aget otifies appropriate users about pedig work, item statuses, ad exceptios that occur i the process. See Gettig Ready to Use Notificatio Aget o page 98 ad Startig Notificatio Aget ad Notificatio Setup o page StarTeam Workflow Extesios User s Guide

97 Chapter 6Usig StarTeam Notificatio Chapter Aget This chapter provides a overview of StarTeam Notificatio Aget ad explais how to: Esure that Notificatio Aget will ru successfully by creatig mailboxes ad user ames ad settig access rights i advace. Set up ad ru Notificatio Aget. Chage the http server port umber, if ecessary. For example, you may be usig the default port (9000) for aother purpose or you might wat to ru multiple http servers. About StarTeam Notificatio Aget StarTeam Notificatio Aget watches the projects, views, ad items cotrolled by workflows ad performs the followig fuctios: Status otificatio If a workflow step requires status otificatio, Notificatio Aget seds messages simultaeously to all the users i the status otificatio list, lettig them kow that a item has reached that workflow step. The otificatio messages iformig users about item status ca be customized. Resposibility otificatio Notificatio Aget esures that users are otified of pedig work. Notificatio messages are set wheever a item uder workflow cotrol eters a step that has a list of participats. The users who are listed as participats for that step are otified, all at oce or i the specified order, depedig o that step s properties i the workflow. Whe a participat accepts a workflow request, the resposibility otificatio process for that step eds. The otificatio messages askig users to accept resposibility for the work ca be customized. Resposibility otificatio messages ow come i the followig types: Those that require a respose Usig StarTeam Notificatio Aget 97

98 Gettig Ready to Use Notificatio Aget Notificatio Aget always seds messages usig the SMTP protocol. It receives messages usig oe of the followig: The Apache HTTP Server IMAP protocol (as i previous releases) POP3 protocol (as i previous releases) You must provide either a Http Server Address or a Mail Store Address so that Notificatio Aget ca process the resposes. You ca provide both addresses. If you provide oly a Http Server Address, Notificatio Aget seds a default message that uses http liks for acceptig ad decliig resposibility. If you provide oly a Mail Store Address, you must also provide Notificatio Aget with a mailbox for your system. Notificatio Aget seds a default message with liks for acceptig ad decliig resposibility. You ca provide both a Http Server Address ad a Mail Store Address. However, this does ot much sese uless you also pla to provide a custom message that will use both http ad liks. I this case, by default, Notificatio Aget will sed the resposibility message that icludes liks. See Settig Up Notificatio Aget to Moitor a Server Cofiguratio o page 102 for more iformatio about settig address optios. You ca provide a custom message usig o liks, liks, or http liks. Custom messages for resposibility otificatio must go i the Edit Step dialog o the Step Notificatio tab. See Specifyig a Notificatio Message ad Iterval o page 61. Those that require o respose Notificatio Aget seds mail messages usig the SMTP protocol. If Notificatio Aget otices that you have provided o Http Server Address ad o Mail Store Address, it seds a default message that requires o respose. You should probably desigate that messages to participats be blasted. This is a Workflow Desiger settig. See Listig the Participats o page 59 for details. Exceptio otificatio Whe a workflow step is ot completed as expected for example, whe a step is ot completed withi the specified duratio, or whe o participat accepts resposibility for a item at this step Notificatio Aget geerates a exceptio message. This message goes simultaeously to the users i the exceptio list for that workflow step. The exceptio message is formed by Notificatio Aget based o the type of exceptio. Notificatio iformatio is logged i files with ames based o whe the files were created, for example, NA log. The log files are stored i Notificatio Aget s istallatio folder. Messages ca be set as plai text for or as HTML (the TomCat http server is istalled alog with Notificatio Aget). Gettig Ready to Use Notificatio Aget Each istace of Notificatio Aget ca moitor oly oe server cofiguratio. That meas that you must ru Notificatio Aget oce for each server cofiguratio to be moitored. Before you ca ru a istace of Notificatio Aget, you must: Create a mailbox i your mail system for the sole use of the Notificatio Istace istace, if you will be sedig otificatio messages that require a respose. 98 StarTeam Workflow Extesios User s Guide

99 Gettig Ready to Use Notificatio Aget Thus, you will use a differet address for each server cofiguratio, as oe istace of Notificatio Aget ca moitor oly oe server cofiguratio. You may eed to request that this mailbox be created by a MIS represetative. If you ru Notificatio Aget o more tha oe server cofiguratio, each server cofiguratio will eed its ow mailbox. Decide what StarTeam user ame ad password will be used by Notificatio Aget. Micro Focus recommeds dedicatig a user licese to Notificatio Aget. However, you ca use a existig user, if you prefer. If you do this: The user must have a address listed i the server s User Maager. Notificatio Aget does ot have to use that user s address, but the user must have oe. If the user ame to be used by Notificatio Aget is that of a team member ad you pla to sed otificatio messages that require a respose, Notificatio Aget must use a differet address. You will ot wat to fill the team member s mailbox with from the Notificatio Aget. For details about addig users, see the StarTeam Admiistrator s Guide. Be sure that the user who rus Notificatio Aget has adequate access rights. See Settig Access Rights for Notificatio Aget o page 100. Decide what to do about items that existed prior to usig Notificatio Aget. Whe Notificatio Aget starts for the first time, it checks all existig items of the specified types i the specified views. After that, it checks oly for items that did ot exist previously ad for those items whose values i the workflow cotrol property field have chaged. You must give each pre-existig item a appropriate value i the workflow cotrol property field. For example, if Closed is a value of the workflow cotrol property for which there is o ext step ad o eed to otify ayoe, Notificatio Aget will give the item o further attetio. You might set most old items to this value. If Fixed is a value of the workflow cotrol property for which otificatio is required, Notificatio Aget seds that otificatio. You might set recet items to this value if you wat to cotiue processig them at the Fixed step i the workflow. For iformatio about a utility that ca be adapted to assist you as you assig values to the workflow cotrol property i pre-existig items, see Chagig Workflow Cotrol Property Values Automatically o page 72. Cosider whether you wat other forms of otificatio to be eabled at the same time as Notificatio Aget. For example, you may wat to tur off otificatio or status tray otificatio. otificatio per server cofiguratio If you eable otificatio, all users will receive whe: A chage request, requiremet, or task for which the team member is resposible is created or modified. For example, a user may eed to fix it or verify a chage request. A topic that has the team member as a recipiet is created or modified. (If a topic has o recipiets listed, o oe receives otificatio.) This type of otificatio is either o for all users or off for all users. This type of otificatio ca be redudat or coflict with Notificatio Aget messages. Redudat example: Suppose Notificatio Aget has bee set up to request users to accept or declie resposibility for a item at a particular step. Suppose that oe user has bee set to that effect. The user accepts resposibility ad receives both cofirmatio from Notificatio Aget ad otificatio from the Server. Usig StarTeam Notificatio Aget 99

100 Settig Access Rights for Notificatio Aget Coflict example: Suppose Notificatio Aget has bee set up to maage resposibility. Suppose that oe user has bee set to that effect. Suppose that aother user forgets to let Notificatio Aget maage the resposibility field ad chages the resposibility for a item maually to the first user. The first user accepts resposibility usig the message from Notificatio Aget. Notificatio Aget otices that the item s resposibility has already chaged. It otifies the first user that it did ot make him the resposible party because the item has already be updated. At about the same time, the Server otifies the first user that he is resposible for the item. This ca be very cofusig for the first user ad ca be avoided if oly Notificatio Aget sets resposibility for such items or if the Server s otificatio is tured off. Status tray otificatio per user: The applicatio cliet otifies you by placig icos i the status tray of the task bar wheever: A chage request that is the user s resposibility is created or modified. A requiremet that is the user s resposibility is created or modified. A task that is the user s resposibility has bee created or modified. A topic (that has the user as a recipiet) has bee created or modified. If a topic has o recipiets listed, o oe receives otificatio. This type of otificatio is tured o ad off per compoet ad per user. There are persoal optios for system tray otificatio i the Widows cliet.??? The Cross-Platform cliet does ot have this fuctioality. Ru Notificatio Aget Setup to idetify each server cofiguratio to be moitored by Notificatio Aget ad to set otificatio properties for that cofiguratio. As part of this process, a Notificatio Aget folder will be added to the server cofiguratio s StarFlow Extesios project. Notificatio Aget uses this folder to store the setup iformatio for the server cofiguratio i a file amed NotificatioAget.cof.xml. This process also creates a serveraddress_port.ac file (for example, orio_49201.ac) for each server cofiguratio. The.ac file cotais the mailbox password but i a ecrypted format. The file is stored i Notificatio Aget s istallatio folder. Settig Access Rights for Notificatio Aget The user ruig Notificatio Aget ad Notificatio Aget Setup must have the followig access rights: At the server level: The server access right Chage user/operatio time. Notificatio Aget eeds this right because it impersoates other users. Whe a user accepts resposibility for a item, Notificatio Aget impersoates the acceptig user as it sets the workflow resposibility property to the ame of that user. The audit log records the actio as if it were doe by the impersoated user. For more iformatio about settig server access rights, see the StarTeam Admiistrator s Guide. The server access right Admiister user accouts Notificatio Aget eeds this right to obtai addresses for users ad other user iformatio. Notificatio Aget caot set the resposibility property for a item to a specific user uless that user (who is beig impersoated by Notificatio Aget) has the correct 100 StarTeam Workflow Extesios User s Guide

101 Startig Notificatio Aget ad Notificatio Setup applicatio access rights. Make sure that the appropriate items ca be accessed by the participatig users. For example, Quality Assurace team members would have most or all of the access rights available for chage requests. To set the resposibility for a chage request to a specific user, that user must have the rights to modify the properties of a chage request, ad so o. The user ruig Notificatio Aget Setup must be able to access the StarFlow Extesios project, create a child folder, ad add a file. At the project level: For the Project ode, set the See object ad its properties right. For the View ode, set the See object ad its properties right. For the Child Folders ode, set the followig rights: See object ad its properties Create folders For the File ode, set the followig rights: See object ad its properties Modify properties See History Set exclusive locks Check i file Check out file Add file Startig Notificatio Aget ad Notificatio Setup Both Notificatio Aget ad Notificatio Setup work oly with the Widows-based Server. They ca be istalled o the same computer as the Server they moitor or aother computer. Whe usig two computers, their times must be sychroized. Locate them o your Start meu at Start > Programs > Borlad StarTeam > Notificatio Aget > Aget ad Start > Programs > Borlad StarTeam > Notificatio Aget > Aget Setup. Idetifyig a Server Cofiguratio A istace of Notificatio Aget ca moitor oly oe server cofiguratio o a applicatio Server. However, you ca ru several istaces o the same computer if you eed to. To fully idetify the server cofiguratio, you must kow: The ame or IP address of the computer o which the cofiguratio rus The port umber for the server cofiguratio The user ame ad password to be used by Notificatio Aget as it logs o to the server cofiguratio The ame ad password for the mailbox created for Notificatio Aget o your mail system for this server cofiguratio The address ad display ame for that mailbox To idetify a server cofiguratio: Usig StarTeam Notificatio Aget 101

102 Settig Up Notificatio Aget to Moitor a Server Cofiguratio Tips 1 Start Notificatio Aget Setup by choosig Start > Programs > Borlad StarTeam > Notificatio Aget > Aget Setup from the Start meu. 2 I the resultig Notificatio Aget Setup widow, choose File> New from the meu bar. 3 I the resultig Select a Cofiguratio dialog: a Click Add Cofiguratio. b I the resultig Add Cofiguratio dialog, idetify the server cofiguratio by: 1 I the Server Address text box, eter the ame or IP address of the computer o which the Server resides. 2 I the Port text box, eter the port umber used to access the server cofiguratio. 3 I the StarTeam User Name ad StarTeam Password text boxes, eter the user ame ad password that Notificatio Aget will use to log o to this server cofiguratio. 4 I the Mailbox ad Mailbox Password text boxes, eter the ame of ad password for the mailbox i your mail system to be dedicated to Notificatio Aget for use with this server cofiguratio. 5 I the Display Name ad Address text boxes, eter the ame ad address for that mailbox. 6 Click OK to retur to the Select a Cofiguratio dialog, which ow displays the server address ad port umber (for example orio [49201] ) as a etry. A.ac file (for example orio_49201.ac) is created for this server cofiguratio ad stored i Notificatio Aget s istallatio folder. You ca click the Cofiguratio Properties butto to chage the settigs that idetify the server cofiguratio or click the Delete Cofiguratio butto to delete a server cofiguratio from the list. Deletig the cofiguratio also deletes the correspodig.ac file. It does ot delete iformatio about the etry (computer/port combiatio) from the NotificatioAget.cof.xml file stored i the server cofiguratio s StarFlow Extesios project. Settig Up Notificatio Aget to Moitor a Server Cofiguratio Before Notificatio Aget ca moitor ay server cofiguratio you idetify, you must set optios for that cofiguratio usig Notificatio Aget Setup. Before you set the optios, esure that: The server cofiguratio is ruig. The StarTeam user ame ad password provided for the cofiguratio are valid. That user ame has access rights that will allow Notificatio Aget Setup to access the StarFlow Extesios project, create a child folder, ad add a file. See Settig Access Rights for Notificatio Aget o page 100. The server cofiguratio already has a StarFlow Extesios project. If the server cofiguratio does ot already have this project, Notificatio Aget will create oe usig a subfolder of Notificatio Aget s istallatio folder as its workig folder. This is ot recommeded. To set or edit moitorig optios. 1 Start Notificatio Aget Setup by selectig Start > Programs > Borlad StarTeam > Notificatio Aget > Aget Setup from the Start Meu. 102 StarTeam Workflow Extesios User s Guide

103 Settig Up Notificatio Aget to Moitor a Server Cofiguratio 2 I the resultig Notificatio Aget Setup widow, choose File > New from the meu bar. 3 I the resultig Select a Cofiguratio dialog, select the etry for this server cofiguratio. 4 Click OK. If the server cofiguratio is ot ruig or the user ame ad password for accessig the cofiguratio are icorrect, you caot set moitorig optios. 5 If this server cofiguratio already has a StarFlow Extesios project, click Yes whe you are asked to create the Notificatio Aget folder i this project. Importat 6 Whe the Notificatio Aget Setup widow displays the optios, click Add to idetify the projects ad views to be moitored. a From the resultig Add Watched Views dialog, select the project, oe or more of its views, ad oe or more item types for Notificatio Aget to moitor. You ca multi-select views ad types or use the Select All Views or Select All Types check boxes to quickly select everythig i the correspodig list box. b Click OK to retur to the Notificatio Aget Setup widow with the specified iformatio displayed. 7 Accept the system default pollig periods or chage them to meet your eeds. a Your Server may have a settig for Iactivity Timeout. If so, both your Miimum Pollig Period ad Maximum Pollig Period settigs should be smaller tha the server s Iactivity Timeout settig. Eter umbers of miutes i the Miimum Pollig Period ad Maximum Pollig Period text boxes. These umbers cotrol how log Notificatio Aget waits before checkig the server for ew items ad chages to the workflow cotrol property ad the resposibility property i existig items. For example, the defaults are 3 ad 30 miutes. Notificatio Aget checks the server every 3 miutes as log as ew ad chaged items are foud. Whe othig is foud, the miimum time is doubled. Notificatio Aget checks the server after a 6-miute wait. If ew or chaged items are foud, Notificatio goes back to checkig every 3 miutes. If othig is foud, the waitig period is doubled oce more ad Notificatio Aget checks the server after a 12-miute wait. This process cotiues as log as the waitig period is fewer tha 30 miutes, the maximum pollig period. I this example, Notificatio Aget would ever wait loger tha 24 miutes (12 miutes doubled), because doublig 24 miutes exceeds the maximum pollig period. b Eter a umber of miutes i the Task Refresh Period text box. This cotrols how ofte Notificatio Aget checks the list of tasks it has created. This value affects how ofte Notificatio Aget checks for exceptios. 8 Eter the http ad mail server iformatio for your istallatio i the Server area. See your system admiistrator if you eed help. a (Optioal) You ca fill the Http Server Address text box for oly oe of the server cofiguratios that ru o the same computer uless you istallatio Notificatio Aget multiple times. With each istallatio, aother copy of the TomCat http server (a product of The Apache Software Foudatio) is istalled. This software is i the cof subfolder beeath istallatio folder. For example, you might have C:\Program Files\Borlad\StarTeam Notificatio Aget_1\cof ad C:\Program Files\Borlad\StarTeam Notificatio Aget_2\cof. Usig StarTeam Notificatio Aget 103

104 Settig Up Notificatio Aget to Moitor a Server Cofiguratio Each copy defaults to port If you use additioal TomCat http servers, each copy must use a differet port umber. If this cofiguratio will use the http server, fill the Http Server Address text box by typig the IP address or ame of the computer o which Notificatio Aget is istalled, followed a colo (:) ad the port umber. Localhost is ot accepted. If Notificatio Aget rus o the orio computer that has the IP address , you ca eter either of the followig: orio: :9000 If the TomCat server for this server cofiguratio uses the default port, which is 9000, you ca omit the :9000. Notes If you eed to chage the port umber for a TomCat http server, see Chagig the Http Server Port Number o page 109. The Http Server Address specified here is the value that will replace the {{{lik_base}}} variable i step otificatio messages ad is where shared files, such as logo image files, should be stored. See the followig URL for more iformatio about TomCat: Leave both the Http Server Address text box ad the Mail Store Address text box empty if: You will create a otificatio that does ot require a respose You wat Notificatio Aget to sed a default otificatio message that does ot require a respose b (Required) All cofiguratios must have the SMTP server ame i the SMTP Server Address text box because Notificatio Aget seds messages usig SMTP. The ame should be followed by a colo (:) ad a port umber. For example, you might use: Exchage:25 Ofte the SMTP server is a Exchage server, although it is usually ot amed Exchage. If the port umber is 25, the default, you ca omit the colo ad port umber. c (Optioal) Eter the ame of the mail store followed by a colo (:) ad the mail store s port umber. For example, you might use: Exchage:110 If the port umber is 110, the default for this Notificatio Aget settig, you ca omit the colo ad port umber. The default port umber for POP3 is 110, ad the default port umber for IMAP is 143. d I the Mail Store Type text box, eter either imap or pop3. The default is imap. Notificatio ca receive messages usig either of these two protocols. This field is igored if you leave the Mail Store Address text box empty. e I the Mail Store Address text box, eter the ame of the folder used by the mail store for icomig mail. The default is ibox. This field is igored if you leave the Mail Store Address text box empty. 9 Idicate the hours durig which Notificatio Aget should sed otificatio . For example, hours of operatio may be 8 A.M. to 5 P.M., Moday through Friday. 104 StarTeam Workflow Extesios User s Guide

105 Settig Up Notificatio Aget to Moitor a Server Cofiguratio Tips The default is 24-7 operatio: Notificatio Aget seds every day of the week from 12 midight to 11:59:59 P.M. a I the Activity Group box, select a day of the week for which the hours of otificatio should be limited to fewer tha 24 hours. By default, Moday is selected. b To replace the 24-hour time iterval with oe or more other itervals: c 1 Select the 24-hour iterval. 2 Click Remove. 3 Click Add. 4 From the resultig Add a Active Iterval dialog, set the appropriate start ad ed times. 5 Click OK. 6 Repeat steps 3 through 6 if you eed additioal itervals for the selected day. To copy the time itervals already specified for aother day. 1 Click Copy. 2 From the resultig Copy Activity Times dialog, select the day to be copied from the drop-dow list. 3 Click OK. 10 Idicate ay holidays o which Notificatio Aget should ot sed otificatio. a I the Holidays portio of the Activity group box, click Add. b I the resultig Add a Holiday dialog, eter the ame for this holiday i the Holiday Name text box. c Select a date usig the caledar. 1 Click >> ad/or << to move the caledar forward or backwards a year at a time. 2 Click> ad/or < to move the caledar forward or backwards a moth at a time. 3 Click the day of the moth. d Select the Recurrig Holiday check box if this caledar date will be a holiday every year. 11 Choose File > Close to close the Notificatio Aget Setup widow. 12 Click Yes whe asked to save your otificatio cofiguratio. 13 I the resultig Revisio Commet dialog, eter a commet about this set of optios. 14 Click OK. Notificatio Aget Setup creates a file amed NotificatioAget.cof.xml ad stores it i the Notificatio Aget folder i the server cofiguratio s StarFlow Extesios project. It uses the revisio commet as either the descriptio or commet for the revisio, depedig o whether this is the first or a later revisio of the file. To remove a row i the Watched Views list, select the row ad click the Remove butto. To export a exact copy of the NotificatioAget.cof.xml file, choose File > Export. Sice every server cofiguratio moitored by Notificatio Aget has a file with this ame, it is a good idea to reame the exported file. Usig StarTeam Notificatio Aget 105

106 Ruig Notificatio Aget Ruig Notificatio Aget If you choose to, you ca ru Notificatio Aget 365 days a year, If you stop Notificatio Aget ad restart, it starts processig the otificatio tasks it missed while it was shut dow. Each istace of Notificatio Aget moitors oe server cofiguratio. You ca ru Notificatio Aget maually or as a service. Ruig Notificatio Aget Maually Notificatio Aget ad Notificatio Aget Setup are separate, but similar lookig applicatios. To ru Notificatio Aget maually: 1 Start Notificatio Aget by selectig Start > Programs > Borlad StarTeam > Notificatio Aget > Aget from the Start Meu. The Notificatio Aget widow opes, displayig a list of server cofiguratios, oe for each.ac file you created as you added server cofiguratios usig Notificatio Aget Setup. 2 Select a cofiguratio. 3 Click Start Aget. After the aget starts, the butto text chages to Shut Dow ad the word Ruig appears beside the cofiguratio s ame. If you use Notificatio Aget Setup to chage the iformatio i a server cofiguratios.ac file, you ca update Notificatio Aget by clickig the Refresh butto. To test otificatio ad workflow processes, you ca use the Ru Now butto. Clickig Ru Now moves a item to the ext workflow step regardless of otificatio times. For example, suppose that Notificatio Aget has just otified the first participat that a item eeds attetio. Clickig Ru Now prompts Notificatio Aget to otify the ext participat without waitig for the step otificatio iterval to expire. See Testig the Workflow o page 95. Ruig Notificatio Aget as a Service May customers ru both the StarTeam Server ad Notificatio Aget as services. Whe ruig the Server ad Notificatio Aget o the same computer, the Server process must start before the Notificatio Aget attempts to start. The best way to accomplish this is to set up a Service depedecy withi Widows. If you are ruig the Server as a service ad Notificatio Aget as a depedet service, you caot shut dow the Server uless the Notificatio Aget service is shut dow first. To avoid depedet servers, some customers ru the Server ad Notificatio Aget o differet computers. Whe usig two computers, you must first sychroize the times o both computers. If Notificatio Aget returs a View Cofiguratio exceptio, the two computers are probably ot sychroized. To ru a istace of Notificatio Aget as a service, do oe of the followig: Modify the commad stored i the NotificatioAgetService.bat file ad the ru the batch file. Copy the updated commad to the DOS commad lie. The example iitially i this file is: 106 StarTeam Workflow Extesios User s Guide

107 Ruig Notificatio Aget Cautio JavaService.exe -istall NotificatioAget "C:\Program Files\Borlad\Java\ Su1.4.1_02\bi\cliet\jvm.dll" -Djava.class.path="C:\Program Files\Borlad\ StarTeam Notificatio Aget\aget.jar";"C:\Program Files\Borlad\StarTeam Notificatio Aget\starteamxx.jar" -Djava.library.path="C:\Program Files\Borlad\ StarTeam Notificatio Aget";"C:\Program Files\Borlad\StarTeam SDK x.x\lib" -start com.starbase.starteam.workflow.narutime. NotificatioAgetFrame - params -service "C:\Program Files\Borlad\StarTeam Notificatio Aget\ localhost_49201.ac" -stop com.starbase.starteam.workflow.narutime. NotificatioAgetFrame -method stopaget -out "C:\Program Files\Borlad\ StarTeam Notificatio Aget\NAService.log" -err "C:\Program Files\Borlad\ StarTeam Notificatio Aget\NAService.log" -curret "C:\Program Files\Borlad\ StarTeam Notificatio Aget" pause This file cotais several complete paths that you may eed to replace with appropriate path ames from your system. Most of these paths are delimited by double-quotatio marks. These paths represet: The path to the Java Rutime Eviromet o your computer. The.bat file uses the followig path as a example. C:\Program Files\Borlad\Java\Su1.4.1_02\ bi\cliet\jvm.dll The class path, which requires two paths The path to the Notificatio Aget.jar file (aget.jar). If you used the default istallatio locatio for Notificatio Aget, this is "C:\Program Files\Borlad\ Notificatio Aget\aget.jar" ad does ot eed to be chaged. The path to the StarTeam Rutime.jar file (starteamxx.jar). If you used the default istallatio locatio for Notificatio Aget, this is "C:\Program Files\ Borlad\ Notificatio Aget\starteamxx.jar" ad does ot eed to be chaged. The library path, which requires two paths The first is very similar to the path to the folder that cotais aget.jar. If you used the default istallatio locatio for Notificatio Aget, this is "C:\Program Files\ Borlad\ Notificatio Aget\aget" ad does ot eed to be chaged. The secod is the path to the folder that stores the Java versio of the StarTeam Rutime file (starteam-sdk.jar). For example, if you used the default istallatio folders, this would be "C:\Program Files\Borlad\StarTeam SDK x.x\lib" as foud i the.bat file. The service path, which is the complete path to the.ac file (Notificatio Aget cofiguratio file) for the istace of the aget beig ru as a service. This is usually similar to the path already i the.bat file ("C:\Program Files\Borlad\ Notificatio Aget\localhost_49201.ac"). The.ac file cotais optios for a specific istace of the aget ad its amig covetio idetifies both the computer ad the port used by Notificatio Aget. The err ad out paths, which are the paths to a output log file. If you used the default path, this would be C:\Program Files\ Borlad\StarTeam Notificatio Aget\ NAService.log as foud i the.bat file followig both -out ad -err. The curret path, which is the path to the Notificatio Aget istallatio folder. This is usually "C:\Program Files\Borlad\ StarTeam Notificatio Aget", as i the batch file. After ruig NotificatioAgetService.bat, this istace of Notificatio Aget rus as a automatic service ad ca be maaged as ay other automatic service. Chages to the registry should oly be made by users who are experieced with the registry. Before makig ay chages always make a backup of the registry. To set up a service depedecy for Widows NT or 2000: 1 Select Start > Ru from the Start meu. Usig StarTeam Notificatio Aget 107

108 Ruig Notificatio Aget 2 Eter Regedt32. 3 Click OK. 4 Select HKEY_LOCAL_MACHINE\SYSTEM\CurretCotrolSet\ Services\ NotificatioAget 5 Select Edit > Add Value 6 Set the Value Name to DepedOService. 7 Set the Data Type to REG_MULTI_SZ. 8 Eter your StarTeam Server Service ame ito the data widow (Example: StarTeamServer-StarDraw). See To fid your service ame: o page 108 for more details. To set up a service depedecy for Widows XP 1 Select Start > Ru from the Start meu. 2 Eter Regedt32. 3 Click OK. 4 Select HKEY_LOCAL_MACHINE\SYSTEM\CurretCotrolSet\Services\ NotificatioAget 5 Select Edit > New > Multi-Strig Value. 6 Set the Value Name to DepedOService. 7 Double-click the DepedOService value to ope the Data widow. 8 Eter your StarTeam Server Service ame ito the Data widow (Example: StarTeamServer-StarDraw). See To fid your service ame: o page 108 for more details. To fid your service ame: Each applicatio service has a service ame ad a display ame. You are probably familiar with the display ames that you have see i the Services applet i the cotrol pael. The DepedOService commad requires the service ame, ot the display ame. 1 Select Start > Ru from the Start meu. 2 Eter Regedt32. 3 Click OK. 4 Select HKEY_LOCAL_MACHINE\SYSTEM\CurretCotrolSet\Services Search the list for ay items prefaced with StarTeamServer All applicatio repositories are i a format of StarTeamServer-RepositoryName. For the StarDraw Repository, for example, the service ame would be "StarTeamServer-StarDraw" Use the service ame you fid here for step 8 of the settig up a service depedecy process. Whe the Notificatio Aget rus, log files are placed ito the istallatio folder "...\ StarTeam Notificatio Aget". Review these logs to determie if the service is workig successfully or ot. Should chages eed to be made to the NotificatioAgetService.bat file to resolve problems, the followig commad will eed to be ru first to uistall the service: JavaService.exe -uistall NotificatioAget You ca use a.bat file or eter the commad at the DOS prompt. Ru the commad from the same locatio as you ra NotificatioAgetService.bat file. If a attempt to re-istall the service fails after a successful uistall, the server should be rebooted to complete the uistall operatio. 108 StarTeam Workflow Extesios User s Guide

109 Chagig the Http Server Port Number Chagig the Http Server Port Number The http server default port umber is 9000, but you ca chage it if ecessary. For example, you may wat to ru more tha oe http server o oe computer ad they eed differet ports. To chage the http server port umber: 1 Stop Notificatio Aget. 2 Each TomCat http server has a server.xml file. As you istall Notificatio Aget, a copy of TomCat is placed a subfolder of the istallatio folder. That folder is amed cof ad, iside that folder, is the file amed server.xml. Ay additioal istallatios of Notificatio Aget result i additioal copies of TomCat ad reside i cof subfolders of those istallatio folders. Each of their server.xml files eeds a differet port umber. 3 Ope server.xml i Notepad or aother text editor. 4 Locate the followig <Coector> statemet: <Coector classname="org.apache.catalia. coector.http.httpcoector" port="9000" miprocessors="5" maxprocessors="75" eablelookups="true" redirectport="8443" acceptcout="10" debug="0" coectiotimeout="60000" /> 5 Chage the port umber to a appropriate umber. For example, if the <Coector> statemet cotaied: port= 9000 you might chage it to: port= Save the modified file. 7 Start Notificatio Aget Setup. 8 Ope the desired cofiguratio. 9 I the Http Server Address text box, eter the ame of the computer, a colo, ad the correct port umber. For example, if the computer ame is orio, you would use orio: Save this cofiguratio. 11 Restart Notificatio Aget or click its Refresh butto. Notificatio Aget will use the ew port umber. Message Sedig ad Exceptio Processig Notificatio Aget costatly moitors project views for items that eed to be processed ad for exceptios i ormal processig. Exceptio messages go to those users or groups listed o the Exceptios tab of the Edit Step dialog for a give workflow step. Exceptio messages are geerated by the system ad caot be chaged. Additioally, exceptio messages are set oly oce ad o further otice is provided. Files Created by Notificatio Aget Notificatio Aget creates the followig server files i the local istallatio folder for server cofiguratios: serveraddress_port.ac Usig StarTeam Notificatio Aget 109

110 Kow Issues for Notificatio Aget This is a cofiguratio file discussed i Gettig Ready to Use Notificatio Aget o page 98 ad elsewhere, for example, orio_49201.ac. serveraddress_port.itemtype_viewid.tsp, for example, orio_49201.chagerequest_13.tsp. Such files are view timestamps used for shuttig dow ad restartig view moitorig processes. serveraddress_port.tasks.dat, for example, orio_49201.tasks.dat. Such files archive the otificatio tasks maaged by this istace of Notificatio Aget It is used whe shuttig dow ad restart view moitorig processes. serveraddress_port.na-date_time.log, for example, NA log Such files are used by Notificatio Aget to log evets ad exceptios. Aother file, NotificatioAget.cof.xml cotais cofiguratio iformatio used by Notificatio Aget per server cofiguratio ad is checked i to each server cofiguratio s StarFlow Extesios project ito a folder amed Notificatio Aget. Kow Issues for Notificatio Aget This sectio covers issues about which you may eed to be aware. Revisio Assumptios Notificatio Aget assumes that oly Notificatio Aget ad the users set by Notificatio Aget are editig (ad, therefore, creatig revisios to) items uder workflow cotrol. If, for example, a third party chages the resposibility for a item to someoe who is authorized to edit it, Notificatio Aget assumes that the resposible perso has already bee otified. Oly Notificatio Aget Should Chage Resposibility Field Notificatio Aget assumes that oly Notificatio Aget ad the users set by Notificatio Aget are editig (ad, therefore, creatig revisios to) items uder workflow cotrol. If a third party chages the resposibility for a item to someoe who is authorized to edit it, Notificatio Aget assumes that the resposible perso has already bee otified. Out-of-Memory Errors from Java Whe you start Notificatio Aget from the Start meu, optios from the otificatio.stjava file are used. This file is i the Notificatio Aget istallatio folder (by default, C:\Program Files\Borlad\StarTeam Notificatio Aget). The optios= parameter i this file is ow set to -Xmx256m, a Java optio used to cotrol memory usage. If you ecouter out-of-memory errors, you may eed to tweak this settig. The documetatio that Su curretly provides about this optio is as follows: -Xmx Specify the maximum size, i bytes, of the memory allocatio pool. This value must a multiple of 1024 greater tha 2MB. Apped the letter k or K to idicate kilobytes, or m or M to idicate megabytes. The default value is 64MB. Examples: 110 StarTeam Workflow Extesios User s Guide

111 Kow Issues for Notificatio Aget -Xmx Xmx81920k -Xmx80m The default cotet of the otificatio.stjava file is similar to the followig: [StJava] class=com.starbase.starteam.workflow.narutime.notificatioagetframe starteam=release_umber test=0 [Java VM] ame=java_versio classpath=istallatio_folder\aget.jar;%classpath% librarypath=%librarypath%;istallatio_folder optios=-xmx256m Usig StarTeam Notificatio Aget 111

112 112 StarTeam Workflow Extesios User s Guide

113 Appedix AStarTeam Extesios Appedix Samples The Samples folder i the default StarTeam Extesios istallatio folder has samples of: APE forms Workflows Tools for the custom toolbar Expect to make modificatios to all of these to suit your orgaizatio s eeds. Sample APEs The sample APE forms cosist of: APE_ame.html The HTML file is used with the JBuilder project file. It is set up to be used as a To Do list. APE_ame.jar The APE s applicatio file. APE_ame.jpx The.jpx file is the JBuilder project file for the form. APE_ame.propertyeditor.xml The.property.editor.xml file cotais details about the applicatio (.jar file). MakeAPE_ameJar.bat This batch file may be used to package the compiled APE as a JAR file if your developmet eviromet does ot support the creatio of JAR files. ReadMe.txt The readme file cotais iformatio that you will eed as you modify the APE file. The followig APE forms are icluded amog the samples. All of them have accompayig source code. StarTeam Extesios Samples 113

114 StarTeam Extesios Samples ChageRequest LikTypeChageRequest LikTypeFile LikTypeRequiremet LikTypeTask LikTypeTopic Requiremet Task Topic Sample Workflows The Workflows folder (istalled as a subfolder of the Samples folder) icludes a sample workflow for each item type, all of them are disabled except the chage request workflow (ChageRequest.Workflow.xml). Each item type that uses a workflow must have a workflow defiitio file amed item_type.workflow.xml. The disabled workflows are: File.Workflow.xml Requiremet.Workflow.xml Task.Workflow.xml Topic.Workflow.xml The followig figure shows a graphical represetatio of ChageRequest.Workflow.xml, as displayed i the Workflow Desiger. It is similar to the built-i workflow that comes with StarTeam chage requests. With Workflow Desiger, you ca completely redesig this workflow by addig additioal steps, chagig the behavior of liks, modifyig the authorizatio, ad addig required, hidde, ad disabled fields to each workflow step. However, if you pla to chage 114 StarTeam Workflow Extesios User s Guide