My Lombardi Experience :

Press Escape to Delete

2010-07-15T06:34:03-06:00

We’ve blogged previously about Dangerous UI Choices, and I think everyone in this shop has been bitten by the issue described in that article. I thought that I had defeated the usability problems presented in that article, by making sure to always leave that particular prompt enabled. Teamworks, however, has outwitted me yet again.

Recently, while inspecting a process in production, I clicked Delete instead of Refresh. No problem, I thought, this is why I don’t turn off that dialog box. When the box popped up, I automatically pressed Escape to dismiss it. Clearly I have been suffering from a dramatic misunderstanding of what that key is supposed to do, since Teamworks deleted the process anyway.

I probably don’t have to elaborate much more on the grotesque violation of user interface traditions represented by this behavior. Escape is accepted on all major operating systems as the "oh-crap-that’s-not-what-I-wanted-to-do" key. The bizarre thing about it is, in most Windows Forms development platforms, the Escape key is automatically wired to the Cancel action in a dialog. You don’t even have to do anything special to make it work correctly.

Teamworks Authoring Environment Display your password

2010-04-07T14:43:20-06:00

When you run a Service from the Authoring Environment, Teamworks launches a new browser window. The Authoring Environment needs to authenticate to the Server so it passes your username and password in plain text in the url. The Server then redirects to a page that does not display your credentials.

Without going into esoteric reason about why passing passwords around in plain text is bad, I have a simple example.

We were running through some test scenarios in a room full of users and decided to launch a test services from the A.E. Up popped the web browser window with my username name and password in full view for the entire room to see and then the server froze. After 10 seconds or so, something woke up and the page finally redirected.

One of the users was kind enough to point out to the entire room that my password was displayed in the address bar.

Just peachy…

I suspect there are ways around it but none of them are terribly convenient.

Rename Considered Harmful

2010-02-16T14:30:36-07:00

The deployment should have been pretty straightforward. It was just a few services, none of which were impacted by the larger project that we are working on in parallel, so we didn’t have to do any by-hand merging or anything. However, when our deployment manager tried to import the changed services into the production environment, he got the following error message:

The excluded service "Map Documents" does not have service parameter documentMappingInfoList defined in the DB. You must either overlay the service or to create the service parameter. The Id of the service parameter in the XML file is 10525.

He asked me about this, and although I had not really worked on the Map Documents or anything related to this minor release, it seemed clear that there must have been some change to the Map Documents service, so he would need to import that as well.

The next thing we knew, all hell broke loose.

During troubleshooting, we discovered that there was a new version of the Map Documents service under development. The old version had been renamed to Map Documents (deprecated). There was one service mistakenly included in the import which was using the new version. But, all of the other services were still using the old version, so why did this cause a system-wide problem?

Services (and other items) are stored in the process server database with an auto-incrementing ID, and you can’t count on the ID for a service being the same in production as it is in development. So, when resolving dependent items during import, Teamworks must use some other mechanism. No problem, that’s why all these things have GUIDs, right?

Well I guess that’s not what the GUIDs are for, because Teamworks uses the name for resolution instead.

Here’s what happened: (deep breath)

There was one service which used the new Map Documents service, and when Teamworks tried to import it, it looked at the existing Map Documents service, even though the GUIDs did not match. It should have recognized that there was no service with the requested GUID, but instead it complained that the input parameters did not match. This prompted us to include the new Map Documents service. This overwrote the existing Map Documents service, again, even though the GUIDs did not match. It should have recognized that this was not actually the same service, but it silently ignored that. That was what did us in, because now all the services that were expecting the old Map Documents are now getting the new one. Obviously this caused errors, since the new service had different parameters and slightly different behavior.

The moral of the story is that you must carefully track your renames. Anything that you rename in development must be manually renamed in production before you perform your normal deployment.

Trading Code Reliability for Process Visibility

2010-02-09T09:12:45-07:00

We’ve been using Teamworks 6.x for 15 months now. The pros and cons of TW compared to traditional .NET / web development are becoming clearer.

Pros:

Our business processes are visible and understoon by the right people. This is huge! We now have the flexibility to change the way we do business. TW provides a visual common domain-based representation that a non-developer can understand. It provides a frame of reference that helps Subject Mater Experts (SME) and Developers discuss the things that are important and aids them in making decisions that effects our organizations productivity. Since using Teamworks to implement our processes, we’ve managed to eliminate waste and productivity has gone way up. And we only expect things to get better.

Teamworks has lots of Business Analysis tools. I’m not an expert in this area but I can tell there are lots of built-in utilities that we didn’t have to develop ourselves. Examples include process variable searches, KPIs, SLAs, and a bunch of other stuff I don’t understand. I don’t know what they do, but I know they get used and I didn’t have to spend 1 minute writing any of them.

Teamworks is collabrative. Business Analysts can build out the UI (with a little assistance) and the processes. The work is shared; developers don’t have to do it all. And documentation can be added everywhere so (if used appropriately) it replaces design documents that have a tendancy to fall out-of-date.

Cons:

Traditional software development Best Practices are immature or unavailable. Unit Testing? Source Control? Change management? Continuous Integration? Refactoring tools? Nope. Not here.

Processes are extremely brittle. Being able to visually represents the process makes you think it is easy to change but lack of refactoring tools makes it very hard to change correctly. Everytime we have a semi-major deployment, we expect something to break (and fail a bunch of process). When we were deploying traditional .NET web applications, these kinds of catostrophic failures were unheard of. We can usually get the problems fixed in short order but our credibility has still suffered.

Development is slower and incurs more strain. Ask any good data-entry person and they can tell you that entering info using the keyboard is faster than using the mouse. TW relies heavily on mousing and switching windows and clicking on stuff and waiting for the GUI to change (and hope it doesn’t decide to just close down instead). Everything good and convenient about using your keyboard and a text editor is MIA.

Code is less visibile. Even though the process is visible, the code behind it is not. Code inside a process can only be viewed piecemeal. (Each code snippet is hidden inside different process componets). Try to search everything or refactor something that is used many places and you are out of luck.

In Conclusion

You’re Developers won’t be doing any happy dances that they get to work in Teamworks BUT your business and bottom line should really see an improvement in its day-to-day productivity.

Dangerous UI Choices

2010-02-09T07:46:16-07:00

When you start the authoring environment with a new workspace you are presented with a number of prompts as you start working. For example, the first time you make a change to an item you are prompted if you want to check this item out. These prompts are numerous and annoying enough that you are trained to check the box that says to always perform this action. Are there any cases where this is bad though? Well…

After you have been using the authoring environment for some time you will eventually want to delete an instance. You will get the same prompt that you have seen for numerous other actions and will absentmindedly click through to always perform this action. What you have just done is get rid of the "Did you really mean to delete this?" prompt. This is bad enough already, but it is compounded by the following fact.

Yes, that is a commonly used refresh button right next to your now irreversible delete button. Now, for example, if you are debugging a process in production and accidentally hit delete instead of refresh you are screwed. Somebody needs to take a remedial class in UI design. This problem exists in both Teamworks 6 and 7.

Phantom Lines

2010-02-03T16:55:12-07:00

This is a pretty common error to get and it usually means exactly what it says: You have no line coming out of your service so Teamworks can’t route you anywhere. But what do you do when there is a line leading to the next service?

In this case there is a good change you have the wonderful phantom line bug. Even though the UI shows that you have a line to the next service and you can select it, as far as the process server knows it doesn’t exist. You can sometimes see if this if you do an export and look at the XML. The line will not be defined. Other times it will show and you need to delete the nested service and insert it again. More so than most other bugs this one angers me, because it leads to start debugging down the wrong path.

Another shortcoming of this is the lack of information with the error message. This is a common problem throughout Teamworks. It would be incredibly helpful for the error message to give you the name of the last service that completed.

First Impressions Count

2009-12-17T12:55:35-07:00

First impressions are important and Teamworks 7 makes a terrible one. When you install the express edition it defaults to creating a directory at the top level of your C: drive. No problem you think, I’ll just move it into Program Files where it belongs. After installation completes you will be in for a surprise though. You won’t be able to login and there will a very odd error in the security log. It turns out that one of the batch files to populate the database at the end of the installation does not escape the install path to allow for spaces. You only get one chance to make a first impression and when that chance is blown it requires more effort to overcome it. We’ll see how Teamworks 7 goes from here.

Violating DRY

2009-08-28T14:36:30-06:00

Teamworks has a nice feature that allows you to create new section and control templates that will appear in your palette when creating coaches. The full potential of this feature is not being realized though.

One central tenet when writing maintainable software is DRY (Don’t Repeat Yourself). This means you only have to change a feature in one location in your application and it will apply everywhere. Teamworks ignores this principle when applying custom templates. Everytime you use your custom section or control in a coach a new copy of it is created in that coach instead of a reference pointing to the shared template. Six months later when you wish to change how that control works you have to update it separately in every coach instead of in one location.

DRY is an important principle of software development for a reason. While Teamworks allows analysts to do some work that used to be done by developers, it is still primarily programming with pictures and proven principles of software development should still be followed.

Authoring Environment Freezes

2009-07-28T09:31:36-06:00

When I visited Lombardi for training in Austin, TX, I had a reasonably possitive impression of Lombardi, Austin, bats, and Texas. As far as the weather goes, I assumed it was always nice and warm in Austin but I’m beginning to think they must some serious cold spells. "Why?" Because the Authoring Environment is always freezing. It freezes when I switch tabs, freezes when I pan around BPD diagrams, freezes when I select coach controls, and freezes when I’m just typing in a text box. Responsive it is not.

It seems to be related to the # of other developers working at the same time so I’m guessing there is some type of server or db dependency causing the UI thread to hang.

I’m really baffled why typing text in a text box, or expanding a static dropdown causes the Authoring Environment to freeze. It doesn’t seem like those actions should be cpu-intensive. Whatever it is doing, it seems like it should be in a background thread and let the UI thread respond to the user.

I try to turn the other cheek but after weeks of feeling like I’m trying to sprint through waist-deep pea soup, I’m getting a little tired of the click-and-wait or type-and-wait pergatory I’m stuck in.

Don’t skimp on your development servers unless you enjoy taking a mandatory 8 second break every minute or two.

(BTW. I’ve typed this entire article while waiting for the Authoring Environament to unfreeze.)

Revision / Depoyment Control Issues

2009-04-03T19:15:45-06:00

Cory asked how we do revision control and Brian has asked me to respond since I’ve been looking at this a lot harder than he has.

If you are hoping to do any kind of revision control with Teamworks such as branch, tag, merge, dif, or commit, then you are going to be disappointed. Teamworks revision control consists of:

develop in your environment
export the components (and their dependencies) that you want to change
import into your test environment
test your changes
import into production
hope nothing unexpected changed

Important points:

You can’t "branch" unless you have multiple develepment server/databases setup.
Instead of "merging" you "replace"
I don’t think that "tagging" can be done in any meaningful way.
All commits (saves) are directly to the main trunk.
When you deploy to production, all the existing (in-flight) processes will immediately begin using the new version.
You can’t just export "changes", you have to export the entire component.
When you export / import, you can’t see what changes are being made (since there is no good DIF tool).
When you do an export, all the dependant components hitch allong for the ride. If you want to make sure that changes in the dependant components don’t make it into production, you have to carefully hand pick your changes during the import step.

So what have we done? We are still relatively new and inexperienced with Teamworks and have only done one (major) deployment. Conceptually we have a Production branch and a Development branch which bounce around between 4 different servers. Anytime we want to do a deployment, we mirror Production onto the Test server and practice our deployment there. It works ok so far but when we start a new development effort, we’re going to start stepping on our own toes.

Although not being able to branch and merge is a pain in rear, the true gremlin in all of this is our inability to reliably see what we are changing. To address this, I’ve built an application I call ‘Referee’ that allows us to:

DIF components
view a change history

Referee takes each of the first class entities (bpd, calendar, connector, epv, historicalScenario, integrationComponent, layout, metric, participant, priority, process, report, resourceBundleGroup, scoreboard, sla, timingInterval, trackingGroup, twClass, underCoverAgent, userAttributeDefinition, webScript, webService) in Teamworks and outputs an XML file for it which can be committed to your source control repository such as SVN.

With each entity split into its own XML file, it is now possible to use Subversion’s DIF tool to see exactly what has changed. (I also highly recommend a tool called BeyondCompare.) So just before we are about to do a deployment to production, we generate all of the entity-XML files from production and all the entity-XML files from what we are going to import and compare them. Doing this, it is easy to see what we are changing, This SIGNIFICANTLY reduces the risk of unwanted changes creaping in.

How does Referee build these first-class entity-XML files? Referee has 2 options.

The easy-to-implement option is to parse the ProcessDefinitions.xml file that is part of the Teamworks export archive file. I basically wrote this parser in an evening while watching Heros and Medium. And you could too.

The hard-to-implement option is to connect directly to the Teamworks Server database and build all the XML files from scratch. This is much-much-much-much harder and I would discourage you from doing it unless you have no hobbies, family, girlfriend, or social activities planned for the next 4 months. That must have applied to me because I’ve managed to reverse-engineer the XML for bpd, process, and twClass entities so that I now have an identical match to the XML generated from the export file.

Having the direct-to-db option has allows us to have a separate ‘watcher’ application that monitors the DateModified column of each of the entities tables and automatically generate the XML file and commit it to SVN anytime someone makes a change. This has proven very effective for seeing what is being changed.

Unfortunately this process is one-way. I am not yet able to use the XML files to reconstruct the ProcessDefinitions.xml file so changes made to the XML files can’t be ‘merged’ back into the database. Doing so is going to be very difficult because the XML file contains many db thingys (db ids, guids, etc) and I don’t fully understand the nature of the problem. For now, Referee is just tool for improving visibility.

Teamworks 7 promises some kind of revision control. I’ve spent a lot of time looking at the database and I think this is a pretty tall order. The database schema doesn’t encourage anything like the branch-edit-merge that we’d like to see. Whatever they come up with will probably be something else.