Edit

Share via

Office.EnhancedLocation interface

Package:
outlook

Represents the set of locations on an appointment.

Remarks

[ API set: Mailbox 1.8 ]

Minimum permission level: read item

Applicable Outlook mode: Compose or Read

Important: To manage the locations of an appointment in Outlook clients that don't support Mailbox requirement set 1.8, use the Office.Location API instead. For guidance on selecting the right location API for your scenario, see Get or set the location when composing an appointmnt in Outlook.

Methods

addAsync(locationIdentifiers, options, callback)

Adds to the set of locations associated with the appointment.
addAsync(locationIdentifiers, callback)

Adds to the set of locations associated with the appointment.
getAsync(options, callback)

Gets the set of locations associated with the appointment.
getAsync(callback)

Gets the set of locations associated with the appointment.
removeAsync(locationIdentifiers, options, callback)

Removes the set of locations associated with the appointment.

If there are multiple locations with the same name, all matching locations will be removed even if only one was specified in locationIdentifiers.
removeAsync(locationIdentifiers, callback)

Removes the set of locations associated with the appointment.

If there are multiple locations with the same name, all matching locations will be removed even if only one was specified in locationIdentifiers.

Method Details

addAsync(locationIdentifiers, options, callback)

Adds to the set of locations associated with the appointment.

addAsync(locationIdentifiers: LocationIdentifier[], options: Office.AsyncContextOptions, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;

Parameters

locationIdentifiers

Office.LocationIdentifier[]

The locations to be added to the current list of locations.

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. Check the status property of asyncResult to determine if the call succeeded.

Returns

void

Remarks

[ API set: Mailbox 1.8 ]

Minimum permission level: read/write item

Applicable Outlook mode: Compose

Errors:

  • InvalidFormatError: The format of the specified data object is not valid.

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/90-other-item-apis/get-add-remove-enhancedlocation-appointment.yaml

const locations = [
  {
    id: "Contoso",
    type: Office.MailboxEnums.LocationType.Custom
  },
  {
    id: "room500@test.com",
    type: Office.MailboxEnums.LocationType.Room
  }
];
Office.context.mailbox.item.enhancedLocation.addAsync(locations, (result) => {
  if (result.status === Office.AsyncResultStatus.Succeeded) {
    console.log(`Successfully added locations ${JSON.stringify(locations)}`);
  } else {
    console.error(`Failed to add locations. Error message: ${result.error.message}`);
  }
});

addAsync(locationIdentifiers, callback)

Adds to the set of locations associated with the appointment.

addAsync(locationIdentifiers: LocationIdentifier[], callback?: (asyncResult: Office.AsyncResult<void>) => void): void;

Parameters

locationIdentifiers

Office.LocationIdentifier[]

The locations to be added to the current list of locations.

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. Check the status property of asyncResult to determine if the call succeeded.

Returns

void

Remarks

[ API set: Mailbox 1.8 ]

Minimum permission level: read/write item

Applicable Outlook mode: Compose

Errors:

  • InvalidFormatError: The format of the specified data object is not valid.

getAsync(options, callback)

Gets the set of locations associated with the appointment.

getAsync(options: Office.AsyncContextOptions, callback?: (asyncResult: Office.AsyncResult<LocationDetails[]>) => 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.LocationDetails[]>) => 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. An array of Office.LocationDetails objects representing the locations of the appointment is returned in the asyncResult.value property.

Returns

void

Remarks

[ API set: Mailbox 1.8 ]

Minimum permission level: read item

Applicable Outlook mode: Compose or Read

Important:

  • The getAsync method doesn't return personal contact groups that were added to the Location field of an appointment.

  • If a location was added using Office.context.mailbox.item.location.setAsync, its location type is Office.MailboxEnums.LocationType.Custom.

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/90-other-item-apis/get-add-remove-enhancedlocation-appointment.yaml

Office.context.mailbox.item.enhancedLocation.getAsync((result) => {
  if (result.status !== Office.AsyncResultStatus.Succeeded) {
    console.error(`Failed to get locations. Error message: ${result.error.message}`);
    return;
  }
  const places = result.value;
  if (places && places.length > 0) {
    result.value.forEach(function(place) {
      console.log(`Location: ${place.displayName} (type: ${place.locationIdentifier.type})`);
      if (place.locationIdentifier.type === Office.MailboxEnums.LocationType.Room) {
        console.log("Email address: " + place.emailAddress);
      }
    });
  } else {
    console.log("There are no locations.");
  }
});

getAsync(callback)

Gets the set of locations associated with the appointment.

getAsync(callback?: (asyncResult: Office.AsyncResult<LocationDetails[]>) => void): void;

Parameters

callback

(asyncResult: Office.AsyncResult<Office.LocationDetails[]>) => 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. An array of Office.LocationDetails objects representing the locations of the appointment is returned in the asyncResult.value property.

Returns

void

Remarks

[ API set: Mailbox 1.8 ]

Minimum permission level: read item

Applicable Outlook mode: Compose or Read

Important:

  • The getAsync method doesn't return personal contact groups that were added to the Location field of an appointment.

  • If a location was added using Office.context.mailbox.item.location.setAsync, its location type is Office.MailboxEnums.LocationType.Custom.

removeAsync(locationIdentifiers, options, callback)

Removes the set of locations associated with the appointment.

If there are multiple locations with the same name, all matching locations will be removed even if only one was specified in locationIdentifiers.

removeAsync(locationIdentifiers: LocationIdentifier[], options: Office.AsyncContextOptions, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;

Parameters

locationIdentifiers

Office.LocationIdentifier[]

The locations to be removed from the current list of locations.

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. Check the status property of asyncResult to determine if the call succeeded.

Returns

void

Remarks

[ API set: Mailbox 1.8 ]

Minimum permission level: read/write item

Applicable Outlook mode: Compose

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/90-other-item-apis/get-add-remove-enhancedlocation-appointment.yaml

const locations = [
  {
    id: "Contoso",
    type: Office.MailboxEnums.LocationType.Custom
  },
  {
    id: "room500@test.com",
    type: Office.MailboxEnums.LocationType.Room
  }
];
Office.context.mailbox.item.enhancedLocation.removeAsync(locations, (result) => {
  if (result.status === Office.AsyncResultStatus.Succeeded) {
    console.log(`Successfully removed locations ${JSON.stringify(locations)}`);
  } else {
    console.error(`Failed to remove locations. Error message: ${result.error.message}`);
  }
});

removeAsync(locationIdentifiers, callback)

Removes the set of locations associated with the appointment.

If there are multiple locations with the same name, all matching locations will be removed even if only one was specified in locationIdentifiers.

removeAsync(locationIdentifiers: LocationIdentifier[], callback?: (asyncResult: Office.AsyncResult<void>) => void): void;

Parameters

locationIdentifiers

Office.LocationIdentifier[]

The locations to be removed from the current list of locations.

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. Check the status property of asyncResult to determine if the call succeeded.

Returns

void

Remarks

[ API set: Mailbox 1.8 ]

Minimum permission level: read/write item

Applicable Outlook mode: Compose