Get-SPOSite

The Get-SPOSite cmdlet returns a reference to a SharePoint Online site collection. As mentioned earlier, the object returned by this method is a SPOSite object as opposed to a SPSite object for an on-premises site collection. Because this object exposes a different type of SharePoint artifact, the properties exposed by it are also different to the one exposed by the on-premises object. I’ve developed a short PowerShell script that allows you to loop through each property of a SPOSite object and prints its value on screen. The script will prompt the user to enter the URL to one of its SharePoint Online site collection, will get a reference to it, and will query its members to obtain the list of available properties. The script then loops through each of these properties obtained, and prints both its name and its value on screen. Figure 9-4 shows the execution of this PowerShell script against our public facing site collection.

$url = Read-Host "What is your Site's Url"
$site = Get-SPOSite $url
 
$members = $site | Get-Member | Where{$_.MemberType -eq "Property"}
for($i = 0; $i -lt $members.Count; $i++)
{
        $name = $members[$i].Name
        Write-Host $name":" $site.$name
}

By default, Office 365 creates four site collections for each Enterprise level accounts. Table 9-1 shows the site collection template ID used for each of these four site collections for your demo account.

It is important to note that although the Search Center and My Site Host templates are also available on-premises, the two site collection templates used for the Public and the Intranet site collections are new templates that are exclusive to SharePoint Online in Office 365.

New-SPOSite

The New-SPOSite cmdlet lets you create a new SharePoint Online site collection. This PowerShell cmdlet takes three mandatory parameters to execute, a URL for the new site collection, the username of the Office 365 user that will be its owner, and a storage quota. You’re probably wondering why you’re not passing the site collection’s template ID as a parameter. Actually, although this is not a mandatory parameter, you can still go ahead and pass it to the cmdlet. If you omit to mention it, your SharePoint Online will force you to select a template the first time that you try to access your new site collection. Figure 9-5 shows the prompt that a user gets the first time he or she accesses a site collection in SharePoint Online for which no default site collection template has been chosen.

Remember that I’m a developer at heart, and so, to me, something is always missing in the default offering of site collections in SharePoint Online. The beauty of Office 365 is that it lets developers create their own sandbox to develop custom business apps and test them out in the cloud. The online service offering gives the user the choice to create a developer’s site collection, which is invaluable to any organization wanting to do testing for their SharePoint 2013 apps. The first thing I always do when registering a new Office 365 account is to connect to its SharePoint Online portal and create such a site collection. The following few lines of PowerShell will show you how you can get started and automatically create such a site collection using PowerShell. The code shown here will automatically create a new developer site collection in your PowerShellBook SharePoint Online account. Figure 9-6 shows the new site collection being created in the SharePoint Online admin center. It normally takes a minute or two after the creation process has been initiated by PowerShell for the SharePoint Online site collection to be entirely created.

New-SPOSite -URL https://powershellbook.sharepoint.com/sites/dev -Owner [email protected] -StorageQuota 500 -Template DEV#0

Remove-SPOSite

The Remove-SPOSite cmdlet is to be used when you wish to delete an existing SharePoint Online site collection. The only parameter required for this PowerShell cmdlet is the URL to the site collection that you wish to delete. The following line of PowerShell code will delete the developer site collection that you’ve created in the previous section of this chapter:

Remove-SPOSite https://powershellbook.sharepoint.com/sites/dev

Repair-SPOSite

This SharePoint Online cmdlet is a special one. You can call Repair-SPOSite against a single or a group of site collections in your SharePoint Online account, and it will run all health analyzer rules against them. If it encounters any errors, it automatically attempts to fix them. This operation is not available through the web interface of the SharePoint Online admin center; you must use the SharePoint Online Management Shell to use it. Although there is no real need for Office 365 clients to use this cmdlet at the moment, it was probably one of the most widely used cmdlets by the Microsoft team when they had to upgrade millions of tenants from SharePoint 2010 to SharePoint 2013 back in the spring of 2013. Assuming that Microsoft ever releases another version of their SharePoint Online offering, there may be some future need for this cmdlet. Figure 9-7 shows the result of running this cmdlet against your demo intranet site.

Repair-SPOSite https://powershellbook.sharepoint.com

Set-SPOSite

Imagine that you wish to use PowerShell to modify a property of an existing site collection, say, its title. Your normal reaction may be to use the Get-SPOSite PowerShell cmdlet to get a reference to the site collection, and then to set its Title property to whatever you wish. The big problem with this approach using SharePoint Online is that a SPOSite object does not expose the Update method that is normally used to commit changes on SharePoint artifacts back to the database. Therefore, simply getting a reference to the site collection and setting the value of one of its property is not going to work. This is where the Set-SPOSite cmdlet comes to the rescue. This cmdlet lets you specify what property of a SPOSite object you wish to set, and in the background it secretly calls the Update method on the object. The PowerShell code below shows you how you could use PowerShell to set the title of your internal SharePoint Online site. Figure 9-8 shows the result of executing this line of PowerShell code:

Set-SPOSite https://powershellbook.sharepoint.com -Title "This is me showing the Set-SPOSite cmdlet"

There are several other properties that can be modified using this method. Table 9-2 gives a list of all of the properties of a SharePoint Online site collection that can be set using this PowerShell cmdlet.

Test-SPOSite

The Test-SPOSite cmdlet does the same thing as the Repair-SPOSite cmdlet, but it doesn’t actually commit the changes. Using it results in the same thing as calling the Repair-SPOSite using the -WhatIf switch, which also won’t commit the results of the operation.

Upgrade-SPOSite

Just as was the case for the test and repair functions, the upgrade cmdlet for SharePoint Online site collections has already served its purpose, and tenants won’t have to use it anymore. It was heavily used by the Microsoft team when upgrading tenant site collections from SharePoint 2010 to SharePoint 2013. If you try to call this PowerShell cmdlet against any of your existing site collections, you will simply get a notification message saying that the site has already been updated and that it does not need to be updated (see Figure 9-9).

Request-SPOUpgradeEvaluationSite

The Request-SPOUpgradeEvaluationSite PowerShell cmdlet lets a user request a temporary Upgrade Evaluation site collection in Office 365. This method was mostly used when Office 365 tenants were given the option to upgrade from their original SharePoint 2010 site collections over to the new SharePoint 2013 ones. Now that every new tenant is automatically given a 2013 environment, the use for this cmdlet is slowing disappearing. Making calls to this cmdlet doesn’t do anything anymore. No upgrade evaluation sites will ever be triggered for site collections that are already running in compatibility mode.

Get-SPODeletedSite

Just as was the case for SharePoint on-premises, site collections that have been deleted through the web interface are given a second shot at life. One major difference in the online world, however, is that in Office 365, even SharePoint site collections that have been deleted through PowerShell are sent to the recycle bin. The SharePoint Online admin center offers the option to view deleted site collections by clicking on the Recycle Bin button in the management ribbon (see Figure 9-10).

The Get-SPODeletedSite PowerShell cmdlet takes in a unique parameter, the URL of the deleted site collection to which you wish to obtain a reference. A deleted site collection in SharePoint Online is represented by the SPODeletedSite object. Figure 9-11 shows how you can obtain a reference to the deleted developer site collection that you’ve deleted previously, and shows you all the methods and properties exposed by this object.

Restore-SPODeletedSite

The Restore-SPODeletedSite PowerShell cmdlet restores a deleted site collection back to life. While they are in the recycle bin, site collections are no longer accessible through the browser. Restoring a deleted site collection puts it back in the list of available site collections in the SharePoint Online admin center. The Restore-SPODeletedSite cmdlet simply takes the URL of the site collection that you wish to restore from the recycle bin. The process of restoring a deleted site collection converts the SPODeletedSite object back to a SPOSite object.

Remove-SPODeletedSite

Remove-SPODeletedSite is like the “Grim”. It takes a site collection that has been previously deleted and that is patiently waiting in the recycle bin, and permanently makes it disappear. Once a site collection has been removed from the recycle bin, it is no longer restorable; it’s gone. One very interesting fact is that in SharePoint 2013, there is no way for an administrator using the web interface to force the deletion of a site collection from the recycle bin. Site collections that have been deleted in Office 365 are given a 30-day grace period during which administrators can reverse their decision and restore them. If after these 30 days the site collections are still in the recycle bin, then SharePoint Online will automatically remove them permanently. Using PowerShell is the only way for an administrator to force an immediate permanent deletion of a site collection. The following line of PowerShell will take the developer site that you’ve deleted previously and permanently delete it from this world. Figure 9-12 shows the permanent removal of your developer site using PowerShell.

Remove-SPODeletedSite https://powershellbook.sharepoint.com/sites/dev

Get-SPOSiteGroup

The Get-SPOSiteGroup PowerShell cmdlet allows you to get a list of all existing security groups for a specific site collection. The default security groups in each site collection vary. Table 9-3 lists the various default security groups in each, and lists their default permissions.

You can obtain the permission level associated with each site collection security group by accessing the Roles property of a group. The following example shows how you can determine the permission level associated with the Translation Managers group of our default Search Center site collection (see Figure 9-13).

$groups = Get-SPOSiteGroup https://powershellbook.sharepoint.com/search
$translationMgr = $groups | Where{$_.Title -eq "Translation Managers"}
$translationMgr.Roles

New-SPOSiteGroup

The New-SPOSiteGroup PowerShell cmdlet lets you create a new SharePoint Online site collection security group. It requires you to pass in the site collection’s URL where you wish to create this new security group, the name of the new group, as well as the permission level that you want to assign to it. Figure 9-14 shows you how you could use this cmdlet to create a new security group on your public site called MyNewGroup having both Contribute and Design rights.

New-SPOSiteGroup https://powershellbook-public.sharepoint.com
-Group "MyNewGroup" -PermissionLevels "Contribute", "Design"

Remove-SPOSiteGroup

Starting to figure out a pattern in the available methods? Yes, you’ve guessed it; the Remove-SPOSiteGroup cmdlet lets you delete an existing site collection security group. It simply requires you to pass it the URL of the site collection, as well as the name of the security group to delete. For example, to delete the security group that you’ve created in the previous section, you could run the following line of PowerShell:

Remove-SPOSiteGroup https://powershellbook-public.sharepoint.com
-Identity "MyNewGroup"

Set-SPOSiteGroup

Just as was the case when we dealt with SharePoint Online site collections, the Set-SPOSiteGroup cmdlet lets you modify properties related to existing site collections’ security groups. For example, if you wish to modify the permission levels of a specific group, you’ll need to use this cmdlet to do it. Assume that you want to modify the permissions level of a custom security group called “Partners” that exists on your public-facing instance. Assuming that this group currently has Design permission, if you wish to bring this down a notch and simply grant contributor access, you could use the following line of PowerShell code to make the change shown in Figure 9-15:

Set-SPOSiteGroup https://powershellbook-public.sharepoint.com -Identity "Partners"
-PermissionLevelsToRemove "Design" -PermissionLevelsToAdd "Contribute"

Get-SPOUser

The Get-SPOUser cmdlet lets you obtain a list of all users (internal and external) on a specific SharePoint Online site collection. The only required parameter is the site collection’s URL. Figure 9-16 shows the result of executing this PowerShell cmdlet against our internal site collection.

$users = Get-SPOUser https://powershellbook.sharepoint.com

You can see from this example that there are some abstract users being returned. Those are simply what I would consider “maintenance” accounts. They are required accounts that the SharePoint farm needs in order to operate properly. What I’m really interested in are the two accounts right in the middle of the list. You can easily see my personal account on my domain ([email protected]), but what about the live.com#[email protected] user? This is an external user I invited to join my SharePoint site. I put him in the Owners group, giving him complete access over the site collection. This user can login to my Office 365 environment by using its personal @Outlook.com email account, and interact with the environment as if he was a company’s user.

Get-SPOExternalUser

The Get-SPOExternalUser cmdlet lets you get a list of all external users specified in your current Office 365 tenant account. The last part of my previous sentence is key to understanding how external users are managed in SharePoint Online. They are not managed at the site collections level directly but are, rather, generic to all of your SharePoint environments. Just like the internal users, these are stored at the account level. When you add an external user to a site collection, however, it gets registered against it, and the site collection keeps a footprint of its login name. This makes sense when you think that even external users a My Site page created in your environment; SharePoint needs to know who they are, no matter what site collection you are in. Get-SPOExternalUser doesn’t require any parameters. It simply connects to your tenant store and returns all of the external users it finds, no matter where in the site collection architecture they were granted access. Figure 9-17 shows the result of executing this cmdlet against our demo Office 365 tenant account:

Get-SPOExternalUser

Note that there is no way for you, with this cmdlet, to identify where in the site collections’ architecture a specific external user has been granted access. You would have to loop through each one and check for their presence in the list of users. The following PowerShell script allows you to enter the user name of a specific external user and to figure out what site collections he’s been granted access to (see Figure 9-18):

# Prompts for the external user's login name;
$extUserName = Read-Host "External User Name?"
 
# Gets a list of all available site collections in the current tenant;
$sites = Get-SPOSite
 
# Loops through all site collections
for($i = 0; $i -lt $sites.Count; $i++)
{
    # Query the list of users for the current site collection to see if external user is in
    # there;
    $user = Get-SPOUser $sites[$i].Url | Where{$_.LoginName -like "*$extUserName"}
    if($user -ne $null)
    {
        # If the user has been found, print the site's Url he has been found in;
        Write-Host $sites[$i].Url
    }
}

Add-SPOUser

The Add-SPOUser cmdlet lets you add an existing user to a SharePoint Online security group. This PowerShell method takes in three required parameters: the URL of the site collection, the name of the group to add the user in, and the login name for the user to add. This cmdlet allows you to add both internal and external users to security group. For example, you could try to add an internal user by passing its user name in the form DomainUsername or add an external user using the default user id provided with Office 365 that includes its email address (e.g., live.com#[email protected]). However, an external user name needs to have been registered against the site collection before attempting to add it to a security group; otherwise, Office 365 won’t recognize its login name. For example, Figure 9-19 shows the use of this cmdlet to try to add the same external user to two different site collections. In the first case, the external user had not been registered with the site collection, whereas, in the second case, the user had properly been registered. Note that there is currently no way to use the SharePoint Online Management Shell to automatically register an external user against a site collection.

Remove-SPOUser

The Remove-SPOUser cmdlet lets you remove both an internal, and an external user from a SharePoint site collection. It requires you to pass it both the site collection’s URL and the login name for the user to remove. Remember that when dealing with external users, when you are at the site collection level, login names take the form of <Authorization Provider>#<User Email> (e.g., Live.com#[email protected]). The following line of PowerShell will remove the external user you’ve added to our internal site collection:

Remove-SPOUser https://powershellbook.sharepoint.com
-LoginName live.com#[email protected]

Remove-SPOExternalUser

You are probably wondering why it is that you need a separate remove method to get rid of external users, when the method I’ve just covered takes care of both internal and external users. You need to remember that when I talk about external users, you must think of this in the tenant context, meaning external users are registered against your entire Office 365 account. When an external user is registered against a specific site collection, it becomes what I’d call a “semi-internal” user, meaning that you can interact with it as if it was just a regular internal SharePoint user. The concept of external user only really makes sense when you’re talking about the higher level of SharePoint management: the entire SharePoint environment. This method deals exactly with this. It gets rid of an external user at the tenant level, meaning that it will no longer be registered at the account level.

In order to use the Remove-SPOExternalUser cmdlet, you’ll need to obtain the external user’s unique id. An important thing to note as well is that by simply removing the entry to the external user at the tenant’s level, you are not revoking the user’s access to the site collections to which he has been granted access previously. The following PowerShell script will come in handy if you ever need to get rid of an external user and want to ensure all registered instances are also removed from the site collections. Therefore, the script makes sure that the specified external user is no longer able to access any SharePoint site collection in your Office 365 environment:

# Get the external user login name;
$extUser = Read-Host "External User Login Name?"
 
# Get a list of all site collection;
$sites = Get-SPOSite
 
for($i = 0; $i -lt $sites.Count; $i++)
{
    $user = Get-SPOUser $sites[$i].Url | Where{$_.LoginName -like "*$extUser"}
    if($user -ne $null)
    {
        # Remove the user from the site collection;
        Remove-SPOUser $sites[$i] -LoginName $user.LoginName
    }
}
 
# Gets the external user's unique id and remove it from the tenant account;
$userRec = Get-SPOExternalUser | Where{$_.LoginName -eq $extUser}
Remove-SPOExternalUser $userRec.UniqueId -Confirm:$false

Set-SPOUser

The Set-SPOUser cmdlet lets you specify if a specific user should be granted site collection administrator rights or not. For example, the following line of PowerShell code could be used to revoke my SharePoint site collection administrator rights from your internal SharePoint environment. Just make sure that you don’t accidentally remove administrative rights from your unique administrator account when using this cmdlet:

Set-SPOUser https://powershellbook.sharepoint.com -LoginName [email protected] -IsSiteCollectionAdmin $false

Get-SPOAppInfo

Assume that you have installed a custom app from the Office marketplace on one of your sites. The Get-SPOAppInfo cmdlet lets you get a reference to this app instance by simply passing it the name of the app you’ve installed somewhere in any of your site collections. Because this is tough to explain, I’ll show you a concrete example. Assume that a user went in the Office app marketplace and installed an app, called Timer Clock, on my internal SharePoint Online site collection. I now want to go and get a reference to this app instance. By using the Get-SPOAppInfo cmdlet and passing it the name of my app instance, I can get easily get a reference to that object. Notice that in this example, I’m simply passing it part of the actual app’s name. This works fine because PowerShell treats this parameter as a wildcard and gets any app that has the word “timer” in its name. Using this method gives you an overview of all of the apps that have been installed throughout the SharePoint Online environment as well as telling you important information about them, such as the source from which they were installed (organizational catalog, marketplace, etc.). Figure 9-20 shows the results of running this line of PowerShell code:

$timerClockApp = Get-SPOAppInfo -Name "Timer"

Get-SPOAppErrors

In Office 365, you are given the option to create an App Catalog for your tenant account. An app catalog site collection is created by using the Apps management section in the Office 365 SharePoint Online admin center (see Figure 9-21). This type of site collection allows you to make custom apps developed by your organization available to all site collections, and lets end users install and use them as they wish.

The question now becomes, how do you monitor errors related to these custom apps your development team produces? The Get-SPOAppErrors cmdlet lets you access information related to errors due to installation, upgrade, and execution errors. It requires you to pass the app’s product ID as a parameter. This data is only being updated every 24 hours by Office 365 timer jobs, so don’t worry if you don’t see stats appear right after your users start calling you about errors. The following example shows a scenario in which a faulty app has been deployed to the organization. Users trying to access the app in question are getting an error page. Calling the following lines of PowerShell code would return a list of all errors associated with the MyCrashingapp instance:

$myCrashingApp = Get-SPOAppInfo -Name "MyCrashingApp"
Get-SPOAppErrors $myCrashingApp.ProductId

Get-SPOTenant

The Get-SPOTenant cmdlet returns information about the current tenant account. Figure 9-22 shows the results of running this cmdlet against our demo environment:

Get-SPOTenant

Set-SPOTenant

You can use this cmdlet to set properties of the current tenant account. One example of properties you can set is the NoAccessRedirectUrl, which specifies a URL to redirect a user if the site they are trying to access has been locked. A locked site means it can’t be access by users. In real life, you want to lock a site while it is in development or while it is undergoing maintenance. It is a temporary state that freezes a site collection into its current state. To illustrate this, assume the following scenario. Pretend that you need to lock down the developer’s site collection in your environment because you want to prevent users from submitting new apps in testing (harsh example). You want users trying to access the developer site while it is locked down to be redirected to a user-friendly page that will explain to them what is going on, and tell them when to expect that the site will be back up. This PowerShell script will start off by locking the developer site, and then will set the NoAccessRedirectUrl property of your tenant account to contain the URL of the temporary page to which you want to redirect users:

Set-SPOSite https://powershellbook.sharepoint.com/sites/dev -LockState NoAccess
Set-SPOTenant -NoAccessRedirectUrl https://powershellbook-public.sharepoint.com

Get-SPOTenantLogEntry

You probably got very excited when you first read the name of this PowerShell cmdlet. Let me burst your bubble right away; it doesn’t do what you think it does, at least not exactly. The biggest downside of SharePoint Online is that we don’t have direct access to our servers and therefore can’t directly get access to the SharePoint logs. The cmdlet lets you get access to certain information pertaining to your tenant account logged in the SharePoint logs. It will contain information about component failures if there are any (BCS, User Profile Service, etc.). It also contains information related to important events that happened on the environment. Figure 9-23 shows you what the results of running the method against our demo environment are. By looking at it, you can see that two events have been logged, one for every developer’s site that I created. This could be important information for you to monitor, because developer sites allow users to side-load SharePoint apps. You probably don’t want anybody creating such sites and loading their own applications in them.

$logs = Get-SPOTenantLogEntry
$logs[0].Message

Get-SPOTenantLogLastAvailableTimeInUtc

Yes, somebody at Microsoft ought to be fired for coming up with such a long name for this PowerShell cmdlet. On the good side, the Get-SPOTenantLogLastAvailableTimeInUtc cmdlet does exactly what its 10-foot-long name says it does: it returns the date of the latest log entry in UTC time. This cmdlet could prove useful if you are automating a script that regularly checks on the cloud server to see if any new errors have been logged, and then notify the user. Figure 9-24 shows the results of running this cmdlet against our demo environment.

Get-SPOWebTemplate

The Get-SPOWebTemplate cmdlet returns a list of all available web templates in SharePoint Online. Figure 9-25 shows the resulting list produced by this cmdlet.