Calendars and Expand Calendar request in CRM 2013 SP 1

In this blog, we have explained how CRM stores the records for calendar, and how can we programmatically retrieve them from CRM.

In CRM 2013 SP 1, two new calendar types are introduced. With that, we now have the following 4 types of calendars in CRM:

Type	Name	Description
0	Default	This type uses for business closure and work schedule’s records of service scheduling.
-1	Inner Calendar Type	Inner Calendars are used by other calendars to build a graph of time slots available for customer service or service scheduling to be performed.
2	Holiday Schedule	This is also a new Type of calendar. And it uses for creating the Holiday Schedule records.
1	Customer Service	This is new type of calendar. And it uses for creating the Customer Service Schedule records.

When we create the records for the weekly schedule for Facility/Equipment and Users, Business Closure, Holiday Schedule and Customer Service Schedule in CRM, out of public view, CRM creates the records for them in the Calendar and Calendar Rule entity. Below, we have explained how the records are created in Calendar and Calendar Rule entities and how we can retrieve them.

Note: As we can’t do the Advance find for the Calendar and Calendar Rule entity, we have displayed the records from the SQL database below. By using the OrganizationService, you can programmatically retrieve the Calendar and Calendar Rule’s records.

1. Default type for Business Closure: By default CRM have a record in the Calendar entity for Type O and Name “Business Closure Calendar” as shown in the below screenshot:

Now if we create the records of the Business Closure in CRM, it will create the record for “Business Closure Calendar” in the “Calendar Rule” entity and not in the Calendar. Hence the records of the Business Closure are created only in the Calendar Rule entity as shown in the below screens:

Now if you need to retrieve all the Business Closures, then you need to follow the below steps:

• First you need to read the Calendar record where the name will be “Business Closure Calendar”. It will give you the Calendar Id, in our case the Calendar Id is “2F3B356D-B21B-E411-80DB-00155D000819”.
• Now you need to read all the Calendar Rules records, where Calendar Id will be “2F3B356D-B21B-E411-80DB-00155D000819”.

2. Default & Inner Calendar type, and how it works for Weekly Schedule of Facility and User: When we define the weekly schedule for facility or users as shown below:

For this schedule, CRM then creates a record, with Type O (Default) in Calendar entity.

As shown in the above screen (Weekly schedule setting for facility), we have chosen the 5 day in a week rule, and Work Hours are 8:00 AM – 5:00 PM. Hence it will create the another Calendar record with Type -1 (Inner Calendar) as shown below:

And for the combination of Inner Calendar Id “FF4BEDC7-BE1B-E411-80DB-00155D000819” and Calendar id “766D0EA5-675F-4F9B-B972-F60908804B14”, it creates the “Weekly Single Rule” in the Calendar Rule entity as shown in the below screenshot:

And if we check the Calendar Rule for “FF4BEDC7-BE1B-E411-80DB-00155D000819” (Inner Calendar ID of 766D0EA5-675F-4F9B-B972-F60908804B14), then we find that it only contains the Offset and Duration and that Offset and Duration helps us to create the start and end time of Schedule as shown in the below screen:

Hence, if we need to create the Start & End Time of the Schedule, then we calculate it from Offset and Duration as follows:

Start Time = Offset/60, hence in our case. It will be 480/60 = 8:00AM

End Time = (Offset + Duration)/60 = (480 + 540)/60 = 1020/60 = 17 = 5:00 PM

Now if you define any time Off in the schedule of Facility or User, it will create the record in the Calendar Rule, where the Description will be “Time Off Rule” as shown in the below screens:

Now, if you need to programmatically read the “Time Off” of any resource (Facility or User), then you need to follow the below steps:

• Manually read the CalendarId from that resource.
• Then read all the records from Calendar Rule entity, based on that Calendar Id, and Description will be “Time Off Rule”. And then based on the Pattern, Duration, and Start Time, you can calculate the Time Off.

Now, if you need to programmatically find the schedule of any facility between the given dates, then there are two ways of doing it:

• Manually read the calendar rules for “Weekly Single Rule” and “Time Off Rule” based on Calendar ID, and based on the Pattern, Duration, and Offset create the Start and End Times. But this will be time consuming and not the best way.
• Hence for this, CRM itself provides a request with the name “ExpandCalendarRequest”. Using this request, you just need to give the Calendar Id, and Start and End date. And it will return the schedule of the Calendar between given dates including time off and business closures.  You need to write the following code for that:

                ExpandCalendarRequest req = new ExpandCalendarRequest();

                req.CalendarId = new Guid(“766D0EA5-675F-4F9B-B972-F60908804B14”);

                req.Start = DateTime.Now.AddDays(-20);

                req.End = DateTime.Now.AddDays(20);

                ExpandCalendarResponse res = (ExpandCalendarResponse)_service.Execute(req);

In response, it will return an array of schedules. If user is available during that time, then it displays the Time Code as “Available”, otherwise it will display the Time Code as “Unavailable” in that particular schedule.

3. Holiday Schedule: When you create a new Holiday Schedule in the CRM, it creates the new Calendar’s record for the Calendar Entity, with type 2 as shown in the below screens:

Same as Business Closure, if you create the records under Holiday, it will create the records of the Calendar Rule entity where Description will be “Holiday Rule” as shown below:

Now if you need to retrieve all the Holiday Schedules, then you need to follow the steps below:

• First, you need to read the Calendar record where the Name will be the given name in your Holiday Schedule and Type will be 2.
• Then, read all the Calendar Rules for the corresponding Calendar Id.

4. Customer Service: When we create the Customer Service Calendar in the CRM, it creates 2 calendar records out of public view.

One record is created with type 1 (Customer Service), and another is created with Type -1 (Inner Calendar). This is same as the Weekly Schedule of Facility or User. In the Customer Service Schedule, we can provide the “Holiday Schedule” as shown below:

Now if you need to programmatically read the Customer Service Schedule between the given dates, then you can use the Expand Calendar Request as we did the for the Facility / User Schedules.

Note: Using the Expand Calendar Request, you can’t retrieve the Business Closers, Time Off and Holiday Schedule calendar’s records between the given dates.