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.

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.

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.

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.)

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.

After doing a major deployment and thinking about how to manage later deployments of bug fixes it really hit me just how poor change tracking is in Teamworks. Specifically, there is basically none. Change tracking consists entirely of an audit trail that tells you who changed a file and when, but not what they changed or why they changed it.

The Teamworks change control model is a simple Check Out-Check In one. When you make a change to a file the authoring environment checks it out. This puts an exclusive lock on the file until you check it back in. If any other user wants to make edits to the file they must wait until you check it back in. This may have been state-of-the-art in the 1980s with RCS (Revision Control System), but not today.

There is also no concept of meta-data associated with these audits, meaning you can’t even associate specific changes with specific fixes. For example, say you are trying to figure out which three services you edited to fix a bug from six months ago similar to one that just cropped up. There is no way for you to find those changes. This makes the audit trail essentially useless for auditing. A change that tidies up the layout looks exactly the same as a change that rewrites the whole service. Its only seeming use is seeing who last edited a file when I need it so I can tell them to check it back in if they are done with it.

Supposedly Teamworks 7 will have real version control, but I am skeptical. First, this is a pretty essential feature to get to version 6 and still not have. To me it shows that they are not dogfooding their product in any meaningful manner. Second, having spoken to a couple of consultants about the new version control coming to version 7 I have real fears that they are implementing their own solution instead of integrating something like Subversion. If this is true it is pretty much guaranteed to be buggy.

On of the first things you will notice when you start to use Teamworks Authoring environment is that every window pane is too small.  You can maximize the too-small pane but then it takes over your entire window at the expense of the other panes.  So everytime you want to look at something, the process basically goes like this:

• Restore current pane to normal size
• Go to new pane of interest
• Maximize new pane

 

This means you can only look at 1 window at time.  And since there are no hot keys (that I can figure out), it is very slow to switch between these views. 

Probably the worse offender is the Data Mapping tab in the Property Pane.  The image below shows how you map data into and out of an embeded component.

 

 

To reference local variable in a service you specify the variable name with a "tw.local." prefix.  So to reference equity-in-property, you must type in tw.local.equityInProperty.  Due to the design of the Data Mapping pane, all you see is the "tw.".

So essentially, in the normal view,  you have no idea what is mapped to the component.  This makes the Data Mapping view nearly worthless in its normal size.  The only way to get anything done is to maximize the pane and sometimes you still need to click into the field and press END to see what’s in the edit box.

A better solution would be for the Data Mapping pane to have 1 column and we can scroll down to see the output mappings.  At least that way, we wouldn’t have to maximize the window just to see what’s mapped to what.

Trying to work with the Data Mappings tab/pane is like trying to tie your shoe with only one hand.  It can be done but its a lot harder than it needs to be.

 

 

 

 

I’ve been monumentally dissappointed with Teamworks Authoring environment for a long long time but this one really takes the cake.

You can embed items inside BPDs and services.  When you embed something there is a tab that allows you to map data from the higher level item to the lower level item.   

For Services, there is a check box for every parameter that allows you to "Use Default".  This is good and natural behavior.

But for BPDs, there is no visual indication that there are any defaults or not.  To use the default value, you must first know it exists, then leave the data mapping blank.

Why is this so incredibly WRONG? 

1) Because we have 2 different Data-Mapping interfaces that behave differently.

2) You can’t tell if a mapping will generate an error or not without openning the embedded item.

3) If an item is set up to use defaults and the default is later moved, there is no indication from the outside that it will crash.

 

Lombardi Tech support finally explained this to me.  I pity anyone trying to develop a process that doesn’t understand how this works.

 

 

Teamworks services define input and output variables that, much like a function takes arguments and returns values. One feature of both inputs and outputs is the ability to set default values. However, it can be tricky to determine when the default output value is first initialized. There are three logical choices:

1. When the service starts
2. When the service completes
3. Some nebulous time in between

The problem for output variables seems to be that the answer is none of the above. Although you can set a default value just as you can on an input, it has no effect that we have been able to find. This is not an isolated problem when using Teamworks either, as there appear to be many features that have been implemented differently in different places or that appear to have never been implemented at all. In addition, there are other features that should never be used as they make long-term maintenance and debugging very difficult. I will touch on some of these soon.

There are some features of modern software that are just accepted as required and you never even consider to ask about them when evaluating software. One of these features is the ability to undo an action, preferably an unlimited number of them. However, the javascript editor in the Teamworks authoring environment does not have an undo. I repeat, you cannot undo an action in the javascript editor. How this happens I don’t know, but this obviously seriously effects the usability of the editor. You are left with the choice of never making an error or using the editor of your choice and pasting in your code when done. If you do use the editor of your choice you lose the autocompletion the authoring environment offers, but the autocompletion really isn’t that useful.