Using Python to Build a Jazz Widget – Part 1

I have been spending the past couple of weeks wondering about what I would write about next.  As a manager, I don’t get a lot of time to dig into the deep technical issues like I used to, and I miss that.  So I had some spare time on my hands, and I wanted to do something different that would help me learn something, and also be useful.  I am picking up Python, so I figured that something useful in Python would be good.

As always, the code in this post is derived from examples from Jazz.net as well as the blog posts I mention. The usage of code from that example source code is governed by this license. Therefore this code is governed by this license, which basically means you can use it for internal usage, but not sell it. Remember that this code comes with the usual lack of promise or guarantee. I did all of this against a v4.0.2. RTC instance.  So read on, and feel free to try this out for yourself.

The Problem and the Approach

One of my big issues as a manager is getting the story of my team across to our stakeholders.  I have widgets which show the state of our significant stories and epics, but my stakeholders are not all technical types, and sometimes they need something a bit more graphic.  The presentation needs to have some color, and some interesting graphics.  I didn’t want to fool around with BIRT, because I might have some custom calculations, and some custom icons that I want to use.  I also don’t want to have to upgrade the report when my tools get upgraded.  So I thought that I could create a Python script that would use OSLC to get the information that I need.  I can then take this information, and create a small HTML page with the information and links that I want to show.  Using the new External Content widget (see my earlier post on Management by Results), I can then display this content on a dashboard.  If I set up a cron job on my machine to run every six hours, I will not put an undue burden on the Jazz infrastructure, and I will give my stakeholders a nice dashboard view of what they want to see.

So this solves my reporting issue, allows me to learn Python, allows me to get deeper into OSLC, and should meet the needs of my stakeholders.  Time to get to work!

Figuring it Out

So since I am a Python newbie, I decided to do what I always do when starting with something new.  Do a web search for using Python with OSLC, and try to borrow as much code as possible from others who may have done this before.  Why reinvent the wheel?  I did see some good blogs on using Python and OSLC with RQM, easy authenticating with Python, as well as some OSLC with Python posts on the Jazz forums.

My First Sample Program

The blog posts were a good place to start, since everything begins with authentication.  So the first thing I did was to download and install the requests library by Kenneth Reitz that was mentioned in the easy authentication with Python blog post.  Since I am running Ubuntu, I just needed to make sure that I had the Python pip module installed.  I then downloaded the requests library,  Then I did a quick “sudo pip install requests”, and BLAM, the whole thing was all set.  My Python environment was set, now to try a quick sample program.

So I just want to get into the repository, authenticate, and see if I can get ONE single resource out of the repository.  No luck.  I keep having authentication issues.  So the next thing that I go and look at is the first blog that I listed, using Python and OSLC with RQM, and use the JazzClient class defined there.  I really like how simple it makes the main program read.  Still no luck.  As I look through the responses that I am getting back, I notice that I am hitting https://jazzserver:9443/ccm, and when I go and look at the Jazz repository the base URI is https://jazzserver:9443/rtc.  Looks like I have been hitting the wrong spot!!  Once I change that to the correct address, and add a second storage of the appropriate cokkies as described in a Jazz forum post, everything begins to work.

Now most of this code is “borrowed” from the blogs that I referenced earlier, but you can find the code out on JazzHub.  You can find my project on JazzHub, under the title “Python Jazz Client“.  Check out the HelloWorld.py and JazzClient.py files.  You can use them, but you will need to change the user, password and base URI in the main module.  Your base URI will probably look like “https://mycompany.com:9445/ccm”.

This Python Jazz Client project on JazzHub is interesting, as it is the first real “development” that I have ever done on JazzHub.  I made it a public project, so if you are interested in this type of work, or you have suggestions for expanding this JazzClient class, please join the project and pitch in.  I can honestly use all of the help that I can get.

Conclusion

So there it is, a bunch of Python code that helped me get more comfortable with Python, utilized OSLC, and gets through authentication and can pull information on individual work items.  It was so easy that even a slow-witted manager like me was able to do it.  Next I will begin to build on these basic capabilities, to pull specific information from work items, and then use this to create some simple HTML presentations of the data.

Management by Results – With an Assist from Jazz

Earlier today one of the people who works on my team (Sudhakar Frederick, or Freddy) sent me an email challenging me to do a blog post on how I manage our technical team.  He is going through his yearly review, and he found that he was able to pull his information together in record time.  I don’t know if it is worthy of a blog post, but Freddy is a pretty smart guy.  I learned a long time ago that it pays to listen to his opinions.  I’m not sure if he wanted me to highlight another effective usage model for RTC and Jazz, or if he felt that I should highlight the management style and philosophy, so I’ll try to highlight both things.

Background

I am a pretty technical guy, and I like being a technical guy.  However, at some point in time each one of us technical types runs into the horror of being recognized for our work, and rewarded with a position as a manager.  For some folks the thought of it is so unpleasant that they turn the job down.  I didn’t, and for the past three years I have been a manager.

IBM/Rational has a performance rating system that we go through every year.  Each year people are evaluated on the results that they have achieved over the previous 12 months.  Each person needs to briefly describe how their actions contributed to some type of measured results.  Now the results being looked for differ depending on your job.  So the relative importance of my results is viewed in the context of my current job.

So each year our technical people are asked to put together a short narrative on their significant accomplishments over the past year.  The key here is that we want a focus on measurable results.  Management will then go over these narratives, and be able to give people feedback on where their results rank within the organization, and then give the technical people feedback on what they can do to improve.

How We Ran Jumpstart – and Run Emerging Technologies

When the Jumpstart team formed, we decided that the best way to learn everything about Jazz was to actually use the tools ourselves.  So while RTC might not be a perfect fit for team focused on customer enablement and education, it can do a pretty good job.  We designed our own work items, with one type representing our customer engagements, as well as the existing Agile work items for epics, stories and tasks.

We record information in the work items, using the discussion area to keep notes, observations, and to share the progress that we make.  We record what we have done, what we learn, and current status of our various tasks and customer engagements.  By having someone indicated as an owner of each work item, we force ourselves to be accountable for moving things forward.  We also added an additional owners field which we use to indicate efforts where a small team of people are collaborating on something.  My team runs with the motto of, “if it isn’t on my dashboard, then it doesn’t exist”.

When we help customers, or provide some sort of enablement and training session, we record these in a specific work item type.  We also use epics, stories, and tasks, to help define and track the work that we do that might not be related to a specific customer.  So if we know that we want to create a “Getting Started Guide”, we will create an epic for this.  Then each chapter of the guide will be a story that is a child of this epic.  In this way we can divide the work across the team, while everyone is able to see what the other guide authors are working on.

Because we collect notes and observations on ALL of our work, the Jazz instance becomes something of a knowledge base for my team.  We often get questions from either our IBM field teams or our customers that we know we have seen before.  We just cannot remember the answer.  When this happens, we can go back through our old work items and search for the situation that we dimly remember from before.  Even if we have not noted the solution to the issue in the work item, we can see other people who were involved, and this often allows us to get input from other people who DO remember how to address that particular situation.

We also use the subscribers field in ALL of our work items, and add the names of team members (or managers) that we want to be aware of what is happening with any particular piece of work.  One of our other techniques is to use @username in the discussion areas of our work items.  When someone is called out in the subscribers area, or in the discussion through the use of their username, they will get an email alerting them to changes in the work item.  It’s a simple technique that we use to help us get the right people involved in any work that we are doing.

This is all predicated on people updating their work items, and in people keeping their notes in the discussion area of the work items.  As long as we stay disciplined about this, then we all reap the benefits of this approach.

How We Share Our Information

We use dashboards, and I refuse to use slides.  We have multiple Jazz instances within our organization, and I need to be able to share information with all of these stakeholders.  Some of this information is direct from the widgets that I use on the dashboard that my team uses.  Because we use special work items for our customer engagements, we are able to easily create queries and widgets that quickly inform people who we are working with, and what we are working on.  In these instances, we need to establish friend relationships between the different Jazz instances.

We use a common convention on what we use for the Summary field of our work items.  We use the  customer name followed by WHAT you are helping them with.  This allows me to use Work Item widgets coupled with queries on open work, to provide a quick list of the things that my team is doing.

How do I filter out just the open content?  I look at the state of the work item, and check to see that it is unresolved.  To see not just what is open, but what people have been working on, I use a different query.  In this Active work query, I look at the open work items, and then I add an additional condition that the Modified Date is after some period of time (I use 14 days, so I see what we have been working on in the past two weeks).  This allows the team to see what has really been actively worked on in the past 14 days.

I often provide analysis and bullets that help describe the data that we are posting on our dashboards.  This is usually in the form of single sentences and bullet lists, which is EASY to do with HTML.  I used to do this with HTML widgets, but I quickly ran into the issue of having to update the same HTML widget in multiple dashboards.  I didn’t like doing that, and I made mistakes.  Not a good solution.  So I decided that I could leverage the new External Content widgets in Jazz.  These widgets allow me to build some simple HTML pages, and then provide a simple pointer to include the content from those pages on my dashboard.  And on a bunch of other dashboards.  So I now can just update a simple HTML status file, and my updates get reflected immediately on ALL of the dashboards of my various stakeholders.  This allows me to focus on giving all of my stakeholders a consistent message and content, based on real data from my team, with each of them seeing the things in the context that they want to see.

Using this approach, with some simple HTML files used to report common status across multiple Jazz instances, does have a downside.  Our various Jazz instances use secure HTTP (with an https:// web address).  My simple HTML status pages are served out as unsecure http content (with an http:// web address).  Newer browser versions will often block this content by default.  You can get around this in a couple of ways:

The first option is the best option, but for the short term I am currently employing option #2.  I don’t have an secure HTTP server just lying around that I can use to host my little status updates.

What Do People Think?

My bosses love being able to surf around and see how my team is doing.  They love having this ability.  They also like being able to put widgets that update automatically on their own dashboards.  They probably also love the fact that they can find out what my team is doing without having to actually talk to me (although none of them will admit it!).

I like only having to update a small set of HTML files to report a consistent message to all of my stakeholders.  If I use a WYSIWYG editor to access those, then I can essentially give this to someone who is not technical, and have the reasonable expectation that they would be able to successfully use this solution.

My team loves this because they get to tell me what is happening, as it happens.  When we talk, they don’t have to remember everything that they have done over the past week.  If they have been updating their work items, then I already know about it.  No need for status reports!  (Hooray!  I hate writing status reports, and I hate reading status reports.)  It allows us to focus on and discuss the issues that we can collaborate on and resolve together.  When we get to end of the year reviews, my team can easily do reports and queries that remind them of all of the work that they did during the year.  They are able to easily and quickly pull together a powerful narrative that highlights their accomplishments and results from the past year.  It also helps us validate who participated in certain efforts, and by looking at the work items, we can determine the relative contributions made by our team members.

As a manager, I love it.  It allows me to see things at a glance, and see what my team is involved in.  By looking into the work items, I can “get up to speed” on any issues that have come up, and I can ask intelligent questions to help people discover solutions to their problems.  So while the dashboard gives me good information, it is only valuable in that it allows me to ask good questions.  You cannot just use it to blindly drive your team, and I don’t try to.  What it does do is give me an efficient way to get an overview of what we are doing, how we are doing it, and discover ways that I can help us improve.  It also gives me a way to consistently report status and analysis to my numerous stakeholders, so they can all have a consistent picture of how my team is performing, and the things that we see in our customer environments.

Key Points to Remember

  • In a team with people solving new problems and discovering new approaches every day, it is important to capture this knowledge somewhere.  We often get so focused on the NEXT thing, that we forget about the solutions that we have already discovered.  Being disciplined about updating work items helps us remember things, and helps us share information inside of our team.
  • We use subscription and the “@username” indicator in discussions a lot.  We use this to pull people into conversations and work.  You team should have a culture of holding each other accountable to responding to these types of alerts.
  • We also use the tags field.  We use this to tag certain work items for inclusion in very specific searches.  If I have a series of work items related to a particular issue, or pattern of issues, then I will tag all of the work items with the same tag, and create a query that returns only the work items with this tag.  That allows me to use a work item widget with this query on my dashboards to bring these things some executive level visibility.
  • I create dashboards for a lot of my stakeholders.  I use the team dashboard for my team, but I create a personal dashboard (and then share it) for many of my stakeholders.  If stakeholders only care about a subset of the activity that my team does, I create a specific tab for them on this dashboard.  That way they can see things in the context that they want to see.