Microsoft Dynamics CRM 2011 supports creating and managing recurring appointment. It also supports its bi-directional synchronization support with outlook calendar just like normal CRM appointments. In CRM 2011 user can create recurring appointment from web client user interface also.
Recurring appointment look and feel is almost similar to outlook recurring appointment. This is designed to provide user a similar experience. But there are two major differentiators as pointed in this blog also.
1. Outlook Recurring Appointments follow Rule based On-Demand expansion model while in CRM instances get created and persisted in Database as individual Appointment records. This expansion based model allows other components of CRM to work seamlessly on individual appointments records.
2. Unlike Outlook, CRM allows us to update recurrence rule of recurring series and still maintain past history of recurring series. On every update of recurrence information, past appointment instances of recurring series are preserved and they can be viewed from a common grouping link in recurring series records.
In this blog I wanted to share more detail on recurring appointment update series logic. At the end we will walk through an example to get more clarity on this.
How past instances are saved in CRM
In CRM when recurrence information is updated for a series we still keep the past instances of series. Unlike in outlook where all existing instances are deleted and new ones are created based on new recurrence pattern. It helps in preserving valuable information which might be associated with past instances. First let’s understand recurrence update. Update of any recurrence attribute (which can change recurrence definition) like occurrence, start date, end date, pattern end type, pattern type etc. comes under this category. From UI any update on recurrence dialog comes under this category.
An important thing to note here is that in CRM we only save history of past instances. If user updates any future instance the information will not be saved. Before starting on how actually past instances are saved in recurring appointment lets understand what could be various cases of recurring appointment series based on today’s date when user do recurrence update on series. There can be mainly three cases based on today’s date on which we do update series.
Case 1: Whole series lies in past
Case 2: Whole series lies in future
Case 3: Series starts in past and continues in future
Like the image shown below. In case 1 and case 3 only we need to save past history. As mentioned earlier in case 3 we will simply delete all instances and new expansion will happen based on new recurrence information.
Figure 1: Different cases of series based on Today's date
I will like to give a brief introduction on metadata related to recurring appointment. For more detail please refer SDK documentation. We have introduced a new entity RecurringAppointment. For preserving instances of series we use same Appointment entity. Before going into logic of update recurrence we should be aware of two fields which play crucial role in update recurrence.
1. SeriesID – This is a new attribute in appointment entity. All instances are associated with their corresponding recurring appointment through this field. SeriesID of all instances is set to ActivityID of their recurring appointment master.
2. GroupID – This is a new attribute in recurring appointment entity. To save history of past instance we create a new recurring appointment master and associate past instances with it. All associated recurring appointments are linked through this field. There can be couple of recurrence update for same series. These all recurring appointment master share same groupid which is set to activityid of first recurring appointment master.
Now let’s start with recurrence update logic. This is what happens when recurrence information is updated for a series.
1. All future instances are deleted
2. If there are any past instances
a. A new recurring appointment master is created in closed state with GroupID same as activity ID of current recurring appointment.
b. SeriesID of all past instances is updated to this recurring appointment.
3. Current recurring appointment master recurrence info is updated which does expansion based on new recurrence rule with effective start date as today.
Below diagram explains it in detail.
Figure 2: Recurrence update series logic
As you can see after recurrence update a cloned recurring series is created and past instances refer this cloned master as their SeriesID. New instances created in future based on new recurrence information refer to same recurring series (with updated recurrence information).
A quick walkthrough with an example
Let us walk through this logic with an example. In this example we assume that today’s date is 10th March 2011.
User creates a series with
Start Date: 7th March 2011 End date: 12th March 2011
Pattern time: 10:00 AM – 11:00 AM Pattern Type: Daily
Figure 3: Recurrence definition of an quick example
On calendar it will look like:
Figure 4: On calendar expansion of series before update
A1 to A6 represents six appointments (instance) of series. R1 is the recurring appointment master. All instances have seriesID set as activityid of R1. Now let’s say user update recurrence pattern by changing appointment time to 11:00 AM – 12:00 AM (initially it was 10:00 AM -11:00 AM).
Figure 5: On calendar expansion of series after update
Now after update A1 to A4 are past instances as there pattern date is less than today. New recurring appointment R2 is created and SeriesID of all past instances (A1-A4) is updated to ActivityID of R2. A5’ and A6’ are new appointment created based on new recurrence rule. They still have R1 as its SeriesID. GroupID of R1 and R2 will be set as activity ID of R1. In this way we can group all recurring appointments which are associated.
Hope this example adds more clarity in the logic of update recurrence.