Edit

Share via

Office.Recurrence interface

  • Reference
Package:
outlook

The Recurrence object provides methods to get and set the recurrence pattern of appointments but only get the recurrence pattern of meeting requests. It will have a dictionary with the following keys: seriesTime, recurrenceType, recurrenceProperties, and recurrenceTimeZone (optional).

Remarks

[ API set: Mailbox 1.7 ]

Minimum permission level: read item

Applicable Outlook mode: Compose or Read

States

State Editable? Viewable?
Appointment Organizer - Compose Series Yes (setAsync) Yes (getAsync)
Appointment Organizer - Compose Instance No (setAsync returns 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)

Properties

recurrenceProperties

Gets or sets the properties of the recurring appointment series.
recurrenceTimeZone

Gets or sets the properties of the recurring appointment series.
recurrenceType

Gets or sets the type of the recurring appointment series.
seriesTime

The SeriesTime object enables you to manage the start and end dates of the recurring appointment series and the usual start and end times of instances. This object is not in UTC time. Instead, it is set in the time zone specified by the recurrenceTimeZone value or defaulted to the item's time zone.

Methods

getAsync(options, callback)

Returns the current recurrence object of an appointment series.

This method returns the entire Recurrence object for the appointment series.
getAsync(callback)

Returns the current recurrence object of an appointment series.

This method returns the entire Recurrence object for the appointment series.
setAsync(recurrencePattern, options, callback)

Sets the recurrence pattern of an appointment series.

Note: setAsync should only be available for series items and not instance items.
setAsync(recurrencePattern, callback)

Sets the recurrence pattern of an appointment series.

Note: setAsync should only be available for series items and not instance items.

Property Details

recurrenceProperties

Gets or sets the properties of the recurring appointment series.

recurrenceProperties?: RecurrenceProperties;

Property Value

Office.RecurrenceProperties

Remarks

[ API set: Mailbox 1.7 ]

Minimum permission level: read item

Applicable Outlook mode: Compose or Read

recurrenceTimeZone

Gets or sets the properties of the recurring appointment series.

recurrenceTimeZone?: RecurrenceTimeZone;

Property Value

Office.RecurrenceTimeZone

Remarks

[ API set: Mailbox 1.7 ]

Minimum permission level: read item

Applicable Outlook mode: Compose or Read

recurrenceType

Gets or sets the type of the recurring appointment series.

recurrenceType: MailboxEnums.RecurrenceType | string;

Property Value

Office.MailboxEnums.RecurrenceType | string

Remarks

[ API set: Mailbox 1.7 ]

Minimum permission level: read item

Applicable Outlook mode: Compose or Read

seriesTime

The SeriesTime object enables you to manage the start and end dates of the recurring appointment series and the usual start and end times of instances. This object is not in UTC time. Instead, it is set in the time zone specified by the recurrenceTimeZone value or defaulted to the item's time zone.

seriesTime: SeriesTime;

Property Value

Office.SeriesTime

Remarks

[ API set: Mailbox 1.7 ]

Minimum permission level: read item

Applicable Outlook mode: Compose or Read

Method Details

getAsync(options, callback)

Returns the current recurrence object of an appointment series.

This method returns the entire Recurrence object for the appointment series.

getAsync(options: Office.AsyncContextOptions, callback?: (asyncResult: Office.AsyncResult<Recurrence>) => void): void;

Parameters

options
Office.AsyncContextOptions

An object literal that contains one or more of the following properties:- asyncContext: Developers can provide any object they wish to access in the callback function.

callback

(asyncResult: Office.AsyncResult<Office.Recurrence>) => void

Optional. When the method completes, the function passed in the callback parameter is called with a single parameter, asyncResult, which is an Office.AsyncResult object. The value property of the result is a Recurrence object.

Returns

void

Remarks

[ API set: Mailbox 1.7 ]

Minimum permission level: read item

Applicable Outlook mode: Compose or Read

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/50-recurrence/get-set-recurrence-appointment-organizer.yaml

Office.context.mailbox.item.recurrence.getAsync(function(asyncResult) {
  if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
    const recurrence = asyncResult.value;
    if (recurrence === null) {
      console.log("This is a single appointment.");
    } else {
      console.log(`Recurrence pattern: ${JSON.stringify(recurrence)}`);
    }
  } else {
    console.error(asyncResult.error);
  }
});

getAsync(callback)

Returns the current recurrence object of an appointment series.

This method returns the entire Recurrence object for the appointment series.

getAsync(callback?: (asyncResult: Office.AsyncResult<Recurrence>) => void): void;

Parameters

callback

(asyncResult: Office.AsyncResult<Office.Recurrence>) => void

Optional. When the method completes, the function passed in the callback parameter is called with a single parameter, asyncResult, which is an Office.AsyncResult object. The value property of the result is a Recurrence object.

Returns

void

Remarks

[ API set: Mailbox 1.7 ]

Minimum permission level: read item

Applicable Outlook mode: Compose or Read

setAsync(recurrencePattern, options, callback)

Sets the recurrence pattern of an appointment series.

Note: setAsync should only be available for series items and not instance items.

setAsync(recurrencePattern: Recurrence, options: Office.AsyncContextOptions, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;

Parameters

recurrencePattern
Office.Recurrence

A recurrence object.

options
Office.AsyncContextOptions

An object literal that contains one or more of the following properties:- asyncContext: Developers can provide any object they wish to access in the callback function.

callback

(asyncResult: Office.AsyncResult<void>) => void

Optional. When the method completes, the function passed in the callback parameter is called with a single parameter, asyncResult, which is an Office.AsyncResult object.

Returns

void

Remarks

[ API set: Mailbox 1.7 ]

Minimum permission level: read/write item

Applicable Outlook mode: Compose

Errors:

  • InvalidEndTime: The appointment end time is before its start time.

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/50-recurrence/get-set-recurrence-appointment-organizer.yaml

// Important: Can only set the recurrence pattern of an appointment series.

const currentDate = new Date();
let seriesTimeObject: Office.SeriesTime;
// Set series start date to tomorrow.
seriesTimeObject.setStartDate(currentDate.getFullYear(), currentDate.getMonth(), currentDate.getDay() + 1);
// Set series end date to one year from now.
seriesTimeObject.setEndDate(currentDate.getFullYear() + 1, currentDate.getMonth() + 1, currentDate.getDay());
// Set start time to 1:30 PM.
seriesTimeObject.setStartTime(13, 30);
// Set duration to 30 minutes.
seriesTimeObject.setDuration(30);

const pattern: Office.Recurrence = {
  seriesTime: seriesTimeObject,
  recurrenceType: Office.MailboxEnums.RecurrenceType.Yearly,
  recurrenceProperties: {
    interval: 1,
    dayOfWeek: Office.MailboxEnums.Days.Tue,
    weekNumber: Office.MailboxEnums.WeekNumber.Second,
    month: Office.MailboxEnums.Month.Sep
  },
  recurrenceTimeZone: { name: Office.MailboxEnums.RecurrenceTimeZone.PacificStandardTime }
};

Office.context.mailbox.item.recurrence.setAsync(pattern, (asyncResult) => {
  if (asyncResult.status !== Office.AsyncResultStatus.Succeeded) {
    console.error(`Failed to set recurrence. Error: ${asyncResult.error.message}`);
    return;
  }
  console.log(`Succeeded in setting recurrence pattern ${JSON.stringify(pattern)}`);
});

setAsync(recurrencePattern, callback)

Sets the recurrence pattern of an appointment series.

Note: setAsync should only be available for series items and not instance items.

setAsync(recurrencePattern: Recurrence, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;

Parameters

recurrencePattern
Office.Recurrence

A recurrence object.

callback

(asyncResult: Office.AsyncResult<void>) => void

Optional. When the method completes, the function passed in the callback parameter is called with a single parameter, asyncResult, which is an Office.AsyncResult object.

Returns

void

Remarks

[ API set: Mailbox 1.7 ]

Minimum permission level: read/write item

Applicable Outlook mode: Compose

Errors:

  • InvalidEndTime: The appointment end time is before its start time.