Edit

Share via

Get and set the recurrence of appointments

  • Article

Sometimes you need to create and update a recurring appointment, such as a weekly status meeting for a team project or a yearly birthday reminder. Use the Office JavaScript API to manage the recurrence patterns of an appointment series in your add-in.

Note

Support for this feature was introduced in requirement set 1.7. See clients and platforms that support this requirement set.

Recurrence patterns

The recurrence pattern of an appointment is made up of a recurrence type (such as daily or weekly recurrence) and its applicable recurrence properties (for example, the day of the month the appointment occurs).

A sample Appointment Recurrence dialog in Outlook.

The following table lists the available recurrence types, their configurable properties, and descriptions of their usage.

Recurrence type Valid recurrence properties Usage
daily
  • An appointment occurs every interval days. For example, an appointment occurs every two days.
weekday None
  • An appointment occurs every weekday.
monthly
  • An appointment occurs on day dayOfMonth every interval months. For example, an appointment occurs on the fifth day every four months.
  • An appointment occurs on the weekNumber dayOfWeek every interval months. For example, an appointment occurs on the third Thursday every two months.
weekly
  • An appointment occurs on days every interval weeks. For example, an appointment occurs on Tuesday and Thursday every two weeks.
yearly
  • An appointment occurs on day dayOfMonth of month every interval years. For example, an appointment occurs on the seventh day of September every four years.
  • An appointment occurs on the weekNumber dayOfWeek of month every interval years. For example, an appointment occurs on the first Thursday of September every two years.

Tip

You can also use the firstDayOfWeek property with the weekly recurrence type. The specified day will start the list of days displayed in the recurrence dialog.

Access the recurrence pattern

As shown in the following table, how you access the recurrence pattern and what you can do with it depends on:

  • Whether you're the appointment organizer or an attendee.
  • Whether you're using the add-in in compose or read mode.
  • Whether the current appointment is a single occurrence or a series.
Appointment state Is recurrence editable? Is recurrence viewable?
Appointment organizer - compose series Yes (setAsync) Yes (getAsync)
Appointment organizer - compose instance No (setAsync returns an error) Yes (getAsync)
Appointment attendee - read series No (setAsync not available) Yes (item.recurrence)
Appointment attendee - read instance No (setAsync not available) Yes (item.recurrence)
Meeting request - read series No (setAsync not available) Yes (item.recurrence)
Meeting request - read instance No (setAsync not available) Yes (item.recurrence)

Set recurrence as the organizer

Along with the recurrence pattern, you also need to determine the start and end dates and times of your appointment series. The SeriesTime object is used to manage that information.

The appointment organizer can specify the recurrence pattern for an appointment series in compose mode only. In the following example, the appointment series is set to occur from 10:30 AM to 11:00 AM PST every Tuesday and Thursday during the period November 2, 2019 to December 2, 2019.

JavaScript 
const seriesTimeObject = new Office.SeriesTime();
seriesTimeObject.setStartDate(2019,10,2);
seriesTimeObject.setEndDate(2019,11,2);
seriesTimeObject.setStartTime(10,30);
seriesTimeObject.setDuration(30);

const pattern = {
    seriesTime: seriesTimeObject,
    recurrenceType: Office.MailboxEnums.RecurrenceType.Weekly,
    recurrenceProperties:
    {
        interval: 1,
        days: [Office.MailboxEnums.Days.Tue, Office.MailboxEnums.Days.Thu]
    },
    recurrenceTimeZone: { name: Office.MailboxEnums.RecurrenceTimeZone.PacificStandardTime }
};

Office.context.mailbox.item.recurrence.setAsync(pattern, (asyncResult) => {
    console.log(JSON.stringify(asyncResult));
});

Change recurrence as the organizer

In the following example, the appointment organizer gets the Recurrence object of an appointment series, then sets a new recurrence duration. This is done in compose mode.

JavaScript 
Office.context.mailbox.item.recurrence.getAsync((asyncResult) => {
  const recurrencePattern = asyncResult.value;
  recurrencePattern.seriesTime.setDuration(60);
  Office.context.mailbox.item.recurrence.setAsync(recurrencePattern, (asyncResult) => {
    if (asyncResult.status === Office.AsyncResultStatus.Failed) {
      console.log("Failed to set recurrence.");
      return;
    }

    console.log("Successfully set recurrence.");
  });
});

Get recurrence as the organizer

In the following example, the appointment organizer gets the Recurrence object of an appointment to determine whether it's a recurring series. This is done in compose mode.

JavaScript 
Office.context.mailbox.item.recurrence.getAsync((asyncResult) => {
    const recurrence = asyncResult.value;

    if (recurrence == null) {
        console.log("Non-recurring meeting.");
    } else {
        console.log(JSON.stringify(recurrence));
    }
});

The following example shows the results of the getAsync call that retrieves the recurrence of a series.

Note

In this example, seriesTimeObject is a placeholder for the JSON representing the recurrence.seriesTime property. You should use the SeriesTime methods to get the recurrence date and time properties.

JSON 
{
    "recurrenceType": "weekly",
    "recurrenceProperties": {
        "interval": 1,
        "days": ["tue","thu"],
        "firstDayOfWeek": "sun"},
    "seriesTime": {seriesTimeObject},
    "recurrenceTimeZone": {
        "name": "Pacific Standard Time",
        "offset": -480}}

Get recurrence as an attendee

In the following example, an appointment attendee gets the Recurrence object of an appointment or meeting request.

JavaScript 
outputRecurrence(Office.context.mailbox.item);

function outputRecurrence(item) {
    const recurrence = item.recurrence;

    if (recurrence == null) {
        console.log("Non-recurring meeting.");
    } else {
        console.log(JSON.stringify(recurrence));
    }
}

The following example shows the value of the item.recurrence property of an appointment series.

Note

In this example, seriesTimeObject is a placeholder for the JSON representing the recurrence.seriesTime property. You should use the SeriesTime methods to get the recurrence date and time properties.

JSON 
{
    "recurrenceType": "weekly",
    "recurrenceProperties": {
        "interval": 1,
        "days": ["tue","thu"],
        "firstDayOfWeek": "sun"},
    "seriesTime": {seriesTimeObject},
    "recurrenceTimeZone": {
        "name": "Pacific Standard Time",
        "offset": -480}}

Get the recurrence details

After you've retrieved the recurrence object (either from the getAsync callback or from item.recurrence), you can get specific properties of the recurrence. For example, get the start and end dates and times of the series by using the SeriesTime methods on the recurrence.seriesTime property.

JavaScript 
// Get series date and time info
const seriesTime = recurrence.seriesTime;
const startTime = recurrence.seriesTime.getStartTime();
const endTime = recurrence.seriesTime.getEndTime();
const startDate = recurrence.seriesTime.getStartDate();
const endDate = recurrence.seriesTime.getEndDate();
const duration = recurrence.seriesTime.getDuration();

// Get series time zone
const timeZone = recurrence.recurrenceTimeZone;

// Get recurrence properties
const recurrenceProperties = recurrence.recurrenceProperties;

// Get recurrence type
const recurrenceType = recurrence.recurrenceType;

Run sample snippets in Script Lab

To test how to get and set the recurrence of an appointment with an add-in, install the Script Lab for Outlook add-in and run the following sample snippets.

  • "Get recurrence (Read)"
  • "Get and set recurrence (Appointment Organizer)"

To learn more about Script Lab, see Explore Office JavaScript API using Script Lab.

The recurrence sample snippet in Script Lab.

See also