A "chautauqua" for developing a Drupal application that tracks employee time off

MamaGubs's picture

I am developing my first module and decided that the application I'm building would make a good case study for learning a lot of aspects of Drupal (including cck, workflow and actions), and so I'm putting it here, with an eye towards posting how I've accomplished the various functionalities, soliciting input for how to approach certain aspects of the application (a few of which are stumping me), and finishing up with a demo and/or webcast of the finished product. I will contribute the module, too, once I figure out how to do that :-). Bottom line - we need learners AND experts in this "chautauqua" to make it a real learning experience. So please jump in and follow along, comment, ask questions, and provide expert opinion!

The application is a time off tracker for a business. An employee can fill out a request (time off request node), specifying the date range and the type of time off (vacation, sick, jury, etc.). Before the request node is saved, however, all the non-weekend/non-holiday days in the range must be presented to the employee with the date, hours (defaulted to 8), and type of time off. The employee can edit these (maybe the first day he'll only be taking 4 hours instead of 8, or maybe one day is a jury day). He will then submit the whole lot.

The request is launched onto a workflow. An email notification is sent to his supervisor, who approves or disapproves the request, with appropriate notifications emailed back to the employee. If approved, the request is also forwarded to HR. After the end date of the time off range, an email is sent to the supervisor with a link to a verification of the time actually taken. Again, that window will contain all the individual days off, including type and hours. The supervisor can update any of this, then click "confirm", whereupon a notification will go to HR, and vacation and sick balances will be updated for that employee.

On the backend, there are employee nodes (attached to users) with vacation and sick balances, and ytd totals of other types of time off taken (e.g. jury, bereavement, fmla). When time is taken, these nodes are updated accordingly. If time off is cancelled, or the employee ended up taking less or more time than requested, this needs to be captured.

A number of views are included in the application. "My time" is for the employee, which shows all time off taken for the current year (or other selected years), along with vacation and sick balances. "My team" and "my group" show the same information, but for every member of a supervisor or manager's team or group. An HR view shows all employees.

That's an overall sketch, and there are all kinds of complexities lurking in this. Such as, how do we determine who is in someone else's team or group, or how can a manager or hr enter a request directly on behalf of an employee, or how do we know if a date is a company holiday?

So, that's the sketch. I'm going to approach this case study using comments for each aspect of this that has to be addressed, so we can segregate them into learnable blocks.


While this sounds like a

eric_sea's picture

While this sounds like a great idea, I have a solution for this that we may be porting over to drupal soon. We should chat about your time table and specific requirements.

Sounds good. Though I'm well

MamaGubs's picture

Sounds good. Though I'm well into the development of this module, I'd sure like to see what you've got cooking. I'll send an email to you directly.

For any others that may be interested in this - I'll post a conclusion here on whether I'll proceed with this or not.


chris.muench's picture

I'm extremely interested in either of the solutions. I'm actually looking into this exact situation. I also need a appoval/disapproval system for change management SAS70 purposes. I'm surprised no one has developed these kinds of modules. I would be more than happy to act as test user or bug person.

Moving forward

MamaGubs's picture

Hi Chris,

That would be great. I'm actually going to be putting considerable time into it this weekend. I did speak with Eric (re: above thread) and he does have a LAMP application that he wants to integrate with Drupal, but I'm going ahead with this chautauqua anyway, for a couple reasons. First is that I've got to finish this application for my company, anyway. Second, I really would like to think it out with the community as a case study for learning Drupal. And I'd love your help in testing it out. So, onward!

User Stories

MamaGubs's picture

First things first. We need to get a handle on what this application needs to do. I have decided to take the agile approach and, after interviewing future users of this project, created a number of "user stories" to describe how this application should work, and prioritized them. As you'll see, this project has a bit more complexity than one might initially assume. I welcome the community to contribute to these.

Aside: I've got these in a "project tracker" application, which I'm also building, and which could become another chautauqua, if this one works out well.

1 - Request time off and approve/disapprove
As an employee I want to create a time-off request and send it to my approver so that I don't have to deal with paper forms, and be notified by email when he approves/disapproves. As a manager, I want to be notified of requests from employees in my group or team. I want to view a list of requests pending approvals and be able to approve or disapprove each request from that view. Only the requestor's manager, department manager or HR can approve a request.

2 - Calendar view of time off
As a manager, I want to see all the time off for my team or group in a calendar format, so that I can quickly see where staff will be out.

3 - Update requests with time actually taken
As an employee, I want to verify that I actually took the time off that was requested, or modify what was actually taken, if it was different from the request, so that I'm not charged vacation or sick time that I didn't take.

4 - Get timely notification of time off taken by employees
As an HR manager, I want to be notified in a timely manner when employees have taken time off so that I can prevent negative vacation and sick balances and provide finance with accurate vacation liabilitiy information.

5 - Decrement vac/sick balances when time is taken
As an HR manager, I want the confirmation of time taken to increment or decrement the vacation and sick balances so that I don't have to update these manually and so they always reflect an accurate balance.

6 - Make changes to request or cancel it
As an employee, I want to be able to make changes to my time off request, or cancel it, in the event that my plans change.

7 - Incomplete workflow report
As an HR manager, I want a report of all past time off requests that are not yet confirmed taken, so that I can follow up and make sure that the workflow for that time off is completed.

8 - Manually adjust vacation and sick balances
As an HR manager, I need to be able to enter time taken manually, without going through the request process, for employees who may no longer be here, or who have gone out without submitting a request, etc., so that the balances are correct for accounting purposes.

9 - View time off and balances
As an employee, I want to see my current vacation and sick balances, time I have taken off for this and previous years, and any open requests.

10 - Day-level granularity in request
(uh oh, one of those user stories that greatly increases the complexity!)
As an employee, I want to be able to specify more complex time off in my request, so that I don't have to submit multiple requests. For instance, I may be taking a week off, but might be working a half day on the first day, or I may have jury duty on one of the days. As an HR manager, I want the employee to specify how many hours he's taking each day and the type, so that I can accurately calculate monthly vacation and sick balances and liabilities when a request spans two months. As a manager, I want to know if an employee is only taking a portion of a day, so that I can plan accordingly.

11 - Disclaimer on balance views
As a controller, I need employees to see a disclaimer when viewing their vac/sick balances so that they understand what that balance includes and does not include (e.g. does it include time approved but not yet taken? Is earned vacation added every day, weekly, monthly?)

12 - Add monthly accruals to vac/sick balances
As an HR manager and controller, I need monthly accrual of vacation and sick to be applied to employee balances at month end. (Note: for a community project, this will need to be configurable - let a properly enabled user choose how often to apply accruals.)

13 - Notification of unconfirmed time off for previous month
As an HR manager or manager, I need a notification of unconfirmed time off for the previous month, so that accounting will have accurate balances for employees for month end processing. The manager should get this notification on the 1st of the month. The HR manager should get the notification on the 4th day of the month. (note: this is related to #7, which would be the view that this notification points to)

14 - Employee balances report
As a manager or HR manager, I need to see a current view of employee vacation and sick balances. This report should show three numbers: 1) the current balance, which includes any accrued time that will be applied at month-end, 2) unconfirmed hours for requests for dates that have passed, and 3) hours for future dates for which requests have been made.

15 - Controller's month end report
As controller, I need to receive a monthly report with all vac/sic balances for all employees, so that I can accurately reflect the liabilities in the books. This report should include the accrued hours that are applied at the end of the month. (Danger, danger! Lights flash, sirens sound. The initial scope for this project was to replace the paper requests that go to HR - HR would still maintain their own system for accounting for employee vacation and sick time and pass this validate. In one innocent use story, the scope expands to take over the HR function. Isn't this fun?)

16 - Adding and managing new employee data
As an HR manager, I need to make sure that new employees are added to the system and their balanced entered correctly, so that they are able to request time off.

17 - Monthly email with link to time taken report
As an HR manager, I want to receive a monthly email with a link to a report that shows me all time taken that month for every employee. It should contain both confirmed time taken, as well as unconfirmed. (note: this is related to a couple of the other stories above, but is different enough that it needs it's own entry)

18 - Yearly reset
As an HR manager, I need the vacation and sick balances to be reset at the end of the year. The vacation should set back to 40 hours if the balance is greater than 40, otherwise leave it as is. Sick back to zero. Probably should include a notification to the employee. Also need to determine when this should be done - manually triggered by HR once books are closed? (note: this will need to be configurable - allow sufficiently enabled user to enter carry-over limits and reset values)

19 - Weekly reminder to followup on incomplete workflows
As an HR manager, I would like a weekly email reminding me to check on incomplete workflows, with a link to the incomplete workflows report. I would like this to be able to switch this reminder on and off.

20 - Allow a time off request to go from approved to submitted status
As an employee, I want to be able to make a change to an approved request and have it go back into the approval process.

Deciding what's in iteration 1

MamaGubs's picture

Whew! It all sounds a little overwhelming. If it weren't raining, I might just decide to slip out and go for a kayak run on the lake. But, it is indeed raining, and there's no sense putting this off.

This is a bit too much to tackle all at once, so we're going to decide what goes into the first iteration. There will always be pain and gnashing of teeth when cutting user stories from an initial release, but it is far better to roll out functionality bit by bit. First, it allows us to get something out the door quickly, and secondly, it is better for user adoption, since it allow the users to learn the application bit by bit as each new piece of functionality is rolled out. Thirdly, it allows our users to change their minds about yet-to-be-implemented user stories once they actually start using the application. It's all about speed and adaptability.

So, we need to identify which of the user stories are "must haves". In the current manual process, the employee submits a paper request form to his manager with a date range, total number of hours and type of time off (vacation, sick, jury, etc.). The manager signs the form (or denies the request while laughing maniacally) and passes it along to HR. The HR manager records the hours in her spreadsheet. If the request spans a month end, she looks at a calendar and applies the appropriate amount into each month based on an 8 hour day (or less for the few part time employees that we have). The HR Manager prepares a monthly report for Finance from her spreadsheet. If an employee wants to know his vacation balance, he asks the HR manager.

The biggest problem is that the paper-based request workflow is cumbersome - employees often forget to put in the paperwork, and managers often forget to pass it along to HR. It is not unusual for HR to get an approved request a couple months after the employee took time off, or to find out that vacation requests that were submitted were subsequently canceled, or less (or more) time was actually taken. This irritates HR and finance alike, as they have to make corrective entries for previous months, and the books are not showing accurate liabilities.

So, our first order of business is to replace the current paper workflow with an electronic workflow, that makes it easier for the employee to submit a request, confirm the amount of time taken, and allows the HR manager to have visibility from the moment the request is made. That means that we can start with implementing only User Story 1 (the electronic workflow), along with a view of requests, filtered depending on who's looking at the list - e.g. my list (employee), my group (manager), everyone(HR). This latter view will become a calendar view later.

Happy, happy. We finally get to start coding!!


freephile's picture

I'd like to have such a module. Great user stories. Please share your code :-)

It's coming!

MamaGubs's picture

I know I've gone silent on this, but that's because I've been heads down getting this app working, which has more complexities to it than I ever envisioned! But I'm nearly there and will publish the app as well as complete this Chautauqua. So stay tuned!


gomezbl's picture

Hi, I would be interested in have a look to you code. I wonder if you are planning to develop one module or a bunch of them to get the functionality you want to get. Tell me!

Agile Drupal Development and more...

One module, but I am also

MamaGubs's picture

One module, but I am also leveraging cck, views, workflow and date modules.

How's it going- can I help?

pinin4fjords's picture

This project would be great to have available- our office has just doubled the amount of paperwork they do for this sort of thing and I'd like to put something together to 'show them the way'. How's it going? I'm happy to help if I can- I've tinkered around and made modules for myself, though I'm not a 'proper programmer'.

Still going ...

MamaGubs's picture

While developing this module, I was also developing an agile project management application in Drupal, which I've been using for this project. It pretty much goes like this: user stories -> design "clips" -> functional tests. User stories tell the story of functionality (see above stories). Each user story is translated into a code design, and may be tweaked as the design progresses, to take into consideration twists and turns that may not have been considered by the user writing the story (e.g. but what if an approver is out - who then approves the request?) The design is the basis for the coding/configuration. Functional tests are written based on the design, and are executed first by the developer, then by two user testers.

I have the designs and code finished for version 1, and am in the process of developer testing.

Then I've got to package the whole thing up as an application (export views, schema, etc.). Right now it's partly in module form (menu items, custom coding, etc) and partly developed within Drupal (content types, views, workflow, etc.)

Then I've got to figure out to contribute the module (read through handbooks, etc) - if I could get an expert mentor in this process, life would be good!

So what I'll do at a minimum is publish the updated user stories, designs and functional tests. I'll try to get that done later today. And maybe I'll switch my attention for the moment away from the testing and work on getting it all packaged up and will solicit your help in executing the tests.

Does that work?

Sounds good

pinin4fjords's picture

Well, I definitely don't fit the description of 'expert mentor' in terms of contributing the module etc. I've got my head around the hooks etc sufficiently to produce my own relatively simple modules, plus some of the AHAH interface stuff, but that's about it. That said, I'm happy to teach myself and help out if no gurus are forthcoming!

But I'll gladly help with any and all testing.

progress on your HR module?

jayacg's picture

hi there!

I was wondering how things were going with your module which sounds just like what I'm looking for in terms of tracking employee holiday, sick leave etc. I'd happily help with testing too!



Hi all, I regret to say that

MamaGubs's picture

Hi all,

I regret to say that I have to abandon this project. I joined a new company that has this functionality as part of its product set, so to continue with this would be a conflict of interest. (and I was having an awful good time with it, too)

Sorry to let you all down, but it is what it is.



just a thought

jayacg's picture

I'm guessing that open-sourcing what you'd already done is going to be a conflict of interests too? If by some miracle it isn't then perhaps others can take up where you left off?


Oh well....

pinin4fjords's picture

Ahh, well that's a shame, but I understand. Maybe it'll be a spur for me to get my head around some of this stuff when I find some time :-).

Good luck,


drupal and HR information management

jayacg's picture

yes that is indeed a shame. Currently the packages out there are either very microsofty and prescriptive or shambly/embryonic and open source. OrangeHRM can be hacked using Firebug (yes it really can!) and the other one (Waypoint?) is pretty young in terms of its road map of basic feature implementation.

I would say that a decent Drupal module for HR would do as well as CiviCRM for membership organisations. If anyone is interested in a collaboration (jon?) let me know :-).



Would love to. But I'm not

pinin4fjords's picture

Would love to. But I'm not nearly strong enough on the Drupal nuts and bolts to do a good job of it I'm afraid- though I'm prepared to hack around and see how far I get :-).

Unfortunately, I really can't

MamaGubs's picture

Unfortunately, I really can't share it at this point. But I did forward this thread to a colleague at my old company who has access to the work that I did, in case he is interested in pursuing it.

Sorry to let you all down. Hopefully, someone will be able to pick it up, because it is a great project.


zeezhao's picture

Hi - please was this shared?

Drupal Dojo

Group organizers

Group events

Add to calendar

Group notifications

This group offers an RSS feed. Or subscribe to these personalized, sitewide feeds:

Hot content this week