ehzhang / helpq

💁 an extensible real-time queue application, for mentorship @ hackathons and classrooms

HELPq

An extensible, customizable real-time queue system, built with Meteor!

What is this?

HELPq was originally built for HackMIT, but has been used at hackathons like Blueprint, Meteor Summer Hackathon 2015, WHACK, MakeMIT and WildHacks (among others!).

It is a real-time help queue and mentor management application, targeted at hackathons and classrooms, where there is a need for issues to be claimed and satisfied within minutes. It includes a simple interface for requesting tickets, claiming tickets, administrating users/mentors, and examining metrics.

It is built with an emphasis on three fundamental user experiences:

Keep it simple

Students should be able to log in and do exactly what they want - submit a ticket. Nothing more complicated than that.

Pull, don't Push

Mentors should not receive any type of push notifications when tickets are requested. Instead, mentors should be pulling from the mentor view and claiming tickets whenever they see them. That way, mentors will not get annoyed by a feed of requests and instead provide high-quality advice because they are themselves actively seeking out people to help.

Encourage in-person interaction

Mentors can claim tickets, complete tickets, or choose to reopen them. Mentors can only claim a single ticket at any given time. There is no ability to message a student through the app in order to encourage a mentor to find that student and help them in person. A student can, however, choose to include other contact information in case contact is needed to clarify location.

Features

Home

1 - Ticket Request

Users can request a ticket, by providing their problem description, where they are, and how they can best be contacted. This copy can be easily modified in one of the config files!

Once submitted, users have an option to cancel their ticket ("Nevermind!"). Tickets will also expire based on a value determined by the admin.

2 - Announcements

Admin can send out announcements with varying colors through the admin dashboard, which appear on on the home screen.

3 - Mentor Status

The mentor status bar shows how many mentors are currently online, and calculates the expected wait time based on historical ticket claim and completion times.

4 - Current Queue

The current queue shows who is currently in the queue and which people are currently receiving help. Because the nature of questions available mentors can address are highly variable, tickets will often not be answered in order of submission.

Mentor

Mentors should be mobile, and the HELPq is designed for mentors to browse the help tickets on their smart phones.

If a user is a mentor, they will have an inbox icon in the top right they can click to navigate to the mentor view. If the HELPq is being viewed on mobile or a very narrow window, the app is responsive and will pull up a navigation bar on the bottom for Home, Mentor, and Profile.

Claim

You can claim a ticket by selecting "Claim Ticket". This will notify the user that you are on your way! Once a ticket is claimed, you cannot claim another ticket unless you complete or reopen the ticket.

Complete

Once you are done working with a student, you should mark that ticket as completed. This will give the student an opportunity to rate their experience with you!

Reopen

You can choose to reopen the ticket if you feel like you could not adequately solve the problem, or think someone would be better at addressing it.

Admin

The admin dashboard has a lot of useful features for hackathon organizers or class staff! Shown above is the Metrics dashboard.

Announce

The announcement section allows you to create announcements for the home screen, with a variety of different colors.

Users

The users table lets you see all of the current users, and mark them as mentors or admins. You can also edit other user's information - of course, be responsible with this power!

User Creation

Login is done through Github or Facebook (which can be enabled or disabled in a config file), but you can manually create user accounts.

This takes a CSV formatted string, which will then check your format, and create users asynchronously. If a user's account creation fails, the result will be shown.

This feature was designed for use in classroom settings, or other restricted access settings, so that you can create an account for each student and a password unique to them.

This feature is also useful for when a user does not want to login with Facebook or GitHub (even though only public information is retrieved).

Tickets

The tickets table will show you a history of all tickets.

• Green: tickets have been completed
• Red: tickets that have been cancelled
• Yellow: tickets that have expired
• Grey: tickets that are currently claimed

Metrics

The metrics pane shows a lot of information regarding the usage of the queue.

The first is a metrics summary, which includes average, median, and std dev of response time and completion time, as well as the raw average of all ticket ratings.

The leaderboard also shows the top 10 mentors with ratings. Their rating is not a raw average of their tickets, but instead blurred slightly with weighting. This is to avoid the situation where a user with a single 5 star rating would be listed above another user with four 5 star ratings and a single 4 star rating.

Feedback

The feedback section is a feed of all mentor feedback, with star rating and a note. Bad ratings are highlighted.

Settings

Settings allows you to adjust various settings in the queue. Right now, you can open/close the queue and set the time for when tickets expire.

Usage Data

We've used this at a bunch of hackathons and we have some data on them :)

Hackathon	Date	Response time average	median	stddev	Completion Time average	median	stddev	Rating Average	Users	Mentors	Tickets
Blueprint High School Hackathon 2015	2/22/2015	5:11	1:26	9:54	10:37	6:29	13:23	4.9	193	64	170
Meteor Summer Hackathon 2015	8/8/2015	6:21	2:29	10:58	5:46	1:26	12:03	4.09	68	66	37
HackMIT 2015	9/19/2015	9:37	2:48	28:00	16:30	10:01	22:59	4.7	425	242	502
WHACK 2015	10/3/2015	7:55	4:56	12:30	18:19	13:02	17:27	4.9	87	39	94
HackIllinois	2/19/2016	56:00	8:47	3:00:29	32:53	18:46	1:00:25	4.6	353	353	221

Bring HELPq to your hackathon/classroom!

Requirements

Make sure that you have meteor installed. You can install Meteor through their website.

Quickstart

Heroku

When deploying to Heroku, you must set at least the ROOT_URL and ADMIN_PASSWORD environment variables.

Mac OS X, Linux

  ./create_config
  meteor

Windows:

Copy the private/config.json.template into private/config.json

  meteor

Deploy

IMPORTANT

Without login configuration, you will only be able to login with the admin username and password specified in private/config.json (or the corresponding environment variables).

If you're not using Heroku, you can deploy with:

  meteor deploy <your domain name>.meteor.com

Configuration

Login

To configure login, edit private/config.json. Alternatively, you can configure login using the environment variables listed in app.json (this is especially useful when using Heroku).

In private/config.json (or the corresponding environment variables), provide the appropriate application id/secret combinations for either Facebook or Github authentication, or choose to disable them.

Branding

For front end branding, edit client/stylesheets/scss/_branding.scss

In this file, you will find brand variables and classes for the main splash and main banner.

You can edit these and observe the changes. There are also comments to explain what each setion does.

Copy

To edit copy, edit lib/constants.js.

In this file, you will find a place where you can change various strings across the site, including the title of your app.

Orientation

The queue has been found to be most effective with an orientation with mentors and a tight integration with the way a hackathon/classroom manages mentorship. If you'd like to talk about how this could work for your hackathon/classroom, don't hesitate to email me at [email protected]!

Feedback

Have you used HELPq or are planning to use it at your hackathon? I'd love to hear how effective it was, what kinds of metrics you got, and what kinds of things people wanted. Don't hesitate to email me at [email protected]!

Contributing

I'd love to take pull requests! Please read the Contributing Guide first!

helpq's Issues

spacing for mentor leaderboard gets messy in the double digits.

If there are 10+ mentors, the spacing between names and numbers in the leaderboard gets a little small.

See # 10 in the attached image.

Thanks!

Quickstart Errors

When following Quickstart instructions for Mac/Linux (./create_config && meteor):

It appears ./create_config completes fine, giving back the following output:

Server side config created.
Edit it in private/config.json to add Facebook or GitHub integration.

However, program spits back these errors when meteor runs with no edits to any files on a fresh install of Meteor:

=> Started proxy.

=> Meteor 1.3: ES2015 modules, npm integration, app testing, mobile
improvements, and more.

This release is being downloaded in the background. Update your app to
Meteor 1.3 by running 'meteor update'.

=> Started MongoDB.
=> Errors prevented startup:

While downloading [email protected]...:
error: getaddrinfo ENOTFOUND

While downloading [email protected]...:
error: getaddrinfo ENOTFOUND

=> Your application has errors. Waiting for file change.

request to update quick-deploy link to not use mlab

MLab is deprecated

Setup and running

How do I set up this and run on localhost ?

[Feature] Password Change

Ability for a user to change their own password.

Add a chat feature

I recently used this as a mentor for Hack OHI/O and noticed that a large, important feature this is lacking is the ability to chat directly with the hackathon participants submitting tickets. This was an issue because there were almost a thousand participants and it was sometimes hard to find the people that submitted the ticket.

Facebook login doesn't work

The meteor version is so old that it is using an outdated version of the FB Oath API. Potential quick fix here: https://github.com/fede-rodes/facebook-accounts-patched

Problems getting Github oAuth to return to the user's page.

This is my first time using Github oAuth and I'm having a bit of a problem.

I have assigned Github OAuth's client ID and User Secret to config.json, and "enable" is set to true. But when I sign in with Github using the "Login With Github" button, it takes me back to the HELPq's login page instead of the homepage.

In my Oauth applications, I am setting the homepage URL to:

http://nameofwebsite.com

and I am setting the Authorization callback URL to:

http://nameofwebsite.com:3000 <-- the application runs on port 3000

I should also mention that when it returns to the login page, I see this in the url:
nameofwebsite.com:3000/error=redirect_uri_mismatch&error_description=The+redirect_uri+MUST+match+the+registered+callback+URL+for+this+application

Am I not properly assigning these URLs? Please let me know what you guys think.

Proposed Feature List v0.3

• Show user ticket content after submit (Easy)
• Ticket Categories and Mentor Filtering

Deploy to Heroku button

Do you think it would be helpful to have a deploy to heroku button (e.g. {link})?

To make this not a pain to use, we'd need to add support for using environment variables in addition to the config.json (should be fairly straightforward), because ideally people should be able to set this up using only the Heroku web UI. Besides that, we'd probably want to do something with how the admin account works so people can change the password via config file (so people don't have issues like #1).

I had already written some config code to make this work on Heroku (for 6.S191), though I haven't done the envvar stuff.

If you think this is a good idea, I can start working on a PR.

[Feature] Add Slack integration

Here's a wishlist for Slack integration:

• A webhook to Slack that will post into a "mentor feed" channel on ticket updates.
• A route that users in Slack can use via a slash command to create, cancel, and get their tickets.

How do hackers access the portal?

While I'm using this application to sign up mentors, Im conceded about how hackers could sign up for the application and post questions. Because it seems like Users can only either be an admin or a mentor. Is it there no implementation for hackers login? Or they have to use facebook / GitHub?

Suggestion: Trim username at the login page before attempting to log in

Currently logging into Helpq requires you avoid spaces before and after typing in your username. So this input will not work:
username: " admin "
password: "hunter2"

My fork has made changes so that the above input works. Of course, only the username is trimmed, not the password. If you would like to implement this change, I've included the modified code block. This change is made in client/components/login/login.js :

  Meteor.loginWithPassword(
      $(t.findAll('#username')).val().trim(),
      $(t.findAll('#password')).val(),
      function(error){
        if (error){
          $(t.findAll('#password')).val("");
          t.error.set(error.reason);
        }
      }
  )
}

[Feature] Request specific mentor

Would be helpful for cases where people get help with someone, but then later have a follow up question on the same issue.

We could either sort tickets differently (e.g. show tickets directed to a given mentor first for that mentor) or have an extra tag on the tickets with the requested mentor name.

Still uses "hunter2" as admin password

Even after changing the admin password in config.json, the application still requires "hunter2" as the password for the admin account.

Save "How can we help you?" input and display while waiting

(context: at Hack@Brown)
It would potentially be a nicer user experience for the requestee to be able to view the form submission while waiting for a mentor – just to have a reference to what he/she requested help on.

If you agree, I could implement it if you don't want to.

Outdated version of iron:middleware-stack

iron:middleware-stack version listed in .meteor/versions is outdated and causes the error specified in this stackoverflow thread.

Github OAuth Broken

Like #31 , the OAuth for logging in with Github doesn't seem to work and instead brings up a 404. Can I expect this to be resolved soon? I'm working on deploying HELPq for a hackathon.