Version 2.0 of Shifts-Payforms, in development by STC at Yale.
Fetching latest commit…
Cannot retrieve the latest commit at this time
Basic Guide to Shifts Creator: Adam Bray Contributors/Maintainers: (add your names here :-)) Harley Trung, Michael Libertin, Ryan Laughlin, Ben Somers, Nathan Griffith, Laura Tomas, Derek Zhao, Aashish Manchanda, Kobby Antwi-Boasiako, Cassandra Kildow, Wei Yan, AJ Espinosa, and Bob Qu h1. Introduction Shifts is a program that allows the easy tracking of employees who work scheduled (and even unscheduled) hours in various locations and times. It also offers payform features, allowing automatic logging of when employees work shifts, with the option for adding addition hours worked outside of shifts. There are two sections of the application, one for employees who work shifts, and another for administrators, who manage these employees (Note: administrators can use the application as both administrators and employees, allowing them to perform administrative duties on top of using payforms, shifts, etc.) Let's begin by explaining some of the concepts of the application from an employee's point-of-view. Shift A shift is a scheduled block of time. A shift specifically contains the following info: Who is working? (Each shift has one owner) When are they working? (Start and end time) Where are they working? (Each shift must be in a Location) A shift basically gives ownership of a spot to an employee. They are responsible for working that shift. However, the program allows the option of the employee to file a sub request. Report A shift report is created once a employee(user) signs in, and finalized when the user signs out. It consists of timestamped line items. The first line item records the login IP address and the last logout IP address. Every 10-15 minutes or so the logged-in employee is supposed to add line items to the report. Sub Request When an employee files a sub request for a future scheduled shift, a request is emailed to the people that this employee inputs or everybody that is allowed to take that shift (a group email defined in the Location Group's settings). For example, if John (a senior tech) has filed a request for a sub for his shift in the 'technology troubleshooting office' location, the request is emailed to the address defined for the 'senior staff' Location Group. You would likely want to define this address to be a mailing list that sends to all the senior techs but not the junior techs. Locations Locations are places where you have employees working. Examples might be a front desk, troubleshooting office, or computing cluster. Locations could even be for non-physical locations, where you have a defined staff working, such for tasks. For example, if you have staff who work on tasks such as an on-duty courier, you could define this as a location. Locations have the following properties: Name Short Name (Used in certain display contexts where name lengths should be shorter) Report Email Address (The email address to which reports are sent to. More will be said on reports later on) Priority (More on this in the later) Max and Min Staffing Desired Location Groups Every Location must belong to exactly one location group. Location groups not only serve as logical groupings, but more importantly, are used for access control. Permissions for things like who can work where are set by location group. This may be explained best by exapmle: Say you have two classes of employees, junior staff, and senior staff. You have four locations/positions where you regularly have staffing: a front desk, a courier, an assistant, and a supervisor. If you intend for the assistant and the supervisor shifts to only be staffed by senior staff, you would want to create two location groups. The first group would contain the 'front desk' and 'courier' locations, and the second group would contain the 'assistant' and 'supervisor' locations. You could then define your groups such that only senior staff could sign up for, or work shifts in the 'assistant' and 'supervisor' locations. Location groups have the following properties: Name Short Name Maximum Shift Length Minimum Shift Length Sub Request Email Address Time Slots TODO: explains how time slots are used to allow shifts to be signup-able h2. Implementation We will use Ruby on Rails terminology here to make easier to explain. Each of the headings below corresponds to a model name and its controller name in plural. We try to stick to the RESTful approach. Note that for some controllers (eg subs controller) we do not need all 7 standard actions (index, new, create, edit, update, show, destroy) - try to keep the design simple by not including unnecessary actions and views. Sometimes additional actions are needed. Shift new: a shift sign-up page letting the user choose the start/end times and the location to work a shift in - (admin only) allow selecting users create: takes the submitted form and verify that request shift can be created. Checking the following - is there a time slot open for that period - is there any constraint? E.g. shift too short/too long, the user is exceed the number of shift hours allowed, there is another location that is more important to work for during that time, etc - if a shift is legal, checks if it can be combined to another adjacent shift edit (loc group admin only): allows an admin to change the details of a shift update: similar to create with validation and saving index: show all shifts, maybe restricted to a location or loc group or department destroy (admin only): allows an admin to cancel a certain shift for another user Sub (sub routing should be nested in shift) new: lets a user create a sub request create: validates and saves. destroy (loc group admin only): allows an admin to cancel a sub *note that there is no editing of a sub. one should request an admin to delete it and create a new one Report (report routing should be nested in shift) new: this is the sign in page, it shows the confirmation that the employee wants to log in create: as usual, redirected from new show: display all line items belonging to this report (line items have shift report id) *there is no index/edit/update/destroy Location *only a loc group admin can manage locations Loc Group *only a department admin can manage loc groups *before_validation hooks are used to create/update/destroy permissions associated to creating/updating/desdtroying a loc group (signup vs view-only vs admin) Department/User *only a superuser can manage departments and all users *before_validation hooks are used to create/update/destroy an associated permission User *only superuser can manage all users or department admin can manage all users in that department Role new: let the admin create a new name and a selection of permissions associated to it *only a department admin can manage roles Permission index: display all permissions pertaining to current_department no other CRUD actions necessary because permissions are only created indirectly (when a new log group or new department is created) Time Slot TODO: A lot more is needed here. h3. Admin stuff We have the following before_filter methods that allow us to perform authorization at controllers' level require_superuser require_department_admin require_loc_group_admin h4. Routing shallow routing is used but bear in mind form_for must be treated differently for new and edit. see code (eg view code for loc group) for more information /departments list all departments (require_superuser) /departments/users (or /users) list all users (require_superuser) /departments/:department_id/* (require_department_admin) asterisk here can be lots of things nested under a department such as roles, users, loc_groups, etc /:department_name/* we can actually implement a check for this: if department_name is actually a real department name we treat it just like /departments/:department_id/ thus we can have urls such as /stc/users or /itg/roles or /stc/shifts etc /loc_groups/:loc_group_id/* (require_loc_groug_admin)