How to Prevent Broken Workflow References in CRM 2011

You might have noticed a very annoying behaviour when you promote processes (workflows or dialogs) across environments and many references in the workflow definition get broken because of the differences in the environment.

For example, assume you have a workflow that assigns an account to the Sales Team on certain conditions. Your assign step will look like this in your development environment:


Now you include your workflow in a solution and promote to a Test (or any other) environment. Even if the target environment contains the same team with the same name, your workflow will now contain a broken reference and cannot be activated. In fact, if you try to automatically activate the workflow on solution import you will get the following error:

This workflow has errors and cannot be published. Please remove the errors and try again.

The reason why the reference is broken is because workflow keeps track of referenced records by GUID, not by name. So unless you have a team with the same GUID in both environments then the reference will be broken. Your workflow step would look like this after import:


You can go ahead and fix the lookup and then activate the workflow, but here are some bad news of that manual approach:

• Each time you import an update to the solution that contains the workflow you have to manually update the workflow again.
• This can happen for teams, queues and many other records referenced in a workflow.
• Trying to find the GUID in the workflow definition XAML is tedious and risky, there is no documented schema or process on how to do this.

Ideally, I would like to see a way to add my “Sales Team” to the solution, so it will be automatically created in every environment and it will preserve its GUID across multiple environments. However, team records are unfortunately not solution aware. the workaround I have been using is to export the teams from the development environment and import to all the other environments (preserving the GUID). Once this is done, I can import the above workflow as many times as I need and the references will not be broken.

To export the teams you need to go create a query that excludes all default teams:


After executing the query, click the Export Teams button. Make sure to select the option to make data available for re-importing:



Now here is the tricky part, you need to modify the Excel file to be able to import it to another environment. This is what you need to do:

1. Save the file as CSV. Close and re-open the CSV file.
2. Rename column A header to “Team”. If there is another column that already has a header called “Team” you should delete that other column and leave column A.
3. Delete all other columns whose header starts by “(Do No Modify)”.
4. If your Business Units don’t have the same name in all environments then you should also delete the “Business Unit” column. The teams will by default belong to the root Business Unit.
5. Save.

Now you just need to import the CSV file in each of your environments, this will create the teams with the same GUID as the source environment. You can re-use the same file for all environments, and you only need to this once per environment. During import you will need to map it to the “Team” entity, but all the fields should be automatically mapped. Now when you open back your “broken” workflow you will see that it is no longer broken! You can import the teams before or after you import the solution.

One little nuisance I have found is that you cannot import the teams if your Sales Person role does not exist. This looks like a bug, but you should be fine unless you have deleted that role, in which case you’d need to bring it back, at least while you import the teams.

Note that the broken references only occur when the workflow references entities which are not solution aware (teams, queues, etc.) but, it will not be a problem with solution aware entities (e.g. email templates) because you can include the record in the solution itself. Additionally in CRM 2011 there is a mechanism to prevent broken links to users and currencies, so even when you cannot include currencies and users in solutions, when importing a workflow that references these 2 records, the mapping will be done based on name instead of GUID so the references will resolve. For example if you have an “Assign” step that assigns an account to “Gonzalo Ruiz”, even if the user “Gonzalo Ruiz” exists in multiple environments with different GUID, it will still be automatically mapped. But all other entities are referenced by GUID.