Office.Recurrence interface

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).

[ API set: Mailbox 1.7 ]

Remarks

Minimum permission levelReadItem
Applicable Outlook modeCompose 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.

[ API set: Mailbox 1.7 ]

recurrenceTimeZone

Gets or sets the properties of the recurring appointment series.

[ API set: Mailbox 1.7 ]

recurrenceType

Gets or sets the type of the recurring appointment series.

[ API set: Mailbox 1.7 ]

seriesTime

The Office.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.

[ API set: Mailbox 1.7 ]

Methods

getAsync(options, callback)

Returns the current recurrence object of an appointment series.

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

[ API set: Mailbox 1.7 ]

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.

[ API set: Mailbox 1.7 ]

Property Details

recurrenceProperties

Gets or sets the properties of the recurring appointment series.

[ API set: Mailbox 1.7 ]

recurrenceProperties: Office.RecurrenceProperties;

Property Value

Remarks

Minimum permission levelReadItem
Applicable Outlook modeCompose or read

recurrenceTimeZone

Gets or sets the properties of the recurring appointment series.

[ API set: Mailbox 1.7 ]

recurrenceTimeZone: Office.RecurrenceTimeZone;

Property Value

Office.RecurrenceTimeZone

Remarks

Minimum permission levelReadItem
Applicable Outlook modeCompose or read

recurrenceType

Gets or sets the type of the recurring appointment series.

[ API set: Mailbox 1.7 ]

recurrenceType: Office.MailboxEnums.RecurrenceType;

Property Value

Remarks

Minimum permission levelReadItem
Applicable Outlook modeCompose or read

seriesTime

The Office.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.

[ API set: Mailbox 1.7 ]

seriesTime: Office.SeriesTime;

Property Value

Remarks

Minimum permission levelReadItem
Applicable Outlook modeCompose 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.

[ API set: Mailbox 1.7 ]

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

Parameters

options
Office.AsyncContextOptions

Optional. 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 method.

callback
(result: 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

Minimum permission levelReadItem
Applicable Outlook modeCompose or read

In addition to this signature, this method also has the following signature:

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

Examples

// This example gets the recurrence object of an appointment or meeting request item.
Office.context.mailbox.item.recurrence.getAsync(callback);
function callback(asyncResult){
    var context = asyncResult.context;
    var recurrence = asyncResult.value;
    if (recurrence == null) {
        console.log("Non-recurring meeting");
        return;
    }

    console.log(JSON.stringify(recurrence));
}

// The following example shows the results of the getAsync call that retrieves the recurrence for a series.
// NOTE: In this example, seriesTimeObject is a placeholder for the JSON representing the 
// recurrence.seriesTime property. You should use the SeriesTime object's methods to get the 
// recurrence date and time properties.
Recurrence = {
    "recurrenceType": "weekly",
    "recurrenceProperties": {"interval": 2, "days": ["mon","thu","fri"], "firstDayOfWeek": "sun"},
    "seriesTime": {seriesTimeObject}, 
    "recurrenceTimeZone": {"name": "Pacific Standard Time", "offset": -480}}

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.

[ API set: Mailbox 1.7 ]

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

Parameters

recurrencePattern
Recurrence

A recurrence object.

options
Office.AsyncContextOptions

Optional. 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 method.

callback
(result: 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

Minimum permission levelReadWriteItem
Applicable Outlook modeCompose
ErrorsInvalidEndTime - The appointment end time is before its start time.

In addition to this signature, this method also has the following signature:

setAsync(recurrencePattern: Recurrence, callback?: (result: AsyncResult<void>) => void): void;

Examples

// The following example sets the recurrence pattern of an appointment series.
var seriesTimeObject = new Office.SeriesTime(); 
seriesTimeObject.setStartDate(2019,10,2);  
seriesTimeObject.setEndDate(2019,11,2); 
seriesTimeObject.setStartTime(10,30); 
seriesTimeObject.setDuration(30);

var pattern = {
    "seriesTime": seriesTimeObject,
    "recurrenceType": "weekly",
    "recurrenceProperties": {"interval": 1, "days": ["tue", "thu"], "firstDayOfWeek": "sun"},
    "recurrenceTimeZone": {"name": "Pacific Standard Time"}};

Office.context.mailbox.item.recurrence.setAsync(pattern, callback);

function callback(asyncResult)
{
    console.log(JSON.stringify(asyncResult)); 
}

//Result: This created a recurring event from November 2, 2019 to December 2, 2019
//        at 10:30 A.M. to 11 A.M. PST every Tuesday and Thursday.