'ensure' commands

[waldekmastykarz]

Currently, Office 365 CLI has dedicated commands for retrieving, creating and updating resources. If you were to create a script that ensures a specific configuration, for each resource you'd need to see if it exists, create it if it doesn't or update it if it does.

We're thinking about simplifying this scenario by introducing commands with a new verb named ensure. For example, to ensure that a particular site collection exists, instead of executing a combination of spo site list/spo site get, spo site add and spo site set, you'd execute spo site ensure with the necessary parameters which would automatically verify if the particular site exists and matches your configuration. If the site doesn't exist, it would create it. If it does, the command would check if the properties you specified match the retrieved site and update them if necessary.

Would you find this useful? Do you have other ideas or feedback that we should take into account when implementing this? We'll start to implement this idea on the spo site commands.

[garrytrinder]

By implementing ensure commands, we would be creating idempotent commands that would reduce the boilerplate in scripts, something which the Azure CLI already implements.

Consider the below script, this would create a site, create a site field, create a content type, add a field to the content type, create a list and finally add the content type to the list.

spo site ensure ...
spo field ensure ...
spo contenttype ensure ...
spo contenttype field ensure ...
spo list ensure ...
spo list contenttype ensure ...

Using the ensure command approach, this would enable the above script to run again against the site without the need for checking the existence of the objects within the executing script, the command would do that and either ignore or update the object if some values are changed in between script executions.

[phillipharding]

Definitely a great idea, almost without exception the scripts I write using CLI are designed to be idempotent, any ensure type command would be a great benefit and help to reduce unnecessary boilerplate 🤓

Typically my use cases revolve around the assets already mentioned by @garrytrinder but I'd also add

spo folder ensure ...
spo customaction ensure ...

[garrytrinder]

Great to hear that this would benefit you @phillipharding and thank you for giving us more commands that would benefit from an ensure variant 👍🏻

[phillipharding]

While on the ensure subject, many times the Site Assets library isn't created when creating a modern site, which means you have to test and create, I've used the following script for this;

function EnsureSiteAssetsLibrary {
	param (
		[Parameter(Mandatory)][string]$siteUrl
	)

	<#
		send a HTTP POST request to:
		https://<tenant>.sharepoint.com/sites/<sitename>/_api/web/Lists/EnsureSiteAssetsLibrary/
		which returns an SPList
	#>
	$list = $null

	Write-Host "-> Ensure Site Assets library: $siteUrl" -ForegroundColor White
	$lists = o365 spo list list --webUrl "$siteUrl" -o json | ConvertFrom-Json
	if (($null -ne $lists) -and ($null -ne $lists.value)) {
		$list = $lists.value | Where-Object { $_.Title -eq "Site Assets" }
	}

	if ($null -eq $list) {
		Write-Host "...Creating Site Assets library" -ForegroundColor White

		try {
			$resource = ($siteUrl -split "/")[2]
			$accessToken = o365 util accesstoken get --new --resource "https://$resource/"
		}
		catch {
			throw "!! Unable to get AccessToken for EnsureSiteAssetsLibrary at '$siteUrl'`nERROR: $_"
		}
		try {
			$headers = @{ "Authorization" = "Bearer $accessToken"; "Accept" = "application/json;odata=nometadata" }
			$endpoint = "$siteUrl/_api/web/Lists/EnsureSiteAssetsLibrary/"
			$response = (Invoke-RestMethod -Uri $endpoint -Headers $headers -Method POST)
			$list = $response

			Write-Host "...Created: $($list.Id)" -ForegroundColor Yellow
		}
		catch {
			throw "!! Unable to EnsureSiteAssetsLibrary at '$siteUrl'`nERROR: $_"
		}
	} else {
		Write-Host "...Already exists: $($list.Id)" -ForegroundColor Yellow
	}

	$list
}

Might this be a candidate for some type of ensure siteassetlibrary command?

[waldekmastykarz]

@phillipharding I think this would make a great sample for the CLI docs (https://pnp.github.io/office365-cli/examples/). Would you like to submit it as a PR? Don't worry about the bash equivalent. We can add that later.

[phillipharding]

@waldekmastykarz sure, do I create an issue first then the PR or just create the PR? in the docs/manual/docs/examples/spo/ folder?

[waldekmastykarz]

Just create the PR. In the PR message you could reference this discussion. Thank you! ❤️

[Adam-it]

😍love the idea... @waldekmastykarz, @garrytrinder what do you think about making this 'official' and add issue to track it and issues for each command?

[waldekmastykarz]

We already have spo site ensure. Before we proceed, we should see if there's any usage and if there's interest for more, we should see which patterns would be intuitive (ensure web, team, list, etc).