Automate ticket response for UserVoice sites. Using this CLI you can automate generating suggestions (or ideas) for open tickets. You can also manage tickets, suggestions, and perform bulk operations.
There are two things you need to get started with the SkillsTickets CLI. From now on called CLI or st.py.
First, you need to get a developer or admin account on your UserVoice installation. When you do, you will have a series of keys that you need to save and use to use this CLI. The following section named Credentials goes into details on how to use these credentials.
Second, you need to setup your environment. See that section for details. However, note that you can either setup your local machine with Python3 and dependencies or better use the Dockerfile to create a container with all the details. You can also use one of my publish images: dockerhub.io/drmax/skillstickets:latest.
Once you have created credentials for your UserVoice account, you will be given the following keys:
subdomainis the URL subdomain for yourUserVoiceinstallation, e.g., support.labs.cognitiveclass.aiurl_callbackset this tohttp://localhost:4567/api_keythis is a unique key for youapi_secretthis is a unique secret key for yousso_keythis another key you need to generate in yourUserVoiceinstallation and it perdiodically expires, so you might have to re-generate itdisplay_namethis is the name that will be used for suggestions and tickets you create with this CLIemailthis is the email you use to login to theUserVoiceinstallation
You will need to keep these and use them when invoking the CLI. You can either pass each key with each invokation using the corresponding option named by the key listed above.
Or as a shortcut, you can create a credentials.yml file and add all your keys and info in there. Then you can pass all credentials at once using --credentials=./credentials.yml.
Create your ./credentials.yml file with a command as follows or with your favorite editor:
cat > credentials.yml <<EOF
# Server
subdomain: cognitiveclass
url_callback: http://localhost:4567/
# APIs
api_key: [API key here, without the []]
api_secret: [API secret key here]
sso_key: [SSO key here]
# User
display_name: [display name here]
email: [email here]
EOFWARNING needless to say that you should not share not checkin to GitHub nor make public your credentials.
The following is a brief user guide for the st.py CLI. You can see an abreviated version of this user guide by running ./st.py --help
➜ skills-tickets git:(master) ✗ ./st.py -h
Skills Tickets
Usage:
st.py tickets list [options]
st.py tickets show ID [options]
st.py tickets delete ID [options]
st.py tickets create TITLE BODY [options]
st.py suggestions list [options]
st.py suggestions show ID [options]
st.py suggestions delete ID [options]
st.py suggestions create FORUM_ID TITLE BODY [options]
st.py forums list [options]
st.py forums show ID [options]
st.py csv verify FILE [options]
st.py csv split FILE CLUSTER [options]
st.py (-h | --help)
st.py (-v | --version)
Options:
--credentials=FILE A YAML file with API key, user, and server options values.
--output-file=FILE The file path to save entries when processing CSV files.
--subdomain=SUBDOMAIN The subdomain name for this UserVoice installation [default: cognitiveclass].
--url-callback=URL-CALLBACK The URL callback for this app [default: http://localhost:4567/].
--api-key=API-KEY The API key for the current user.
--api-secret=API-SECRET The API secret key for the current user.
--sso-key=SSO-KEY The API SSO key for the current user.
--display-name=DISPLAY-NAME The user's name to display in messages.
--email=EMAIL The email for the current user.
--show-details Print the details of a show command, e.g., prints the list of suggestions [default: Fasle].
--verbose Show all output.
-h --help Show this screen.
-v --version Show version.This lists the help for all command and options in the CLI.
The suggestions command group is used to manage UserVoice suggestion or idea objects.
Usage:
st.py suggestions list [options]
Description:
Lists all the suggestions (or ideas). Use --show-details to print all the suggestions found. This can take a while.
Example:
./st.py suggestions list --credentials=./credentials.yml
Found '465' suggestionsUsage:
st.py suggestions show ID [options]
Description:
Displays the details for one suggestion. You need to have the unite ID for the suggestion to list it.
Example:
./st.py suggestions show 11343366 --credentials=./credentials.yml --show-details
Suggestion: 40333864 title: 'final exam : while taking it had server issues multiple times, for CC0101EN cloud- I sent mail but no response - please respond it soon' is currently 'published'
referrer: https://support.cognitiveclass.ai/forums/317580-general
vote_count: 1, subscriber_count: 1, comments_count: 0, supporters_count: 1
category: Courses, status: None, response: None
text: final exam : while taking it had server issues multiple times, for CC0101EN cloud- I sent mail but no response - please respond it soon - I need to get the badge for my future project
------Usage:
st.py suggestions create FORUM_ID TITLE BODY [options]
Description:
Creates a suggestion. You need to find the ID of the forum where this suggestion will be created. Use the forums command to list and show forums and get their IDs.
Example:
./st.py suggestions create 317580 "test max" "test maxim" --credentials=./credentials.yml --show-details
Created suggestion `27530678`Usage:
st.py suggestions delete ID [options]
Description:
Delete a suggestion by ID.
Example:
./st.py suggestions delete 27530678 --credentials=./credentials.yml
Deleted suggestion `27530678`The tickets command group is used to manage UserVoice ticket objects.
Usage:
st.py tickets list [options]
Description:
Lists all tickets.
Example:
./st.py tickets list --credentials=./credentials.yml
Found '5711' ticketsUsage:
st.py tickets show ID [options]
Description:
Shows the details for a ticket passing its ID.
Example:
./st.py tickets show 457108345 --credentials=./credentials.ymlUsage:
st.py tickets create TITLE BODY [options]
Description:
Creates a ticket with TITLE and BODY
Example:
./st.py tickets create "my title" "text body" --credentials=./credentials.yml
Created ticket '87529309'Usage:
st.py tickets delete ID [options]
Description:
Delete a ticket by ID.
Example:
./st.py tickets delete 457108345 --credentials=./credentials.yml
Deleted ticket '457108345'The forums command group allows listing and accessing forums used to submit suggestions.
Usage:
./st.py forums list [options]
Description:
List the various forums. Use --show-details to show the ID and name for the forums.
Example:
./st.py forums list --credentials=./credentials.yml --show-details
Found '1' forums
1. ID: '317580', name: 'General'Usage:
st.py forums show ID [options]
Description:
Shows the details for a forum object by ID.
Example:
/st.py forums show 317580 --credentials=./credentials.yml --show-details
Forum: '317580', name: 'General'The csv command group contains command to manipulate CSV files of tickets data to perform --bulk operations.
Usage:
st.py csv verify FILE [options]
Description:
This command will verify a CSV file with clustered tickets data. You can use it to see the fields, find the number of entries, and also list the clusters.
Example:
./st.py csv verify ./clusters/all.csv
Entries: found '5717' entries in './clusters/all.csv'
Keys: found '18' keys: , id, ticket_number, name, email, subject, text, user_agent, state, assignee_name, assignee_email, user_messages_count, agent_messages_count, last_message_at, created_at, updated_at, type_field, cluster
Clusters: found '17' clusters: Miscellaneous, error, open, work, jupyter_notebook, data, file, load, run, email, time, hello, able, unable_access, python, start, jupyter_labUsage:
st.py csv split FILE CLUSTER [options]
Description:
This command will split a CSV file into smaller files with entries for the cluster specified.
Example:
./st.py csv split ./clusters/all.csv error --output-file=error.csv
Found '627' entries for 'error' cluster
Wrote '627' entries for cluster 'error' in file: 'error.csv'TODO
We welcome your contributions. You can do so by opening issues for features and bugs you find. Or you can submit PRs when you have specific changes you would like to make. These changes can be both for source code, tests, and docs.
This CLI uses Python 3.0 or later. Please download Python 3 for your particular environment to get started.
To run this CLI in your local machine. Besides Python 3 you will also need to install some dependencies. You can do so using Python's pip tool. Fist ensure pip is installed on your machine.
Once pip is installed, then install the dependencies with:
pip install docopt
pip install uservoice
pip install cryptoYou can verify that your system is running by running the unit tests: ./hack/build.sh --test.
Also run the CLI help with: ./st.py --help
TODO
The code includes both unit tests and integration tests. You can run all unit tests by invoking: ./hack/build.sh --test.
Integration tests will require you to have Credentials for a running UserVoice installation in a file called credentials.yml. You can then invoke ./build/build.sh --e2e to run the integration tests.
You can run both types of tests with ./hack/build.sh --all
Once you can run all the tests. Please make your changes, add more tests, verify that all tests are passing. Create and submit a PR.
The following are immediate next steps:
-
Add
--bulkoptions for operations using a CSV file as the input for parameters -
Refine the
Dockerfileand use it inhack/build.shsuch that all tests are run on a container to avoid and remove dependencies on local development system -
Add missing
client_test.pytests -
Add more docs, particularly refining this README.md and more example workflows
-
Fix an intermitent issue with SSO login