Blog written by:
Chris Ang
SharePoint Architect
CCNA, MCPD, MCTS, A+
Intro
Office 365 has grown in popularity and is a fantastic option for those who need to collaborate and share documents. Like SharePoint (on-premise) it has excellent integration with MS Office tools such as MS Word, Excel, PowerPoint, etc… These factors make adoption and usage grow quite quickly. With that growth, comes management concerns and more administrative tasks.
Luckily, there is a way to help automate these tasks. Using ‘command-line’ operations, in what we know as PowerShell (programming language), you can efficiently manage your SharePoint Online/Office 365 environment – such as creating new SharePoint Online lists, applying the list settings, adding users to sites and granting them certain permissions, as well as creating whole new new sites – all without opening your web browser!
In short, PowerShell for Office 365 is a very effective administrative tool, especially for batch or repetitive operations.
Advantages of Using PowerShell
- Built-in scripting language makes it flexible and powerful. One can automate complex tasks with a set of commands.
- Object-Oriented makes it easy for administrators to directly work with rich objects within a text-based shell, leading to huge time savings. This topic would be for more advanced developers, but is an option for those that could benefit from it.
- Repetitive Tasks are better handled when using a script. Once you have a script to set do what you need, it is easy to repeat this by just re-running or copy pasting the script instead of using the User Interface (which would require more clicks and waiting for post-backs).
- For example, you can create a bunch of commands to create a new ‘Project Site’, add 3 lists to it (‘Project Files’ ‘Assignments’ and ‘Key Contacts’), then add a specific Group to have access to it. Then using this ‘saved’ script, you can easily recreate a new ‘Project’ site again when you have a new ‘Project’. There are other alternatives to creating ‘Project’ sites, but this is just an example of a repetitive task that PowerShell can help automate.
- You specify all the options/settings/parameters once, save it and make sure it works, and then re-use the script to just recreate new ones as needed, much faster than re-clicking 100 times!
SharePoint Online Command-lets
There are multiple cmdlets available in SharePoint Online and most of them are for Site Collections, User and Application Management. Here, we shall explore the various cmdlets available for Office 365 and SharePoint Online and how they can help administrators manage users and sites efficiently.
Setup
- Install Windows PowerShell 3.0 from Windows Management Framework 3.0.
- Install the SharePoint Online Management Shell from the Microsoft Download Center.
- Click Start>All Programs>SharePoint Online Management Shell.
Connections
After you are set up and have the PowerShell cmdlets on your machine, you need to connect from your machine to your Office 365 site (you connect to your Office 365/SharePoint Online environment remotely!). The commands below will allow you to connect to your environment, this is the first thing you would need to do before any other commands.
You will need to know the following:
- URL of your Office 365/SharePoint Online site
- Administrator Credentials used to access the site(s)
Connect-SPOService – this is the cmdlet which connects you to a SharePoint Online connection. This has to be run before any other SharePoint Online cmdlets can be run. See full list of parameters here.
Connect-SPOService -Url https://contoso.sharepoint.com -credential admin@contoso.com
Disconnect-SPOService – it disconnects a previously established SharePoint Online service connection.
Connect by Storing Context in code to pass to function
Below is an example of creating a security context, and passing it to a method (in this case – to connect to this site and add a SharePoint field to a list).
This can be useful if you need to write multiple scripts for multiple Office 365 tenancies in one batch.
[System.Reflection.Assembly]::LoadWithPartialName("Microsoft.SharePoint.Client")
[System.Reflection.Assembly]::LoadWithPartialName("Microsoft.SharePoint.Client.Runtime")
$UserName = "chris.ang@qipoint.com"
$Password = Read-Host -Prompt "Please enter your password" -AsSecureString
$URL = "https://yourcompany.sharepoint.com/sites/sales"
$Context = New-Object Microsoft.SharePoint.Client.ClientContext($URL)
$Credentials = New-Object Microsoft.SharePoint.Client.SharePointOnlineCredentials($UserName,$Password)
$Context.Credentials = $Credentials
$listTitle ="Quotations"
#This function will add the specified fields to this list
function Provision-Field([Microsoft.SharePoint.Client.ClientContext]$Context,[string]$ListTitle,[string]$FieldSchema)
{
$list = $Context.Web.Lists.GetByTitle($ListTitle)
$List.Fields.AddFieldAsXml($FieldSchema,$true,[Microsoft.SharePoint.Client.AddFieldOptions]::AddFieldToDefaultView)
$Context.Load($List)
$Context.ExecuteQuery()
}
#Now we call the function with below cmdlets, we create 3 fields here in the list 'Quotations'
Provision-Field $Context $listTitle "<Field Type='DateTime' Name='QuoteDate' DisplayName='QuoteDate' Required='FALSE' Format='DateOnly'/>"
Provision-Field $Context $listTitle "<Field Type='Text' Name='ClientId' DisplayName='Client ID' Required='FALSE'/>"
Provision-Field $Context $listTitle "<Field Type='Text' Name='Rep' DisplayName='Rep' Required='FALSE'/>"
Sites
The PowerShell script creates new site in SharePoint Online based on specified variables, which will need to be changed to suit your Office365 tenant after downloading it from the library. One can use a template that suits the requirement, check all available parameters, make changes to variables and copy it to PowerShell.
You can create powerful scripts by using these cmdlets that are easy to use with standardized syntax. The cmdlets return quickly, make the creation faster and can create several sites at once or create batches of Site Collections that can be run smoothly.
PowerShell Commands:
New-SPOSite – creates a new SharePoint Online site collection for the current company. See the full list of parameters here
New-SPOSite -Url http://contoso.sharepoint.com/sites/mynewsite -Owner joe.healy@contoso.com -StorageQuota 1000 -Title "My new site collection"
New-SPOSiteGroup – creates a new group in a SharePoint Online site collection. See full list of parameters here
New-SPOSiteGroup -Site https://contoso.sharepoint.com/sites/siteA -Group "Project Leads" -PermissionLevels "Full Control"
Get-SPOSite – returns one or more existing site collections. See full list of parameters here.
Get-SPOSite -Identity https://contoso.sharepoint.com
Get-SPOSiteGroup – retrieves all the groups on the specified site collection. See full list of parameters here.
Get-SPOSiteGroup -Site http://contoso.sharepoint.com/sites/siteA
Site Details
Below is an example of displaying detailed information about an Office 365 Site
Get-SPOSite https://contoso.sharepoint.com/ -Detailed | select *
Sample Result:
LastContentModifiedDate : 03/2/2016 6:03:50 PM Status : Active ResourceUsageCurrent : 0 ResourceUsageAverage : 0 StorageUsageCurrent : 1 LockIssue : WebsCount : 3 CompatibilityLevel : 15 Url : https://contoso.sharepoint.com/ LocaleId : 1033 LockState : Unlock Owner : s-1-5-21-3176901541-3072848581-1985638908-189897 StorageQuota : 1000 StorageQuotaWarningLevel : 0 ResourceQuota : 300 ResourceQuotaWarningLevel : 255 Template : STS#0 Title : Contoso Team Site AllowSelfServiceUpgrade : True
Lists & Libraries
Administrators often need to manage SharePoint lists and manipulate them. Luckily when you need to modify many lists at one time, you can do so using PowerShell scripts!
PowerShell Commands:
Below is an example using the ‘Security Context’ method above (under Connections).
$UserName = "chris.ang@qipoint.com"
$Password = Read-Host -Prompt "Please enter your password" -AsSecureString
$URL = "https://yourcompany.sharepoint.com/sites/sales"
$Context = New-Object Microsoft.SharePoint.Client.ClientContext($URL)
$Credentials = New-Object Microsoft.SharePoint.Client.SharePointOnlineCredentials($UserName,$Password)
$Context.Credentials = $Credentials
#Retrieve lists
$Lists = $Context.Web.Lists
$Context.Load($Lists)
$Context.ExecuteQuery()
#Create list with "custom" list template
$ListInfo = New-Object Microsoft.SharePoint.Client.ListCreationInformation
$ListInfo.Title = $ListTitle
$ListInfo.TemplateType = "100"
$List = $Context.Web.Lists.Add($ListInfo)
$List.Description = $ListTitle
$List.Update()
$Context.ExecuteQuery()
#Retrieve site columns (fields)
$SiteColumns = $Context.Web.AvailableFields
$Context.Load($SiteColumns)
$Context.ExecuteQuery()
#Grab city and company fields
$City = $Context.Web.AvailableFields | Where {$_.Title -eq "City"}
$Company = $Context.Web.AvailableFields | Where {$_.Title -eq "Company"}
$Context.Load($City)
$Context.Load($Company)
$Context.ExecuteQuery()
#Add fields to the list
$List.Fields.Add($City)
$List.Fields.Add($Company)
$List.Update()
$Context.ExecuteQuery()
#Add fields to the default view
$DefaultView = $List.DefaultView
$DefaultView.ViewFields.Add("City")
$DefaultView.ViewFields.Add("Company")
$DefaultView.Update()
$Context.ExecuteQuery()
#Adds an item to the list
$ListItemInfo = New-Object Microsoft.SharePoint.Client.ListItemCreationInformation
$Item = $List.AddItem($ListItemInfo)
$Item["Title"] = "New Item"
$Item["Company"] = "Contoso"
$Item["WorkCity"] = "London"
$Item.Update()
$Context.ExecuteQuery()
Security Groups
Administrators can create security groups so that only a certain group of people get access to a SharePoint site. Also, with the help of Exchange Online Groups, you can assign permissions to a group of users and SharePoint security groups, which in turn can grant rights and access to users of sites and site collections.
PowerShell Commands:
Get-SPOUser – gives a list of all users on a site. See full list of parameters here.
Set-SPOUser – set whether an existing site collections user is a Site Collection administrator or not. See full list of parameters here.
Set-SPOSite – you can set the owner, title, storage quota, storage quota warning level, resource quota, resource quota warning level, locale ID, whether site collection allows self-service upgrade or not. See full list of parameters here.
Set-SPOSiteGroup – you can set the permission level and assign the ownership rights of an existing site collection group. See full list of parameters here.
Users
Once you have created site groups, you can add or delete users to and from the group. With PowerShell cmdlets, administrators an easily add an existing Office365 user or an Office365 security group to a SharePoint Group. You need to be SharePoint Online global administrator and a site collection administrator to use this feature.
PowerShell Commands:
Add-SPOUser – adds user to an existing site collection site group. See full list of parameters here.
Remove-SPOUser – removes a user or a security group from a site collection or group. See full list of parameters here.
Remove-SPOSite – this moves a SharePoint Online site collection to the SharePoint Online Recycle Bin. See full list of parameters here. The cmdlet doesn’t remove the site collection permanently; it moves it to the recycle bin from where you can restore it later using the Restore-SPODeletedSite cmdlet.
Remove-SPODeletedSite – permanently deletes the site collection from the Recycle Bin. See full list of parameters here.
Remove-SPOSiteGroup – used to remove a SharePoint online group from a site collection by specifying the name of the group in the Identity parameter. See full list of parameters here.
External Users
Sharing content with clients, outside users and vendors is a very tricky business. After all, you’ll have to grant the same level of access to the external users as you’ve granted to the internal users. One has to be very cautious while managing external users as they can also copy, add, remove and share content. With PowerShell cmdlets, you can keep track and manage the external users and sharing. You must have global tenant administration rights to run these queries.
PowerShell Commands:
Get-SPOExternalUser – gives you a complete list of external users in the tenant’s folder for a given site collection based on specified criteria. See full list of parameters here.
Remove-SPOExternal User – this cmdlet permanently removes a collection of external users from the tenant’s folder. Users who are removed lose access to all of the tenant’s resources. See full list of parameters here.
Repair & Maintenance
You can check the health of the Site Collection and its contents; conduct specific tests to see if they are functioning smoothly as per the rules and run applicable repair codes to address the failed health check rules.
PowerShell Commands:
Test-SPOSite – this cmdlet runs the specified health checks on the site collection and its contents, without making any changes unless if run in the repair-mode. It gives you a complete summary of the results along with the report of the rules. See full list of parameters here.
Repair-SPOSite – this cmdlet will make changes if issues are found and automatically repair a failed health check on the specified Site Collection. It basically runs an applicable repair code to fix the issue; although some issues cannot be fixed automatically, most have the ability to repair on their own. See full list of parameters here.
Upgrade-SPOSite – use this cmdlet to upgrade an existing site collection, either through a build-to-build upgrade (e.g. RTM to SP1) or a version-to-version upgrade (e.g. 2010 to 2013). This can also be used to resume failed upgrades. The default is build-to-build; so if you want a version upgrade, you need to use the VersionUpgrade parameter. In case of a version-to-version upgrade, the site collection health checks are first run in the repair mode to ensure that the upgrade can be run successfully. See full list of parameters here.
Request-SPOUpgradeEvaluationSite – the administrator can request for a copy of the existing site collection to validate the effects of the upgrade without impacting the original site. Such requests are not automatically processed; they are scheduled to take place in the background to cause minimal effect on the service. See full list of parameters here.
Monitoring & Troubleshooting
Using the tenant-specific cmdlets, you can get all the information about your tenant, view logs, raise queries and also change some of the properties that you can view when running these cmdlets. You also use the apps and connections categories to get lists of installed applications, errors, establish and clear connection with the SharePoint Online Tenant Administration Site.
PowerShell Commands:
Tenant-Specific
Get-SPOTenant – this cmdlet gives you all information about your tenant; organization-level site collection properties like StorageQuota, StorageQuotaAllocated, ResourceQuota, ResourceQuotaAllocated, and SiteCreationMode. It also tells you if External Services are enabled and other features like the No Access Redirect URL. Presently, there are no parameters for this cmdlet.
Get-SPOTenantLogEntry – gives you logs of SharePoint Online errors (however, not all errors are retrieved. Only a subset of errors that occur due to external systems are reported. See full list of parameters here.
Get-SPOTenantLogLastAvailableTimeInUtc – as the names suggests, it gives you the time when the logs were collected last. See full list of parameters here.
Set-SPOTenant – use this cmdlet to set properties like Minimum and Maximum Compatibility Level, enable External Services and specify versions in which the Site Collections can be created. When used together with Set-SPOSite, this cmdlet can help you block access to a site in your organization or redirect traffic to another site. See full list of parameters here.
Apps
Get-SPOAppErrors – gives list of application monitoring errors for the specified application. See full list of parameters here.
Get-SPOAppInfo – gives list of all installed applications. See full list of parameters here.
SharePoint Essentials Toolkit
There is a tool available as well for those who may want to do bulk tasks or reporting on Office 365 / SharePoint online sites, called the SharePoint Essentials Toolkit.
It helps with Permissions and Security Reporting, and more, I put a direct download link below. It’s an awesome product!
Download a Trial Version of the SharePoint Essentials Toolkit
Conclusion
To conclude, these PowerShell cmdlets are a very convenient and powerful way to manage your site collections, users, security groups, governance and troubleshooting processes.
As Office 365/SharePoint Online grows, so will the support for new commands and online resources. It is a good idea to start now and build your knowledge and PowerShell script library!
References:
http://blog.falchionconsulting.com/index.php/2013/01/using-powershell-to-manage-sharepoint-2013-online/
https://technet.microsoft.com/en-us/magazine/2006.12.powershell.aspx
https://blogs.technet.microsoft.com/fromthefield/2014/02/18/office-365-powershell-script-to-create-a-list-add-fields-and-change-the-default-view-all-using-csom/
Currently working at Cognillo (https://www.cognillo.com), he has helped architect and develop SharePoint Enterprise products for customers such as the U.S. Navy, U.S. Army, U.N. Security Council of Netherlands, Australian Government, U.S. Dept of Treasury, U.S. Dept of Justice, Canadian Dept of Defense, Scotiabank, JPMorgan CHASE Bank, Intel, Ford Motors, Microsoft, NASA, DARPA, SNC Lavalin, Penguin Books, and more.
He is a proud father of 2, and when he has any spare time, he loves to paint portraits of his kids.
- What is SharePoint? A Beginner’s Guide to MS SharePoint Software - October 8, 2018
- Beginner’s Guide: Windows PowerShell – How to Use Tutorial for Dummies - October 8, 2018
- Remote PowerShell to Manage SharePoint on-premises - August 14, 2018