Add Set-PnPMultiGeoCompanyAllowedDataLocation (#5368)

* Add Set-PnPMultiGeoCompanyAllowedDataLocation

Adds the PnP cmdlet and matching multigeo REST client path to start setting up an allowed SharePoint Online data location.


* Address Set-PnPMultiGeo review feedback

Adds output metadata and the changelog PR reference while preserving SPO-compatible REST and confirmation behavior.

Author: gautamdsheth

CHANGELOG.md

@@ -9,6 +9,7 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/).
 ## [Current nightly]
 
 ### Added
+- Added `Set-PnPMultiGeoCompanyAllowedDataLocation` cmdlet to start setting up a SharePoint Online multi-geo allowed data location. [#5368](https://github.com/pnp/powershell/pull/5368)
 - Added `Get-PnPSiteContentMoveState` cmdlet to retrieve SharePoint Online site content move states. [#5365](https://github.com/pnp/powershell/pull/5365)
 - Added `Stop-PnPSiteContentMove` cmdlet to stop SharePoint Online multi-geo site content move jobs. [#5366](https://github.com/pnp/powershell/pull/5366)
 - Added `Get-PnPUnifiedGroupMoveState` cmdlet to retrieve SharePoint Online Microsoft 365 group move states. [#5362](https://github.com/pnp/powershell/pull/5362)

documentation/Get-PnPMultiGeoCompanyAllowedDataLocation.md

@@ -54,4 +54,6 @@ Returns objects with `Location`, `Domain`, and `IsDefault` properties.
 
 ## RELATED LINKS
 
+[Set-PnPMultiGeoCompanyAllowedDataLocation](Set-PnPMultiGeoCompanyAllowedDataLocation.md)
+
 [Microsoft 365 Patterns and Practices](https://aka.ms/m365pnp)

documentation/Set-PnPMultiGeoCompanyAllowedDataLocation.md

@@ -0,0 +1,115 @@
+---
+Module Name: PnP.PowerShell
+title: Set-PnPMultiGeoCompanyAllowedDataLocation
+schema: 2.0.0
+applicable: SharePoint Online
+external help file: PnP.PowerShell.dll-Help.xml
+online version: https://pnp.github.io/powershell/cmdlets/Set-PnPMultiGeoCompanyAllowedDataLocation.html
+---
+ 
+# Set-PnPMultiGeoCompanyAllowedDataLocation
+
+## SYNOPSIS
+Starts setting up a multi-geo data location for the SharePoint Online tenant.
+
+## SYNTAX
+
+```powershell
+Set-PnPMultiGeoCompanyAllowedDataLocation [-Location] <String> [-InitialDomain] <String> [-Connection <PnPConnection>] [-WhatIf] [-Confirm]
+```
+
+## DESCRIPTION
+Starts setting up an allowed SharePoint Online multi-geo data location for the tenant.
+
+## EXAMPLES
+
+### EXAMPLE 1
+
+```powershell
+Set-PnPMultiGeoCompanyAllowedDataLocation -Location EUR -InitialDomain contoso.onmicrosoft.com
+```
+
+Starts setting up the EUR multi-geo data location for the tenant with the initial domain `contoso.onmicrosoft.com`.
+
+## PARAMETERS
+
+### -Confirm
+Prompts you for confirmation before running the cmdlet.
+
+```yaml
+Type: SwitchParameter
+Parameter Sets: (All)
+
+Required: False
+Position: Named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+### -Connection
+Optional connection to be used by the cmdlet. Retrieve the value for this parameter by specifying `-ReturnConnection` on `Connect-PnPOnline` or by executing `Get-PnPConnection`.
+
+```yaml
+Type: PnPConnection
+Parameter Sets: (All)
+
+Required: False
+Position: Named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+### -InitialDomain
+Specifies the initial SharePoint Online domain for the data location.
+
+```yaml
+Type: String
+Parameter Sets: (All)
+
+Required: True
+Position: 1
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+### -Location
+Specifies the multi-geo location code to set up.
+
+```yaml
+Type: String
+Parameter Sets: (All)
+
+Required: True
+Position: 0
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+### -WhatIf
+Shows what would happen if the cmdlet runs. The cmdlet is not run.
+
+```yaml
+Type: SwitchParameter
+Parameter Sets: (All)
+
+Required: False
+Position: Named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+## OUTPUTS
+
+### System.String
+Returns a message indicating that setting up the new location has started.
+
+## RELATED LINKS
+
+[Get-PnPMultiGeoCompanyAllowedDataLocation](Get-PnPMultiGeoCompanyAllowedDataLocation.md)
+
+[Microsoft 365 Patterns and Practices](https://aka.ms/m365pnp)

src/Commands/Admin/SetMultiGeoCompanyAllowedDataLocation.cs

@@ -0,0 +1,50 @@
+using PnP.PowerShell.Commands.Attributes;
+using PnP.PowerShell.Commands.Base;
+using PnP.PowerShell.Commands.Model;
+using PnP.PowerShell.Commands.Properties;
+using PnP.PowerShell.Commands.Utilities.MultiGeo;
+using System.Globalization;
+using System.Management.Automation;
+
+namespace PnP.PowerShell.Commands.Admin
+{
+	[Cmdlet(VerbsCommon.Set, "PnPMultiGeoCompanyAllowedDataLocation", SupportsShouldProcess = true, ConfirmImpact = ConfirmImpact.High)]
+	[RequiredApiApplicationPermissions("sharepoint/Sites.FullControl.All")]
+	[RequiredApiDelegatedPermissions("sharepoint/AllSites.FullControl")]
+	[OutputType(typeof(string))]
+	public class SetMultiGeoCompanyAllowedDataLocation : PnPSharePointOnlineAdminCmdlet
+	{
+		private const string SharePointAppId = "00000003-0000-0ff1-ce00-000000000000";
+
+		[Parameter(Mandatory = true, Position = 0)]
+		[ValidateNotNullOrEmpty]
+		public string Location { get; set; }
+
+		[Parameter(Mandatory = true, Position = 1)]
+		[ValidateNotNullOrEmpty]
+		public string InitialDomain { get; set; }
+
+		protected override void ExecuteCmdlet()
+		{
+			var tenantName = InitialDomain.Split('.')[0];
+			var mySiteHostUrl = string.Format(CultureInfo.InvariantCulture, "https://{0}-my.sharepoint.com", tenantName);
+			var sharePointHostUrl = string.Format(CultureInfo.InvariantCulture, "https://{0}.sharepoint.com", tenantName);
+			var warningMessage = string.Format(CultureInfo.InvariantCulture, Resources.CrossGeoWarningAddAdlMessage, mySiteHostUrl, sharePointHostUrl);
+
+			if (!ShouldProcess(warningMessage, warningMessage, Resources.CrossGeoWarningAddAdlMessageQuery))
+			{
+				return;
+			}
+
+			var multiGeoRestApiClient = new MultiGeoRestApiClient(AdminContext);
+			multiGeoRestApiClient.AddAllowedDataLocation(new MultiGeoCompanyAllowedDataLocationEntityData
+			{
+				AppId = SharePointAppId,
+				Domain = InitialDomain,
+				Location = Location
+			});
+
+			WriteObject(Resources.CrossGeoWarningAddAdlSuccessMessage);
+		}
+	}
+}

src/Commands/Model/MultiGeoCompanyAllowedDataLocationEntityData.cs

@@ -0,0 +1,28 @@
+using System.Text.Json.Serialization;
+
+namespace PnP.PowerShell.Commands.Model
+{
+	/// <summary>
+	/// Contains the payload used to add an allowed multi-geo data location.
+	/// </summary>
+	internal class MultiGeoCompanyAllowedDataLocationEntityData
+	{
+		/// <summary>
+		/// The application identifier used by SharePoint Online for the allowed data location.
+		/// </summary>
+		[JsonPropertyName("appId")]
+		public string AppId { get; set; }
+
+		/// <summary>
+		/// The initial SharePoint Online domain for the geo location.
+		/// </summary>
+		[JsonPropertyName("domain")]
+		public string Domain { get; set; }
+
+		/// <summary>
+		/// The geo location code, such as NAM or EUR.
+		/// </summary>
+		[JsonPropertyName("location")]
+		public string Location { get; set; }
+	}
+}

src/Commands/Properties/Resources.Designer.cs

@@ -126,6 +126,18 @@
   <data name="Confirm" xml:space="preserve">
     <value>Confirm</value>
   </data>
+  <data name="CrossGeoInvalidVersion" xml:space="preserve">
+    <value>The client version '{0}' is not supported. Please try to upgrade client version first.</value>
+  </data>
+  <data name="CrossGeoWarningAddAdlMessage" xml:space="preserve">
+    <value>The new location will use the following addresses for OneDrive and SharePoint sites:&#xD;&#xA;&#xD;&#xA;{0}&#xD;&#xA;{1}&#xD;&#xA;&#xD;&#xA;</value>
+  </data>
+  <data name="CrossGeoWarningAddAdlMessageQuery" xml:space="preserve">
+    <value>Do you want to set up this location?</value>
+  </data>
+  <data name="CrossGeoWarningAddAdlSuccessMessage" xml:space="preserve">
+    <value>Successfully started setting up the new location. You will receive a notification when the process completes. You can check status using the following command: Get-SPOMultiGeoCompanyAllowedDataLocation.</value>
+  </data>
   <data name="CurrentSiteIsNoTenantAdminSite" xml:space="preserve">
     <value>Current site is not a tenant administration site</value>
   </data>

src/Commands/Properties/Resources.resx

@@ -13,6 +13,7 @@
 using System.Text.Json;
 using System.Threading;
 using System.Threading.Tasks;
+using CommandResources = PnP.PowerShell.Commands.Properties.Resources;
 
 namespace PnP.PowerShell.Commands.Utilities.MultiGeo
 {
@@ -147,6 +148,22 @@ internal IEnumerable<MultiGeoCompanyAllowedDataLocation> GetAllowedDataLocations
 			return GetFeed<MultiGeoCompanyAllowedDataLocation>(AllowedDataLocationsPath, AllowedDataLocationsApiVersion);
 		}
 
+		internal void AddAllowedDataLocation(MultiGeoCompanyAllowedDataLocationEntityData allowedDataLocation)
+		{
+			if (allowedDataLocation == null)
+			{
+				throw new ArgumentNullException(nameof(allowedDataLocation));
+			}
+
+			var apiVersion = GetCurrentApiVersion();
+			if (!IsSupportedApiVersion(apiVersion, AllowedDataLocationsApiVersion))
+			{
+				throw new NotSupportedException(string.Format(CultureInfo.InvariantCulture, CommandResources.CrossGeoInvalidVersion, typeof(MultiGeoRestApiClient).Assembly.GetName().Version));
+			}
+
+			PostWithoutResponse(AllowedDataLocationsPath, allowedDataLocation, apiVersion);
+		}
+
 		internal UserAndContentMoveState GetUserAndContentMoveState(string userPrincipalName)
 		{
 			var apiVersion = GetCurrentApiVersion(UserMoveJobsMinimumApiVersion);
@@ -311,6 +328,12 @@ private T Post<T>(string path, object payload, TimeSpan? timeout = null, string
 			return DeserializeResponse<T>(responseText);
 		}
 
+		private void PostWithoutResponse(string path, object payload, string apiVersion)
+		{
+			var jsonPayload = payload == null ? null : JsonSerializer.Serialize(payload, SerializerOptions);
+			Send(() => CreateRequest(HttpMethod.Post, path, apiVersion, jsonPayload), timeout: null, allowRetries: false);
+		}
+
 		private void PostWithEmptyBody(string path, string apiVersion)
 		{
 			Send(() => CreateRequest(HttpMethod.Post, path, apiVersion, string.Empty), timeout: null, allowRetries: false);