Doco Home Overview Home

Overview of the Timesheet App and Workflows

The concept of workflows is central to developing a Platypus app. This section describes workflows in the context of the tutorial application, Timesheet.

Timesheet App

The sample application is an employee timesheet. Those of you familiar with Enhydra will quickly recognise the timesheet app as a typical Enhydra servlet: It has an HTML front end and is backed by a PostgreSQL database. Like other Enhydra apps, the database may be changed.

The timesheet application can be (and is) used for employee time reporting. Employees can report their activities based on calendar days and run reports to generate their timesheets. Simple, really.

Later additions to this application will involve better reporting capabilities, the ability for supervisors to view others timesheets, etc. Since the application is an Open Source project, we'd like your help!

What is a workflow?

The timesheet app is shown here. Each bubble is a presentation object (including the dashed-line bubbles). A workflow is a string of presentation objects which, in their normal use, are invoked sequentially. (The dashed bubbles aren't displayed to the user. See Commit POs, below, for more details.)

The Welcome PO is the central PO of the app. It has links which lead to each workflow in the app. It is not really part of any workflow. Every page will have a link to the Welcome PO.

The app has five workflows:

AddOneItem
This workflow allows the user to add one (or more) time entries - a project, activity, some details, and a number of hours - to their records for a given day.
The AddOneItemQuery PO gets the date from the user. (The system already has the user's name from when they authenticated themselves, on entry to the system.)
The AddOneItemForm PO gets the data for a single time entry. It allows the user to commit a new time-entry and return to this PO again, or to commit the new time-entry and go to EditWorkItemsForm, with a period consisting of just this day.
EditWorkItems
This workflow allows the user to edit all their time entries in a given period.
The EditWorkItemsQuery PO gets the dates delimiting the period from the user.
The EditWorkItemsForm PO allows the user to edit the time-entries in the period.
The user may commit the changes and see the results displayed in EditWorkItemsResults.
Alternatively, the user may request that the changes be commited, and go into the AddOneItemForm for a given day. This functionality is invoked by clicking the submission button on a day summary line. When AddOneItemForm is invoked in this way, it will return to EditWorkItemsForm after adding a new item, rather than returning to AddOneItemForm again.
ReportPeriod
This workflow displays all the users time-entries in a particular period.
This is the simplest workflow.
AddPerson
This allows a new person to be added to the system.
This is a fairly simple workflow - but the EditPerson workflow has been merged into it. This means that the AddPersonCommit PO has to handle being invoked by EditPersonForm as well as AddPersonForm.
EditPerson
This allows a persons details to be edited.
The EditPersonQuery workflow gathers information to do a database search for the person to be updated.
The database search might return zero, one or many person's records.
If no records are found, the EditPersonList PO redirects to a No-Records-Found PO, which informs the user that no records were found, and allows them to return to their search page, with the FORM restored.
If one record is found, the EditPersonList PO redirects immediately to the EditPersonForm PO.
If several records were found, the EditPersonList PO lists all the records matching the query, with a drill-down link in each record. The drill-down goes to the EditPersonForm PO.
The EditPersonForm PO allows the person's fields to be edited. When it is submitted, it goes into the AddPerson workflow's Commit PO.

The ReportPeriod workflow is the simplest example of a workflow.

Naming conventions for workflows and POs

By convention, a PO is named by the workflow it is a part of, and the role it plays in that workflow. Thus, the ReportPeriodQuery PO is gathers the parameters to the database query used in the ReportPeriod workflow. Likewise, the EditPersonForm PO displays a form which allows the fields of a Person record to be updated (or initialised).

We also have a convention regarding the naming of workflows, although we tend to be more relaxed about it. The prefix of a workflow describes the type of operation done by that workflow, and rest of the name describes what is being operated on. For example, the EditPerson workflow edits a Persons details in the database. Likewise, the AddOneItem workflow adds a new WorkItem record to the database.

We always use word-initial-capital (WIC) names for POs. The role within the workflow is given by one word (eg Query, Form), the workflow may be several words (eg ReportPeriod, EditPerson). Thus, the last capital begins the role, and everything before it is the workflow.

Some more information on workflow and PO naming conventions is here.

Commit POs

"Commit" POs add a new record to the database. We do not display this to the user, for the following reason ...

The pages served by Enhydra are dynamic, and are usually not cached. If the browser redraws the screen (for example, if the browser is resized), the browser resends the request to the server. The server will execute the PO again - and add another, identical, new record to the database if thats what the PO did the first time the page was served. (At least, this is the behaviour we observed, without joy, under Netscape.)

We have found that serving the Commit page with a client-side redirect to the next PO prevents this behaviour.

We don't use a Commit page for database updates, because they only update an existing record. Doing this twice is inefficent, but doesn't cause errors. We decided that occasionaly duplicating a database update was more efficient than always serving the separate Commit page.