Control Async Workflow Retries

The Dynamics CRM Async Server is a great mechanism to host integrations to external systems without affecting the responsiveness of the user interface. Once such example is calling SharePoint as I describe in my series – SharePoint Integration Reloaded. A draw back of this approach (compared to using an integration technology such as BizTalk) is that any exceptions thrown during the integration will simply fail the workflow job with no retries. You might already know that the Async Server does in fact have a retry mechanism built in as described by this excellent post from the archives - http://blogs.msdn.com/b/crm/archive/2009/03/25/when-do-asynchronous-jobs-fail-suspend-or-retry.aspx. As you'll see from this article there are some built in exceptions where CRM will automatically retry a number of times as defined by the 'AsyncMaximumRetries' deployment property. The interval between these retries is defined by the 'AsyncRetryBackoffRate' property. So how can we make use of this retry mechanism with our custom code? There is an undocumented and unsupported way of using this retry mechanism in your custom workflow activities. I first used this technique back in the CRM 4.0 days and I'm pleased to report that it still works with CRM 2015! Although unsupported, the worst that could happen is that the workflow would stop retrying in future version of Dynamics CRM and revert to simply reporting the exception. However it still wouldn't be a good idea to rely on this functionality for mission critical operations. So…plz show me the codez… catch (Exception ex) { // TODO: Rollback any non-transactional operations

OrganizationServiceFault fault = new OrganizationServiceFault();
fault.ErrorCode = -2147204346; // This will cause the Async Server to retry
fault.Message = ex.ToString();
var networkException = new FaultException(fault);
throw networkException;

}

When an exception is thrown by your custom workflow activity you'll see the workflow enter into a 'Waiting' state and the 'Postpone until' attribute will be set to the time when the retry will take place. Once the maximum number of retries has been performed, it will enter the 'Failed' status.

You can use this technique to ensure that any temporary integration failures such as service connectivity issues will be dealt with by a graceful retry loop. It only remains to ensure that you before throwing the exception you rollback any operations performed already by your code (such as creating records) so that your retries will not create duplicate records. Hope this helps! @ScottDurow

Using the Configuration Data Migration Tool with non-unique display name values

Just thought I would share this little tip to prevent someone else having the same issue: The Configuration Data Migration Tool is a great way of moving records such as custom auto number settings from one organization to another. You can find it in the SDK under SDK\Tools\ConfigurationMigration. When configuring the data schema, you are prompted to select the entities and the attributes that you would like to export and then eventually import. This seems like this is all that is required before hitting 'Save and Export' – but be warned there is one more important step if your data does not have unique display name values.

In my example I had two records that had the same name and they already existed in the target organization. Normally, the tool will use the display name attribute to perform a lookup rather than use the primary unique identifier for the record. The result will be that the same record will be updated twice in the target, rather than the two separate records being updated accordingly. To ensure that the primary name field is not used as the lookup on the target system you must select 'Tools->Configure Import Settings'. This then gives you the option to select the primary key field that you want to use other than the display name:

You can no click 'Save' and export your data knowing that the primary unique identifier field will be used to match the records between the source and destination. The xml schema file created adds the magic 'updateCompare' attribute to the xml and you are good to go! <field updateCompare="true" displayname="Counter" name="xbitz_counterid" type="guid" primaryKey="true" />

You can learn more about this very useful tool here - https://technet.microsoft.com/en-us/library/dn647422.aspx Hope this helps!

@ScottDurow

SparkleXRM now available on NuGet

I've just published the latest version of SparkleXRM on NuGet to make it easier to use from within Visual Studio. You can simply add a NuGet reference to SparkleXRM and the dependancies will be pulled in as well. PM> Install-Package SparkleXRM Once installed, the Sparkle XRM assemblies will be referenced in your project and the latest managed solution can be found in the '\packages\SparkleXRM.7.2.3\content' folder. Currently there is the CRM2015 version 7.2.3 available but I'll add the 2011/2013 version as well shortly.

Business Rules & “SecLib::RetrievePrivilegeForUser failed - no roles are assigned to user”

When publishing your Ribbon Workbench solution you may receive the following error:

"SecLib::RetrievePrivilegeForUser failed - no roles are assigned to user."

The first step in diagnosing these issues is to try and export the same solution using the CRM solutions area and then immediately re-import to see what error is shown. This is exactly what the Ribbon Workbench does behind the scenes. When doing this you might see:

Upon Downloading the Log File you'll see that the error occurs on a 'Process' and the same error message is shown as reported by the Ribbon Workbench. The User ID is also given which can be used in a URL similar to the following to find the user record causing the issue.

https://<orgname>.crm.dynamics.com/userdefined/edit.aspx?etc=8&id=%7b<User GUID>%7d

You will most likely discover that this user has been disabled or has no roles assigned – this could be that they have left the company or changed job role. You will need to find any Workflows or Dialogs that are assigned to them and re-assign to yourself before you can import the solution.

In most cases, you should not include Dialogs or Workflows in the solution that is loaded by the Ribbon Workbench since this only slows the download/upload publish process down. There is one exception to this – and that is Business Rules. Business Rules are associated with their particular entity and cannot be excluded from the solution. Oddly like Workflows and Dialogs they also are owned by a user but it is not shown in the user interface – nor is there an option to re-assign. There is a handy option on a user record that allows you to 'Reassign Records'

You would think that this would reassign any Business Rules but unfortunately you'll get the following error:

"Published workflow definition must have non null activation id."

The only way to reassign these Business Rules is to perform an advanced find for Processes of Type 'Definition' and Category 'Business Rule'

The results can then be reassigned to yourself using the 'Assign' button on the results grid. @ScottDurow

The dependent component Attribute (Id=transactioncurrencyid) does not exist. Failure trying to associate it with Workflow

I recently answered a question on this error on the Community forms and coincidently I've just come up against exactly the same issue! When importing a solution you receive the error 'There was an error calculating dependencies for this component' and on downloading the log you see the full message similar to:

The dependent component Attribute (Id=transactioncurrencyid) does not exist. Failure trying to associate it with Workflow (Id=<GUID>) as a dependency. Missing dependency lookup type = AttributeNameLookup.

Although this message can appear for other attributes, this post is specifically to do with the transactioncurrencyid attribute being referenced. When you add a money field to an entity CRM automatically adds a N:1 relationship to the currency entity to hold the currency that the value is stored against. The foreign key attribute is always named transactioncurrencyid. In this increasingly 'agile' software development world attributes are added and remove fairly regularly during the development phase. If a money field is added to an entity and then removed, the transactioncurrencyid attribute is not removed. Because the relationship automatically created by the system it is not created when deploying to another environment via a solution import because there are no money fields. This leads to your development environment having the additional relationship. This wouldn't cause a problem apart from that when you create a workflow with a 'create' or 'update' step, the currency field is usually pre-populated with the default currency. Consequently when you try to import this workflow into another organization that does not have the currency relationship you will see this error. The solution is to either delete the transactioncurrencyid field from your development environmentm and from the workflow create/update steps or simply add a dummy currency field to your target environment in order to create the relationship to currency. @ScottDurow

The cream cracker conundrum (or customising the sub grid command bar)

I still find the streamlined user experience offered by the Command Bar a welcome change from the CRM2011 Ribbon. The sub-grid command bar is the only possible exception with the loss of the ability to add custom sub-grid buttons. There are only at most two buttons on a sub grid – 'Add' and 'Open Associated Sub-Grid'The user must click on the 'Open associated sub-grid' button to show the full associated view and the full command bar with custom buttons. I say 'possible exception' because in fact there are still the same number of clicks involved (users had to click on the sub grid to show the contextual ribbon before) but it does feel as though we should have the ability to add buttons to the sub-grid command bar. I can think of some good reasons why this design decision may have been made (performance for one!) – but this post details what you CAN do to the sub-grid command bar. Because the 'Open associated sub-grid' button is a bit of a mouthful, I'll refer to it from now on as the 'cream cracker' because it kind of looks like one and is equally a bit of a mouth full! (Thanks goes to my friends at the British Red Cross who first named it this way!) Hiding buttons We have established that you cannot add buttons to the form sub grid, but both the 'Add New' and 'Cream cracker' buttons are customisable in terms of their command and visibility (but you cannot change the image or the tool tip text). To hide the sub grid buttons you have the following options:

Hiding based on a security role (if the user does not have access to append a record to the parent or create new records of the sub grid type, the 'add new' button will be invisible Hiding all of the time using a 'Hide Action' Hiding conditionally using a security role Hiding conditionally using a custom JavaScript rule.

A common requirement is to hide the Add New button on a sub-gird until a specific criteria is met on the parent form. The standard ValueRule cannot be used because this rule will only work when the command button is added to a form command bar. So to achieve the conditional show/hide we must use a Custom JavaScript Rule. The first hurdle is to determine which button needs to be customised. The sub grid 'Add New' button calls a different command depending on the nature of the relationship. If you have a foreign-key attribute on your child entity that is marked as Field Requirement = 'Optional' then the Add New button will be the AddExistingStandard since it allows you to search for an existing record first. If the Field Requirement = 'Business required' then the button will be AddNewStandard  

  Once you've identified the right button, you can then open the ribbon workbench and click Customize Command and add the Value Rule as described by my user voice article. Changing the command actions Although we cannot add new buttons (did I mention that?!) we can change the command actions that either of those two buttons call. Since we can't customise the button, the only option here is to customise the command and change its behaviour in a very similar way to adding custom enable rules.

Right click the button in the Ribbon Workbench and select Customise Command Expand the command in the Commands node in the Solution Elements panel and select the command that has been created for you to customise. Right click Edit Actions and you can simply delete the standard action and add your own custom ones. Remember to mark all the enable and display rules that you don't want to customise as IsCore=True.

Once such use of this technique is to replace the standard add new button with a custom dialog. Refreshing the sub grid Command Bar You will find that when the form is loaded and the sub grid is refreshed for the first time the EnableRules are evaluated. If however the conditions for the EnableRules change (e.g. a value changes on the parent form) the sub grid command bar will not automatically refresh to reflect the new state. Upon adding or deleting rows in the sub grid the command bar is refreshed – but this isn't much use in this case. The main form command bar can be refreshed using Xrm.Page.ui.refreshRibbon() however this will not refresh sub grid command bars. Instead, we can add an onchange event to the fields that are used in our ValueRule and call: Xrm.Page.data.save(); This will refresh the sub grids and re-evaluate any of the EnableRules however it will also save any other dirty attributes and so should be used with caution if you do not have auto-save enabled. Responding to new/deleted rows in the sub grid Since the sub grid command bar is refreshed when new rows are added or deleted we can use the fact that the EnableRules will be re-evaluated to call custom JavaScript when the sub grid changes. This simulates a sub-gird onchange event and was first described by James Wood's blog post for CRM2011. He states on his blog that this technique doesn't work for CRM2013 – however if we add the custom EnableRule to the existing command (rather than use a new button as James describes) then this technique works well in CRM2013 and CRM2015. So we can customise the command for the Add New or cream cracker and add a Custom JavaScript Enable Rule that always returns true in just the same way that you might use the EnableRule to dynamically show/hide the button but rather we just run our onchange code. Perhaps in the future there will be more possibilities but for now that about sums up the possibilities for customising the sub grid command bar. @ScottDurow

SparkleXRM for CRM2015 with process API support

I've just committed an update to SparkleXRM with CRM2015 support and the process client API. One of the design decisions I made early on with SparkleXRM was to stick with a CRM2011 solution format to allow installation on both CRM2011 and CRM2013. Now that CRM2015 does not support installing CRM2011 solutions I've had to branch and make both CRM2011 and CRM2015 versions available. The code base still remains the same but they are distributed through two separate solution files depending on your target version. You can download the new CRM2015 SparkleXRM solution from github. The new client side process control API is such a welcome addition. The latest version of SparkleXRM contains support for this so that you can: Write code to run when the stage is changed or the user selects a process tab (such as hiding/showing sections on the form. // Add On Process Stage change Page.Data.Process.AddOnStageChange(delegate(ExecutionContext context){ // Stage Stepped forwards backwards });

// Add On Process Stage change Page.Data.Process.AddOnStageSelected(delegate(ExecutionContext context) { // Stage Tab Selected });

Write code to get the current process and stage so that onload functions can show/hide sections on the form. // Get Current Process Process process = Page.Data.Process.GetActiveProcess();

Stage stage = Page.Data.Process.GetActiveStage(); Script.Alert("Process = " + process.GetName() + " Stage = " + stage.GetName()); Write code to get the stages and steps of the current process and find the attributes that are referenced – I've not found a use for this yet! // Get Stages ClientCollection stages = process.GetStages();

if (stages.GetLength() > 0) { // Get Steps Stage stage0 = stages.Get(0); ClientCollection steps = stage0.GetSteps(); steps.ForEach(delegate(Step step, int index) { Script.Alert(step.GetName() + " " + step.GetAttribute()); return true; }); } Write code to show/hide or collapse/expand the process ribbon: // Show/Hide Process Page.Ui.Process.SetVisible(true);

// Expand/collapse Page.Ui.Process.SetDisplayState(ProcessExpanded.Collapsed); Write to advance/step back the stage or change the process/stage completely: // Change stage Page.Data.Process.MoveNext(delegate(MoveStepResult result) { Script.Alert(result.ToString());

});

// Change process Stage currentStage = stages.Get(0); Page.Data.Process.SetActiveStage(currentStage.GetId(), delegate(SetActiveStageResult result) { Script.Alert(result.ToString()); });

// Change process to the first available process that the user has access to. // If the same as the current process, this does nothing. Page.Data.Process.GetEnabledProcesses(delegate(Dictionary processes) { Page.Data.Process.SetActiveProcess(processes.Keys[0], delegate(SetActiveProcessResult result) { Script.Alert(result.ToString()); }); });

Along with the server side branching support for processes – I think this really finishes off this feature nicely. The business process flow feature is now by far my favourite in terms of innovation, business usefulness and developer API. First it was gold in CRM203 RTM, then green in SP1 - now with CRM2015 I especially like the calming cool blue that the process ribbon is now rendered with!

Cheers, @ScottDurow  

Ribbon Workbench 2015 (Happy New Year!)

Happy New Year – I hope 2015 will bring you lots of good things. Dynamics CRM 2015 upgrades are rolling out to Dynamics CRM online organisations with rapidly increasing frequency and so I have updated the Ribbon Workbench for 2015 support. You will see a new update notification when you next open the Ribbon Workbench and you can let the auto update do the download and install for you. If you would rather install manually you can download and install over the top of the previous version.

Automatic update is mandatory after 10th January – why? You'll have the option to update before the 10th of January and then you'll be forced to update after that. Some people have asked me other the last couple of years why I roll out these mandatory updates. Initially this was about ensuring that the beta version was updated with any bug fixes but since then it has been a way of ensuring that I keep rolling out new version. I set a 6 month release cycle target so that even though I roll out minor updates I have to roll out at least one mandatory update every 6 months! I hope you don't mind being forced to update too much – I certainly feel that the benefits outweigh the downsides and it keeps me on my toes J Command bar 2015 The good news about the 2015 command bar is that after the big shift from the ribbon in CRM2013 there haven't been any significant changes. All of your ribbon xml customisations in CRM2013 will remain to work in CRM2015 provided that any JavaScript you are calling in your commands doesn't use any deprecated SDK elements. If you compare the RibbonXml XSD between the CRM2013 and CRM2015 SDKs you'll see that they are in fact identical! All the best for 2015! @ScottDurow

SharePoint Integration Reloaded – Part 3

In Part 1 and Part 2 of this series we have discussed how the new server-to-server integration with SharePoint works under the covers. In this post I'll show you how to integrate with SharePoint directly from a sandboxed workflow activty/plugin rather than relying on the out of the box integration. Using the standard integration, a new folder will be created for each record underneath the default site. In some solutions you'll find that you want to modify this behaviour so that folders are created in a custom location. You may for example want to have an opportunity folder created under a site that is specific to a particular client rather than all under the same site. The challenge with integrating with SharePoint using a CRM Online Workflow Activity/Plugin is that you can't reference the SharePoint Assemblies which authenticating and calling the SharePoint web service somewhat harder. Thanks goes to fellow Dynamics CRM MVP Rhett for his blog that provided a starting point for this sample - https://bingsoft.wordpress.com/2013/06/19/crm-online-to-sharepoint-online-integration-using-rest-and-adfs/. The sample code in this post shows how to create a folder in SharePoint and then associate it with a Document Location. The authentication with SharePoint works via ADFS and since the out of the box integration uses a trust between CRM and SharePoint that is not accessible from a sandbox (even if you try and ILMerge it!) we have to provide a username and password that will act as our privileged user that can create folders in SharePoint. I have left a function where you can add your own credentials or implement a method to retrieve from a secure entity in CRM that only administrators have access to. Look in the code for the 'GetSecureConfigValue' function. The sample contains a custom workflow activity that works in a CRM online 2013/2015 sandbox accepting the following parameters:

Site – A reference to the site that you want to create a folder in. You could store a look up to a site for each customer and populate this parameter from the related account. Record Dynamic Url – The 'Dynamic Record Url' for the record that you want the SharePoint document location to be related to. This uses my Polymorphic input parameter technique. You simply need to pass the Record Url (Dynamic) for the record that you wish to create the folder for. Document Library Name – The name of the document location to create the folder underneath. In the out of the box integration this is the entity logical name (e.g. account) Record Folder Name – The name of the folder to create. You could use the client name, client ID etc. – but it will automatically have the GUID appended to it to ensure uniqueness just like the out of the box integration.

Calling the workflow activity might look like:

The workflow activity is deployed using the Developer Toolkit for Dynamics CRM and performs the following:

Checks if the document location already exists for the given site/document library – if so it simply returns a reference to that Checks if a document location exists for the given document library – if not, one is created Creates a SharePoint folder using the SpService class. It is worth noting that if the folder already exists, no exception is thrown by SharePoint. The SpService class must first authenticate using the SpoAuthUtility class. Creates a Document Location for the newly created folder.

You could choose to run the workflow in Real Time or asynchronously on create of a record – the down side of real time is that it will increase the time that the record takes to save. Check out the code in MSDN Samples- you'll need to do a Nuget package restore to pick up the referenced assemblies. View/Download Code That's all for now – have a Happy New Year! @ScottDurow    

Separate Content from Code

Back in the On-Prem CRM 3/4 days I would regularly customise the Dynamics CRM help files to add new topics and amend existing ones to match a company's solution. Context sensitive help was also possible by linking specific entities to specific help topics. With CRM2011 and the advent of the 'getting started pane' help became more of an inline experience with links being displayed above grids of records however customising the online help was no longer supported. CRM2013 removed the 'getting started pane' and so it was much harder to provide a customised help experience. I'm really pleased that the Dynamics CRM team has invested in this area in CRM 2015 in the form of the 'Custom Help URL' feature. Global Help URL If you navigate to Settings->Administration->System Settings you'll see the new Custom Help URL options. To use this new feature you must first enable 'Use custom Help for customizable entities' You then have the option to provide a global help URL that will be used when users click the '?' icon on the top right of any refreshed UI page. It is also used when user click on the 'classic' style help icon on non-refreshed pages.

If the help button is clicked on an entity form then some contextual parameters are passed. For the Case entity the following are added to the Global Help URL:

entrypoint=form&formid=4a63c8d1-6c1e-48ec-9db4-3e6c7155334c&typename=incident&userlcid=1033

Solution Deployment vs. Content Management You have the option to use either a relative URL that points to a WebResource as shown in the screenshot above but you can also use an absolute URL to content hosted outside of CRM. You can also then create a help URL per entity in the entity customisation properties as shown below.

The disadvantage with this external URL per entity approach is that this URL is likely to be different in your DEV/UAT/PROD environments and since this URL will be transferred with each solution deployment we'll have to update this setting every time we deploy. I've found that although the software development lifecycle is usually a regulated release process, the help content authoring process tends to be more of an evolving one. With the CRM2011 getting started pane being linked to Web resources I always found it much harder to get this content updated due to the rigor of the deployment process. For this reason I now recommend not coupling your company's help content to your CRM solution's web resources but rather use an external content management system such as SharePoint. This allows you to then regular release updates and new content without having to schedule a new release and the down time associated to this. But how do we avoid having to update the entity URLs on each DEV/UAT/PROD environment? We use only the Global Help URL in combination with the typename querystring parameter and not use the entity Help URL at all. To do this in SharePoint: 1. First we must enable embedding of code into SharePoint pages. 2. Edit the SharePoint page that is the default landing page in the Global Help URL (e.g. SitePages/Home.aspx) 3. On the Insert ribbon tab, select 'Embed Code'

And paste the following code: <script> function getQueryStringArray(){ var assoc=[]; var items = window.location.search.substring(1).split('&'); for(var j = 0; j < items.length; j++) { var a = items[j].split('='); assoc[a[0]] = a[1]; } return assoc; } var qs = getQueryStringArray();

if (qs.typename!=null) { window.location.href = '/SitePages/' + qs.typename + '.aspx'; } </script>

Now when CRM opens your Global Help URL it will redirect to the specific page for that entity passed on the typename. You can then create pages for each typename in the Site Pages library:

Since the Global Help URL is not solution aware, you can deploy your solution to multiple environments without having to change all those URLS with each deploy. You can read more about this on Bryce Holmes' post on this feature. Read the Online Help about this feature and read Magnetism's blog on this feature. Hope this helps! @ScottDurow