Requirements Gathering
https://voluntarily.atlassian.net/l/c/vJWFtK2Q
User Interface Prototyping
Prototypes for the basic data dashboard layout a
https://www.figma.com/file/MU9xFHIxhJW9bErc6P1i9I/Voluntarily-Application?node-id=1265%3A5923
System Architecture Overview
...
Authorisation
Feedback API
CASL middleware was used for authorisation on the feedback API.
Permissions:
Volunteer: (must be the respondent) CREATE, LIST, READ, UPDATE
OrgAdmin: (must be an orgAdminFor an org in respondentOrgs) LIST, READ
Admin: MANAGE (all permissions)
Statistics API
CASL was not used as there were issues in dynamically evaluating access to the statistics API resource. This was because the subject was not a mongoose schema, similar to existing use cases. Therefore, custom middleware was introduced which verifies the user is an organisation admin for the organisation they are retrieving statistics for.
API Documentation
Statistics API:
GET /api/statistics/summary/:orgId/:timeframe
Description:
retrieves the total number of volunteers in the organisation, total hours volunteered and average hours per volunteer
Params:
orgId - the organisation to retrieve statistics for
timeframe - “year” or “month” - the timeframe to retrieve statistics for
Example response:
| Code Block | ||
|---|---|---|
| ||
{
"totalHours": 61.3,
"totalVolunteers": 5,
"avgHoursPerVolunteer": 12.26
} |
GET /api/statistics/locations/:orgId/:timeframe
Description:
retrieves the number of opportunity attendances by the organisation’s volunteers at each location.
Params:
orgId - the organisation to retrieve statistics for
timeframe - “year” or “month” - the timeframe to retrieve statistics for
Example response:
| Code Block |
|---|
[
{"name": "auckland", "value": 2},
{"name": "wellington", "value" : 1},
] |
GET /api/statistics/activityTags/:orgId/:timeframe
Description:
retrieves the weighted occurrences of each activity tag in the opportunities attended.
Params:
orgId - the organisation to retrieve statistics for
timeframe - “year” or “month” - the timeframe to retrieve statistics for
Example response:
| Code Block | ||
|---|---|---|
| ||
[
{"name": "react", "value" : 0.5},
{"name": "javascript", "value": 1},
{"name": "node", "value": 0.5},
{"name": "python", "value": 1}
] |
Feedback Schema Design
In storing feedback for the feedback system, two approaches were considered.
To nest the feedback document in an InterestArchive document.
To create a new feedback collection.
Decision and Justification:
Whilst the InterestArchive would be a logical place to leave feedback; the second approach was chosen because coupling feedback to the InterestArchive schema could prevent feedback being created from other sources that do not require an InterestArchive. Additionally, it would require changing the existing InterestArchive system, which could incur additional bugs
Feedback schema
...
Report Query Design
A significant design component of the data module was constructing the MongoDB query to retrieve volunteer attendance statistics. This query would be executed for each API request so that the information reported was always accurate. The query needed to be performant, as multiple reporting components would use it on the reporting dashboard
The query construction was problematic, as multiple collections needed to be efficiently traversed to attain the final result. In plain English, the query was to retrieve the opportunity details for all attendances by volunteers from an organisation. The arrangement of document schemata and direction of references meant that the query would have to traverse the Member, InterestArchives and ArchivedOpportunities collections while filtering on the opportunity date and member organisation.
The standard mongoose method of attaining document data from a document reference is to use the populate method. Each call to populate requires an additional database query to be executed, to retrieve that data. Each step of the query had the potential to produce a large intermediate result set. Populating references in each document in these intermediary result sets could result in an enormous number of network calls to the database, significantly reducing the performance of the query.
The solution to optimising this query’s performance utilised MongoDB’s aggregation functionality. Here, documents are processed through a multi-stage pipeline that transforms the documents into an aggregated result. Filters, transformations and reference lookups could all be done in a single query, minimising the number of network calls between the application server and the database.
React dashboard component design
A key requirement for the data dashboard was that it was highly modular. Although the current dashboard implementation is static, they may be generated dynamically in the future. As such, it is important that components can be added and removed easily. This was achieved through a highly modular design with minimal dependencies.
Reporting components include text summaries and graphs. Each reporting component is isolated, responsible for retrieving, storing and rendering its report. This means that there is a minimal coupling between reporting components. Adding or removing a component should have minimal effect on the other components on the data dashboard. Redux was not used for report state management for the same reason (global state can introduce coupling). Each report type has its own API endpoint responsible for producing the report data. This means that one of the components can be modified (e.g. passing additional parameters), without modifying the data retrieval for other report components.
Feedback submission user flow
It is important that the feedback submission flow is as seamless/frictionless as possible, to maximise the responsiveness of the survey. The design of the feedback submission process achieves this by minimising the number of clicks/input from the user.
The post-event thank you email template has been augmented with 5 stars that are linked to the feedback submission page, each with the respective URL for that rating. The user can click on the star, and be taken to the submission page where the rating is submitted on page load. As such, the feedback is submitted with a single click from the user.
Future Work
The current implementation of the data dashboard satisfies the basic user requirements for reporting volunteering success. Several features have been proposed as the next steps in the data dashboard’s development. The aim of these features is to increase the comprehensiveness of data reported.
Extend the feedback submission process to support optional feedback.
Currently, the feedback submission process only registers a rating out of five stars, when the page is visited. The idea of this was to streamline the feedback submission process to maximise the number of responses. However, an opportunity exists to capture additional feedback without introducing more friction to the process (retaining responsiveness).
The feedback submission page could include optional fields, asking for further feedback on the event. This could be quantitative (Likert scale) or qualitative feedback (text answers). The page would still submit the star rating feedback automatically but could modify the feedback submission (using the feedback API) with these fields if the user-provided optional feedback.
Increase the reporting/graph interactivity
Currently, the reports on the data dashboard are controlled by the timeframe (month/year) and selected organisation. While offering basic reporting, customised reports are not supported. The reports could be extended to use additional controls, for example, activity type, location, asking for help, offering for help etc. to filter the responses and deliver a more tailored report to the user.
Add time series reporting functionality
Currently, the reporting dashboard only supports a snapshot of the volunteering activity data. While this is useful for determining how the volunteering program is functioning in the present, it does not provide information about how the program has changed over time. This feature would be useful to org admins that are interested in improving the volunteering program, as they can see how the activity responds over time when subjected to various changes (e.g. an internal volunteering awareness campaign should increase activity).
Add dynamic dashboard generation and customisation
The current implementation of the data dashboard is static, and reports shown are tailored to org admins. However, these dashboards could be created dynamically, on a per user basis. This would allow dashboards to be used by every type of user, with appropriate content shown as per their user type. Additionally, users could have the option to customise their dashboard, selecting which reports they are interested in, the layout and order of the reports etc.