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.
setAsync(recurrencePattern, callback)	Sets the recurrence pattern of an appointment series.

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

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.

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

Important:

setAsync is only available for series items and not instance items.
The setAsync method isn't supported on a message that's currently loaded using the loadItemByIdAsync method. For more information, see Activate your Outlook add-in on multiple messages.

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.

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

Important:

setAsync is only available for series items and not instance items.
The setAsync method isn't supported on a message that's currently loaded using the loadItemByIdAsync method. For more information, see Activate your Outlook add-in on multiple messages.

Errors:

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

Share via

Office.Recurrence interface

Remarks

Properties

Methods

Property Details

recurrenceProperties

Property Value

Remarks

recurrenceTimeZone

Property Value

Remarks

recurrenceType

Property Value

Remarks

seriesTime

Property Value

Remarks

Method Details

getAsync(options, callback)

Parameters

Returns

Remarks

Examples

getAsync(callback)

Parameters

Returns

Remarks

setAsync(recurrencePattern, options, callback)

Parameters

Returns

Remarks

Examples

setAsync(recurrencePattern, callback)

Parameters

Returns

Remarks

Additional resources