Welcome to part 4 of my 5 part series looking at the practical implications surrounding the General Data Protection Regulation (GDPR) in the context of Dynamics CRM/Dynamics 365 for Enterprise (CRM/D365E). The series looks at how some of the features within this application can assist you in your journey towards GDPR compliance. This week’s post will be jumping across to an arguably underrated aspect of the application – Bulk Record Deletion and how it be used to satisfy your organisation’s data retention policy.

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.

As we get started, here’s a question for you: Do you know how long your organisation holds personal data for before it is deleted?

Most organisations that you speak to may struggle to provide an answer to the above question. The tendency is very much towards holding data for an indefinite period, with this approach typically being borne out of a lack of understanding of legal/contractual requirements, a result of a genuine oversight or as a necessary evil. The problem with any of these justifications is that, as well as falling foul of GDPR, it more than likely also is a contravention of your countries existing data protection legislation. In the UK, for example, Principle 5 of the Data Protection Act 1998 states clearly that “Personal data…shall not be kept for longer than is necessary…”. Despite being quite broad in its interpretation, it can be inferred very clearly that organisations should be aware of how long all of their data is held for and to have the appropriate documentary evidence to support this, via a policy or similar.

The existence of this principle demonstrates one of the areas where GDPR does not differ greatly from the Data Protection Act 1998. Article 17 covers all aspects concerning when and how data should be removed, under the broad principle of the “right to be forgotten”:

The data subject shall have the right to obtain from the controller the erasure of personal data concerning him or her without undue delay and the controller shall have the obligation to erase personal data without undue delay where one of the following grounds applies:
(a) the personal data are no longer necessary in relation to the purposes for which they were collected or otherwise processed;
4.5.2016 L 119/43 Official Journal of the European Union EN
(b) the data subject withdraws consent on which the processing is based according to point (a) of Article 6(1), or point (a) of Article 9(2), and where there is no other legal ground for the processing;
(c) the data subject objects to the processing pursuant to Article 21(1) and there are no overriding legitimate grounds for the processing, or the data subject objects to the processing pursuant to Article 21(2);
(d) the personal data have been unlawfully processed;
(e) the personal data have to be erased for compliance with a legal obligation in Union or Member State law to which the controller is subject;
(f) the personal data have been collected in relation to the offer of information society services referred to in Article 8(1).

To summarise, this means that organisations should remove information pertaining to data subjects when:

  • There is no further requirement to do so, either contractually or legally (i.e. they are no longer required to as part of a statutory instrument)
  • The subject has withdrawn their consent
  • It has been identified that data is being held which is at odds with an organisations policies or primary business activities

Article 5 extends this further by making it clear that data which you are unable to keep sufficiently accurate should be “erased…without delay”. To avoid this scenario would require the need to regularly contact the data subject concerned to verify their details are correct. One of the major “get out of jail free” cards that GDPR provides surrounding data retention is in instances where the data will be used as part of “archiving purposes in the public interest, scientific or historical research purposes or statistical purposes..” (Article 5). The scope of this is, as you can tell, rather limited and most non-governmental organisations/businesses may struggle to demonstrate their data archiving is in line with these broad principals.

The importance of ensuring a clearly defined and structured process for the removal of customer data, therefore, becomes a paramount concern under GDPR. Investigating and defining your organization’s data retention periods is an exercise that should be carried out if it has not been done so already. Once implemented, we can then turn to a component within CRM/D365E to automate and streamline the actual process – the Bulk Record Deletion feature.

In a nutshell, this feature is a really efficient means of deleting large amounts of predefined data within CRM/D365E. Administrators of the application will most often work with them when attempting to reduce the storage footprint of a CRM/D365E instance, via the removal of completed System Job records and other superfluous record types. The ability to define filter criteria, re-occurrence settings and to send out email notifications upon completion of a job, make them an excellent candidate to consider when streamlining your internal processes surrounding data retention.

For example, let’s assume your business has implemented a data retention policy that states Contact entity data that has not been updated or changed within 12 months should be deleted from the system. Setting up a Bulk Record Deletion Job within the application to assist with this task is remarkably straightforward, as the step-by-step guide below indicates:

  1. Within the application, navigate to Settings -> Data Management on the Sitemap and click the icon to navigate to the Data Management page:
  2. On the Data Management page, click on the Bulk Record Deletion icon to open the All Bulk Deletion Systems Jobs view. Once this has loaded, click on the New icon:
  3. The Bulk Deletion Wizard will open a pop-up window. Click Next on the first screen to move to the Define Search Criteria window. Modify the settings as follows:
    • Look for: Contact
    • Search Criteria: Modified On Older Than 365 Days

An example of how this looks can be seen below:

   

  1. Click Next when you are ready to navigate to open the Select Options page. Give the Bulk Record Deletion Job a descriptive name and then ensure that the following settings are configured:
    • Specify whether the Job should run immediately or in the future. It is recommended to schedule Jobs out of peak hours to prevent any performance detriment to other users.
    • Ensure that the Run this job after every box is ticked and then select an appropriate time period. I would recommend 30 days.
    • Ensure that the Send an email to me… box is ticked. You can also (optionally) specify additional email recipients, but note that these have to be valid application users (i.e. not any other email enabled entity such as Contact, Account etc.)

The screenshot below indicates how this should look. Click Next when you are ready to proceed:

  1. The final step in the wizard gives you the opportunity to review all configured settings. Press Submit to create the Job in the system and, if specified to start immediately, begin running it in the background. You can also navigate to the Recurring Bulk Deletion System Jobs view at any time to review the current status of a job, check to see when it is next scheduled to run or even modify its properties to suit your requirements:

 

The example above is a simplified one but could be extended further in conjunction with other features in the application to suit specific requirements. For example:

  • Create a custom entity to store contractual/statutory data retention limits and link these to your common entities within the application via a 1:N relationship. Once selected when a record is created, you can then define a workflow with a wait condition that updates a Two Option custom field on the entity as a flag for a Bulk Delete Job to remove from the system.
  • Using a custom field on your entity to indicate that a customer has expressed their “right to be forgotten”, define a workflow that sends a customer confirmation that their details will be removed from the system within 30 days and then use this same field as a flag for a Bulk Record Deletion Job.
  • Define a workflow that sends an email to owners of records that have not been modified within a set period (i.e. are inaccurate), prompting them to speak to the customer to update their details. Records that are not updated would then be deleted, using a Job similar to the one above.

Application features, such as the one discussed in this week’s post, really start to come into their element when you combine them with other tools found within the application. With this in mind, I would encourage you to roll up your sleeves to see what you can “cook” up 🙂

Thanks for reading! Be sure to check out the other posts in this series if you haven’t already using the links below. Part 5 next week will look at Subject Access Requests and how these can be processed more efficiently using CRM’s/D365E’s Word Template feature.

Part 1: Utilising Transparent Database Encryption (TDE)

Part 2: Getting to Grips With Field Security Profiles

Part 3: Implementing & Documenting A Security Model

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.

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.