Swap Old Sites for New With the Invoke-SPOSiteSwap PowerShell Cmdlet
Office 365 Notification MC187289
Office 365 Notification MC187289 posted on August 5 told us that Microsoft has started the roll-out of the SharePoint “site swap” feature described in Office 365 roadmap item 51259. The original plan for the roll-out called for a measured deployment (some would say “slow”) across different categories of tenants and is due to complete in October 2019. On September 6, Microsoft issued notification MC189866 with news that they had started to deploy to to Office 365 tenants with less than 10,000 tenants. Larger tenants will still have to wait for a further update. Fortunately, my tenant was updated in the first part of the deployment and I could swap sites to my heart’s content.
The new feature uses the Invoke-SPOSiteSwap PowerShell cmdlet (part of the SharePoint Online PowerShell module from version 16.0.8812.1200 on). The latest version is 16.0.9119.1200, but I used the cmdlet with version 16.0.9021.1201. The cmdlet swaps an entire site collection.
Old SharePoint Site
I’ve been using SharePoint Online since 2011 and my root site was a very old page (Figure 1) that I put together years ago when sites could still be accessed by external users. I haven’t paid any attention to the page for a long time.
Figure 1: Old SharePoint root site
To replace the root page, I created a new SharePoint communications site and made some minor changes to it. I then ran the Invoke-SPOSiteSwap cmdlet to swap the new communications site to become the root site using this command:
# Swap a SharePoint site
Invoke-SPOSiteSwap -SourceURL https://office365itpros.sharepoint.com/sites/NewMarketingComms -TargetURL https://office365itpros.sharepoint.com -ArchiveURL https://office365itpros.sharepoint.com/sites/OldMarketingComms
Figure 2: The new root page after Invoke-SPOSiteSwap does its magic
Audit Records
Office 365 captures audit records when you run Invoke-SPOSiteSwap to start the background job (SiteSwapScheduled) and when the job completes (SiteSwapped). These records are visible through the Audit log search in the Security and Compliance Center. They can also be found with the Search-UnifiedAuditLog cmdlet using a command like:
# Find records for SharePoint site swaps
Search-UnifiedAuditLog -Operations SiteSwapped, SiteSwapScheduled -StartDate 7-Aug-2019 -EndDate 8-Aug-2019
Some Restrictions
Some restrictions exist. The source or target sites can’t be associated with an Office 365 Group (team) or a hub site. The target site can only be the root site or the search center. There’s several other notes to read up on in the documentation. Basically, this is a focused cmdlet that does what it says: Invokes a job to swap the location of a site with another site while archiving the original site.
Read more about managing SharePoint Online in the Office 365 for IT Pros eBook, including many other PowerShell examples.
This has to involve a simple dns change by Msft, rerouting the tenant sub-domain to the modern site and a new subdomain to the old site. But as usual, Msft’s terminology is vague – is it SITE COLLECTION swap or SITE swap? What happens to the many subsites under the root site I need to retain at their existing urls?
{"id":null,"mode":"button","open_style":"in_modal","currency_code":"EUR","currency_symbol":"\u20ac","currency_type":"decimal","blank_flag_url":"https:\/\/office365itpros.com\/wp-content\/plugins\/tip-jar-wp\/\/assets\/images\/flags\/blank.gif","flag_sprite_url":"https:\/\/office365itpros.com\/wp-content\/plugins\/tip-jar-wp\/\/assets\/images\/flags\/flags.png","default_amount":100,"top_media_type":"featured_image","featured_image_url":"https:\/\/office365itpros.com\/wp-content\/uploads\/2022\/11\/cover-141x200.jpg","featured_embed":"","header_media":null,"file_download_attachment_data":null,"recurring_options_enabled":true,"recurring_options":{"never":{"selected":true,"after_output":"One time only"},"weekly":{"selected":false,"after_output":"Every week"},"monthly":{"selected":false,"after_output":"Every month"},"yearly":{"selected":false,"after_output":"Every year"}},"strings":{"current_user_email":"","current_user_name":"","link_text":"Virtual Tip Jar","complete_payment_button_error_text":"Check info and try again","payment_verb":"Pay","payment_request_label":"Office 365 for IT Pros","form_has_an_error":"Please check and fix the errors above","general_server_error":"Something isn't working right at the moment. Please try again.","form_title":"Office 365 for IT Pros","form_subtitle":null,"currency_search_text":"Country or Currency here","other_payment_option":"Other payment option","manage_payments_button_text":"Manage your payments","thank_you_message":"Thank you for supporting the work of Office 365 for IT Pros!","payment_confirmation_title":"Office 365 for IT Pros","receipt_title":"Your Receipt","print_receipt":"Print Receipt","email_receipt":"Email Receipt","email_receipt_sending":"Sending receipt...","email_receipt_success":"Email receipt successfully sent","email_receipt_failed":"Email receipt failed to send. Please try again.","receipt_payee":"Paid to","receipt_statement_descriptor":"This will show up on your statement as","receipt_date":"Date","receipt_transaction_id":"Transaction ID","receipt_transaction_amount":"Amount","refund_payer":"Refund from","login":"Log in to manage your payments","manage_payments":"Manage Payments","transactions_title":"Your Transactions","transaction_title":"Transaction Receipt","transaction_period":"Plan Period","arrangements_title":"Your Plans","arrangement_title":"Manage Plan","arrangement_details":"Plan Details","arrangement_id_title":"Plan ID","arrangement_payment_method_title":"Payment Method","arrangement_amount_title":"Plan Amount","arrangement_renewal_title":"Next renewal date","arrangement_action_cancel":"Cancel Plan","arrangement_action_cant_cancel":"Cancelling is currently not available.","arrangement_action_cancel_double":"Are you sure you'd like to cancel?","arrangement_cancelling":"Cancelling Plan...","arrangement_cancelled":"Plan Cancelled","arrangement_failed_to_cancel":"Failed to cancel plan","back_to_plans":"\u2190 Back to Plans","update_payment_method_verb":"Update","sca_auth_description":"Your have a pending renewal payment which requires authorization.","sca_auth_verb":"Authorize renewal payment","sca_authing_verb":"Authorizing payment","sca_authed_verb":"Payment successfully authorized!","sca_auth_failed":"Unable to authorize! Please try again.","login_button_text":"Log in","login_form_has_an_error":"Please check and fix the errors above","uppercase_search":"Search","lowercase_search":"search","uppercase_page":"Page","lowercase_page":"page","uppercase_items":"Items","lowercase_items":"items","uppercase_per":"Per","lowercase_per":"per","uppercase_of":"Of","lowercase_of":"of","back":"Back to plans","zip_code_placeholder":"Zip\/Postal Code","download_file_button_text":"Download File","input_field_instructions":{"tip_amount":{"placeholder_text":"How much would you like to tip?","initial":{"instruction_type":"normal","instruction_message":"How much would you like to tip? Choose any currency."},"empty":{"instruction_type":"error","instruction_message":"How much would you like to tip? Choose any currency."},"invalid_curency":{"instruction_type":"error","instruction_message":"Please choose a valid currency."}},"recurring":{"placeholder_text":"Recurring","initial":{"instruction_type":"normal","instruction_message":"How often would you like to give this?"},"success":{"instruction_type":"success","instruction_message":"How often would you like to give this?"},"empty":{"instruction_type":"error","instruction_message":"How often would you like to give this?"}},"name":{"placeholder_text":"Name on Credit Card","initial":{"instruction_type":"normal","instruction_message":"Enter the name on your card."},"success":{"instruction_type":"success","instruction_message":"Enter the name on your card."},"empty":{"instruction_type":"error","instruction_message":"Please enter the name on your card."}},"privacy_policy":{"terms_title":"Terms and conditions","terms_body":null,"terms_show_text":"View Terms","terms_hide_text":"Hide Terms","initial":{"instruction_type":"normal","instruction_message":"I agree to the terms."},"unchecked":{"instruction_type":"error","instruction_message":"Please agree to the terms."},"checked":{"instruction_type":"success","instruction_message":"I agree to the terms."}},"email":{"placeholder_text":"Your email address","initial":{"instruction_type":"normal","instruction_message":"Enter your email address"},"success":{"instruction_type":"success","instruction_message":"Enter your email address"},"blank":{"instruction_type":"error","instruction_message":"Enter your email address"},"not_an_email_address":{"instruction_type":"error","instruction_message":"Make sure you have entered a valid email address"}},"note_with_tip":{"placeholder_text":"Your note here...","initial":{"instruction_type":"normal","instruction_message":"Attach a note to your tip (optional)"},"empty":{"instruction_type":"normal","instruction_message":"Attach a note to your tip (optional)"},"not_empty_initial":{"instruction_type":"normal","instruction_message":"Attach a note to your tip (optional)"},"saving":{"instruction_type":"normal","instruction_message":"Saving note..."},"success":{"instruction_type":"success","instruction_message":"Note successfully saved!"},"error":{"instruction_type":"error","instruction_message":"Unable to save note note at this time. Please try again."}},"email_for_login_code":{"placeholder_text":"Your email address","initial":{"instruction_type":"normal","instruction_message":"Enter your email to log in."},"success":{"instruction_type":"success","instruction_message":"Enter your email to log in."},"blank":{"instruction_type":"error","instruction_message":"Enter your email to log in."},"empty":{"instruction_type":"error","instruction_message":"Enter your email to log in."}},"login_code":{"initial":{"instruction_type":"normal","instruction_message":"Check your email and enter the login code."},"success":{"instruction_type":"success","instruction_message":"Check your email and enter the login code."},"blank":{"instruction_type":"error","instruction_message":"Check your email and enter the login code."},"empty":{"instruction_type":"error","instruction_message":"Check your email and enter the login code."}},"stripe_all_in_one":{"initial":{"instruction_type":"normal","instruction_message":"Enter your credit card details here."},"empty":{"instruction_type":"error","instruction_message":"Enter your credit card details here."},"success":{"instruction_type":"normal","instruction_message":"Enter your credit card details here."},"invalid_number":{"instruction_type":"error","instruction_message":"The card number is not a valid credit card number."},"invalid_expiry_month":{"instruction_type":"error","instruction_message":"The card's expiration month is invalid."},"invalid_expiry_year":{"instruction_type":"error","instruction_message":"The card's expiration year is invalid."},"invalid_cvc":{"instruction_type":"error","instruction_message":"The card's security code is invalid."},"incorrect_number":{"instruction_type":"error","instruction_message":"The card number is incorrect."},"incomplete_number":{"instruction_type":"error","instruction_message":"The card number is incomplete."},"incomplete_cvc":{"instruction_type":"error","instruction_message":"The card's security code is incomplete."},"incomplete_expiry":{"instruction_type":"error","instruction_message":"The card's expiration date is incomplete."},"incomplete_zip":{"instruction_type":"error","instruction_message":"The card's zip code is incomplete."},"expired_card":{"instruction_type":"error","instruction_message":"The card has expired."},"incorrect_cvc":{"instruction_type":"error","instruction_message":"The card's security code is incorrect."},"incorrect_zip":{"instruction_type":"error","instruction_message":"The card's zip code failed validation."},"invalid_expiry_year_past":{"instruction_type":"error","instruction_message":"The card's expiration year is in the past"},"card_declined":{"instruction_type":"error","instruction_message":"The card was declined."},"missing":{"instruction_type":"error","instruction_message":"There is no card on a customer that is being charged."},"processing_error":{"instruction_type":"error","instruction_message":"An error occurred while processing the card."},"invalid_request_error":{"instruction_type":"error","instruction_message":"Unable to process this payment, please try again or use alternative method."},"invalid_sofort_country":{"instruction_type":"error","instruction_message":"The billing country is not accepted by SOFORT. Please try another country."}}}},"fetched_oembed_html":false}
How do you know when it is available for your tenant?
I assume when the cmdlet shows up. That’s when I knew.
Hi, how do you know that you can not perform swap sites with O365 groups? Aren’t all of new SPO sites associated with a group?
You know that you can’t swap group-connected sites because Microsoft says so…
Questions:
1. What is the difference using this “Invoke-SPOSiteSwap” cmdlet and “Make Homepage” button to make a modern page as the main homepage?
2. If I use “Invoke-SPOSiteSwap” cmdlet to promote a new modern page, will this use the Master Page of the current homepage?
Thank you for your replies.
Site swap replaces a complete site…. not a page.
This has to involve a simple dns change by Msft, rerouting the tenant sub-domain to the modern site and a new subdomain to the old site. But as usual, Msft’s terminology is vague – is it SITE COLLECTION swap or SITE swap? What happens to the many subsites under the root site I need to retain at their existing urls?
Can I use this un a Classic subsite?