Whenever you create a new Entity within CRM, you generally find yourself going through the same rhythm each time, both in terms of the general approach from a planning perspective and then the setup involved just after you hit ‘Save’ when creating the new Entity. Whilst often somewhat laborious, these steps are essential in ensuring that your Entity is configured in a professional and clear way. Anyone who works often within the Customizations area within CRM should have a well-defined “checklist” of items that are worked through as a minimum after an Entity is created. In this week’s blog post, we will focus on what I think are the most important things you have to look at doing once a new Entity has been created. Note that the below checklist should not be taken as “gospel” for what you should be doing, and there are a few things below that are more personal preference based as opposed to being absolutely required. I would be interested to hear if anyone has their own checklist items they follow when creating new Entities in the comments below, so please feel free to share ūüôā

Decide Options for Entity

You have a number of different options you can specify on Entity creation, which facilitates additional functionality such as duplicate detection, support for Business process flows etc:


Since a lot of these options are irreversible once you select them, it is generally better not to add them in when your Entity is first created, unless you are absolutely sure you need them. Enabling them from the outset will potentially add a number of additional attributes, which may impact on performance long-term. As a minimum, however, I would suggest that the Duplicate detection option is always selected. This is because you will almost always want to configure some kind of duplicate detection rules on your data, in order to ensure your CRM does not get clogged up with useless or unnecessary data.

Give everything within your Entity a clear and meaningful description

Regardless of whether it’s a form, attribute or a view, you should always ensure that a Description field is supplied with an appropriate 1 or 2 lines of text that describes what it is and what it is doing. You should never assume that it is obvious what a particular field is doing, and you are potentially doing a disservice to yourself, colleagues and your end-users by not taking the time to complete this step. My preference is always to be borderline obsessional in this regard, as past experience has taught me the invaluable nature of clear documentation and how my extra effort at the outset can potentially save hours for someone down the line.

The Curious Case of the Name field

Every custom Entity needs to have a Name, or Primary, field, which is specified on creation. You are limited in how this is customised, which can lead to trouble deciding how best to utilise it:


Where possible, you should customise the Name field so that is storing some required value on your new Entity. For example, if you have a new¬†Event¬†Entity, then you can use the Name field as the¬†Event Name field. If it’s the case that you decide not to use the Name field at all or are unable to find a suitable use for it, then you will still need to ensure that this is populated with a value of some kind. The reason? On the record page itself, CRM will populate the field with a rather undescriptive and generic value:


Now you could just force it so that end users populate this field with a value, but this in my view creates unnecessary data inputting steps and could lead to significant discrepancies within the database on how this data looks. It is better to create a workflow that populates this with a consistent value, that references other fields that will always contain data of some kind. The benefit of this route is that, if these fields are ever changed on the record, you can configure your workflow to run again to update the Name field accordingly.

Rename the Main form and update the description

I find it really annoying and strange that the default form created for new entities is called ‘Information‘ as opposed to just ‘Main‘, so I generally always rename this accordingly, updating the description of the form as well in the process.

Tidy up the default System Views

This step will generally need to be done after you have created all of your Entity attributes. When you first create your Entity, CRM will automatically create the following views for you:

  • Two default public views – one that shows all Active records and another that shows Inactive records.
  • An Advanced Find View – This is used whenever a user clicks the¬†Create Personal View button or selects [new]¬†from Advanced Find when creating a new view. Essentially, it is used as a default template to assist users when creating new views.
  • An Associated View – Shown when the user clicks on the related records button on the sitemap from a form.
  • A Lookup View – Shown when the user clicks on the ‘Look Up More Records‘ button on a lookup field
  • A Quick Find View – This view is displayed when a user performs a Quick Search function from the Entity view page. The important thing to remember with this is that only the fields that are specified under¬†Add Find Columns will be searchable via a Quick Search, so you will almost certainly need to customise this at some stage.

The views are always populated with the Name field and the Created On field. You will need to ensure that all of these views are modified so they contain the information that is most pertinent about your new Entity. If you are not using the Name field at all, then removing it from these views would be sensible, to ensure that end-users are not confused by a list of Entity records with a blank value being displayed.

Update your Security Roles accordingly

This can be sometimes easy to overlook, but unless you have configured your organisation’s security roles to include all relevant permissions, then your users won’t even be able to see, let alone use, your new Entity! So you should always ensure that your organisation’s security roles are updated to reflect the data access requirements of your business.

Conclusions or Wot I Think

Having a consistent approach when it comes to designing a CRM system is important for a number of reasons. It helps to inform and shape best practice approaches within a business, enables you to ensure a minimum level of quality as part of your solution and is essential when working as part of a team to ensure that team members are able to easily go into a solution and understand how everything operates. By combining together past experience, mixed together with well-understood best practice approaches, it can be very straightforward to put together a set of items that need to be checked-off as part of creating a new Entity, and will give everyone within a team the confidence and surety that they are customising CRM in the correct manner.

I have been really excited recently, as I began working more closely with ADXstudio & CRM Portals. This was perhaps one of the more exciting new features introduced as part of the CRM 2016 Spring Wave earlier this year and presents a major step forward for the CRM product. Now, businesses can start to leverage their CRM and its data in developing professional, accessible, customer and/or partner facing websites that integrate natively with your existing CRM system and processes.

One of the first challenges when getting to grips with portals is how you go about changing the OOB design of your site – for example, how do you modify the colour for a background or a particular button? Both products¬†utilise Bootstrap to enable portal designers to very quickly develop professional looking portals that are customised to suit particular businesses design/theming preferences. In addition to this, as outlined on ADXstudio’s website:

By using Bootstrap’s layout system, it’s possible to develop a single site that presents an appropriate interface to all devices your customers might use.

In the days where mobile responsiveness is an absolute requirement for website projects, Bootstrap provides a framework that ensures a consistent UI experience is maintained at all times for your end users. But, if you are scratching your head at just how to start working with Bootstrap (like I recently was!), it can be a major hurdle figuring out how to begin styling your portal. In this week’s blog post, I will take a closer look at what Bootstrap is, what “shortcuts” are out there that can greatly speed up developing your first Bootstrap template and how you go about applying this to your custom portal site:

What is Bootstrap?

Bootstrap was originally developed by Twitter but has since become an open-source project, on its 3rd major version. The Bootstrap website contains a nice little summary around the history of the project and its interesting journey from internal project to open-source release:

Bootstrap was created at Twitter in mid-2010 by @mdo and @fat. Prior to being an open-sourced framework, Bootstrap was known as Twitter Blueprint. A few months into development, Twitter held its first Hack Week and the project exploded as developers of all skill levels jumped in without any external guidance. It served as the style guide for internal tools development at the company for over a year before its public release, and continues to do so today.

Source: http://getbootstrap.com/about/

I was actually surprised to learn about its popularity, having not had any previous exposure to it, and its status as the almost de-facto standard in website design circles.

Creating your first Bootstrap Template

Microsoft’s article on portal theming (replicated from ADXStudios original article) suggests a few different websites to try in the first instance. We’ll take a closer look at 3 of the websites mentioned here that enable you to customise a Bootstrap template from scratch, and then at an alternative route not mentioned on either website:

Official Bootstrap Customizer

Via the official Bootstrap website, you can¬†create your own custom bootstrap¬†template. As pointed out in the above articles, there is no GUI interface that lets you preview your customised template; which means you have to download and apply the Bootstrap files to your website in order to get a feel for how it looks. If you’re feeling particular masochistic, then this is definitely the route for you ūüôā


Argh, too many settings! (‚ēĮ¬į‚Ė°¬įԾȂēĮÔłĶ ‚ĒĽ‚ĒĀ‚ĒĽ


When you first start using BootSwatchr, you immediately warm to it straight away – it provides a WYSIWYG editor, enabling you to very quickly tinker around with the various settings on the default Bootstrap template, and see how they will look in a browser. VERY nice! However, I have encountered some issue using the tool on Internet Explorer/Microsoft Edge, particuarly when it comes to the most crucial bit – exporting your BootStrap template .css file using the ‘Get CSS…‘ button. This is definitely one of the tools you should check out in the first instance, but just be aware that it may not work correctly on your browser of choice.


Code editor? Check. WYSIWYG view? Check. Instant applying of changes to the preview? Check. Full marks!


What is encouraging when you first start using BootTheme is that it looks to be constructed in the same vein as BootSwatch. However, I have had real trouble figuring out how to use this tool, as it is initially quite daunting figuring out where to start. I think with some dedicated time and learning, this could be a really effective tool to use when building your Bootstrap templates, but perhaps not the best beginners tool.


So er, yeah, looks pretty good – where do I start? :S


These tools are the ones that I have used when creating Bootstrap templates, and used in tandem, are quite effective in creating a Bootstrap template that conforms to specific branding requirements. You start off by creating a ColourLovers account, which lets you then create a “colour scheme” that can be used in PaintStrap. A “colour scheme” is essentially a collection of up to 5 different colours that you want to use on your BootStrap, which can be generated very easily using the ColourLovers website. Simply go to Create -> Palette, specify your colours, give it a descriptive name and save onto your profile:

1011 12

Once you’ve saved your COLOURLovers template, you then copy across the 6 digit code for the template into the PaintStrap 3 step wizard. This can be found within the URL of your selected template:


Which is then entered onto PaintStrap:


Then, on Step 2, you can start to customise which colours will appear where on your BootStrap – the nice thing being that you are not restricted to just the colours on your template and you can get a partial and full-screen preview of your template as you build it:


When you are happy with your template, click the ‘Generate CSS!’ button to download your BootStrap .css file. You will want to grab the bootstrap.min.css file; this is exactly the same as the bootstrap.css file¬†but has been slimmed down to remove line breaks, whitespace etc.

Once you’ve got your Bootstrap, how do you apply it to your portal?

Let’s assume we are using the Basic Portal, provided as part of ADXStudio; the steps are the same for CRM Portals, rest assured:


Navigate to the home page of your portal, ensuring that you are logged in as a Contact that has the Administrators Web Role. On the ADX widget on the top right of your page, click on New -> Child file:


You’ll be greeted with the¬†Create a new child file screen. Populate the details as follows:

  • Name: bootstrap.min.css
  • Upload File: Browse and select your bootstrap.min.css file
  • Partial URL: bootstrap.min.css
  • Hidden from Sitemap: Tick the box

It should look something like this:


Press Save and then refresh your browser. Your new bootstrap will be applied to your site; and, because we have configured it on our home page, it will cascade automatically across our portal site:

4 5
Looks…err…interesting! I would not recommend or endorse creating a bootstrap that looks like this, but this example provides an excellent illustration of the versatility of Bootstrap.

Getting up to speed with Bootstrap may look quite daunting initially, but fortunately, there are lots of tools and resources available online that can get you running quickly with BootStrap. These tools can significantly ease your learning journey with ADXstudio/CRM Portals and also allows you to look like a website design whizz in the process ūüôā

One factor that anyone considering CRM Online for their business would need to address is determining the amount of data you are intending to bring across into the CRM and how you expect this to expand in the long term. CRM Online includes 5GB of database storage for all of your CRM instances on an Office 365 tenant, which is included as part of the base plan (i.e. 5 Professional Licenses). If you run out of storage, there are only two ways in which you can increase this:

  • By purchasing 20 Professional user licenses, you will be granted an additional 2.5GB storage. This is cumulative up to a maximum of 50GB (e.g. if you add an additional 20 Professional licenses to your existing 400, then your storage will not increase further)
  • Additional storage can be purchased, at a whopping ¬£6.20 per GB

Based on the above costs, a careful analysis needs to be performed to ensure that a migration does not end up costing more than expected; either in the immediate or long term. In any event, administrators will need to keep a careful eye on their database storage levels over time by frequently reviewing the CRM Online Administration Center on their deployment:


I was recently investigating why a particular CRM Online deployments storage had ballooned from a rather modest 0.75GB all the way up to nearly 4GB – all over the space of a few months! After doing some further digging, I determined that the Attachment entity was consuming the most amount of data in the CRM instance. This was not spotted readily, due to the rather strange way that this entity works within CRM, which I wanted to highlight and discuss further as part of this weeks blog post:

Why should administrators regularly check Attachment Entity records?

Every time an email is automatically synced into CRM, either with Server-Side Synchronisation or via CRM for Outlook, all the attachments are also brought into CRM. This will include your typical files (a .pdf document, an Excel worksheet etc.); but may also include images from your email signature or any other content on the email that is not stored in plain text. Over time and, in particularly large deployments, this can start to eat away at your database storage very quickly. Ignore the impact that this entity can have on your CRM deployment at your peril…

Why administrators may struggle to¬†regularly¬†check Attachment Entity records…

The attachment entity cannot be searched using Advanced Find. It’s just not there on the list of entities available to query:


Oh, Attachment, where art thou?

The only way within the CRM interface to get a rough indication of how many attachment records are stored within the database is by running an Advanced Find Query against the Email entity, filtering out only email records that have a related attachment record:


(You can then customise the File Size (Bytes) filter to search for emails where the attachment is over a certain size Рthen, drill down in the email record to see the actual Attachment records).

So, what other options are available to us? You can use FetchXML to query the data on an Online/On-Premise deployment, but you are restricted in what information is returned. Only the following fields will be returned by a FetchXML; even if you specify, for example, the activityid field, it will never be returned in your request:

  • mimetype
  • filename
  • attachmentid
  • body
  • filesize

So with these restrictions in mind, you can run the below FetchXML query to return all attachment records where the file size is over 50MB:

  <entity name="attachment" >
    <attribute name="attachmentid" />
    <attribute name="filename" />
    <attribute name="filesize" />
    <filter type="and" >
      <condition attribute="filesize" operator="gt" value="10485760" />
    <order attribute="filesize" descending="true" />

To actually delete the record, you would have to either locate the record within CRM, a potentially laborious task. Unfortunately, there is no way to navigate to the record using query parameters appended to your CRM URL or to even use a Delete request in the SDK to remove the records. If you are running On-Premise CRM, then you could always run this manual query against the CRM organisation database:



DELETE FROM dbo.ActivityMimeAttachment
WHERE AttachmentID = 'B18FBFCA-046D-E611-80CB-00155D02DD0D'

I¬†am not sure whether this a supported way of using the application, so use at your own risk ūüôā

Be Proactive: 2 Tips to reduce the Attachment Data Footprint

To avoid a situation where you are having to go through the above to delete unnecessary email attachments, there are 2 things you can do to try and avoid this entity from swelling up unexpectedly:

  1. In Settings -> Administration -> System Settings, on the General tab, you can specify the list of blocked file extensions for attachments. Out of the box, CRM automatically populates this with a list of the most harmful file types, as a semi-colon delimited list:1You are able to freely modify this list to include/remove the list of attachments that you want CRM to automatically strip out. So if for example, your organisation uses high resolution .png images as part of your email signatures, this may be a good candidate to add to this list.
  2. Staying within the System Settings area, but this time jumping across to the Email tab, you have an option where you can specify the maximum file size for all attachments saved in the system:2By default, this is set to 5.1MB РI would not recommend increasing this to any large degree, and there may be a case to reduce this further to around the 2-3MB mark.

Consider all things as well Рhow essential is it that any attachment is stored within CRM in the first place?

Certain organisations may use separate email archiving solutions, that automatically backup and store and all emails sent across an organisation into an archive that can then be accessed by end users and (most importantly) system administrators. Examples of these solutions may include Exchange Online Archiving, MailStore, Mimecast or Metalogix. If you know that your organisation has one of these solutions in place and that emails are being backed up/archived with all of their appropriate attachments, then it may be prudent to block CRM from storing any type of attachment file altogether. On the flip-side, if your organisation does not have such a solution in place, then this can work in reverse РCRM could act as an excellent way of implementing an email archiving-lite solution for your business. Although, I would expect that this is only practical for an On-Premise deployment, where your storage costs will be typically more cost-effective compared to CRM Online.

I was writing some code recently for a CRM plugin, that involved working with multiple link entity attributes as part of a QueryExpression. Accomplishing this is relatively straightforward, thanks to some of the code samples provided within the SDK. For example, the following sample code gives you everything you would need; how to build the query and, more importantly, include the attributes you would need to return as part of the request:

//Create a query expression specifying the link entity alias and the columns of the link entity that you want to return
QueryExpression qe = new QueryExpression();
qe.EntityName = "account";
qe.ColumnSet = new ColumnSet();

qe.LinkEntities.Add(new LinkEntity("account", "contact", "primarycontactid", "contactid", JoinOperator.Inner));
qe.LinkEntities[0].Columns.AddColumns("firstname", "lastname");
qe.LinkEntities[0].EntityAlias = "primarycontact";

EntityCollection ec = _orgService.RetrieveMultiple(qe);

Console.WriteLine("Retrieved {0} entities", ec.Entities.Count);
foreach (Entity act in ec.Entities)
       Console.WriteLine("account name:" + act["name"]);
       Console.WriteLine("primary contact first name:" + act["primarycontact.firstname"]);
       Console.WriteLine("primary contact last name:" + act["primarycontact.lastname"]);

Very handy! But there are two problems that you may encounter when attempting to run the code yourself:

  • The code snippet attempts to print out the value of the LinkEntity First Name and Last Name Contact fields to the console. So, for example, when your code retrieves the Fourth Coffee¬†(sample)¬†record, we would expect to see¬†Rene Valdes (sample)¬†printed out. Unfortunately, this doesn’t happen, and we are instead greeted with a value that may precipitate some serious head-scratching:1The issue lies in how the SDK handles link-entity attributes included as part of a query. Instead of returning the value in the data type we would expect and, despite appending the appropriate namespace within our code to indicate the link entity our attribute is from (in this case,¬†primarycontact), CRM instead gives us the attribute as part of an AliasedValue object. The comforting thing to know is that the attribute value that we may (desperately!) want to grab is in this object somewhere, and we will look at the best way of accessing this later on in this post.
  • Putting aside the above issue, let’s assume that we weren’t working with an AliasedValue and just a standard CRM data type – for example, Single Line of Text/string. Our above code would work fine against all of the sample data records within CRM. But if we add a new Account record and add a Primary Contact record that doesn’t have a First Name value, we get an error thrown within our code when it attempts to output this value into the console:2Regular readers of the blog may be able to guess what is happening – as part of one of my previous posts looking at the GetAttributeValue method, we looked at the danger of accessing attributes via the Entity class, particularly when these attributes may end up containing blank values. In this particular example, there is another factor at play too – when a QueryExpression attempts to bring back all of the requested attributes, any attribute(s) that do not contain a value in the CRM database (i.e. are NULL) are not returned at all. This fact is useful in ensuring that our code can run as optimally as possible, but in this case, is our downfall – because our Entity object has no Contact attribute with a First Name value, no value is available¬†to return, so our code panics and throws an error; for the simple reason that it is attempting to access something that does not exist.

So how can we get around both of these issues? First of all, we need to alter the code so that the actual value of the First Name and Last Name fields are displayed correctly. One way of executing this is to explicitly cast our attribute values as AliasedValues, access the inner properties of the object and then cast to string the value of the attribute. An updated version of our code would, therefore, look like this:

    Console.WriteLine("account name:" + act["name"]);
    Console.WriteLine("primary contact first name:" + ((AliasedValue)act["primarycontact.firstname"]).Value.ToString());
    Console.WriteLine("primary contact last name:" + ((AliasedValue)act["primarycontact.lastname"]).Value.ToString());


Running this against our Sample Account/Contact results returns what we expect, which is good ūüôā


But, unfortunately, does not give us a complete solution to the above as we still hit a “The given key was not present in the dictionary.” error message as before, for the same reasons:



The above method is not satisfactory then, as we would need to include additional lines of code to handle the fact that the attribute value is not present – an if…else statement or a try…catch block. If we forget to put this in, then another issue surfaces in bad code potentially seeping into a Production environment – causing errors for end-users and hours of unnecessary debugging.

Our old friend GetAttributeValue has saved the day for us previously; can it do again? We can try by using the code snippet below – specifying the fact that we are returning an AliasedValue object and then getting the inner attribute Value:

Console.WriteLine("account name:" + act["name"]);
Console.WriteLine("primary contact first name:" + act.GetAttributeValue<AliasedValue>("primarycontact.firstname").Value);
Console.WriteLine("primary contact last name:" + act.GetAttributeValue<AliasedValue>("primarycontact.lastname").Value);

The code errors again, unfortunately, with a different error message, indicating that a NULL value is attempting to be accessed:


In this case, we must rely on our knowledge of C# to save the day, with a few options at our disposal. I’ve already suggested two possible options, but another could be considered, which would reduce the number of lines in our code. By using the conditional operator (?:), we can “test” for a NULL value in our GetAttributeValue and, if a NULL value is present, substitute it for an empty string or a value of our choice. Our final, error-free code, would look like this:

foreach (Entity act in ec.Entities)

        Console.WriteLine("account name:" + act["name"]);
        Console.WriteLine("primary contact first name:" + (act.GetAttributeValue<AliasedValue>("primarycontact.firstname") == null ? "" : act.GetAttributeValue<AliasedValue>("primarycontact.firstname").Value));
        Console.WriteLine("primary contact last name:" + (act.GetAttributeValue<AliasedValue>("primarycontact.lastname") == null ? "" : act.GetAttributeValue<AliasedValue>("primarycontact.lastname").Value));


Then, just to be sure, we run a quick test and confirm everything works as expected:


Now we can rejoice that our code is error free and that we’ve found another good example of how the GetAttributeValue method should always be used when working with CRM attributes.¬†It is a shame though that the code above, provided by Microsoft as part of the SDK, has such a significant error within it. Hopefully, it will be addressed as part of a future version of the SDK and we should be thankful that we at least have all of the sample code in the SDK in the first place; it gives developers and CRM customisers a great starting point to start developing consistent and supported code.