Using the Discourse helper
UserVoice is a support system that is commonly deployed at large centers to accept user requests for help, typically via an email. On the user side of things, the user can submit a tickete asking for help via email. On the agent (research computing) side, there is a web interface to manage and respond to the tickets.
It’s very likely that a UserVoice ticket is coming from a user that is working on a command line. This means that in order to submit a ticket, he or she needs to stop working in the terminal, open a browser to an email client, and then write up the issue, sometimes copy pasting content from the terminal. While this works for many use cases, arguably, the extra clicks and need to copy paste are un-needed extra steps. It also does not do well to show the agent exactly what is going on, or to add extra detail from the environment. Helpme it better integrated because:
UserVoice isn’t one of the default clients provided by HelpMe, so you need to install one extra dependency:
$ pip install helpme[uservoice]
If you are installing helpme yourself, you will need to export a set of environment variables the first time that you use HelpMe. Primarily you will need a HelpDesk Api token, and to specify that it will not be in a trusted location. Note that @vsoch is waiting to hear back from UserVoice support about whether:
It likely is the case that we will be fine to use the untrusted location key and secret, and then rely on authentication to the service via the user email. This documentation will be updated when we know the answer to this.
For now, you can test by way of an untrusted api key and secret, and you will need to export them to the environment (only once when you first use HelpMe with UserVoice). For example:
export HELPME_USERVOICE_SUBDOMAIN=srcc export HELPME_USERVOICE_API_KEY=xxxxx export HELPME_USERVOICE_SECRET=xxxxxx export HELPME_USERVOICE_EMAILemail@example.com
If you are an admin on a shared resource and want to provide this for your users, then you can also define these variables in the global configuration in the uservoice section:
[uservoice] helpme_uservoice_subdomain=srcc helpme_uservoice_api_key=xxxxx helpme_uservoice_secret=xxxxxx
And your users would be responsible for exporting the email environment variable still.
This means that if you are the user on the shared resource, you would only need to export your email to the environment. If you don’t have any of these variables defined, you will get an error message telling you which are missing:
ERROR export HELPME_USERVOICE_EMAIL environment or add to helpme.cfg
A request for help takes the following steps:
And then the ticket is submit! Here is what that looks like.
$ helpme uservoice [helpme|uservoice] Hello Friend! I'll help you post a UserVoice ticket today. Please describe the issue you are having: Hello Research Computing! I am having so many problems, I am a very easily distracted user. Oh, and I looove Matlab, it's like, so great! Please do my science for me and solve the thing. Thanks! Would you like to send a terminal recording? Please enter your choice [Y/N/y/n] : Y asciinema: recording asciicast to /tmp/helpme.bji8orya.json asciinema: press <ctrl-d> or type "exit" when you're done ... exit asciinema: recording finished asciinema: asciicast saved to /tmp/helpme.bji8orya.json Asciinema If you need to run helpme again you can give the path to this file with --asciinema /tmp/helpme.bji8orya.json Environment USER|TERM|SHELL|PATH|LD_LIBRARY_PATH|PWD|JAVA_HOME|LANG|HOME|DISPLAY Is this list ok to share? Please enter your choice [Y/N/y/n] : Y https://srcc.uservoice.com/admin/tickets/23818 [submit=>uservoice]
You can also use an asciinema that you already have:
$ helpme uservoice --asciinema /tmp/helpme.bji8orya.json