Monday, February 6, 2012

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:
image

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:
image

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:
image

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


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.

15 comments:

  1. Gonzalo,
    I have a similar issue but with a user. I have several workflows that have to be owned by a specific user. When I move those WFs to my Testing environment I always have to update those manually by fixing the owner reference. I'm wondering if you have any recommendations.

    Thanks for your help.

    ReplyDelete
  2. The owner of any record is not transported with the solution, it will always be the person who imports the solution that becomes the owner of the workflows. You can either import the solution using the account of the desired workflow owner, otherwise you will always need a manual step for assigning the workflows.
    If the workflow already exists in the system, the owner will remain the same as it was before, but if the workflow is active, you will not be allowed to import a solution which contains updates to an active workflow unless you own it.

    ReplyDelete
  3. Hi there - a very useful blog post. I have a similar question - I have a simple workflow that creates a Task when a Case is created. The owner of the created Task needs to be the same across environments - so I stumble into the exact problem you describe. I have looked importing the owning user so that the guid is the same across environments. The problem I now face is the deleting the duplicate user in order to import to the version with the correct Guid. It doesn't seem possible to delete user records - do you have any thoughts?

    ReplyDelete
  4. You need the users to have the same FULL name in all environments. This way CRM will automatically update the workflow definition to point to the users in the target environment, even if the GUID's are different

    ReplyDelete
  5. Hi Gonz,
    I have the same issue.Its regarding the Teams and queues.I have followed your tips but still its not getting done.
    Do I need to modify all workflows manually ??

    ReplyDelete
  6. Hi Gonz- thank you very much for this usefull blog.i was able to resolve the long standing issue with your help.

    Omar

    ReplyDelete
  7. This resolved the issue in UAT in a minute.Thanks a lot!

    -Hina

    ReplyDelete
  8. This blog helped to resolve the issue in UAT so fast. Thanks a lot!

    ReplyDelete
  9. It Resolved the issue.Thanks a lot!

    ReplyDelete
  10. I have a similar problem. I have a dev-test-production CRM environment. I have alreadu uploaded the Business Units and Teams using the standard Import Data process. Can we programtically change the GUID's in the Test and Production environment to match the devs environment? Would that break anything?

    ReplyDelete
    Replies
    1. you cannot update GUIDs of any record in CRM. You could delete your teams and re-import them with a GUID that matches your DEV GUID.

      Delete
  11. I am trying the same patterm but everytime the GUID for the teams are coming as different, I tried the same approach for other entities, it worked fine but for team its not working.
    Our teams has different security role assigned to it than sales person role

    ReplyDelete
  12. Thank you for the the great article, this was very helpful! I do have a question for your. Will this method work for business units as well? We are trying to match the GUID's of our business units across development, user testing, and production environments. --Meredith

    ReplyDelete
    Replies
    1. It will only work if you import the business units with the Same GUID in all environments. However, it will not work for the root business unit because the root BU always has a different GUID in each environment.

      Delete
  13. To get around this issue, I create my dev and UAT environments from a copy of the prod one. Then all your guids for the reference data should be the same. Then you just need to always stick with you release process ie always create in dev and move to prod from there. i have a large set of custom reference entities and this helps.

    ReplyDelete