This is the GitHub repository for the service portion of the team project for group 'Innov8' associated with COMS 4156 W Advanced Software Engineering at Columbia University.
Please use the following link to view the repository relevant to the client app: https://github.com/jonghyun-joann-lee/Innov8-Client
Innov8
Anavi Lohia (al3750)
Jane Lim (jl6094)
Jonghyun Lee (jl6509)
Jungyun Kim (jk4661)
Team member conrtibutions can be found on the JIRA project at this link: Innov8 JIRA - List of tasks
LiveSched:
A versatile scheduling and resource management service tailored to handle the complex needs of diverse industries, including but not limited to healthcare, manufacturing, and logistics. By dynamically adjusting schedules based on real-time data, specifications, and prioritization rules, LiveSched optimizes operations, maximizes resource utilization, and enhances client service delivery.
This ReadMe has been tested using a Mac, please make changes as needed for Windows.
To build and use this service you must install the following:
- Maven 3.9.5
- JDK 17
- IntelliJ IDE (Recommended IDE, optionally you may use any other)
- Clone this repository using git clone or IntelliJ
To set up and run the repository after installation, you can use the following commands inside LiveSched folder.
By default, the service operates in local mode, saving and loading files from local storage.
If you would like to use Google Cloud Storage (GCS), you can enable GCS operations by passing the --useGCS flag as noted below.
But please note that if you plan to run the service with GCS enabled, you need to install and set up Google Cloud CLI.
cd LiveSched
If you want to optionally set up an example database for the first time or want to reset it, run the following command:
mvn spring-boot:run -Dspring-boot.run.arguments="setup"
This will set up an example database for client ID: demoClientId.
If you want to enable GCS during setup:
mvn spring-boot:run -Dspring-boot.run.arguments="setup --useGCS"
To run the service normally (in local mode by default):
mvn spring-boot:run
If you want to enable GCS operations:
mvn spring-boot:run -Dspring-boot.run.arguments="--useGCS"
mvn -B clean install --file pom.xml
All unit tests are located under the directory src/test
They can be run individually in IntelliJ using right click on the test files or to run the whole test suite use the following command:
mvn clean test
mvn checkstyle:check
mvn checkstyle:checkstyle
The results can be found under target/site/jacoco directory
mvn jacoco:report
mvn pmd:check
This service is currently available as a google cloud based instance that can be accessed using the following url:
https://innov8-livesched.ue.r.appspot.com
A successful connection should lead you to a homepage that displays the following message:
Additional data requests and tests can be made using a service like Postman using the following format:
https://innov8-livesched.ue.r.appspot.com/endpoint?arg=value&arg=value
Note: For the cloud based instance, GCS operations are enabled by default, meaning the service will load and save files to Google Cloud Storage without any additional configuration.
This section describes the endpoints that the service provides, as well as their inputs and outputs.
- Expected Input Parameters: N/A
- Expected Output: Welcome message (String)
- Description: Redirects to the homepage.
- Upon Success: HTTP 200 Status Code with a welcome message in the response body.
- Expected Input Parameters: clientId (String)
- Expected Output: A JSON array containing the details of all tasks
- Description: Returns the details of all tasks in the database for the specified client.
- Upon Success: HTTP 200 Status Code with a list of tasks in the response body.
- Upon Failure:
- HTTP 404 Status Code with "Tasks Not Found" if there are no tasks.
- HTTP 500 Status Code with "An Error has occurred" if an unexpected error occurs.
- Expected Input Parameters:
- taskId (String)
- clientId (String)
- Expected Output: A JSON object containing the details of the specified task
- Description: Returns the details of a specified task in the database.
- Upon Success: HTTP 200 Status Code with the task's details in the response body.
- Upon Failure:
- HTTP 404 Status Code with "Task Not Found" if the specified task does not exist.
- HTTP 500 Status Code with "An Error has occurred" if an unexpected error occurs.
- Expected Input Parameters: clientId (String)
- Expected Output: A JSON array containing the details of all resource types
- Description: Returns the details of all resource types in the database.
- Upon Success: HTTP 200 Status Code with the list of resource types in the response body.
- Upon Failure:
- HTTP 404 Status Code with "ResourceTypes Not Found" if there are no resource types.
- HTTP 500 Status Code with "An Error has occurred" if an unexpected error occurs.
- Expected Input Parameters: clientId (String)
- Expected Output: A JSON array containing the details of the master schedule
- Description: Returns the details of the master schedule in the database.
- Upon Success: HTTP 200 Status Code with the schedule details in the response body.
- Upon Failure:
- HTTP 404 Status Code with "Schedules Not Found" if there are no schedules.
- HTTP 500 Status Code with "An Error has occurred" if an unexpected error occurs.
- Expected Input Parameters:
- taskName (String)
- priority (int)
- startTime (String, format: "yyyy-MM-dd HH:mm")
- endTime (String, format: "yyyy-MM-dd HH:mm")
- latitude (double)
- longitude (double)
- clientId (String)
- Expected Output: A JSON object containing the details of the newly added task
- Description: Adds a new task to the database.
- Upon Success: HTTP 200 Status Code with the task's details in the response body.
- Upon Failure: HTTP 500 Status Code with "An Error has occurred" if an unexpected error occurs.
- Expected Input Parameters:
- taskId (String)
- clientId (String)
- Expected Output: A success message string
- Description: Deletes a task from the database.
- Upon Success: HTTP 200 Status Code with "{taskId} successfully deleted" in the response body.
- Upon Failure:
- HTTP 404 Status Code with "Task Not Found" if the task doesn't exist.
- HTTP 500 Status Code with "An Error has occurred" if an unexpected error occurs.
- Expected Input Parameters:
- typeName (String)
- totalUnits (int)
- latitude (double)
- longitude (double)
- clientId (String)
- Expected Output: A success message string
- Description: Adds a new resource type to the database.
- Upon Success: HTTP 200 Status Code with "Attribute was updated successfully" in the response body.
- Upon Failure: HTTP 500 Status Code with "An Error has occurred" if an unexpected error occurs.
- Expected Input Parameters:
- taskId (String)
- typeName (String)
- quantity (int)
- clientId (String)
- Expected Output: A success message string
- Description: Modifies resource type for a specified task.
- Upon Success: HTTP 200 Status Code with "Attribute was updated successfully" in the response body.
- Upon Failure:
- HTTP 404 Status Code with "Task Not Found" if the task doesn't exist.
- HTTP 404 Status Code with "ResourceType Not Found" if the resource type doesn't exist.
- HTTP 500 Status Code with "An Error has occurred" if an unexpected error occurs.
- Expected Input Parameters:
- typeName (String)
- clientId (String)
- Expected Output: A success message string
- Description: Deletes a resource type from the database.
- Upon Success: HTTP 200 Status Code with "{typeName} successfully deleted" in the response body.
- Upon Failure:
- HTTP 404 Status Code with "ResourceType Not Found" if the resource type doesn't exist.
- HTTP 400 Status Code with "Cannot delete a resourceType currently in use" if the resource type is being used by tasks.
- HTTP 500 Status Code with "An Error has occurred" if an unexpected error occurs.
- Expected Input Parameters:
- maxDistance (double)
- clientId (String)
- Expected Output: A JSON array containing the updated schedule details
- Description: Updates and returns the schedule for current tasks and resources.
- Upon Success: HTTP 200 Status Code with the updated schedule in the response body.
- Upon Failure:
- HTTP 404 Status Code with "Tasks Not Found" if there are no tasks.
- HTTP 404 Status Code with "Master Schedule Not Found" if there is no master schedule.
- HTTP 500 Status Code with "An Error has occurred" if an unexpected error occurs.
- Expected Input Parameters:
- taskId (String)
- clientId (String)
- Expected Output: A success message string
- Description: Removes a task from the master schedule.
- Upon Success: HTTP 200 Status Code with "Task unscheduled successfully" in the response body.
- Upon Failure:
- HTTP 404 Status Code with "Task Not Found" if the task doesn't exist.
- HTTP 404 Status Code with "Master Schedule Not Found" if there is no master schedule.
- HTTP 400 Status Code with "Task Not Scheduled Yet" if the task isn't in the schedule.
- HTTP 500 Status Code with "An Error has occurred" if an unexpected error occurs.
The following tools were used in the development and modification of this repository:
-
Maven Package Manager
-
GitHub Actions CI
- Enabled via the "Actions" tab on GitHub, it runs automatically for every pull request and commit to 'main' branch
- It runs a Maven build to make sure the code builds on branch 'main'
- Link to CI reports: https://github.com/anavilohia/Innov8/actions/workflows/maven.yml
-
GitHub Branch Protection Rules
- Requires at least one review approval for every pull request into 'main' branch
- Requires a successful build
-
Checkstyle
- Checks that the code follows style guidelines, generating warnings or errors as needed
- This runs as part of the CI pipeline; the most recent report can be found by clicking the above CI reports link and clicking the most recent workflow run > Artifacts > ci-reports (this is also included in the reports folder in the root of the repo)
- It can also be run using the "Checkstyle-IDEA" plugin for IntelliJ
- Most recent checkstyle results (Dec 6, 2024)
-
PMD
- Performs static analysis of the Java code, generating errors and warnings as needed
- This runs as part of the CI pipeline; the most recent report can be found by clicking the above CI reports link and clicking the most recent workflow run > Artifacts > ci-reports (this is also included in the reports folder in the root of the repo)
- The current code includes the following rulesets as specified in pom.xml:
<ruleset>/category/java/errorprone.xml</ruleset> <ruleset>/rulesets/java/maven-pmd-plugin-default.xml</ruleset> - Most recent PMD results (Dec 6, 2024)
-
JUnit
- JUnit tests get run automatically as part of the CI pipeline
- They can also be manually run using the code specified in the above sections
-
JaCoCo
- JaCoCo generates code test coverage reports such as branch analysis
- This runs as part of the CI pipeline; the most recent report can be found by clicking the above CI reports link and clicking the most recent workflow run > Artifacts > ci-reports (this is also included in the reports folder in the root of the repo)
- Most recent jacoco report with 90% overall branch coverage (Dec 6, 2024)
-
Postman
- Used for testing that the API and its endpoints work as intended
- Ran the application locally in setup mode (please refer to the above build and run guide) to generate example data for testing purposes
- API Endpoint Test Results for demoClientId
/index
/retrieveTasks?clientId=demoClientId
/retrieveTask?taskId=1&clientId=demoClientId
/addTask?taskName=checkup&priority=4&startTime=2024-12-17 11:30&endTime=2024-12-17 12:00&latitude=40.83&longitude=-73.91&clientId=demoClientId
/modifyResourceType?taskId=4&typeName=Nurse&quantity=1&clientId=demoClientId
/deleteTask?taskId=4&clientId=demoClientId
/retrieveResourceTypes?clientId=demoClientId
/addResourceType?typeName=SurgeryRoom&totalUnits=10&latitude=40.84&longitude=-73.94&clientId=demoClientId
/deleteResourceType?typeName=SurgeryRoom&clientId=demoClientId
/retrieveSchedule?clientId=demoClientId
/updateSchedule?maxDistance=10&clientId=demoClientId
/unscheduleTask?taskId=1&clientId=demoClientId
- Note that the database for a different clientId is unaffected by the above API calls. Below are a few results of calling the APIs for another client.
/retrieveTasks?clientId=otherClientId- The database for this clientId is empty so you get the Tasks Not Found
/retrieveResourceTypes?clientId=otherClientId- The database for this clientId is empty so you get the ResourceTypes Not Found
citations.txt is located at root level of this repository, it specifies urls for all resources used as reference in the development of this repository