Caution
READ EVERYTHING BEFORE STARTING ON THE PROJECT!!!
The current process for managing procurement paperwork submitted by students from EPICS, Capstone, and UTD Makerspace is outdated and inefficient. The workflow involves students filling out Excel sheets and emailing them to their mentors for review. Mentors then either approve the form and forward it to the administrator, Oddrun Mahaffey, for order placement or rejection, providing the student with a reason for the rejection. To streamline this process and make it more convenient for all parties involved, the objective is to create a centralized UTD Procurement Manager website where the entire procedure can be completed online. The web application will primarily benefit students engaged in Capstone, Senior Design, and EPICS projects by simplifying their procurement process and enabling more effective financial management. Furthermore, project mentors and UTDesign staff will experience the advantages of reduced email correspondence and a more streamlined approach to handling requests and budgets, making the system more efficient for all involved parties.
- This project seeks to digitalize the process of part and reimbursement requests for ECS Senior Design and EPICS students.
- Currently, requests are managed through Excel sheets, emails, and in-person meetings, so the website will facilitate communication digitally and present financial information in a user-friendly format.
- There are 3 types of users: admins, mentors, and students.
- Admins are able to process or reject requests, and can modify any data in the UTDesign database relating to users, projects, requests, vendors, departments, and so on.
- Mentors are able to approve requests which will send those requests to be processed by admins, or reject requests. They cannot edit any request data.
- Students are able to submit requests but cannot edit requests, unless an admin or mentor rejects one and then students have the option to edit and resubmit.
- Frontend: React.js
- Frontend & Backend: TypeScript, Next.js
- Database: MySQL
- Database Connector: Prisma
- Other Tools: Postman (API Testing)
- Allows users to sign in with UTD SSO
- Students can fill out request information such as date needed, additional information, and details for each part needed in the request
- Students can also upload files if needed such as design specifications, which will be stored in the cloud
- Students can fill out reimbursement information such as additional information and details for each part purchased that needs to be reimbursed
- Students are required to upload receipts for verification, which will be stored in the cloud
- Single Orders & Reimbursement Page for mentors, but 2 separate pages for students and admins (Orders Page shows requests that need to be ordered)
- For each project a user is in, displays the submitted request data for unprocessed requests/reimbursements
- Students cannot edit submitted data unless the request/reimbursement is rejected, then they can edit and resubmit
- Mentors can approve or reject requests/reimbursements with comments for rejection reasons, but cannot edit the data
- Admins can process requests/reimbursements or reject requests/reimbursements with comments for rejection reasons
- When processing, admin users can edit the data such as by:
- editing existing request/reimbursement data if needed
- adding/deleting parts if needed
- adding other expenses if needed
- adding/deleting orders (required)
- Single Projects & Order History Page for mentors and admins, but only Order History Page for students
- For each project a user is in, displays:
- project information (project number, title, starting budget, remaining budget)
- user information (names of the mentors and students in the project)
- processed request/reimbursement information (were either approved and ordered/reimbursed, or rejected)
- Students and mentors can view this data, but admins can edit the data such as by:
- changing the status of a request/reimbursement
- editing comments visible to other users
- editing existing request/reimbursement data
- adding/deleting parts
- adding/deleting orders
- adding other expenses
- allows admins to upload excel files for adding users, projects, and modifying any data in the UTDesign database
- Update Login Page for UTD SSO Integration.
- Implement Reimbursement Form In Student View.
- Add form validation to make sure input values follow type requirements.
- Enhance UI, test, and fix the Database Updates Page.
- Enhance UI, test, and fix the request form page (Student View).
- Complete remaining TODOs for Orders, Projects & Order History, and Request Form pages.
- Make sure all work adheres to the UTD guidelines.
- Implement UTD SSO (Single Sign-On) feature for user authentication.
- Continue developing API endpoints and integrating them with the front-end to provide full functionality of the application. APIs to work on: Backend_APIs.docx
- Update the list of APIs done so far with the new add/delete orders APIs. (docs/api.md)
- Integrate cloud software to store uploaded request/reimbursement files in the cloud (DB Updates Page & Student View of Request Form).
- Improve code by implementing type-checking and error handling, and resolve any bugs/TODO comments in code/APIs from previous semesters.
- Student
- Able to request reimbursement of funds with the reimbursement form (TODO) and the ordering of parts with the request form. Also able to view requests made in the Orders page.
- The Student opens the Request Form page and fills it out, then press submit.
- Reimbursement Form. (TODO)
- Mentor
- Role: Views requests made by the student on the Orders page and can either approve or deny the request to go to the admin.
- Admin
- Role: Views requests approved by the mentor and can review request orders, edit order request information, add shipment details, and view the history of previous projects and orders. They can also edit information in the DB
- In the orders page, the admin can edit the request by pressing the edit button, enabling the admin to add/remove shipping details and order details.
- In the Projects and Order history page, the admin can view the history of previous projects and orders and edit them by pressing the edit button.
- In the Database Updates page, the admin can add/delete users and projects (TODO). They are also able to upload files by clicking the Upload Files button.
You must have the following tools installed:
- VS Code - recommended code editor
- Node.js - needed for running the app locally
- Git - version control system
- Helpful reference guide: Git Installing Guide & Customizing
- GitHub Desktop - optional, provides a GUI to interact with Git repositories
- MySQL Workbench - optional, provides a GUI to interact with the database
This project uses MySQL as the database where all application data is stored. On Windows**, you'll run MySQL directly on your computer. On macOS, you'll run MySQL in a Docker container on your computer.
Tip
For more info about Docker, see 'What is Docker?' on the EPICS Guide repo.
For a rough overview of SQL and more info about MySQL and Prisma, check out this page from the EPICS Guide repo.
Download MySQL, then follow along with the installation instructions in this video. You don't need to watch the whole video, just the section on installing MySQL.
Warning
REMEMBER THE PASSWORD that you used to create your database! (and make sure you do not use special characters). You'll need it to continue with setup later.
Docker is a tool that allows you to run applications like MySQL in 'containers' on your computer. Running MySQL in Docker is preferred as opposed to running MySQL on your computer directly because it is easier to set up and provides isolation between any other MySQL instances you may have on your computer. On Windows, setting up Docker is more of a hassle so we only recommend it on macOS.
Install Docker Desktop.
Once Docker Desktop is installed and running on your computer, open a terminal to the procurement-manager folder, then run docker compose up -d to start your database.
In the Docker Desktop app, you should see a new Docker container running. In the future, you can run the database server by pressing the Start button on the container in Docker Desktop, or running docker compose up -d in the terminal.
- Install all the required software specified above.
- Check if you have git, Node.js, and npm installed by typing in your terminal:
git --versionandnpm --version - If you haven't learned how to use the terminal, please do so first to your respective operating system. Some basic commands are
cd,pwd, andmkdir.
-
Find a folder to save this repository and go there using your terminal. For example mine is saved in
C:\Isaac\Programming.a. In your terminal, write
git clone https://github.com/UTDallasEPICS/UTDesign-Procurement.gitor the SSH link if you have that set up. Sign in to GitHub if asked.b. Cloning a repository should create a folder for you inside the folder the terminal is in, so don't make a folder like "UTDesign Procurement"
-
Open the repository in VS Code.
- Clone a repository by clicking
File > Clone Repositoryand finding it through GitHub.com or through URL tabs. - Open the repository in VS Code.
Dependencies are the packages used to create the project.
- To install the dependencies, in VS Code, create a new terminal in the editor and run
cd procurement-manager/to make sure that the terminal is in the procurement-manager folder (the project itself) and runnpm installornpm i. This will install all the packages as specified in ourpackage.jsonfile.
Note
The steps in the database setup section need to be complete before continuing with environment configuration.
-
Copy the .env.example from the docs folder into the procurement-manager folder and rename it to .env.
-
In the .env file, update the line beginning with
DATABASE_URL=.- On Windows, replace
YOUR_MYSQL_ROOT_PASSWORDwith the password you set when initially setting up MySQL. - On macOS, replace
YOUR_MYSQL_ROOT_PASSWORDwithpassword.
- On Windows, replace
-
Open a terminal and change directory to the procurement-manager directory. The next step requires you to be in the procurement-manager directory.
-
To sync your database with the project schema, run
npx prisma migrate dev.
The schema.prisma file under the prisma folder has the schema setup and can be edited to change the database.
After making any changes to the database schema, running npx prisma migrate dev will also update the database.
Tip
Some more documentation regarding this is provided here: Prisma Migrate
If you installed MySQL Workbench, you can use it to manually add some data into the tables and view changes done to the database. You can also run npx prisma studio instead of using MySQL Workbench to see the database through a locally-hosted web interface developed by Prisma.
-
In the terminal, enter
openssl rand -base64 32which will generate random characters and copy it. -
In the .env file, below the DATABASE_URL, fill in EXAMPLE_NEXTAUTH_SECRET by pasting the random characters in the randomcode.
This is what makes the fake authentication work.
-
(Only for external servers) If setting up the repository in an environment where it's not being accessed on
localhost, change theNEXTAUTH_URLvalue to match the external URL.- More documentation on this option is provided here: https://next-auth.js.org/configuration/options#nextauth_url
-
Change the
NODEMAILER_PASSWORDto be"nnft zpaq rooq iwkq". This allows the Upload Files page to email error files to admins.
- Making sure you are still in the procurement-manager folder, run
npm run devwhich runs the website. - In your browser, go to http://localhost:3000/api/test. This creates all the sample data to run the project.
- Finally, go to the website at http://localhost:3000.
- 🎉🎉 GOOD LUCK AND HAVE FUN! 🎉🎉
- Student:
abc000000 - Mentor:
def000000 - Admin:
ghi000000
This contains the UI mockups of the app and is located in the /docs folder.
These are located in the /docs folder.
The /docs folder contains various documents on the design and schemas of the app, including documentation on APIs. These should be looked at.
- Familiarize using Prisma with Next.js
- Creating API routes in Next.js 13
- API Route Handlers in Next.js 13
- API GET Request
- Postman API Testing
Extensions can add features to VS Code that make working with this project easier. When opening this project in VS Code, you may see a notification prompt like this one, allowing you to install all these recommended extensions with one click. If you missed the prompt, you can open the extensions pane in VS Code and install each extension manually.
- Prisma - formatting and snippets for Prisma
- GitLens - lets you see who last edited code in your editor, includes other helpful Git-related features
- CodeSnap - if you want to take screenshots of code
- Auto Close Tag, Auto Rename Tag - good for quickly editing the HTML/component tags
- ES7+ React/Redux/React-Native Snippets - quickly create components
- ESLint - shows unused or errors in your code, may need some customizing and research (we should have done a configuration for the project so everybody has the same formatting)
- Live Share - incredibly useful! it's like Google Docs but for coding
- Prettier - awesome code formatting
- Thunder Client - good for testing API and alternative to Postman
Although this was a new project in SPRING 2023, there was a previous version of this project from past semesters. We are constantly trying to improve from their mistakes so that the reset button for this project won't be pressed again. Please do not have duplicated code and resources since this is what the previous version of this project had and document your code as much as you can. I know that some of our code does not have the same format of documentations, some are made by me, and others used a documentation generator, but we tried to explain our code to you nonetheless. Please do the same for others as well. Good luck team! -- Isaac (SPRING 2023)