One of the most sought after additions to the Timeline was support of custom entities. This new feature opens up amazing potential to expand the Timeline and customise it to suit many different scenarios. In this post we’ll discuss how to take advantage of this functionality by adding a custom entity to the Timeline.

If you would like us to configure the Timeline for your custom entities/needs we’d be pleased to help – please email us on sales@xrmconsultancy.com.

Timeline Configuration

Firstly, let’s take a look at the existing configuration to give us an idea of how the timeline works. Open up the Timeline solution and from the configuration page click on the link to open the Timeline Configuration.

Screen Shot 1

You can see here how all the existing entities currently supported by the Timeline have a configuration record associated with them. Open up the appointment record to see what it contains. You’ll notice some HTML, some Fetch XML and some other settings in here.

Screen Shot 2

An important piece of the configuration is the Timeline Entity links at the bottom. These records drive how the relevant entity links to the parent entity you place the timeline on.

Adding a custom entity

Ok, let’s put this into practice and configure a custom entity to appear on the timeline. Currently my timeline looks like the following.

Screen Shot 2014-01-22 at 23.31.50

To demonstrate how the custom entity works I will configure another entity to appear on the timeline. For the purposes of this example I have installed our SMS solution and the custom entity I will add is the SMS entity (xrmc_sms). Firstly open up the Timeline Configuration record via the solution file. Hit the plus button on top of the Timeline Entities grid to add our custom entity.

A quick summary of the more important fields we’ll use are:

Entity Logical Name: xrmc_sms. This is the underlying schema name of the entity.
Headline Field: subject. The main headline that will appear on the timeline.
Date Field: actualend. The date field that drives where it appears on the timeline. If your entity is a custom activity then putting ‘actualend’ in as the date will tell the timeline to use actual or scheduled start and end dates.
Small Icon: /WebResources/xrmc_SMSIcon16x16. The small icon that is associated with this entity
HTML: The HTML that will render the custom entity record and data within the timeline. We will discuss further below
Query: The Query that is run to pull back an individual activity record. We will discuss further below

For more details on these fields you can consult the Timeline Install Guide.

How the HTML works

The HTML we are going to use is as follows:


<div class="summaryinfo">
<div class="openentity">
<a id="recordURL" href='#' title="Open full record"></a>
</div>
<p id="to" class="xRMC-Attribute xRMC-PartyList">
<span>To:</span>
</p>
<p id="from" class="xRMC-Attribute xRMC-PartyList">
<span>From:</span>
</p>
<p id="regardingobjectid" class="xRMC-Attribute xRMC-Reference">
<span>Regarding:</span>
</p>
</div>
<p>
<span>Message:</span>
</p>
<div class="innerwrapper">
<p id="description" class="xRMC-Attribute">
</p>
</div>

Let’s take a closer look at this HTML. The main thing to point out within the first 2 divs is the openentity class and the recordURL anchor. These are used to create a link back to the record for the current entity so ensure to include them in your custom HTML:

<div class="summaryinfo">
<div class="openentity">
<a id="recordURL" href='#' title="Open full record"></a>
</div>
... other fields and attributes
</div>

The next set of tags you’ll see all have the xRMC-Attribute class. This tells it that the id of this tag is an attribute on the entity. So when you put in “to” it will look at the entity and extract the “to” field.

<div class="summaryinfo">
<div class="openentity">
<a id="recordURL" href='#' title="Open full record"></a>
</div>
<p id="to" class="xRMC-Attribute xRMC-PartyList">
<span>To:</span>
</p>
<p id="from" class="xRMC-Attribute xRMC-PartyList">
<span>From:</span>
</p>
<p id="regardingobjectid" class="xRMC-Attribute xRMC-Reference">
<span>Regarding:</span>
</p>
</div>

Also, as you will probably know, in CRM the “to” fields are a special type called Party Lists, and regarding are references to other entities. So these have special classes to allow the timeline to handle the attributes appropriately. There are many more different types of classes you can use to display different types of fields and all are covered in the Timeline Install Guide as mentioned previously.

Query CRM for the Entity Record

The final piece of the puzzle when configuring an entity is telling the Timeline how to get the record from the database. This is done using Fetch XML. A really quick way to build some Fetch XML is using the Advanced Find to create your query and then using the Download FetchXML button. For now let’s just use the following to pull back the required record:


<fetch version="1.0" output-format="xml-platform" mapping="logical" distinct="false">
<entity name="xrmc_sms">
<attribute name="to" />
<attribute name="regardingobjectid" />
<attribute name="activityid" />
<attribute name="description" />
<attribute name="from" />
<filter type="and">
<condition attribute="activityid" operator="eq" value="{0}" />
</filter>
</entity>
</fetch>

The main thing of note here is the special id parameter here:


<condition attribute="activityid" operator="eq" value="{0}" />

This will be replaced with the relevant SMS id at execution time to load the correct SMS entity record.

Linking this entity to a Timeline

We’re missing one last important link, when I place a Timeline on the Account page how does the Timeline know how to link this SMS entity to the Account entity? That’s where Timeline Entity Links come into play. If we take a look at the bottom of our Timeline Entity form you’ll see a section at the bottom for these Timeline Entity Links. Add a new one to the grid with the following details:

Name: SMS
Logical Entity Name: xrmc_sms

And put the following in as the query. It will locate all of our xrmc_sms records that are regarding a particular account:

<fetch version="1.0" output-format="xml-platform" mapping="logical" distinct="false">
<entity name="xrmc_sms">
<attribute name="subject" />
<attribute name="statuscode" />
<attribute name="regardingobjectid" />
<attribute name="activityid" />
<attribute name="scheduledstart" />
<attribute name="actualstart" />
<attribute name="actualend" />
<attribute name="activitytypecode" />
<attribute name="statecode" />
<order attribute="actualend" descending="true" />
<order attribute="actualstart" descending="true" />
<filter type="and">
<condition attribute="regardingobjectid" operator="eq" value="{0}" />
</filter>
</entity>
</fetch>

The main thing you’ll notice here is we’ve put in account for our Logical Entity Name. This tells the timeline, when placed on an account record, to use this timeline entity link.

Also, in addition to this, in the query you’ll notice that special field again:

<condition attribute="regardingobjectid" operator="eq" value="{0}" />

This will get replaced with the Account Id when it’s rendered on the account page.

Timeline with Custom Entities!

If you navigate back to an account you’ll now see SMS messages appear in the timeline:

Screen Shot 2014-01-23 at 23.16.53

Download

The updated Timeline is supported on CRM 2013 and CRM 2011 and is available for download now.

A free version of the Timeline is still available with all the features of the previous version, but to unlock custom entities and other great new features purchase a license key today!