Martin's Blog

This blog post is part of my “Automating Power BI deployments” series, and you can find a list of the other posts here.

What you should know

There are two things to keep in mind when creating workspaces in an automated fashion:

• The workspace may already exist. When you delete a workspace, it isn’t really deleted…only its status changes to “deleted”. That’s great if you want to restore a workspace you’ve accidentally deleted, but your code will have to account for it or it will fail.
• Whether you are creating or restoring a workspace, you have to provide an account to be the new administrator in the workspace. This ensures that the workspace is accessible, and by design a workspace cannot exist without an administrator.

Retrieve the workspace

To see if the workspace already exists, we’ll attempt to retrieve it by using the Get-PowerBIWorkspace cmdlet and assigning the results to a variable. Once that is done, it’s as easy as checking whether the variable is empty (null) or not. Here’s how you do it:

#Retrieve the workspace
$WorkspaceObject = (Get-PowerBIWorkspace -Scope Organization -Name $WorkspaceName -WarningAction SilentlyContinue)

#Check to see if the workspace exist
if (!$WorkspaceObject) {
    #Workspace does not exist. We have to create it.    
}
else { 
    #Workspace already exists. We have to restore it.
}

Note that we’re using some of the methods described in an earlier post about PowerShell basics, and you have to connect to the service first before attempting to retrieve a workspace.

The code snippet above assumes that we have already declared and assigned values to a variable (or parameter) for the name of the workspace ($WorkspaceName). We’re also forcing the cmdlet to just SilentlyContinue if it fails and not throw an error, which will happen if the workspace doesn’t exist.

Create the workspace

If the workspace doesn’t exist, we can create it with the following cmdlet.

#Create the workspace 
New-PowerBIWorkspace -Name $WorkspaceName -OutVariable WorkspaceObject

Did you see the interesting new addition here? We’ve created the $WorkspaceObject variable in the first code snippet, and assigned it to the workspace object after attempting to retrieve it. Now we’re using the -OutVariable switch to assign the output (i.e. the workspace object) to that same variable so that we can use it later. Also note the omission of the $ prefix when using -OutVariable.

One more thing: You may have noticed that we didn’t provide the details of the administrator account, which is required when you create a new workspace. By default the account that you’ve used to connect to the service will be the administrator of the new workspace. I wish it was possible to specify that in this cmdlet, but it isn’t and you’ll have to take that into consideration.

Restore the workspace

Restoring the workspace takes a little more effort, and we’ll use our workspace object to extract the Id and use that in the cmdlet. I’m using the same name for the workspace here, but you can also change it if you want. Also note that we have to explicitly assign an administrator when restoring the workspace…it doesn’t make the same assumption as the previous cmdlet we used to create a new workspace.

#Restore workspace 
Restore-PowerBIWorkspace -Id $WorkspaceObject.Id -RestoredName $WorkspaceName -AdminUserPrincipalName $AdminUser

There’s one more catch when trying to restore workspaces: You should check the state of the workspace to make sure it’s in a “deleted” state before restoring it. Workspaces can be in one of a few different states, and blindly trying to restore it may result in some errors. Use the following construct to check the state of the workspace object:

if ($WorkspaceObject.State -eq "Deleted") { 
    #Workspace is in a deleted state 
}

Want to download the PowerShell script to perform these actions, and also see how you can change the description of the workspace at the same time? Get it from my GitHub repo.