Timesheet Application

In this section, we will develop a sample timesheet application using the free fastCode Community Edition. The Timesheet application allows the organization to track employees working and vacation time.

Developing the Timesheet Application

To develop the timesheet application using the fastCode Community Edition, we need to follow three steps:

  1. Develop the timesheet data model
  2. Generate the timesheet application using the fastCode Application Generator, including any add-ons
  3. Download the generated application and make the necessary code changes using an IDE to meet the business requirements

Develop the timesheet application data model

The above diagram shows the timesheet data model. It consists of 9 tables. These tables can be categorized as lookup tables that consist of data that doesn't change often, and transactional tables that consist of data that changes often as end-users use the application.

Lookup tables

The following tables can be considered as the lookup tables for the Timesheet Application.

  1. Customer
  2. Project
  3. Task
  4. Users
  5. Usertask
  6. Timeofftype
  7. Timesheetstatus

As you can see, there are seven lookup tables which consist of mostly static data. These tables are defined below:

  1. Customer - consists of a list of the organization's customers
  2. Project - consists of a list of projects that the organization is working on with each customer
  3. Task - consists of a list of tasks for each project
  4. Users - users of the Timesheet Application. They can take on the role of an employee, a manager, or an admin
  5. Usertask - the list of tasks assigned to a employee. In this application, employees can complete and submit timesheets. An employee completes the daily timesheet by allocating X number of hours to each customer/project/task. The list of tasks available for an employee to fill the hours may be different from those available to other employees. Therefore, an Admin will assign the list of tasks to each user in the employee role, and this information is stored in this Usertask table
  6. Timeofftype - consists of the different types of time offs taken by an employee such as Paid Time Off and Company Holiday
  7. Timesheetstatus - consists of the status types for a timesheet such as open, submitted, and rejected

Transactional tables

The following tables can be considered as transactions tables for the Timesheet Application.

  1. Timesheetdetails - timesheetdetail consists of Customer/Project/Task/Hours completed by an employee. A working day may have one or more timesheetdetails.

  2. Timesheet - a timesheet is composed of one or more timesheetdetails for a period of 2 weeks. For example, if an employee has worked on 4 different tasks each day for two weeks, the number of timesheet details in that 2-week period would be 4 x 10 = 40.

Application Generation

fastCode enables developers to reduce the time to develop a web applications by over 50%. In the current version of the platform, fastCode generates an application from a data model. Once the web application is generated, the developer can access the source code for the front-end and the back-end of the web application, make the remaining changes necessary to meet the business requirements, and deploy the application.

fastCode's Application Generator generates the application's back-end and front-end.

The back-end uses the Java/Spring Boot technology stack and uses an n-layered architecture with ReST controller layer, the application (service) layer, and data access layer. The back-end exposes a ReST API with Create/Read/Update/Delete (C.R.U.D) operations for each database table represented in Java as a Java Persistence API (JPA) entity.

The generated front-end uses Angular/ Angular Material technology stack and will have UI screens that enable the end-user to perform C.R.U.D. operations on the database tables.

Additionally, during the application generation, the developer can specify pre-built add-ons that should be included with the generated application. These add-ons are commonly used functionality in enterprise web applications and accelerate the development of the web application. Some of these add-ons have both a front-end and a back-end, while others have only a back-end.

Generated Application

The generated Timesheet Application does not fulfill 100% of the business requirements of the Timesheet Application. It only takes us to 80+% of the final application. We now needs to add additional functionality to the generated application source code to fulfill all the requirements.

Once you download the generated application (or clone from your GitHub repository) and unzip it, you can run the application using the following command from the unzipped root directory:

Windows - PowerShell.exe -ExecutionPolicy Bypass -File install.ps1

Linux / Mac - ./install.sh

The above command will setup the necessary docker containers for the generated application to run. If you have not chosen reports as an add-on, three docker containers are setup - UI, API, Database. If you have chosen the reports add-on, an addition fourth container is setup for reports.

Once the docker container are running, you can run the application as follows:

https://127.0.0.1:5555

The browser will complain about the self generated SSL certificate. You should instruct the browser to proceed.

https://127.0.0.1:4700 - this will bring up the login screen.

Login with the username "admin" and the password "secret".

The Home page of the generated application is shown below. We will now analyze the generated application and explain how it not yet meets the final requirements.

A single user with an Admin role is created when the application is generated. This also means an Admin role is created, the default set of permissions are created, and the Admin role is assigned these default set of permissions.

Once an Admin logs into the application, he sees the following application side-menu:

The above side-menu consists of the following menus:

  • Language
  • Entities
  • Tools
  • Administration
  • API

Timesheet Application Requirements

We will now describe each menu to understand whether or not it should be displayed to each of the user roles.

Language - This menu allows a user in any role to switch among languages supported by the application. Therefore, this menu can be displayed to all roles.

Entities - The timesheet application has 9 entities. 7 of these 9 entities have relatively static data that doesn't change often and is primarily used as lookup data. When setting up the application for usage by employees, managers, and developers, the Admin fills 5 out of these 7 tables, while the rest of the 2 tables (Timesheetstatus, Timeofftype) are pre-filled by a user in the Developer role.

*Administration - User Management - The Admin uses this menu to create roles (Employee, Manager, Developer, Admin) and assigns the pre-generated permissions to these roles. Next, the admin creates users and assigns them one of these four roles. Therefore, we need to display this sub-menu to users in an Admin role.

We can also choose to display this sub-menu to users in a Manager role in READ-ONLY mode so that they can view the list of users in the system.

Lastly, in addition to setting up the data in the 5 lookup tables, the Admin also sets up data in Timesheet entity that has the following fields:

  • Periodstartingdate
  • Periodendingdate
  • Timesheetstatus
  • Notes
  • Users

Each Timesheet entry, even if it's for the same period (ex: January 1st - January 15th or January 16th - January 31st) is specific to a user and therefore we need to provide user information when creating a Timesheet entry.

Therefore, for the Admin user, we need to display only 6 entities. Out of the remaining three entities, one entity (Timesheetdetails) is used by users in an employee role, and the other two entities (Timesheetstatus, Timeofftype) are used by users in a Developer role.

Administration - Entity Audit - This tool is used by users in the Developer role. Therefore, we don't need to display this tool to users in other roles.

API - This tool is used by users in the Developer role. Therefore, we don't need to display this tool to users in other roles.

Tools - Ad-hoc Reports - Ad-hoc reports may be used by the developer to setup the Cube.js schema files, by the Admin to run reports across all manager and employee data, by managers to run reports on employee data, and by employees on their own data. Therefore, this sub-menu should be displayed to users in all roles.

Tools - Jobs Scheduler - The Jobs Scheduler is used by the Admin to setup jobs and trigger them on a schedule. This sub-menu should be visible only to users in the Admin role

Note: When generating this application, we have also added the Email API and Document Management API add-ons. These add-ons are not visible from the UI because they are APIs and don't have a UI component. Also, this application does not need User Registration and we therefore did not add this add-on when generating this application.

Summary

Developer - Language, 2 entities, Administration/Entity Audit, Tools/Ad-hoc Reports, API
Admin - Language, 6 entities, Administration/User Management, Tools/Ad-hoc Reports, Tools/Jobs Scheduler
Manager - Language, Tools/Ad-hoc Reports
Employee - Language, 1 entity, Tools/Ad-hoc Reports

Once the Admin and the Developer setup the application as discussed above, an employee and a manager should be able to perform the following actions:

Employee

  1. Should be able to create Timesheetdetails for each day.

  2. Should be able to submit a Timesheet for a Timesheet period (1st-15th or 16th to end of month in our sample application) when the Timesheet is in Open or Rejected status

  3. Should be able to set daily reminders to receive an email at a specific time during the day

Manager

  1. Should be able to view a list of timesheets submitted by employees for each specific time period

  2. Should be able to view the details of each submitted timesheet

  3. Should be able to approve or reject each timesheet, providing notes

Missing functionality

Except for action (1) specified above under the Employee, the application does not have the functionality to allow an employee and a manager to perform other actions.

Even for performing the action (1) with the functionality of the generated application, the employee has to do the following:

Employee enters the hours for that day for each task and any hours taken off during the day to create Timesheetdetails entries.

The employee needs to provide the following information to create a new entry for Timesheetdetails.

  • Workdate
  • Task or Timeofftype
  • Hours
  • Timesheet

To enter the information for the Timesheet field, the employee needs to select one of the Timesheets created by the Admin and assigned to the employee.

Secondly, logic has to be added to the Timesheetdetails Create and Update screens that would allow the employee to only enter the information for a Task or Timeofftype fields, but not both.

There are several problems with the above approach:

  1. The Admin has to create Timesheet entries for each period and for each employee, which is an onerous task

  2. The employee has to manually create each Timesheetdetails entry, one after the other. Additionally, the Create/Update screens would not work if the employee enters information for both the Task and Timeofftype fields.

To alleviate the above problems, it would be nice to have a custom UI screen that would do the following:

  1. Allow the employee to enter all the Timesheetdetails entries for each day in a calendar using a single screen

  2. Once the employee saves the entries for the day, automatically create a Timesheet based on the current date and the username of the logged in user. Then, associate the saved Timesheetdetails for the day with the Timesheet.

The above approach saves time for employees in entering Timesheetdetails for each day and eliminates the need for the Admin to manually create a Timesheet for each period and each employee.

In summary, if we add the following additional functionality to the generated Timesheet application, the Admin no longer needs to perform the application setup task of, but needs to perform the other setup tasks previously mentioned. The Developer needs to perform the same setup tasks previously mentioned.

Additional Employee Functionality

  1. Allow the employee to enter all the Timesheetdetails entries for each day in a calendar using a single screen

  2. Once the employee saves the entries for the day, if a Timesheet entity for the period does not exist, automatically create a Timesheet based on the current date and the username of the logged in user. Then, associate the saved Timesheetdetails for the day with the Timesheet.

  3. Should be able to submit a Timesheet for a Timesheet period (1st-15th or 16th-end of month, in our sample application) when the Timesheet is in Open or Rejected status

  4. Should be able to set daily reminders to receive an email at a specific time during the day

Additional Manager Functionality

  1. Should be able to view a list of timesheets submitted by employees for each specific time period

  2. Should be able to view the details of each submitted timesheet

  3. Should be able to approve or reject each timesheet, providing notes

Final Timesheet Application

The final timesheet application that includes the additional functionality described above for employees and managers is available at the following location for your preview:

  1. First visit https://54.226.12.222:5555/ and ask the browser to proceed. You will get a "Whitelabel error page", which is expected and fine.

  2. Go to https://54.226.12.222:4700/

You can login with the following users/credentials

admin / secret

Missing functionality source code

Once the timesheet application is generated using the fastCode Application Generator, the developer can download the source code, open it in IDE, and make the necessary code changes to achieve the full business requirements.

The generated application provides an mechanism to add the additional functionality through extension classes. Currently it supports extending the back-end domain, application, and restcontrollers packages and the front-end account, admin, core, entities, and timesheeet-module modules.

Extending the generated application using these extension classes allows us to update the application with data model changes without having to re-write the source code changes made by the developer to the generated application. This is accomplished by re-generating only the core classes in the back-end domain, application, and restcontrollers packages and the front-end front-end account, admin, core, entities, and timesheeet-module modules and not touching the source code in the corresponding extension back-end packages and front-end modules.

NOTE: At this time, add-ons generated with the application, and other files in the back-end and the front-end do not have extension mechanisms. In the near future, we intend to provide extension mechanisms for these files. Until then, during an update of the application, the application generator does an automatic git merge where possible. After the update, the developer needs to manually resolve the Git merge differences in these files that currently do not have an extension mechanism.

Back-end extension code

In the back-end, to accomplish our requirements, we wrote source code to extend the following entities:

1. Timesheet Extended Package

TimesheetControllerExtended.java file changes

  • findTimesheetdetailsByWorkDate - fetch timesheet details against timesheet by workDate and return a custom output dto.

  • createMultipleDetails - create/update multiple timesheet details all at once

  • findTimesheetByDate - fetch timesheet and timesheetDetails for any work date that lies in periodstartingdate and periodendingdate and return a custom output dto

  • updateTimesheetStatus - update timesheet status to handle conditional status update

  • @Override timesheet create method to allow access to all users

TimesheetAppServiceExtended.java file changes

  • findTimesheetByDate
  • @Override timesheet create method to set default status and userId
  • @Override timesheet find method to return custom output dto
  • add updateTimesheetStatus method

New Dtos

  • TimesheetOutput
  • UpdateStatus

ITimesheetRepositoryExtended.java changes

  • add findByDate method

2. User Extended Package

UsersControllerExtended.java File Changes

  • createTriggerAndSendEmail - send reminder emails to employees for timesheet completion and associate that trigger with user

  • getReminderDetails -fetch details associated with reminder email

  • getEmployees - search and get a list of employees

UsersAppServiceExtended.java File Changes

  • parseTokenAndCheckIfPermissionExists - check if required permission is assigned to user

  • associateTriggerWithUser - assign required trigger info to user

  • @Override user delete method to remove trigger associated with user

  • findEmployees - search and find employeees

New Repository Creation

  • IUsersRepositoryCustom.java - create a custom repository to implement a new method that returns the list of users with the employee role.

3. UserTask Extended Package

UsertaskControllerExtended.java File Changes

  • getTaskAgainstUser - fetch all tasks against a user

UsertaskAppServiceExtended.java File Changes

  • getUsertaskList - get list of all tasks assigned to a user

New Dtos

  • UsertaskOutput

IUsertaskRepositoryExtended.java File Changes

  • findByUserid

4. Timesheetdetails Extended Package

TimesheetdetailsAppServiceExtended.java File Changes

  • createMultipleDetails

  • deleteIfInputNotContainsEntity

  • findByTimesheetId

  • findByWorkDate

  • setProjectAndCustomerInfo

New Dtos

  • TimesheetdetailsInput

  • TimesheetdetailsOutput

ITimesheetdetailsRepositoryExtended.java File Changes

  • findByTimesheetid

  • findByWorkdateAndUserId

5. Timesheetstatus Extended Package

TimesheetstatusAppServiceExtended.java File Changes

  • findByStatusname - fetch timesheetstatus entity on the base of statusname

ITimesheetstatusRepositoryExtended.java File Changes

  • findByStatusnameIgnoreCase

Front-end Extension Code:

1. Create the timesheet module with routing and add the following components in this module.

src/app/extended/timesheet-module/

  • Timesheet
  • Timesheet-details
  • Manager-sheet
  • Notification

2. Add timesheet module in app routing module.

3. Update Usertask new component to assign multiple tasks to a user at once.

4. Move entities menu item under administration

5. Create permission with the name “showEntities” and assign it to the “admin” role.

6. Create permissions with the names "SET_REMINDER", "FILL_TIMESHEET" and assign it to the “employee” role.

7. Make changes in the navbar component to add these permissions in the permission map.

8. Add new methods in extended service classes

Usertask

  • getTasks

Timesheet

  • createTimesheetDetails

  • getTimesheetDetails

  • getByDate

  • setTimesheetStatus

  • Create

  • getFormattedDate

Users

  • setReminder

  • getReminderDetails

  • getEmployees

9. Add links for new components in side-navbar and menu