Github Repo for Danial, Naveen, and Kevin's Senior Project. Link to drive folder with documentation: https://drive.google.com/a/stanford.edu/folderview?id=0B7PzQ09wI7vcM0VsMTFqWU9NeHc&usp=sharing Login Information: http://easypayroll194.herokuapp.com/ Username: Amazon@gmail.com Password: password
The main file for our project is the views.py file located in payroll/payroll_app. This file has the core functionality of receiving network requests, handling them properly, and returning responses. We chose to use the Django framework for our project, which handled all the routing logic (see payroll/payroll/urls.py to see the url binding), and allowed us to focus primarily on application logic. Our application handles requests in 2 main forms: curl request for those who prefer only a back end and those who want to integrate their existing timekeeping software with our payroll software. We also supply a clean, useful front end similar to our potential competitor quickbooks for those who would rather have just one site for adding data, viewing analytics, and keeping track of pay data. First, let's take a look at the web APIs.
It is completely possible to use our product as a RESTFUL API and never take a look at our front end. We support APIs to add employees, jobs, pay data, and bonuses solely through HTTP POST requests. The routes for these requests start at line 382 of views.py. Each of these methods supports adding data in both JSON format, as well as through csv files. We chose these two formats because many existing frameworks are compatible with JSON, and people often keep their data in excel which is easily convertible to csv. Each of the creating APIs looks at the content-type header of the HTTP Request, and from there forwards the request on to either the JSON or csv utility file. These files parse the data, and create Payroll Objects from them. These objects are instances of classes created through Django's ORM, and allow easy interaction with our sqlite3 database making it so that we never had to touch any sql ourselves. These files also handle data validation and error checking, making sure that improper formatting, as well as duplicate data, triggers an error message.
There is also a way to get payroll data through JSON requests. The data can be retrieved in either a CSV or a PDF file by calling getPayrollData and getPayrollCSV respectively, found in views.py. Both requests must take an employer id and key, that will be authenticated, and an error CSV or PDF will be returned if they are invalid. There are other optional parameters: employee id, employee name, start date, and end date. If an employer decides to not enter an employee id then it is assumed that they would like to get an overview of the pay periods within the time period given. Therefore the pdf format of this view gives the employer simple overview data (namely the hours and pay that an employee received over a period of time). Since the csv’s can also be used for analysis, the csv version gives the employers all the information of each employee’s pay period in a simple grid that makes analysis simple. If an employee id is entered then it is assumed that the employer want’s to see all of that employee’s data, so both the CSV and PDF return the data in a more print and view friendly way. Also if an employee id is entered then the employee name parameter is ignored. If no employee id and employee name are entered, then all employee names are returned. If no start date is entered then all the pay periods up to the end date will be returned. Finally if there is no end date, then it will show all timecards up to that day. To see examples of these curl commands please look at the curl.txt file.
Both the CSV and PDF are built in the file_utils.py folder. The CSV is built through simple string manipulation. The PDF however is first built as a LaTeX file and then converted into a PDF, using the pdflatex command.
After the midquarter demo, we reached out to employers in an effort to learn more about how they interact with their payroll data. We learned that many employers use a web app such as quickbooks that incorporates analytics, and allows users to easily input data. In order for our product to function as a competitive alternative to current offerings, we realized that it was imperative to create a web front end for our project that was sleek, easy to use, and mobile-friendly. To this end, we designed an intuitive web interface that allows users to seamlessly create an account, input different types of data, upload timecards, and download payroll data. Our web application also incorporates basic analytics and powerful search functionality in order to empower employers to gain a more nuanced understanding of their payroll data.
The web experience begins with account authentication. Account creation and login functionality for the system was developed by extending Django's built in user authentication system. Errors messages are stored and displayed using Django's built in sessions framework, and messages middleware. After succesfully authenticating, the user's account information is securely stored in their session, which is used to ensure that users are only able to access and modify their own data. The users are then given access to the application's various pages, which were developed using a variety of libraries and platforms, including JQuery, Bootstrap, and Inspinia's admin theme. See our project proposal for a more complete list of technologies that were used in the design of our application.
####### Front-end Back-end Integration Our front end works by sending post requests to our webserver. We use the security methods built into Django (including encrypted cookies and csrf tokens) to allow the user to securely access their data, and add/modify their employees, jobs, pay data, and bonuses. The post requests go to views.py, and then are routed to the web_utils.py file where the bulk of the logic takes place. The web_utils.py file routes validates the data (returning a helpful error message to the user for any bad data) and stores it in the data base. We support adding employees, jobs, bonuses, and pay data solely through our web interface, and also allow employers to upload their time data from an excel file (xls xlsx format) which is then parsed and added to the database. One key issue that comes up is keeping track of dates. In python, dates can either be timezone aware or timezone unaware. Unfortunately, aware and unaware dates cannot be compared, so there are a few places in the code where there are hacks to make all dates aware so that we can filter our database using the __lte and __gte (less than or equal to and greater than or equal to) options supplied by Django.
In addition to adding data, employers can also use our web interface to view their timecard information. The homepage shows a graph of how much they have spent on payroll over the past year. The code for this is in the index method in views.py and involves filtering the pay periods for each month and summing their total. Also, through the employee tab, the employer can search and/o filter their pay statements based on a number of different optional parameters. The search will first return a row with overview information for each of the employees pay periods. Each of the names in the table is also links that allow the employer to view the details of that employee’s specific pay period. On both the pages, an employer can download the table’s data as a CSV or a PDF file. Our web application uses Javascript code that relies on the JQuery File Download library to request and download a dynamically generated file from our server, using the getPayrollCSVWeb and getPayrollDataWeb commands found in views.py.