Martin's Blog

Fun fact: When you delete a workspace in Power BI, it doesn’t really get deleted immediately. The State of the workspace changes from “Active” to “Deleted” and will only be removed later when there is a need for space in your tenant.

This “soft delete” mechanism causes some nuances when you try to create workspaces programmatically, but at the same time give us the ability to restore a workspace if it was removed by accident.

Here’s how you can see all of the workspaces in your Power BI tenant, and potentially restore a deleted workspace…

Prerequisites

If you’re attempting to run PowerShell scripts for the first time, there are some things you need to do before you get started:

1. Always run Windows PowerShell as Administrator, otherwise you will not be able to run certain commands.
2. Set the execution policy for the current user, session or machine. As part of the default security policy on your machine, you will not be able to run PowerShell commands without the necessary permissions. I like to set the policy for the local machine, so that I don’t have to do it again.

#this will show you all the existing execution policies
Get-ExecutionPolicy -List

#if you want to set it for the machine
Set-ExecutionPolicy -ExecutionPolicy Unrestricted -Scope LocalMachine
 
#if you want to set it for the current process
Set-ExecutionPolicy -ExecutionPolicy Unrestricted -Scope Process
 
#if you want to set it for current user only
Set-ExecutionPolicy -ExecutionPolicy Unrestricted -Scope CurrentUser

3. Install and import the necessary PowerShell modules. Every Windows machine will have some base modules installed, but not the ones we need for Power BI.

#install the module in order to use the cmdlets
Install-Module -Name MicrosoftPowerBIMgmt -AllowClobber

#import the module into the current session
Import-Module MicrosoftPowerBIMgmt

The AllowClobber parameter will force any preexisting modules or cmdlets with the same names to be replaced by the latest versions, and the name of the module we’re installing is MicrosoftPowerBIMgmt. Ok, now we’re ready to roll…

Connect to the Power BI tenant

#Connect to Power BI tenant
Connect-PowerBIServiceAccount | Out-Null

Running this command will pop up an authentication dialogue, and you should use an account with the necessary administrative permissions in Power BI.

An interesting addition in the code above is the use of Out-Null. When you connect to something in PowerShell, you will typically get a response. In the case of Power BI, it will be the GUID of the tenant and the username you’ve used to connect. If you have a PS script that performs multiple tasks, the responses may create a lot of “noise” in the output window and that’s why I like to exclude that in my scripts.

List all workspaces

#Retrieve workspaces
Get-PowerBIWorkspace -Scope Organization -All

With the command above you need to use the Scope parameter with the Organization value to return everything in the tenant (including personal workspaces and workspaces created by Teams and O365 groups). If you don’t, you will only see the workspaces owned by the user you’ve used while connecting.

The output will look something like this…

Restore the workspace

#Restore workspace (replace {...} with your values)
Restore-PowerBIWorkspace -Id {workspace guid} -RestoredName {workspace name} -AdminUserPrincipalName {admin user}

To restore the workspace you’ll need the GUID, provide a name (which could be the same or different to the original workspace) and provide the username of the user who will be the administrator. Each workspace should have an admin user assigned, otherwise access could become an issue.

There’s a few things you need to know about the restored workspace:

• Preexisting users will no longer be there, so you will have to add them again.
• If the workspace contained any reports or datasets, they will still be there.
• Refresh schedule(s) will be disabled and you will have to provide credentials for the datasets again.

Want to download the PowerShell scripts to perform these actions? Get it from my GitHub repo.