Requirements¶
Acronyms, Abbreviations and Definitions¶
- UWA: The University of Western Australia
- SHL: System Health Lab
- Organisation: A club, lab, or group of people at UWA, for example, the Makers club, Motorsports club, System Health Lab, unit coordinators, etc.
- Asset/equipment: These terms will be used interchangeably, and will refer to ready-to-use engineering equipment owned by organisations at UWA. Assets include 3D printers, portable microscopes, slamsticks, motors, and other large equipment. It will not include infrastructure-based equipment or assets, or equipment parts.
- Administrators: The users that have access to creating organisations and adding users to particular organisations.
- Maintainers: Also known as organisation maintainers. A member of a UWA organisation responsible for maintaining the equipment database of their organisation.
- Users: General users of the system, specifically pheme authenticated UWA staff and students.
- MERN - MongoDB, ExpressJS, ReactJS, NodeJS - a JavaScript set of technologies to build full-stack web applications
Aim and Scope¶
UWA currently houses thousands of engineering equipment across the multiple disciplines. However, this proposes a problem as there is no database of the existing equipment that can be searched through by UWA staff and students. The ASER project aims to develop a central, consolidated equipment database that can be searched by the university's staff and students. This gives staff and students the opportunity to locate and request access to tools and equipment that they wouldn't otherwise be able to use outside of their enrolled units and university clubs.
ASER will only track pieces of equipment that are ready to use, for example, 3D printers, portable microscopes, ovens, slamsticks, motors, and other large equipment. It will not track infrastructure-based equipment or assets, or parts, for example pumps, sensors, screwdrivers, and dremels.
This will replace the current system which consists of private, non-accessible data from the finance department (asset IDs) and Matt Arpin's Excel spreadsheet, neither of which include complete lists of the equipment. The issues with this current system is outlined in Table 1 below.
Table 1: Issues with the current system
| Issue | Description / impact | The Solution |
|---|---|---|
| Non-accessible data | Staff and students aren't able to search for the equipment they require as information regarding the equipment is only available through Matt Arpin's Excel spreadsheet or the finance department, neither of which is publicly available. | Will be able to be accessed by UWA staff and students using their PHEME credentials. |
| Non-centralised data | The assets or equipment in UWA is recorded in many places or not even recorded in some case. | Will be a centralised system that consolidates all the equipment in different organisations |
| Isn't regularly updated | Staff and students may go to the specified equipment location, only for it to not be there as the spreadsheet hasn't been updated. | Will have an intuitive user interface, so that it will be easy for users to update information about an equipment. |
| Doesn't keep track of all equipment | The finance department only has asset IDs for equipment meeting a certain crtieria. Matt Arpin's Excel spreadhseet doesn't include some equipment from research labs, although it is unclear what equipment is included and what isn't. | Will become the only database to keep track of all equipment outlined, and should therefore be kept up-to-date with any new equipment. |
Requirements¶
Stage 1 Functional Requirements¶
The following are the core functional requirements for the first stage application, which will support all user levels: administrators, maintainers, and users
Administrators¶
| Identifier | Name | Description |
|---|---|---|
| FRA1 | Administrator login | The user can login using pheme |
| FRA2 | Add administrators | |
| FRA3 | Add organisations | |
| FRA4 | Add maintainers to organisations |
Maintainers¶
| Identifier | Name | Description |
|---|---|---|
| FRM1 | Maintainer login | The user can login using pheme |
| FRM2 | View organisation's equipment | |
| FRM3 | Add new equipment | |
| FRM4 | Edit/update equipment information | e.g. location, quantity |
| FRM5 | Remove equipment | |
| FRM6 | Add maintainers to the organisation |
Users¶
| Identifier | Name | Description |
|---|---|---|
| FRU1 | User login | The user can login using pheme |
| FRU2 | Equipment search | |
| FRU3 | Contact the maintainer about equipment | |
| FRU4 | Request equipment location update |
Stage 2 Functional Requirements¶
| Identifier | Name | Description |
|---|---|---|
| FRG1 | Transfer Ownership | Organisations can give equipment to another organisation. This typically occurs when an organisation is dissolved. |
| FRG2 | Loan | Organisation can loan equipment to users in the system and should be able to record which equipment has been loaned, to who, and for how long. |
| FRG3 | Automated Reminder System | The maintainers should receive a list of equipment that needs to be updated based on the last updated time at a certian period in the year. |
| FRG4 | Sync the data from Finance System | As mentioned, the Finance department tracks of certain equipment as well that fits a certain criteria. Since, this is one of the existing procedures in UWA. It would be great if the system can sync data in the Finance System especially for new equipment that comes in. |
"Nice to have"¶
The "nice to haves" of this project will not be covered in this requirements documents. This is because the "nice to haves" will come along as the users of the system see fit. This will be documented in the Issue Tracking Management sytem of the code repository.
Some of the "nice-to-haves" as of this writing are:
- Ability to click the location and show the location in the UWA Campus
- Ability to scan the barcode of an equipment which will show the equipment's information on the ASER webapp
- Ability to ensure that prior to items being deleted, either the finance department or Matt Arpin have been contacted. Also link the Asset Disposal Form.
- Ability to have parent and child assets, and automatically update the parent and/or child assets, depending on the status of the related parts. For example, an asset may be made up of multiple child assets. If the asset goes missing, all the child assets should also be marked as missing.
Non-functional Requirements¶
| Identifier | Name | Description |
|---|---|---|
| NFR1 | Security | Only authenticated and authorised users should be able to perform actions such as adding equipment, updating equipment location and information, or searching for specific equipment. |
| NFR2 | Performance | The loading time should not hinder the user experience and productivity of the user in the website. The page and actions should have a loading time < 5 seconds on most computing environments on standard internet connections |
| NFR3 | Maintainable and extensible | The website should be relatively easy to update and extended to accomodate for new contexts. |
| NFR4 | Recoverable | In the event of the web server or database server crashing, all stored data should be fully recoverable. |
| NFR5 | Intuitive user interface | The website should have an intuitive / easy-to-use user interface, so that users will be able to easily use the website and update the equipment database |
| NFR6 | Compatibility | The application should be compatible with recent versions of the major browsers (Safari, Chrome, Firefox and Edge) on laptop and desktop computers |
| NFR7 | Deployability | The application should be compatible with deployment in the SHL VPS |
Proposed Solution¶
The proposed solution is to build a custom web application that will encompass and satisfy the requirements (by completing the suggested "ideal solution" as per the Aim and Scope).
Some research for existing design solution has been done for this project see Appendix: Existing Design Solution. The beauty of custom web application for the UWA SHL is that it upskills the current software engineers in the lab as aligned in the values of SHL, and the high possibility of extending application depending on the requirements without being constrained with the bulk of codebase of other unmaintained opensource projects. Comparatively to enterprise systems, most enterprise systems will charge per users that use the system, this easily becomes expensive because the amount of users that will use the system should be able to accomodate the number of users that are interested in looking for the assets.
Core Technologies¶
The custom web application will aim to satisfy all the requirements in here along with the "Nice to haves" as they come up. The application will be built using the MERN stack, the same stack used by the IndEAA (of UWA SHL) and AMIRA (UWA Future Tails) project. By using the same stack, the codebase can be share such that development in one codebase will easily be transferred or translated to another codebase, essentially reducing the total development time while delivering high value in this project and other projects.
The authentication system will be outsourced to the UWA Pheme Authentication API to allow any users in with a UWA Pheme account to login.
ReactJS/NextJS¶
React is a popular frontend technology to create website divided into components and utilizes client-side rendering to allow fast loading speed with the trade-off of slower initial load speed (NFR2 - Performance).
The division of UI into components allows easier re-usability of UI components such as a header and a footer that appears in every page, and allow easy to change for update - "one change, change it all" (NFR3 - Maintenance and Extensibility).
The main power of React is the ecosystem and libraries that are available on top of it such as NextJS and Material UI which can ultimately cut the development speed, and allows easier upgrade than other technologies (NFR5 - Maintenance and Extensibility). Two of the common technology used with React is Babel Transpiler for cross-compatibility (NFR6 - Compatibility) and webpack bundler/minifier for lower bundle or required downloads size (NFR2 - Performance).
NextJS is a library for React that allow server-side static web generation, handling web routes, and code splitting. Server-side static web generation allows the processing of HTML, CSS and JS in the server for the initial serving of web content, and allows web crawlers to read content. Furthermore, NextJS handles web routing with hot reloading - loading only components that has not been downloaded by the browser to allow fast navigation (NFR2 - Performance). Code Splitting is used by NextJS to allows faster initial load speed by only loading code that will be used for the initial session (NFR2 - Performance).
Backend: MongoDB¶
MongoDB is a noSQL database solution that is efficient and flexible with minimal overhead. It would fulfil all data storage requirements of the system.
Backend: ExpressJS/FeathersJS¶
Express is a library on Nodejs (a platform to run JavaScript outside of the browser) to easily create HTTP servers.
Feathersjs is a wrapper for application in Express, essentially to make development easier by loosely enforcing developers on creating RESTFul API (following uniformity of HTTP methods). It makes development easier by making route to database call uniform.
Material UI/Material Kit¶
CSS libraries allows cutting the development time for design such as Material UI that contains ready-to-use UI components that are compatible to cross-browsers (NFR6 - Compatibility), excellent in design (NFR5 - Intuitive user interface), easy to use, and extensible (NFR3 - Maintenance and Extensibility).
Material Kit is an extension of Material UI that provides a base template for few pages, and a package of configuration for the most common UI component.
Docker¶
Docker is a deployment technology that allows virtualization in a server to allow the packaging of software into containers for deployment. To satisfy NFR7 - Deployability, the web platform will use docker to allow the deployment through the SHL VPS Server.
Furthermore, Docker will be used for orchestration of different services in development to increase speed of development, and reduce inconsistency between developers devices (NFR3 - Maintainable and extensible).
Code Quality¶
The code quality will be ensured by peer reviews between the developers in the team.
Code Storage and Development Control¶
Git source control will be used, using the remote UWA System Health Lab organisational GitHub (NFR3 - Maintenace and Extensibility).
Prototype¶
See the Prototype mentioned in Figma Interface Prototype
Execution Team¶
The development of the web platform will be performed by the UWA System Health Lab Redbacks Team: Ivy Bui, Michael Nefiodovas, with the lead of Frinze Erin Lapuz, and the guidance of Melinda Hodkiewicz.
Development and Methodology¶
As per the staged requirement, majority of the development will take place on the stage 1 whereas stage 2 are feature-based requirements for the syste,.
Below is the rough development methodology:
Appendix¶
Existing Design Solutions¶
Some of the design solutions that have been considered with great detail and justification are here.
MYOB¶
MYOB is known for its accounting software that is integrated with inventory systems. However, the functionalities for registry of equipment and asset differs from inventory systems. Furthermore the cost for the features for MYOB starts at $109.00/month. The biggest problem faced would be the difficulty to make the system accessible for multiple users. Hence, it is ruled out in the possible design.
Google Sheets / Excel Sheets in OneDrive¶
Excel sheets and google sheets are one of the most flexible systems out there. Authentication within someone that has "uwa.edu.au" account is automatically enforced within documents shared within the campus. However, the biggest problem that can easily be seen are:
- the ease of use. This is especially visible if the excel sheet will have so many columns to accomodate all possible information that is there.
- Authorisation/permission. A system being centralised requires that maintainers can only edit information regarding their own assets. This is hard to enforce in either Google Sheets or Excel sheets, as the only permissions are "write" and "read"
- Consistency - because Excel does not enforce any types or columns in the Excel sheet, if a maintainer cannot find a field that satisfies their information, they will create another column which increases inconsistency since not all equipment/asset will have that field
- Difficulty to display Many-to-Many data relationships. This is easily thought of for "Tags" system (ability for users to see equipment at a particular category), that is very hard to display in flat-file tabular format.
Mazemap Asset Tracking¶
Mazemap Asset Tracking is an API designed by Mazemap to visualise and track assets in real-time. According to the case study, the example use cases are:
- Shopping mall kiosks / map stations
- Hospital self-service kiosks
- Conference venue mobile applications
- Hotel customer program applications
- Facility management applications
- Facility cleaning service applications
The cost is unknown. It looks perfect for this project, however there are too many unknowns in terms of its limitation. It has a lot of shiny features such as real-time equipment tracking (that possibly may require sensors), which means that there are a lot features that may not be used. By practice, this will usually complement the cost, not to mention the setup to integrate the UWA Authentication system (either UWA Pheme Authentication API or UWA SAML SSO) with a third-party application. It is presumed with these assumptions that the API may be "overkill" for this project.
However, it is worth pointing out that UWA already uses a MazeMap product see UWA Campus Map. This means that although the project might not use Mazemap Asset Tracking, it is possible to use the existing UWA Map API without extra costs. The Map API can be seen here. More information about different API can by reverse engineering the Map API with network request scanners.