Configure Calendar instance in Pega
In this blog article, we will see how we can configure a calendar instance and use it in a pega application.
Business Requirment: Say, ABC banking organization uses Pega CRM application to treat the customers. Based on the customer needs, banking employees (application users) start creating the appropriate case types. Case types may have different work steps that need to be performed at different time periods and can be assigned to pick and process during different business hours. For example – The assigned workstep should always be processed within 3 business days. The term business days/hours refers to working hours that may vary per organization, geography, or time period. Also, the business days calculation should exclude the banking holidays.
How can we sync the holidays and business hours of an organization in a pega application processes? – The answer is to create a calendar instance.
What is a calendar instance?
– It is a data instance that can define business days and holidays for an organization.
– It belongs to the organization category.
– Calendar instances can be referenced in organization, workqueue, operator instances and used in service level agreement.
First, let’s check the shipped calendar instances.
Records -> Organization -> click on calendar
You can click and open any instance to see how it is configured.
You will see the Identifier of a calendar instance has a start date as the second key part.
What does this start date mean? Should it always start on Jan 1? – No. It is not mandatory to always make the start date as Jan 1.
Let’s see some characteristics of the start date in a calendar.
– The second key part of the calendar instance is the start date.
– You can have multiple calendar instances on different start dates.
Note: Also you can have many calendar instances per year as well – Like 20210101, 20210701
So how system identify which calendar to use?
First, you need to understand the end date of the calendar.
The calendar end date is one year (as per documentation) or 11 months (as per this tutorial hands-on) after the last holiday defined in the schedule tab.
In the above example, USDefault with start date as 20140101 – Dec 25, 2014 is the last holiday defined (9th row in the below picture), then Dec 25, 2015 is the end date for the calendar.
So the start date is Jan 1, 2014 and the end date is Dec 25, 2015.
Let’s say there is another calendar with start date as Jan 1, 2015 and the last holiday as Dec 25, 2015 and so the end date will be Dec 25, 2016.
Now, When your current date is June 01, 2015 and you want to add 5 business days, which calendar instance will be used?? Remember June 01, 2015 falls inside start and end period of both calendar instances.
– System finds the calendar instance with the latest start date not greater than the supplied date ( in our case June 01, 2015 is the latest or nearer date to the supplied date). So the system picks the calendar with start date as Jan 1 2015 instead of 2014.
– Java exception will be thrown if the supplied date is not covered by any calendar instance.
We will see about it shortly 😉
Food for thought: I still couldnt logically reason why Pega didnt include the end date as well as one of the key identifier for the calendar instance. That could have made simple, but instead Pega has some weird calculation for end date. If you could reason it, please comment below.
In my requirement, bank ABC is located in the Netherlands country and all the national holidays apply to the bank.
Let’s create a new calendar instance for ABC Bank.
How to configure a Calendar instance?
Step 1: Create a new instance
Records -> Organization -> Calendar -> Create new
I am defining the start date as Jan 1 2021.
Step 2: Configure the schedule tab.
Calendar locale This is an optional configuration where you can specify the locale by which the starting date is parsed. You can also just leave it empty because this is mostly used only for non-gregorian calendars.
Schedule
You can select what days can be considered as the business days for the organization.
You can mention the start time and end time as hhmmss.
ABC organization has business hours like 8 AM to 5 PM on all weekdays.
Closed days
You can mention all the holidays in the format YYYYMMDD
I am going to mention all the public holidays for Netherlands – https://www.government.nl/topics/working-hours/question-and-answer/public-holidays-in-the-netherlands
Enter all the days in YYYYMMDD and save the instance.
We have successfully configured the calendar instance with start date Jan 1 2021 and end date Dec 26 2022 (+1 year)
Calendar instance is mainly used by the functions defined under BusinessCalendar library.
Let’s test the function(s) from BusinessCalendar library
Step 1: I want to use the expression builder modal. Create a data transform or an activity rule.
Step 2: Use the function – @(Pega-RULES:BusinessCalendar).isBusinessDay(Param.Date, ABCDefault)
Tip: Is BusinessDay function, uses the calendar to determine if the input date is a business day (true) or not (false)
Step 3: Test the function.
a) Use current date in parameter. Today is 27/11/2021
It returns false as not a business day. Yes of course today is Saturday.
b) Now change the date to Friday – 26/11/2021.
It returns true.
The last holiday on the calendar is 26 Dec 2021 and so the end date for the calendar is 26 Dec 2022.
c) Try a working day in 2022 – 24/01/2022.
It returns true.
Now a final check.
d) Try dec 31, 2022 which is out of the range from end date.
It says dec 31, 2022 does not fall within the range of start date and end date of the calendar 2021.
Important note: As mentioned before, we see in the error message the end date is calculated as 11 months + of last-mentioned holiday. But in the documentation, it was mentioned as 1 year to last holiday. I Hope Pega clears this out 😉
How to maintain the calendar instance?
– It is the responsibility of administrators to create and maintain the calendar instance.
For easy maintenance, you can create a calendar per year with Jan 1 as the start date and enter all the applicable holidays for the year.
Important tip: make sure to create the calendar instance for the future years as well, because some processes may add business days that can extend for years and if calendar instance not found for the future date, then it will end in exception
Where to reference a calendar instance?
a) Organization instance
This is an optional configuration to set the default calendar for the organization.
The business day calculations involving the organization will use the mentioned default calendar.
Note: In none of the rule references, you will mention the second key part of the calendar instance. System will pick it dynamically based on the supplied date as we saw before.
b) Work queue
In the preference tab, you can mention the optional Calendar instance.
If we want to restrict the days on which work can be added to the queue, you can mention the calendar instance.
c) Operator instance
The business day calculations for the operator will be based on the calendar instance mentioned in the operator instance.
The calendar instance mentioned here will override or take precedence over the calendar instance mentioned in the organization instance.
Note: When you do some changes for the calendar, that will reflect to the operators only when they re-login.
d) Service level agreement
Service level agreement uses business days calculation configuration.
But we dont mention any calendar instance!, So how does Pega picks the calendar instance for this SLA processing?
It follows the priority order
- First it looks if any calendar is associated with the workitem. pyCalendar work property. You can explore the DefineSLATimes activity for more details on it.
- Calendar specified in the operator instance or in the organization instance.
- If all are empty, then it uses the calendar instance with name Default.
As summary,
– Use calendar data instance to define business days and holidays for an organization
– Second key part of the calendar instance identifies the start date for use. End date is computed as 1 year or 11 months after the last specified holiday in the schedule tab.
– Functions that are part of Pega-RULES:BusinessCalendar use the calendar instance.
– Calendar instance is referenced in organization, operator, workqueue instances and also used in service level agreements.
We are at the end of this blog article.
