Table of contents
This use case explores the workflow involved with activity management, including: (a) definition of an activity by an admin; (b) browsing of activities by a user; (c) submission of an activity for verification by an admin; (d) verification of a submitted activity by an admin; and (e) post-verification correction by an admin.
Exploration of this workflow reveals two data structures (tables) that must be available to the user:
- A table providing a browser of activities available to the user;
- A table providing a list of activities that have been submitted by the user for processing and their status
There are three data structures (tables) that must be available to the admin:
- A table with all defined activities, allowing modification, creation, and deletion.
- A table with all activity instances that have been submitted by users and that await processing by an admin.
- A table with all activity instances that have been processed by one (or more) admin.
Note that there are multiple users and multiple admins, so race conditions are an issue. Also, there must be some support for transactions so that multiple admins can be processing the queue of submitted activities simultaneously. Perhaps an admin must obtain a lock on an activity before processing it.
Some other issues to consider:
- It is probably unwise to manage a user's kukui nut total as a single field, since admins can retract previously awarded activities. Instead, the system should maintain the list of submitted activities (and their state) for each user, then sum up the awarded kukui nuts each time that value is to be displayed.
- If it is possible for the admin to change the number of kukui nuts associated with an activity after defining it, then activity "instances" (i.e. the submitted activity by a user) should contain a link to the activity definition and use that link to obtain the current number of kukui nuts associated with that definition whenever that value is needed.
- Once an activity is defined, can it be deleted? If so, what happens to "instances" of that activity?
Finally, it would be helpful to create Balsamiq mockups of these tables, but I will leave that as a task to the development teams. Hopefully someone will take the initiative after reading this. :)
Activity Definition by Admin
Admin logs in.
- System puts her in Admin page.
Admin goes to admin-level Activities Manager page.
- This page contains a table ("Defined Activities") where each row summarizes a defined activity by its title, type, kukui nuts, and number of users who have been awarded nuts for this activity. The admin can select an activity row and either delete or edit the activity. There is also a button to add a new activity.
Admin clicks on "Add new activity" button.
- System brings up Add activity form, which contains:
- Title;
- Type (Event, Action);
- Event date/time (for events)
- Expected duration (how much time is required for this activity in minutes)
- Publication date (when this activity becomes visible on the system.) Defaults to today.
- Expiration date (when this activity disappears from the system)
- Kukui Nuts
- Description (steps required to carry out activity). This should support some sort of markdown syntax so that images, links, tables, etc. can be used to format the description. HTML is also possible, but markdown is generally better. The description will also specify in general terms what will be required for verification.
- Verification Type (Text Field, Upload Image, Confirmation Code). If Text Field, then the system will display a randomly selected prompt (provided by the admin below) during verification. If Upload Image, then the system will display the Upload Image prompt along with a file upload field. If Confirmation Code, then the system will display the Confirmation Code prompt followed by a text field in which the student can enter the confirmation code.
- Verification Text Field prompt(s) and answer(s). There are typically more than one prompt/answer pair to verify a given activity. The system will randomly select one to provide to the student. The answer will be displayed to the admin to aid in validation. Not every prompt has an answer.
- Upload Image prompt. The text string prompt for image upload. Example: "Upload a picture that includes your face and you holding an incandescent bulb and the CFL bulb you will use instead."
- Confirmation Code prompt. The text string prompt for the confirmation code. Default: "Enter the confirmation code you received at this event".
- Number of confirmation codes to generate. The user can enter a number that specifies how many confirmation codes they need for this event. The system will make available a page with confirmation codes for this event that the admin can print and use a paper cutter to transform into individual tickets. Or maybe this is a CSV file that can be imported into Excel and formatted into tickets or something.
Note that the last four fields (Verification Text Field prompts and answers, Upload Image prompt, Confirmation Code prompt, and Number of confirmation codes to generate) are context-sensitive and depend upon the value the user selected for Verification Type.
Admin adds a new activity called "Attend Blue Planet Foundation meeting"
- Type is event.
- Publication date is today.
- Event date/time is in five days.
- Expiration date is in ten days.
- Expected duration is 2 hours.
- Verification Type is Confirmation Code. Prompt is "Enter ticket code provided at meeting".
- Kukui nuts is 5.
Admin adds a new activity called "Attend Energy Pong competition"
- Type is event.
- Publication date is in five days
- Event date/time is in ten days.
- Expected duration is 1 hour.
- Verification Type is Confirmation Code. Prompt is "Enter ticket code provided at meeting".
- Expiration date is in fifteen days.
- Kukui nuts is 5.
Admin adds a new activity called "Replace an incandescent with a CFL"
- Type is action.
- Publication date is today.
- Expected duration is 5 minutes.
- Kukui Nuts is 10.
- Verification Type is Upload Image.
- Upload Image prompt is: "Upload a photo of you holding the incandescent and the CFL you replaced it with."
Admin adds a new activity called "Watch "Be Energy Akamai!, Episode 1" video"
- Type is action.
- Publication date is today.
- Expected duration is 10 minutes.
- Kukui Nuts is 10.
- Verification Type is Text Field.
- Text field prompt and answer is: "What is the unit of measurement for household energy?", "kilowatt-hour"
- Text field prompt and answer is: "What is the unit of measurement for power?", "watt"
After adding these activities, the table view of all activities is updated to list these activities.
Admin logs out.
Activity selection by user
User logs in.
- User is placed on their home page.
User navigates to user-level Activity Manager page.
- Page displays:
- A table ("Open Activities") with all activities currently available to user to perform.
- Note that the "Attend Energy Pong competition" activity is not visible to user.
- Table shows the title, date(s), Kukui Nuts, Expected duration, number of students who have completed that activity, number of students who "like" that activity. Clicking brings up a new page/modal window with the description.
- A user can indicate a Facebook-like "Likes this" for any given activity. This puts a little star (or something) next to it, and can be used by the system to indicate interest in the activity by others.
- There is a button in each row for each activity called "I did it!".
- A table ("Submitted Activities") with all activities the user has submitted for validation, or have been validated.
- The activity name and date/time submitted are shown, along with status (submitted, awarded, declined) and if awarded, the Kukui Nuts given. There is also a comment field that can contain text by the admin regarding the status of the activity.
User indicates that the activity "Replace an incandescent with a CFL" looks cool.
- This updates the display of the number of students who think it is cool by one.
User logs out.
Activity submission by user
User replaces an incandescent with a CFL and obtains a photo of themselves with the two bulbs.
User logs in.
- User is placed in their home page.
User navigates to user-level Activity Manager page.
- They scroll down to the "Replace an incandescent with a CFL" activity, then click the "Submit for verification" button.
- A new page (or modal window) pops up with an upload file button and the verification text field ("Upload a photo of you holding the incandescent and the CFL you replaced it with.").
- The user uploads the photo.
- There is always an additional text field with the label "Note to admin (optional):". This allows users to provide additional information about their submission if they wish.
User sees that this activity now appears in the "Submitted Activities" table.
- The status of this activity is "submitted", and the current date and time.
User logs out.
Activity is validated by admin
Admin logs in.
- System puts her in Admin page.
Admin goes to "Activity Manager" page.
- This page also contains a table called "Pending Validations". Each line of the table describes one submitted verification by a user, including:
- The user ID.
- The name of the activity submitted.
- The date/time it was submitted.
- The prompt the user saw.
- The user's answer (text or photo or confirmation code).
- The suggested response for that specific prompt (if any).
- The "Note to admin" text (if any).
- Button to "award", button to "decline".
Admin finds the submitted verification by the user in the "Pending Validations" table, and clicks "award".
Admin now sees the user's activity in the "Completed Validations" table.
- There is a third table on this page called "Completed Validations".
- It includes all of the fields from the Pending Validations table, plus a field indicating the date/time that an admin made a decision, the user ID of the admin that made the decision, the decision made, and an "Admin comments" field for the admin to note optional info about the decision.
- There is also a button called "Undo decision" that an admin can press to move the submitted verification out of the completed validations table and into the Pending Validations table. This should also reverse any kukui nuts that were awarded to the user (if the prior decision was to award them).
Admin logs out.
Awarded activity is noticed by user
User logs in.
- User is placed in their home page.
User navigates to user-level Activity Manager page.
- User sees that the state of "Replace an incandescent with a CFL" activity in their "Submitted Activities" table has been changed from "submitted" to "awarded", and 10 kukui nuts now appears there.
User notices that their total number of Kukui Nuts has been incremented by 10.
User logs out.
Admin reverses decision
Later, the admin discovers that this user has used someone else's photo, so they want to retract the points.
Admin logs in.
- System puts her in Admin page.
Admin goes to "Activity Manager" page.
- Admin finds the activity in the Completed Validations table by the user.
- Admin clicks "Undo decision" to move it into the Pending Validations table.
- Admin clicks "Decline" button, and indicates in the "Admin Comments" field that the photo was not of that user, and to email if any questions.
Admin logs out.
User finds out about the reversed decision
User logs in.
- User is placed in their home page.
User navigates to user-level Activity Manager page.
- User sees that the state of "Replace an incandescent with a CFL" activity in their "Submitted Activities" table has been changed from "awarded" to "declined", and the comment from the admin that the photo is not of that user.
User notices that their total number of Kukui Nuts has been decremented by 10.
User clicks on the "Contact Admin" button on every page to send an email to the admin to discuss the issue further.
