New-Place

Use the New-Place cmdlet to create buildings, floors, sections, rooms, workspaces, or desks within your Places directory.

Syntax

Building

New-Place
 [-DisplayName]
 [-Type]
 [-Label]
 [-PostalCode]
 [-CountryOrRegion]
 [-State]
 [-City]
 [-Street]
 [-GeoCoordinates]
 [-ResourceLinks]
 [-Tags]

Floor

New-Place
 [-DisplayName]
 [-Type]
 [-Label]
 [-ParentId]
 [-SortOrder]
 [-Tags]

Section

A section is a grouping of spaces within a floor, for example, a neighborhood. Desks and workspaces are required to be parented to a section. Rooms can also optionally be parented to a section or they can be directly parented to a floor.

New-Place
 [-DisplayName]
 [-Type]
 [-Label]
 [-ParentId]

Room

Creating a room automatically provisions an associated mailbox.

New-Place
 [-DisplayName]
 [-Type]
 [-Label]
 [-ParentId]
 [-Capacity]

Workspace

Creating a workspace automatically provisions an associated mailbox.

New-Place
 [-DisplayName]
 [-Type]
 [-Label]
 [-ParentId]
 [-Capacity]

Desk

Desks are a newly introduced entity type in Microsoft Places, representing individual desk units. Each desk includes a Mode property that specifies how the desk can be booked. For more information, refer to the mode section below.

For Desk, There are some dependencies between mode and mailbox as follows:

• If the Mode property isn't defined, the desk defaults to Unavailable, and no desk mailbox is created automatically.
• For desks set to Reservable or DropIn mode, a desk mailbox is required. One is automatically created when the desk is provisioned. Alternatively, you can link an existing mailbox by specifying the EmailAddress in the Mailbox parameter.
• For desks in Assigned or Unavailable mode, linking a mailbox is optional, and no mailbox is created by default. However, you may manually associate these desks with custom mailboxes if needed.
• If no mode is configured initially, the desk remains in Unavailable mode. Linking a mailbox afterward doesn't automatically update the desk’s mode.

Unlike Room or Workspace types, desks aren't automatically provisioned by creating a mailbox. Additionally, metadata such as Capacity or DisplayName isn't synchronized with mailbox properties. The mailbox is used primarily by the reservation engine, while metadata is read from the Places Directory.

New-Place
 [-DisplayName]
 [-Type]
 [-Label]
 [-ParentId]
 [-GeoCoordinates]
 [-Mailbox]
 [-Mode]

Description

Microsoft Places requires a fully established hierarchy across buildings, floors, sections, rooms, workspaces, and desks to function correctly. After creating buildings and floors, you can link them using the parentId property. A floor must be associated with a building, a section must be linked to a floor, a room must be connected to either a floor or a section, and a workspace or desk must be tied to a section.

To run this cmdlet, you must have the appropriate permissions. This includes either the Exchange Admin, Places Administrator or custom roles with Places TenantPlacesManagement permissions.

Examples

Example 1

This example creates a new building and a floor within that building.

New-Place -Type Building -Name 'Building 3'

After Building 3 is created successfully, read its PlaceId to use when setting the ParentId on the floors.

New-Place -Type Floor -Name 'Lobby' -ParentId f12172b6-195d-4e6e-8f4f-eb72e41de99a
New-Place -Type Floor -Name '1' -ParentId f12172b6-195d-4e6e-8f4f-eb72e41de99a

Example 2

This example creates a new building with address information.

New-Place -Name 'Building 3' -Type Building -Description 'Building 3 in North of Redmond Campus' -CountryOrRegion US -State WA -City Redmond -Street 'Street 3' -PostalCode 98052

Example 3

This example creates a new building with resource links.

New-Place -Name 'Building 3' -Type Building -ResourceLinks @{name="TestLink";value="https://contoso.com/";type="Url"}'

Example 4

This example creates a new room parented to a section and with a capacity 10.

New-Place -Name 'Room a' -Type Room -ParentId -ParentId $SectionId -Capacity 10

Example 5

This example creates a section parented to a floor, then creates a desk mailbox and assigns it to an existing desk entity. Before running this sample script, make sure the ExchangeOnlineManagement module is installed and that you've connected to Exchange Online using the Connect-ExchangeOnline cmdlet.

$mbx = New-Mailbox -Room <DeskMailboxName>
Set-Mailbox $mbx.Identity -Type Desk -HiddenFromAddressListsEnabled $true
$section = New-Place -Name 'Section1' -Type Section -ParentId 'someFloorId'
New-Place -Name 'Desk101' -Type Desk -ParentId $section.PlaceId -Mailbox $mbx.EmailAddress

Example 6

This example creates a reservable desk under a section without specifying mailbox details. A desk mailbox is automatically created and linked, and the MailboxOID property is populated. The desk appears in Places Finder and is available for booking by anyone.

$section = New-Place -Name 'Section1' -Type Section -ParentId 'someFloorId'
New-Place -Name 'Reservable Desk101' -Type Desk -ParentId $section.PlaceId -Mode @{Name='Reservable'}

Example 7

This example creates an assigned mode desk parented to a section and assigns it to a person. Only the assigned person can use this desk. Others can no longer reserve it.

$section = New-Place -Name 'Section1' -Type Section -ParentId 'someFloorId'
$modemetadata = New-Object 'System.Collections.Generic.Dictionary[String,object]'
$modemetadata.Add("AssignedPersonEmailAddress","someUserEmailAddress")
New-Place -Name 'Bookable Desk101' -Type Desk -ParentId $section.PlaceId -Mode @{Name='Assigned';Metadata=$modemetadata}

Parameters

-City

The City parameter specifies the building's city. If the value contains spaces, enclose the value in quotation marks ("). The maximum length is 200 characters.

-CountryOrRegion

The CountryOrRegion parameter specifies the building's country or region. A valid value is a valid ISO 3166-1 two-letter country code (for example, AU for Australia) or the corresponding friendly name for the country (which might be different from the official ISO 3166 Maintenance Agency short name).

A reference for two-letter country codes is available at Country Codes List.

Address information is used by the Places Explore page to show nearby buildings.

-Label

The Label parameter specifies a descriptive label for the place. If the value contains spaces, enclose the value in quotation marks ("). The maximum length is 200 characters.

-GeoCoordinates

The GeoCoordinates parameter specifies the building's location in latitude, longitude, and (optionally) altitude coordinates. A valid value for this parameter uses one of the following formats:

• Latitude and longitude: For example, "47.644125;-122.122411"
• Latitude, longitude, and altitude: For example, "47.644125;-122.122411;161.432"

-DisplayName

The DisplayName parameter specifies the display name of the place. The maximum length is 200 characters.

A building's display name is visible:

• In Outlook, when users are setting up their work hours and location, they're able to select a building.
• In Places Explore page that shows who else is in the same building, nearby buildings, and more.
• In Places Finder, as a filter when searching for a conference room or workspace.

A floor's display name is visible in Places Finder as a filter when searching for a conference room or workspace.

-ParentId

The ParentId parameter specifies the ID of a Place in the parent location hierarchy in Microsoft Places.

• A room should have a parent floor or section.
• A workspace or desk should have a parent section.
• A section should have a parent floor.
• A floor should have a parent building.

-PostalCode

The PostalCode parameter specifies the building's postal code. The maximum length is 200 characters.

-ResourceLinks

The ResourceLinks parameter specifies external links or Teams app IDs that should be associated with this building, such as a dining menu, a link to services or a Teams app for visitor management. For more information on how to set up services in Places, see Services in Places.

The value must be provided as an array of links, as shown in Example 4. Each link should contain the following properties: Name, Value, and Type.  For example, a link would be written as @{name="TestLink"; value="https://contoso.com/"; type="Url"}.

• Name
  • This string is used to show how your link or app name is displayed in the Places app.
  • The maximum length is 200 characters.
• Value
  • This value should be either a url link or a Teams app ID. Teams app IDs can be found in the App Details page of the app in the Manage apps page in Teams admin center.
  • The maximum length is 1000 characters.
• Type must be one of the supported types:
  • Url - indicates that this is a url link.
  • MetaOsApp - indicates that this link is a Teams app.

-SortOrder

The SortOrder parameter specifies the sort order of the floor. For example, a floor might be named "Lobby" with a sort order of 0 to show this floor first in ordered lists.

-State

The State parameter specifies the building's state or province. The maximum length is 200 characters.

-Street

The Street parameter specifies the building's physical address. The maximum length is 200 characters.

-Tags

The Tags parameter specifies other features of the room (for example, details like the type of view or furniture type). There's no maximum length currently.

You can specify multiple labels separated by commas. If the labels contains spaces, enclose the values in quotation marks: "Label 1","Label 2",..."Label N".

-Mode

The Mode parameter defines how a place is intended to be used or booked. Currently, mode is only available for desks and desk pools(workspaces).

Currently, there are four modes in total.

• Reservable- Reservable desks are the desks that are configured to be booked in advance or on-the-spot.
• Drop-in- The desk is available for on-the-spot use and can't be reserved in advance. You can use the capability from Microsoft Teams to link the peripheral devices present on these desks to the individual desk object in the directory.
• Assigned - An assigned desk is permanently linked to a specific user and can't be booked by others. Every assigned desk must always have a designated user.
• Unavailable- The desk isn't available for reservation due to maintenance or for any other reason.

The mode value should contain the following properties: Name and Metadata, as shown in Example 6. Name is string and metadata is a dictionary object.

• Name: The Name field specifies the active mode for a place. It uses an enumeration value, and the available options vary by place type. For desks, supported modes include Reservable, DropIn, Assigned and Unavailable. For desk pools, the supported modes are Reservable, DropIn and Unavailable.

• Metadata: The Metadata field is a dictionary used to store additional information relevant to the selected mode. This metadata supports business logic tied to specific booking scenarios.

  • Places in Reservable and DropIn modes don't support any metadata fields.
  • Places in Unavailable mode support a Reason field (string) that explains why the desk is unavailable. Values include New for newly created desks and Maintenance for Places undergoing service.
  • Assigned mode supports two metadata fields: AssignedPersonEmailAddress and AssignedPersonId. These identify the user assigned to the desk. Providing either field is sufficient to enable the assigned mode.

-Type

The Type parameter specifies the type of the place that is being created. Valid values are:

• Building
• Floor
• Section
• Desk