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.