This is part 2 of a 5 part series, where we take a closer look at the practical implications the General Data Protection Regulation (GDPR) will have upon your organisation and some of the ways Dynamics CRM/Dynamics 365 for Enterprise (CRM/D365E) can assist you as part of the transition. Last week, we took a look at the database encryption feature within the application and why you should devote some time to understanding how it works. The primary focus of this weeks post is how an organisation can ensure that highly sensitive data categories are only made accessible to authorised individuals only.

All posts in the series will make frequent reference to the text (or “Articles”) contained within Regulation (EU) 2016/679, available online as part of the Official Journal of the European Union – a particularly onerous and long-winded document. If you are based in the UK, you may find solace instead by reading through the ICO’s rather excellent Overview of the General Data Protection Regulation (GDPR) pages, where further clarification on key aspects of the regulation can be garnered.

Introduction – Sensitive Data Categories, their meaning and practical implications

We saw as part of last week’s post the importance encryption plays as a “reasonable” step that any well-established organisation should have implemented to safeguard themselves against the risk of a data breach. The implications of a data breach are covered more in-depth under Articles 33, 34 and 35 of the regulation. The key takeaway from this is that encryption is by no means a silver bullet, and you must instead look at a complementary range of solutions to mitigate the risk and impact of a data breach.

Although not technically a form of encryption, Field Level Security can be seen as an apparatus for providing encryption-like functionality on a very granular basis within your CRM/D365E deployment. Whilst implementing them does broadly conform to the specifications as set out in Article 32 of GDPR, they do also provide a means of satisfying some of the requirements set out in Article 9, which states clearly:

Processing of personal data revealing racial or ethnic origin, political opinions, religious or philosophical beliefs, or trade union membership, and the processing of genetic data, biometric data for the purpose of uniquely identifying a natural person, data concerning health or data concerning a natural person’s sex life or sexual orientation shall be prohibited.

Unless one of the following conditions apply:

  • The data subject has provided consent to record the data or has placed the details into the public domain.
  • The data needs to be processed as part of a specific line of legitimate business (employment, social security, social protection law, not-for-profit foundation/association, medical care, public health purposes or as part of scientific/historical research).
  • The recording of such personal details is required to protect the vital interests of the person concerned.

Many of the organisations listed above may already be using CRM/D365E as their primary business system and, as a consequence, will be storing the types of information referenced above. Whilst this is surely a legitimate case of data processing, issues may arise, for example, when it comes to which persons within the organisation can see and access this data; a medical doctor/nurse accessing a patient’s health information is appropriate, but surely a receptionist or IT support personnel viewing a patient record has no fair interest in viewing this information. Having appropriate controls in place to protect against these types of scenarios become a primary concern under GDPR, and Article 30 enshrines this further by requiring organisations to clearly document and implement processes that define individuals access to personal data:

Each controller and, where applicable, the controller’s representative, shall maintain a record of processing activities under its responsibility…[including] the categories of recipients to whom the personal data have been or will be disclosed including recipients in third countries or international organisations;

To summarise, therefore, by piggybacking upon the very robust security model contained within CRM/D365E, Field Level Security can very quickly be implemented to ensure that users of the system only see the information that is relevant to them as part of their role, without disrupting the entire end-user experience in the process.

With this in mind, let’s take a look at how straightforward it is to begin working with Field Security, by following the steps outlined below:

  1. Identify the field(s) that need to be secured from being accessed by a specific group of users. Navigate to the field(s) properties and verify that the Field Security option has been set to Enable. For this example, we are going to use the Primary Contact field on the Account entity:
  2. Within the Customizations area of the application, select the Field Security Profiles option on the left-hand bar and then click on New to create a Field Security Profile:
  3. On the New Field Security Profile window, specify a name and an (optional) description value for the new profile and press the Save button:
  4. Once saved, you can then begin to configure the two most important aspects of the profile – the permissions that are granted to secured fields and the Users/Teams in the application that they apply to. In this example, we are going to restrict the Primary Contact field from step 1) so that users who are part of our Account Executive team role cannot view, update or create a record with a value in this field. To begin with, click on the Teams button and then click on Add to find and select the Account Executive team role:
  5. Next, click on the Field Permissions icon and double-click the Primary Contact field on the list. Verify that the Allow ReadAllow Update and Allow Create options are set to No:

Now, when we log into the application as a user who is a part of the Account Executive role and navigate to a sample record on the system, we can see that the field in question has been obfuscated. We have no way of seeing, changing or otherwise interacting with the value contained within this field:

Fields that are impacted in some way as a result of Field Security can always be clearly distinguished by the key icon on the top left of the field name. This can prove useful in helping users to understand their current levels of access and in troubleshooting why a user cannot read or modify a particular field.

So what have we learned about Field Security Profiles and how they conform to GDPR? Here’s a quick summary of the key points:

  • Demonstrates that sensitive data information is stored with “appropriate security” in place (Article 5)
  • They can be used as a tool for storing and controlling access to sensitive data types (Article 9)
  • Provides a mechanism to demonstrate compliance with the relevant articles of GDPR, should the organisation be subject to an Audit as a Data Processor (Article 28)
  • Can be seen as an appropriate technical safeguard in the protection of both non-sensitive and sensitive data types (Article 32)
  • Could be used as documentary evidence (or the basis thereof) that covers the documentation requirements for data processing (Article 30)

Thanks for reading! As part of next’s week post, we will take a deeper dive into CRM/D365E’s wider security model and the importance of documentation in the context of GDPR.

I was recently involved in deploying my first ever Office 365 Group. I already had a good theoretical understanding of them, thanks to the curriculum for the Business Applications MCSA, but I had not yet seen how they perform in action. The best way of summing them up is that they are, in effect, a distribution group on steroids. As well as getting a shared mailbox that can be used for all communications relating to the group’s purpose, they also support the following features:

  • Shared Calendar
  • SharePoint Document Site
  • Shared OneNote document
  • Shared Planner

In a nutshell, they can be seen as an excellent vehicle for bringing together the diverse range of features available as part of your Office 365 subscription. What helps further is that they are tightly integrated as part of the tools that you likely already use each day – for example, they can be accessed and worked with from the Outlook desktop client on and Web Access (OWA) portal.

Given that this feature is a very Office 365 centric component, the natural question emerges as to why an exam for Dynamics CRM/Dynamics 365 for Enterprise (CRM/D365E) would want to test your knowledge of them. Since the release of Dynamics CRM 2016 Update 1, you now have the option of integrating Office 365 Groups with the application, to provide a mechanism for easily working with groups from within the CRM/D365E web interface, effectively providing a “bridge” for non-CRM/D365E users who are using Office 365.

You may be pleased to hear that the steps involved in getting setup with Office 365 Groups in CRM/D365E are remarkably straightforward. Here’s a step-by-step guide on how to get up and running with this feature within your business:

Microsoft provides a managed solution that contains everything you need to get going with Office 365 Groups, and this is made available as a Preferred Solution. These are installed from the Dynamics 365 Administration Center by navigating to your instance, selecting the little pen icon next to Solutions and clicking on the Office 365 Groups record on the list that is displayed:

Click on the Install button and then accept the Terms of Service – as Office 365 Groups creates an intrinsic link between your CRM/D365E and Office 365 tenant, it is only natural that data will need to be shared between both, so there are no major concerns in accepting this:

The solution will take a couple of minutes to install, and you can safely refresh the window to monitor progress. Once installed, the Settings sitemap area will be updated with a new button – Office 365 Groups:

Clicking into this will navigate you to the Office 365 Groups Integration Settings page, which allows you start configuring the entities you wish to use to utilise with Office 365 Groups:

For reference purposes, the default out of the box entities that can be used with this feature are as follows:

  • Account
  • Competitor
  • Contact
  • Contract
  • Case
  • Invoice
  • Lead
  • Opportunity
  • Product
  • Quote
  • Sales Literature

You may be wondering if it is possible to enable additional entities for use with Office 365 Groups. At the time of writing, only the system entities recorded above and custom entities can be used with Office 365 Groups.

Now that we know how to get CRM/D365E setup for Office 365 Groups, let’s look at how it works when set up for the Account entity:

Going back to the Office 365 Groups Integration Settings (if you have closed it down), click on the Add entity button to enable a drop-down control, containing a list of the entities referenced above. Select Account and, when you are ready to proceed, click Publish all to enable this entity for Office 365 Groups functionality:

For this example, the Auto Create button is left blank. I would recommend that this setting is always used, so as to prevent the creation of unnecessary Office 365 Groups, that may get named incorrectly as a consequence (you’ll see why this has the potential to occur in a few moments).

Once enabled, when you navigate to an existing Account record, you will see a new icon on the Related Records sitemap area:

After clicking on this, you are then asked to either Create a new group – with the ability to specify its name – or to Search for an existing group. The second option is particularly handy if you have already been using Office 365 Groups and wish to retroactively tie these back to CRM/D365E:

For this example, we are going to create a new group. The process can take a while (as indicated below) so now may be a good opportunity to go make a brew 🙂

Leaving the screen open will eventually force a refresh, at which point your new group will appear, with all the different options at your disposal:

With your group now up and running, you can start uploading documents, configure the shared calendar and fine-tune the group’s settings to suit your purposes. Here are some handy tips to bear in mind when using the group with CRM/D365E:

  • Just because the group is linked up with CRM/D365E doesn’t mean that you have to be a user from this application to access the group. This is one of the great things about utilising Office 365 Groups with CRM/D365E, as standard Office 365 users can join and work with the group without issue. The only thing you have to remember is that the Office 365 user has to have the appropriate license on Office 365 – as indicated by Microsoft, any subscription that gives a user an Exchange Online mailbox and SharePoint Online access will suffice.
  • Remember that the ConversationsNotebook and Documents features are not in any way linked with the equivalent CRM/D365E feature. For example, any Conversation threads will not appear within the Social Pane as an activity; you will need to navigate to the Office 365 Group page to view these.
  • Utilising Office 365 Groups as an end-user requires that you have the appropriate security role access. If you do not, then you may be greeted with the following when attempting to open an Office 365 Group within the application:

That’s right – a whole heap of nothing! 🙂 To fix this, you will need to go into the users Security Role and ensure that they have Organization-level privilege on the ISV Extensions privilege, as indicated below:

Conclusions or Wot I Think

Office 365 Groups present a natural choice when working as part of large-scale teams or projects – especially when they are internally based. They can also be a good fit for when you wish to liaise with 3rd party organisations, thanks to the ability to grant Guest access to external accounts. Having the ability to then tie these groups back within CRM/D365E is useful, but I do wonder whether they are a good match for all of the record types that Microsoft suggests in the list above. Certainly, Account records are a justifiable fit if you are working with an organisation to deliver continuous services or multiple projects. I doubt highly, however, that you want to go to the trouble of creating a shared document repository for a new Lead record right from the bat – particularly if your CRM/D365E deployment is more focused towards B2C selling. You may be tempted to over-excitedly roll out Office 365 Groups carte blanche across your CRM/D365E deployment, but I would caution against this. Don’t forget that the creation of a new Office 365 Group will result in additional overhead when managing your Exchange Online mailbox lists and SharePoint sites, as well as having long-term storage implications for the latter. Acting prudently, you can identify a good business case for enabling specific entities for use with Office 365 Groups and ensure that you manage your entire Office 365 deployment in the most effective manner possible.

The ability to incorporate document management functionality within Dynamics CRM/Dynamics 365 for Enterprise (CRM/D365E) is one of the ways that the application integrates neatly with other products in the Microsoft “stack”, giving you the ability to drive further benefit from your existing CRM/D365E deployment. Documents that specifically concern a particular record can be stored within SharePoint and accessed via a few clicks within the application, allowing for quicker collaboration and visibility behind a specific contact, business or sales opportunity. By leveraging the full functionality of SharePoint alongside this, businesses can begin to take advantage of features such as document history, check in/check out capability and the ability to access SharePoint content via the OneDrive desktop client, negating the need to work solely within a web browser to access your documents.

When you are first getting to grips with Document Management, you may come across an oddity with no apparent way of resolving: GUID names are appended onto the names of your SharePoint folders:

There is an understandable reason why this is done (which will be discussed later on in this post), but the folder names can appear jarring and nonsensical to end users of the application. Fortunately, there is a way in which you can change the global setting for this within the application, but it requires making some modifications to your CRM/D365E Organisations global settings – one of those changes that are simple to do if you know how to, but more complex if you don’t 🙂

CRM’s/D365E’s Organisation settings are not exposed within an accessible format natively within the application. To make changes to these settings within the application, the best tool available for both Online and On-Premise versions of the application is the Organization Settings Editor. I have previously discussed how to install and use this tool on the blog, and it is a really straightforward way of updating some of the CRM’s/D365E’s more obscure settings to suit your preferences. The setting that controls all of this is this is the aptly named CreateSPFoldersUsingNameandGuid, which needs to be set to false. Once this is configured, all newly created SharePoint folders will no longer have the GUID appended to them.

How to Fix Existing Folders

It may be the case that you have lots of existing SharePoint folders that are configured in the default manner, but you want to look at “tidying” them up. Simply renaming the SharePoint folder will not work, as CRM/D365E stores “pointers” to each individual folder setup for Document Management, containing a partial URL link; a link that will become broken if anything is modified within SharePoint. To correctly fix your folders and not break anything, you will need to do the following:

  1. Locate the Document Location record within CRM/D365E and modify the Relative URL value to remove the GUID value (e.g. the Document Location record for Test Co5_B3D5C8DFDB77E51181023863BB357C38 should be updated to have a Relative URL value of Test Co5). You may receive a warning that the URL does not exist, which can be safely disregarded.
  2. Rename the folder in SharePoint to match the updated Relative URL value from above.

This could potentially be a laborious task, depending on the number of Document Locations involved. To ease you in your journey, I would recommend digging out the CRM/D365E SDK & the .NET Client API for SharePoint to iteratively update all Document Locations and ditto for all folders within SharePoint online, based on a .csv/spreadsheet input.

Having the ability to make your SharePoint folders look more visually appealing is nice, but keep in mind the following…

By storing a GUID within each folder name, the application can always ensure that the correct folder can be linked back to a CRM record. By implication, this also facilitates situations where duplicate record names are allowed within your environment (for example, you could have two Account records both called Test Company Ltd). By overriding the above setting within the application, you lose the ability to support duplicate folder names; instead, the application will resolve back to any existing folder that matches the Name of the record, essentially becoming a document repository for 2 records as opposed to 1.

An example can better demonstrate this. Below is a test Account record that has been setup for Document Management – with a few test documents saved within and a Document folder successfully configured in SharePoint called My Test Account:

When we then go and create a brand new Account record with the same name – My Test Account – and go to configure Document Management, we are asked to confirm the creation of a Folder with the same name as the one already setup:

Once confirmed, instead of seeing a blank folder, all of the test documents set up on the similarly named record are visible – because the application is pointing to the folder above:

It is highly unlikely that you would allow duplicate record names in the first place within your CRM/D365E instance (particularly for entity types such as Account), so this may be a concern that requires little notice. However, be sure to perform a full analysis of the all the record types that you are hoping to use with Document Management, as there is no way to fine tune the global setting to accommodate specific entities – it is all or nothing.

Conclusions or Wot I Think

Keeping things looking tidy and non-technical are endeavours that need to drive any successful software deployment. End users who exposed to strange looking, “techie” stuff as part of working with a system day in day out may soon start to lose faith in a system, hampering user adoption and faith that it is fit for purpose. Removing GUID’s from a SharePoint folder can obviously present some serious technical problems, depending on the nature of your deployment; but it is arguably something that you should consider if you want to ensure that end users feel that their SharePoint folders are “correctly” named (i.e. do not contain superfluous information). As with anything in IT, proper testing must be carried out for all possible scenarios before rolling out a feature change like this and, assuming your business ticks all of the boxes for safely removing GUID’s from your SharePoint folders, it is definitely something to be considered seriously.

If you are British and a keen Dynamics CRM/Dynamics 365 for Enterprise (CRM/D365E) fan, then May 4th, 2017 was a proud day to be both. This is because Microsoft announced the general availability of UK hosted D365E instances. UK-based Office 365 customers who configure a new D365E subscription will have their instance(s) hosted within the UK, using the brand new crm11 URL identifier. This is line with the launch of 2 Azure Data Centre regions within the UK last year and represents an important development in the evolution of Microsoft’s cloud services within the UK.

For the “old fogies” (like me!), previously all CRM/D365E tenants in the UK were hosted by default within the Europe, Middle East and Africa (EMEA) region. The data centres for these locations are hosted within Amsterdam and Dublin, areas that are within the European Union and somewhat local to the UK. Those with tenants within this region may now be asking whether it is possible to move their existing instances to the UK. The reasons for this may be straightforward, complex or oddly patriotic in nature – ranging from data residency requirements through to the desire of being a proud Brit with a wholly British D365E instance 🙂 In this week’s post, we’ll take a look at whether it is possible to currently migrate an existing non-UK based tenant into the UK via the various options at our disposal.

For those who do not wish to read ahead, the TL;DR version can be accessed by clicking the button below:

Spoiler Inside SelectShow

 

If you have decided to stick around, then let’s take a closer look at the two avenues potentially at our disposal for migrating a CRM/D365E instance: A Microsoft Support Request and the Backup/Restore Feature.

Asking Microsoft Directly: What did they say?

Microsoft supports the ability for businesses to a move their CRM/D365E instance to an entirely different region. This is all handily summarised as part of a TechNet article:

The Geo Migration feature for Dynamics 365 (online) will allow customers to move their instances in a single tenant from one region to another.

I was recently involved as part of a support request with Microsoft, in which we asked the question whether it is possible to migrate an EMEA D365E instance to the UK. We were told that it is not currently possible to do this, with the following response given:

The data residency option, and the availability to move customer data into the new region, is not a default for every new region we launch. As we expand into new regions in the future, we’ll evaluate the availability and the conditions of data moves on a region by region basis.

No specific timeframes on when (if ever) this type of Geo Migration would be made available when this was queried with Microsoft. However, I would posit its likeliness for the near future, given that you can currently request the very same for your Office 365 tenant. At the time of writing (June 2017), however, the Geo Migration option is not viable for migrating your CRM/D365E instance across to the UK.

Backup and Restore: The Saviour of the Hour?

The ability to backup and restore your CRM/D365E Online instance(s) was a much welcome feature when it was introduced last year. Microsoft frequently performs backups of your instance(s), to provide sufficient disaster recovery potential on their end. These backups are exposed to Administrators via the Administration Centre, as well as the ability to generate your own backups at any time. These can then be restored into a spare Sandbox instance for testing/development. The key thing to remember with this feature is that it is limited to Online backup/restore only. You cannot, for example, download a copy of the SQL Server backup file and then use this as part of an On-Premise install.

You may be thinking at this stage this feature would allow us to get around the above issue by taking a backup of your non-crm11 existing organisation and restoring to your crm11 instance. Unfortunately, this is not possible, either via the Administration Centre or through logging a ticket with Microsoft. This is very likely due to the fact that different regions have different Administration Centres, with all of the functionality within that (backup/restore, administrative settings and update management) contained for instances within that specific region.

This can be confirmed by taking a look at the URL. When you are within the EMEA region, for example, the URL looks like this:

https://port.crm4.dynamics.com/G/Instances/InstancePicker.aspx

Whereas for the Great Britain (GBR) region its:

https://port.crm11.dynamics.com/G/Instances/InstancePicker.aspx

Businesses that have multiple instances across different regions are classed as “multi-tenanted” by Microsoft, and you have the ability to switch your region and access desired functionality from within the Administration Centre:

Going back to the above point re. functionality being “containerised”, this can be confirmed by accessing the properties of a crm11 instance whilst within the crm4 Administration Centre:

Our options to Edit, Reset, Copy etc. the instance are non-existent; to make them appear, you have to open the Administration Centre for the GBR region.

So why is all of this so important?

When speaking with customers regarding new IT Projects, the question of data location is one that is almost always raised. Whereas in the past, organisations would choose to host their entire IT infrastructure on-premise, the rise of cloud computing has meant it is generally more cost-effective to migrate infrastructure into a data centre or a SaaS provider, such as Microsoft. Whilst these solutions generally tick all of the boxes from a resiliency, performance etc. standpoint, the awkward tick box – the actual, physical location of the data itself – is more difficult to extrapolate. An organisation such as Microsoft, for example, has data centres all over the globe, leading to the potential of data leaving particular jurisdictions and some potentially controversial realities, such as the implication of the US Patriot Act on data that Microsoft holds. As a business, you may be required by local law to ensure that data is stored within the current jurisdiction, within the European Economic Area (EEA) and even be required to literally identify the server rack on which a particular database/system is hosted on. With this in mind, one barrier for adoption of CRM/D365E in the UK could be the question over data residency. There are also other performance considerations that arise from the location of your CRM/D365E instance. It is entirely feasible that connections to a UK hosted tenant will be faster compared to connecting to a tenant based in Europe, the US or anywhere else in the world. Administrators who may be attempting to identify ways in which their instance can run optimally may, therefore, benefit from having their CRM/D365E instance hosted in the UK.

Finding an Interim Workaround

For businesses who have strict, data residency requirements that could have serious legal implications, the situation is currently not ideal if they currently use CRM/D365E. In terms of finding a workaround until Microsoft support geo-to-geo migrations for UK regions, customisation components can be straightforwardly migrated via solutions, but other instance-specific settings/data could take a significant amount of time to move across. There are tools out there that can help in this:

  • Use KingswaySoft’s Dynamics 365 SSIS Integration Toolkit to create a .dtsx package to migrate all of the required data to a newly provisioned instance.
  • Utilise Scribe Online to configure a D365E to D365E one-time replication job.
  • Migrate the data using the applications built-in tools and Configuration Migration Tool, available within the SDK.

There is, fortunately, a way forward for the desperate, but the steps involved need to be carefully planned out in advance to ensure that no issues are encountered. For example, if you have recurring Workflows in your old environment, how do you migrate these across and ensure they are restarted correctly? I would envision that Microsoft will very soon offer the ability to migrate into the UK region, so it may end up being more prudent to hold off until this is announced and generally available.

When working with applications day in, day out, you sometimes overlook something that is sitting there, staring at you in the face. It may be an important feature or an inconsequential piece of functionality, but you never really take the time to fully understand either way just what it is and whether it can offer any distinct benefits or assistance. I realised a great example of this when recently deploying some new Plug-ins into Dynamics CRM/Dynamics 365 for Enterprise (CRM/D365E). When you are setting up a new Step for your Plug-in, you are given the option of specifying an Unsecure Configuration and Secure Configuration via a multi-line text box to the right of the window:

1

I was curious about just what these are and why it is not something that you ever really come across when you are first learning about Plug-in development with the application. I took a closer look at what these text boxes do and, as part of this week’s blog post, I wanted to share my findings and provide a demonstration of how they work in practice.

The Theoretical Bit: Unsecure/Secure Configuration Overview

Typically, when we want to get some juicy information relating to a piece of CRM/D365E functionality, we would turn to our good friends TechNet or MSDN. In this instance, however, there is no dedicated page that covers this topic in-depth. We must instead navigate to the Write a Plug-in Constructor page to find dedicated information about how these work:

The Microsoft Dynamics 365 platform supports an optional plug-in constructor that accepts either one or two string parameters. If you write a constructor like this, you can pass any strings of information to the plug-in at run time.

These “one or two” parameters are the multi-line text boxes indicated above. Information is exposed as string objects within you C# code and you enable this feature within your code by specifying the following, SDK adapted constructor within your Plug-in class:

public MyPlugin(string unsecureString, string secureString)
    {
        if (String.IsNullOrWhiteSpace(unsecureString) ||
            String.IsNullOrWhiteSpace(secureString))
            {
                throw new InvalidPluginExecutionException("Unsecure and secure strings are required for this plugin to execute.");
            }

            _unsecureString = unsecureString;
            _secureString = secureString;
    }

As with anything, there are a number of important caveats to bear in mind with this feature. These can be gleaned via additional online sources:

In terms of use cases, the above articles highlight some potential scenarios that they are best utilised within. Perhaps the best example is for an ISV solution that requires integration with external web services to retrieve data that is then consumed by CRM/D365E. Credentials for these web services can be stored securely when the Plug-in is deployed via the use of Secure configuration parameters. Other than that, if you are developing a Plug-in for internal use, that is unlikely to be deployed/managed across multiple environments, then it is probably not worthwhile to look at utilising configuration parameters when you can just as easily specify these within your code.

Practice Makes (for) Perfect (Understanding)!

The best way to see how something works is by getting hands-on and seeing how it works in action. Let’s assume you wish to deploy a plugin that executes whenever a record is opened/viewed by any user across the platform. The plugin should update the First Name (firstname) and Last Name (lastname) fields to match the value(s) in the Unsecure and Secure Configuration properties accordingly. The below plugin code will achieve these requirements:

using System;
using Microsoft.Xrm.Sdk;

namespace D365.BlogDemoAssets.Plugins
{
    public class PostContactRetrieve_PluginConfigurationTest : IPlugin
    {
        private readonly string _unsecureString;
        private readonly string _secureString;
        public PostContactRetrieve_PluginConfigurationTest(string unsecureString, string secureString)
        {
            if (String.IsNullOrWhiteSpace(unsecureString) ||
                String.IsNullOrWhiteSpace(secureString))
            {
                throw new InvalidPluginExecutionException("Unsecure and secure strings are required for this plugin to execute.");
            }

            _unsecureString = unsecureString;
            _secureString = secureString;
        }
        public void Execute(IServiceProvider serviceProvider)
        {
            // Obtain the execution context from the service provider.

            IPluginExecutionContext context = (IPluginExecutionContext)serviceProvider.GetService(typeof(IPluginExecutionContext));

            // Obtain the organization service reference.
            IOrganizationServiceFactory serviceFactory = (IOrganizationServiceFactory)serviceProvider.GetService(typeof(IOrganizationServiceFactory));
            IOrganizationService service = serviceFactory.CreateOrganizationService(context.UserId);

            // The InputParameters collection contains all the data passed in the message request.
            if (context.InputParameters.Contains("Target") &&
                context.InputParameters["Target"] is EntityReference)
            {
                Entity contact = new Entity("contact", ((EntityReference)context.InputParameters["Target"]).Id);
                
                contact["firstname"] = _unsecureString;
                contact["lastname"] = _secureString;
                service.Update(contact);

            }
        }
    }
}

When deploying the plugin using the Plugin Registration Tool, we specify the step to execute on the Retrieve message and to execute in the Pre-Operation Stage (otherwise the form will need to be refreshed to see the updated values!). We also need to specify our desired values for the First Name and Last Name fields in the appropriate Configuration fields. The Register New Step window should look similar to the below if configured correctly:

When we navigate into the Jim Glynn (sample) Contact record within CRM/D365E, we can see that the Plug-in has triggered successfully and updated the fields to match against the values specified on Step above:

We can also confirm that the appropriate error is thrown when one of the configuration properties is missing a value, by modifying our Plug-in step and attempting to reload our sample Contact record:

Can you spot what’s missing? 🙂

By clicking Download Log File, we can view the error message specified as part of the InvalidPluginExecutionException call. Below is a modified excerpt of the ErrorDetails XML that is generated:

  <InnerFault>
    <ActivityId>ed4a2021-9c87-4f06-a493-6d804676bf96</ActivityId>
    <ErrorCode>-2147220891</ErrorCode>
    <ErrorDetails xmlns:d3p1="http://schemas.datacontract.org/2004/07/System.Collections.Generic" />
    <Message>Unsecure and secure strings are required for this plugin to execute.</Message>
    <ExceptionSource i:nil="true" />
    <InnerFault i:nil="true" />
    <OriginalException i:nil="true" />
    <TraceText i:nil="true" />
  </InnerFault>

Conclusions or Wot I Think

It is impossible to become what I would like to term a “pub quiz champion” in CRM/D365E; what I mean by this is that I would defy anyone to rattle off every little detail and fact about the entire platform. As with any pub-quiz, those that do may more than likely end up cheating by having their phone out. With this metaphor in mind, I think Plug-in configuration properties would be an excellent topic for a quiz of this nature. As mentioned previously, it is not something that I was ever made aware of when starting to learn about Plug-in development and is not a feature touted regularly within the online community. Perhaps this is because of its very specific and limited application – although it is handy to have at our disposal, I think its usage is really only targeted towards those who are developing solutions that are deployed across multiple environments AND require the need to store configuration properties for external URL’s/web services in a compact and secure manner. Therefore, if you are currently having to use a custom entity within the application to store this type of information, it would make sense to reduce the footprint of your solution within the application itself and make the appropriate changes to use Secure configuration parameters instead. Using a bit of ingenuity (such as XML configuration parameters), you can achieve the same requirements without the need to customise the application unnecessarily.