Understanding Repeat Blocks (calendar, resource and service)

Repeat Blocks Explained

Blocks can be set to repeating for Calendar, Resource and Service blocks.
This functionality allows you to set up availability blocks on a daily, weekly, or monthly basis.

All blocks have the same required fields:

Required fields: startDate, endDate, startTime, endTime and reason.

The reason will be displayed with the block when applicable via the unavailability endpoint for easy identification. These blocks are identified as SAB, Calendar Block, RAB Resource Block and VAB for a Service Block.

If you are looking to block out a time for the entire company, this should be done using a Calendar block. All resources and services are tied to the company’s main calendar. The easiest way to block out a slice of time companywide is to post/create a calendar block.

You can define blocks at the Calendar, Resource or Service level. The following endpoints are used to define the various blocks.

OTHER BLOCKING METHODS INCLUDE:

Holidays - Holidays are also blocking and are handled as holidays. We have typical holidays set up for most countries that we do business in. If you are in a country that is not properly showing holidays, please create a support ticket defining the country and the holidays that need to be added.

Company and Business Hours - If you are closed on weekends, this is typically handled in the Business Hours of a company or location.

Appointments booked – If you already have an appointment booked in a time slot, that would block another appointment being booked.

Google and Outlook calendar synced events – if you use the google or Outlook calendar sync you may have other blocks in your availability.

HOW DO BLOCKS WORK?

A calendar block is simply a mechanism to block out a span of time, a series of time over a range of dates, either daily, weekly or monthly. This may sound simple but the resulting availability calls when blocks are involved can be confusing if not set up properly.

Blocks can be set up one time. In this case you may need to block a few hours on a specific day, companywide. An example is there is a Town Hall with the President of your company on Monday June 28th, 2021, from 3pm – 5pm.

SINGLE DAY BLOCK
The best way to handle this is to create a calendar block, here is the post schema. You need the calendar ID to post the calendar block.

Use the GET/setup/v1/calendars endpoint to get your calendar ID.

To post a calendar block go to the: POST/setup/v1/calendars/{id}/block endpoint.

The following schema blocks out 2 hours on 6/28 companywide.

{
"startDate": "2021-06-28",
"endDate": "2021-06-28",
"startTime": 1500,
"endTime": 1700,
"reason": "Annual Town Hall by the CEO",
"allDay":false,
"repeats": false,
"repeat": {
}
}

Note that REPEAT = FALSE. As long as repeat = false, the block will be treated as a single block.

DAILY BLOCKS - MULTIPLE DAYS BLOCK
If you want to repeat the block for more than one day, you can use the frequency field, within the repeat section.

The frequency can be set to a value of D,W,M,Y for Day, Week, Month, or Year respectively.
Daily blocks will repeat for each day of the week for the date range specified. This example will add a block from 5/1-5/31 from 12noon – 1pm. There will be no availability during this time frame.

Sample schema for a Daily block:
{
"startDate": "2021-05-01",
"endDate": "2021-05-31",
"startTime": 1200,
"endTime": 1300,
"reason": "Company closed for lunch from noon – 1pm, daily",
"allDay": false,
"repeats": true,
"repeat": {
"frequency": "D"
}
}

This block will add a block from 5/1-5/31 from 12noon – 1pm. Nothing can be scheduled during that time. Note: frequency is D-Daily so the block is applied to all the days in the date range specified.

WEEKLY BLOCKS
Use a weekly block if you want to specify the day of the week you need to block. For example, let’s say the company is closed for 2 hours every Friday from 9-11am. This can be accomplished by using a weekly block.

In order for the weekly block to work, repeats must be set to true and the following 3 fields must be supplied in the repeat section. Frequency, weekdays and interval.

"repeats": true,
"repeat": {
"frequency": "W",
"weekdays": "5",
"interval": 1
}

frequency: can be set to a value of D,W,M,Y for Day, Week, Month, or Year respectively.

weekdays: Weekly blocks will repeat only on the specified days of the week for the date range specified. For a weekly block you must also specify the weekdays parameter. Weekdays are expressed as a string of digits with each single digit in the string representing a day of the week. The possible values are 0,1,2,3,4,5,6 where 0=Sunday, 1=Monday, 2=Tuesday, 3=Wed, 4=Thursday, 5=Friday, 6=Saturday.  For our example, Friday is identified as #5. If you were to apply the block on Tuesdays and Thursdays, you would specify #2 & #4.

interval: Use the interval property to specify the interval that the block repeats. For example, an interval of 2 for a weekly block means that the block will repeat every second week beginning on the day specified. The interval property applies to all repeat frequencies. For every week, the interval should be 1.  Note: If an interval is not supplied, the default will be 0, resulting in no working block being created.

For the example above the schema would look like this:

{
"startDate": "2021-07-1",
"endDate": "2021-07-31",
"startTime": 900,
"endTime": 1100,
"reason": "Friday late start day!",
"allDay":false,
"repeats": true,
"repeat": {
"frequency": "W",
"weekdays": "5",
"interval": 1
}
}

Note: Using an Interval of 2, would add the block, every other week (2 week interval)

MONTHLY BLOCKS
Use a monthly block if you want to specify a specific day of a month you need to block or a particular weekday of the month.

Monthly blocks repeat either on the day of the month specified in the monthDay property or on the day of the week and the week of the month specified by the start date. For example, repeat every 3rd Friday of each month or repeat on the 21st day of the month.

These scenarios are managed by using the monthType parameter. There are two possible values for monthType: D for Day of Month or W for Week of Month.

For monthType D, monthDay value must be between 1 and 31. It is the day of the month.

For monthType M, monthDay value contains 2 digits: day of week(0-6), (0,1,2,3,4,5,6 where 0=Sunday, 1=Monday, 2=Tuesday, 3=Wed, 4=Thursday, 5=Friday, 6=Saturday) and week of month (1-5). 1 being the first week, 2 being the second. The third Thursday of the month is depicted as a monthDay=”43”.

frequency is required, it should be set to “M”, monthly
monthDay is the day of the month you want blocked off

Example 1: The CFO speaks to all employees on the 21st of every, from 12pm-2pm. In this case you would create a Monthly Block. This schema blocks off 12-2pm, every 21st of the month between “July 1st – Dec 31th”.

{
"startDate": "2021-07-1",
"endDate": "2021-12-31",
"startTime": 1200,
"endTime": 1400,
"reason": "CFO speaks on the 21st of every month”,
"allDay": false,
"repeats": true,
"repeat": {
"frequency": "M",
"monthDay": 21,
"monthType": "D"
}
}

Example 2: The is an employee get together on the 3rd Thursday of every month. This schema blocks off 12-2pm, every 3rd Thursday of every month between “July 1st – Dec 31th”. Note: monthType=”W” for week and monthDay=”43” for 4-Thursday, 3-3rd week of month.

{
"startDate": "2021-07-1",
"endDate": "2021-12-31",
"startTime": 1200,
"endTime": 1400,
"reason": "Employee get together, Third Thurs of every month",
"allDay": false,
"repeats": true,
"repeat": {
"frequency": "M",
"monthType": "W",
"monthDay": 43
}
}

ALL DAY BLOCKS
Setting an AllDay block as a calendar block essentially shuts down all availability for the company for the day or date range specified. If your company closes for an extended period of time, use the AllDay parameter to block the day(s). In this example the company is closed from July 1 – July 14th.

Example AllDay Block – from July 1- July 14th, 2021

{
"startDate": "2021-07-01",
"endDate": "2021-07-14",
"startTime": 0,
"endTime": 2400,
"reason": "Company closed for 2 weeks",
"allDay":true,
"repeats": false,
"repeat": {
}
}

Note:  It is important to enter the startTime as 0 and EndTime as 2400.

REPEAT BLOCK TIP
When you create a block(s) it is always good practice to validate that it is working by running the unavailable endpoint on a specific day that you expect the block to appear on. This will validate that the block has been applied properly.

GET/consumer/v1/availability/{serviceId}/{startDate}/{endDate}/unavailable

OTHER BLOCK TYPES
In addition to calendar blocks we also have the ability to create RESOURCE and SERVICE BLOCKS. The resource blocks are applied to specific resource only. Service blocks apply to services only. If you offer a service that has limited accessibility, that is a good use case for a service block.

The parameters and functionality used in the Calendar Blocks applies to both resource and service blocks.

Note: All three block types can be used simultaneously when accessing the availability endpoint. Be sure to use the unavailability endpoint to answer any availability questions you may have on any particular date or dates(s).