Creating a Class and Workflow with ArgoUML and ArchGenXML

ArgoUML

ArgoUML is a diagramming tool similiar to Visio, but better cause it's Open Source, and cross platform.  It's a Java thick client application, so you'll need a Java Runtime Environment before you can run it.  Again, I won't cover installation, but once you get it all installed and the ArchGenXML profile configured, fire it up.

Creating the Class

The Class is the business object that will be holding all the information that we'll be collecting from the users.  We define what kind of data we want it to hold, and put in a few configuration parameters, and ArchGenXML and the archetypes framework will create the forms for us.  Hurray for Archetypes!

1. First we're gonna make a package to store all of our classes in.  In the example, it doesn't make much of a difference, but it's probably a good habit to have, so click on the New Package icon on the top of the main diagram area and then click in the diagram area.
   
2. Stretch the corner out to it takes up most of the screen.  On the bottom of the screen, in the properties tab, give your package a name like "ProcessImprovement".
3. Now click on the New Class icon on the top, next to the New Package icon, and click inside of your package.  You've just created a class.  Give it a name like "ImprovementSuggestion".
4. Now we'll start defining some datatype.  The ArchGenXML supports a whole series of Archetype predefined datatypes and they're associated requestor widgets (quick reference).  We're going to keep this real simple and use just three fields:
   
   • Name (String): To hold the user's name, since users need not be logged in in our senerio, this field will allow them to manually enter their name.
   • Suggestion (Text): This will be a basic text area for them to enter their suggestion.  If you wanted to get fancy you could Rich type and allow HTML and the fancy Kupu editor input.
   • ImprovementArea (Selection): This will be a selection list of possible choices.  It will allow the users to select the  area the improvement will impact from a list.
   To add these types, click int the area below the the class name, and enter the name of the field.  Then from the properties tab on the bottom of the screen, select the choose the Type from selector on the right.  Click in the same box on the class to add additional types.  Don't click in the bottom division in the class diagram, that's for methods, not data elements.  Repeat this for the data elements listed above.  Your class diagram should look like this:
   
5. Next we need to put some additional information into the class diagram so that ArchGenXML know how to display the fields, and addition option that we have available to us.  We do that by giving each field tagged values.  Click on the Name field one time to select it, and then click on the "Tagged Values" tab in the bottom pane.  This is where we're going to put our widget and field configuration.  Enter the following Tagged Values in the Name data element:
   
   • widget:label = Your Name
     This is what the form field will be labeled.  If it is not specified, the label will default to the name of that field.
   • widget:description = Enter your name, or 'Anonymous'
     This is the description of the form field displayed on the page.
   • required = True
     Whether or not the field is required.
   • searchable = python: True
     By prepending the entry with "python" ArchGenXML will not process the text that follows, it will just pass it directly.  This entry will ensure that the field can be searched on.
6. Click on the Suggestion field and enter the following Tagged Values:
   
   • widget:label = Your Suggestion
     This is what the form field will be labeled.  If it is not specified, the label will default to the name of that field.
   • widget:description = Enter your improvement suggestion with as much detail as possible.
     This is the description of the form field displayed on the page.
   • required = True
     Whether or not the field is required.
   • searchable = python: True
     By prepending the entry with "python" ArchGenXML will not process the text that follows, it will just pass it directly.  This entry will ensure that the field can be searched on.
7. Click on the ImprovementArea field and enter the following Tagged Values:
   
   • widget:label = Improvement Area
     This is what the form field will be labeled.  If it is not specified, the label will default to the name of that field.
   • widget:description = Enter the area that your suggestion will affect.
     This is the description of the form field displayed on the page.
   • required = True
     Whether or not the field is required.
   • searchable = python: True
     By prepending the entry with "python" ArchGenXML will not process the text that follows, it will just pass it directly.  This entry will ensure that the field can be searched on.
   • vocabulary = python:["Sales", "Help Desk", "Factory Floow", "Other (please specify above)"]
     vocabulary take in a python list, and will make a select list out of it.  It will automatically determine whether it should be a drop down list or a series of radio buttons, depending on how many entries you have.
   This is by no means the limit to the configuration options available.  There are internationalization option, and many other customizations available.  Consult the ArchGenXML documentation for a full list.
8. One last thing before we generate our initial Zope Product.  In the navigation tree in the left hand pane, click on "untitledModel", and give it a name in the Properties pane on the bottom.  Name it "ProcessImprovement".
   
9. Now, save this file as "ProcessImprovement.zargo".  Pull up a command prompt and navigate to that directory.  Make sure that you've added the ArchGenXML directory to your env path, and type the following:

   C:\Sandbox\Plone\Tutorial>ArchGenXML.py ProcessImprovement.zargo
   ArchGenXML 1.4.0-beta2
   (c) 2003-2005 BlueDynamics KEG, under GNU General Public License 2.0 or later
   INFO  Parsing...
   WARNING Empty package: '.:0000000000001DE2'.
   WARNING Empty package: '.:0000000000001DE2'.
   INFO  Directory in which we're generating the files: ''.
   INFO  Generating...
   WARNING Can't build i18n message catalog. Module 'i18ndude' not found.
   WARNING Can't strip html from doc-strings. Module 'stripogram' not found.
   INFO  Starting new Product: 'ProcessImprovement'.
   INFO      Generating package '.:0000000000001DE2'.
   INFO      Generating package 'ProcessImprovement'.
   INFO          Generating class 'ImprovementSuggestion'.
   

   This will have generated a complete Plone Product called "ProcessImprovement". 
   

10. Copy the entire "ProcessImprovement" directory tree into your Plone Products directory.  Restart your Plone service, log in as a user with administrative priviliges, go to the site preferences and click on "Add/Remove Products".
    
    Check the checkbox next to the new Product and click "install".  Congratulation!  You've just built your first custom Plone product!
    
11. You should now be able to navigate to any folder in the Plone website, and add an "improvementsuggestion" content type.  It should look something like this:
    
12. Feel free to go back and add additional content types.  There some really cool ones like "File".  Also toy with the available options for each.  Be sure to poke around the generated code.  We'll be digging into that later on, so get familiar with it now.

Creating the Workflow

The workflow is path through which the Class we just defined travels.  In our case there will be two paths, one of approval and one of rejection.  First we'll draw out the states, then we'll define how one gets from one to the next, and finally will fill in some detail on the process.  We'll be working with a StateChart diagram.  If you're unfamiliar with what one of those is, there is some good basics on StateChart Diagrams here.

1. Go back to AgroUML and the class that we just completed.  Click on the ImprovementSuggestion class, and then select Create->New Statechart Diagram from the top menu.  Click on "(anon StateMachine)" in the left nav tree and give the workflow a name in the Properties tab on the bottom.  Name it "ImprovementSuggestionWorkflow".
2. In the main chart area, add a new "Initial".  It looks like a solid black dot.  Drop it on the left hand side of the workspace, and give it a name (in the Properties tab) of "Creating".
3. Next add a new Simple State (looks like a rounded box with a horizontal line in it) a to the right of the Initial.  Name this one "Submitted".
4. Above and to the right of Submitted, add another Simple State called "Approved".
5. To the right of "Approved", and another Final State (circle with black dot inside of it) called "Complete".
6. Below "Approved", add a Final State called "Rejected".
7. Now click on the Inital and drag a connecting line from it to "Submitted".  Connect Submitted to both "Approved" and "Rejected".  And finally connect "Approved" to "Complete".  The completed diagram should look somthing like this:
   
   Business types LOVE this kinda stuff.  So take a screenshot of this workflow, throw some labels on it and send it off to them right way.  CC your boss, and then followup and ask for a raise.  You deserve it!
   
8. Now we're going to go back and name out state transitions (the connecting lines).  The transistion going into Submitted should be names "Submit", the trans going into Approved should be called "Approve", the trans going into Rejected should be called "Reject" and the trans going into Completed should be called "Complete".  Click on each transition state and set it's name in the Properties tab on the bottom of the screen.
9. We need to define what kind of users can trigger different state transitions.  We have anonymous users to be able to Create (an initial state) and Submit (a state transition) requests, but we don not want them approving.  We want Managers and Reviewer to be able to approve/reject/complete the Suggestions.  But, we want anonymous users to be able to view the requests all the way through the process.
   
   To accomplish this, we'll start by setting the permissions on all the states.  Click on the Submitted state, and go to the Tagged Values tab.  We're going to add a tagged value for each permission on that state and the groups that should have that access.  Add the following tags:
   
   • view=Anonymous
   • list=Anonymous
   • access=Anonymous
   • modify=Manager, Reviewer
   If a Tag is not available you can add it to the list by clicking on the "TD Tag Definition" button on the top of the Tagged Values tab.  After you click the "TD Tag Definition" button, click on the Propeties tab and give the new Tag Definition the name you would like to appear in the list.  Then navigate back to your list of Tag Values for the State.  I needed to add list, access and modify to mine.
10. Go through and give the same Tag Values to the Approved, Complete and Rejected states.
11. Next we'll add "guards" to the state transitions that will define who can, and cannot trigger those state changes.  The first state transistion (Submit) should be available to everyone, so we won't put a guard there, but we will on the rest.  Click on the "Approve" state transition, and find the "Guard" form field in the Properties tab.  Right click in that and select "New" (your only option).  Give the new Guard a name of "Approve", and in the expression field (on the right) enter "guard_roles:Reviewer;Manager".  This will limit that transistion's availablity to those two groups.
12. Do the same for the Reject and Complete state transitions.  Permissions are now done.
13. TODO: Define worklist, and provide clarification about how it functions and what it does.
14. Your workflow is now complete!  Run the same cli as in step #9 of "Creating the Class" section above.
    

    C:\Sandbox\Plone\Tutorial>ArchGenXML.py ProcessImprovement.zargo
    ArchGenXML 1.4.0-beta2
    (c) 2003-2005 BlueDynamics KEG, under GNU General Public License 2.0 or later
    INFO  Parsing...
    WARNING Empty package: '.:00000000000021E3'.
    WARNING Empty package: '.:00000000000021E3'.
    INFO  Directory in which we're generating the files: ''.
    INFO  Generating...
    WARNING Can't build i18n message catalog. Module 'i18ndude' not found.
    WARNING Can't strip html from doc-strings. Module 'stripogram' not found.
    INFO  Starting new Product: 'ProcessImprovement'.
    INFO      Generating package '.:00000000000021E3'.
    INFO      Generating package 'ProcessImprovement'.
    INFO          Generating class 'ImprovementSuggestion'.
    INFO  Generating workflow 'ImprovementSuggestionWorkflow'.
    INFO  Generating workflow script(s).

15. Copy your directory over to your Plone products directory again, restart Plone and go back to the Add/Remove Products section.  The product is still installed, but now will need to be upgraded.  Click the link next to your product to upgrade it.

At this point, you should now be able to create "improvementsuggestion"'s and route them through your workflow by changing their state.  Hurray!