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.

 

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.

 

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.

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.