A VersionOne Work Item Hygiene Dashboard

If you haven’t been following along, it might be helpful to review prior posts, Getting into the VersionOne Query API and Working with the VersionOne API. The short version is that V1 doesn’t make it as easy as it should be to suss out work items whose data aren’t quite right — and therefore will at least skew the metrics you are depending on. Thanks to Brandon Call for reminding me to close this off with some code y’all can use.

Part of the delay in getting this last piece out was that I didn’t want to just throw some code out there and wish you the best getting it to work. I wanted to be able to walk you through getting it to work in a context we all have access to. To follow along, if you don’t have your own VersionOne instance running somewhere already, you’ll need to head to the VersionOne pages and request a free trial. After you get that, don’t dawdle as it expires after 30 days. Apologies and thanks to CollabNet for the unintended assistance with this. After you have your backend instance, use the instructions in “Working with…” to get your API key value and <server base url>.

Solution Overview

I’ve built a small backend service using Node 8.x (Carbon LTS) that runs in a Docker container. You can run it without the container if you prefer on your desktop but I wanted it working in a container so it’s ready to run somewhere else if you prefer (we run it as a Fargate container on AWS). This service is API-only and you can use the MVP UI I made or build something you prefer.

The other piece is a very simple UI that uses Vue to offer some easy-to-use custom elements. It’s very POC/MVP — doesn’t even use the Vue CLI to scaffold all of the typical stuff. You get what you pay for. ;-)

We’ll get the service working first, then connect the UI to it.

Getting the Hygiene Service up

Follow the instructions in the README.md in the GitHub repository for the project — it just won’t work out to repeat them here and then try to keep them up-to-date in both places. There is also some explanation of the code/approach there if you are interested.

The important parts summarized:

1. Clone the project to your local system.
2. Run npm init to pull in the project dependencies.
3. Set your API Key as the environment variable V1APIKEY (e.g., export V1APIKEY=1.Z2…Xyg=).
4. Configure your v1ServerBaseUrl in config.js (don’t try to use mine as your API Key won’t work with it). Save config.js.
5. Run npm start or the container commands (see docker-cmds.txt) to get an instance up and running.

Assuming all has gone well to this point, and that you just ran npm start (instead of using the container) because you want to get going, you should be able to hit the /healthcheck endpoint to make sure it’s at least listening (localhost:3000/healthcheck).

We interrupt this program for an important aside…

I’ll assume you created a temporary V1 instance courtesy of CollabNet in the examples/discussion that follows. Because from here on it, it’s about the data in your V1 and I don’t know what that data looks like. The temporary free instance from CollabNet comes with a “Sample: Company” planning level, a couple sample teams and some sample data. I’ve pre-set some of the query parameters presuming that you are using the V1 default sample as well. [If you need more help, we can chat, but I need some sort of LCD for continuing.]

Testing your connection

Presuming your /healthcheck returned a somewhat cheeky “situation normal”, you can test the connection to V1 (and your API Key) by hitting localhost:3000/getteams. You should see something similar to the image below.

Results of Get Teams query against Sample: Company data

If that worked, we can move onto adding the UI into the mix. If not, please review steps above and give it another go.

The Hygiene Dashboard, v.mvp

Services and APIs are awesome, but they don’t get most users particularly excited. To be fair, the UI in the companion GitHub repository is only a small step above that, but it can be a starting point for something bigger or at least an example of how to work with the API.

The README.md in the repo linked above is the best place to get info on how to use the code. Short version is: (1) clone the repository to your system, (2) update the serviceUrl in load-config.js to point to where the service you started above is running, (3) save load-config.js, (4) open the index.html file in your favorite browser (only tested in Chrome). You should see something similar to the image below.

First look at V1 Work Item Hygiene Dashboard

Aside: This was built for an environment with many teams sharing a single V1 instance. Getting the right Planning Level (Scope) is how we focus the results for our team(s). Teams are not associated with a particular planning level in V1, so there’s no reasonable query to show just the right teams for a planning level/scope. Most of our teams are named with an organizational prefix, hence the Team filter input box as a way to limit the number of team selections. I’ve seeded the initial data items to suit the default V1 example.

If you see that, things are going well. The UI is up and connected to your service which is talking to V1 just fine.

To see some data in the queries, choose “Sample: Release 1.0” as the Planning Level and “Sample: Team A” as the Team.

Looks better with real data

The items in the query results are all links that will open in a new tab when clicked. The dashboard page will not auto-refresh (there’s likely little need to re-run all of the queries) — there’s a Reload button on the right side that will re-run just that query and refresh the results. Keep going until they are all cleaned up — the whole point of this dashboard is that those items are failing a data check.

It’s about what matters to you

You may look at my queries and think “Who cares about that?”. Fair enough (but the people I work with clearly do). Hopefully I’ve provided enough context and enough example for you to chase what matters to you.

As I get early comments, I’ll make some edits here to improve the experience. Comments that improve the code will be covered in the appropriate README.md at GitHub, though, not here.

Fight GIGO by making sure your work items are in good data health.

Container addendum

coming very soon… I’ll walk through how to use the containerized versions of the two projects.