Background

Have you ever needed to update a single field on a Sitecore item across multiple environments without affecting or changing the entire item?

This is not a replacement for Unicorn, as Unicorn provides a great way to serialize entire Sitecore items. However if you only want to change a single field value on a item and you want these changes reflected from from you local development environment all the way to QA and Production, Unicorn will only overwrite all fields for serialized items.

In a nutshell

This PowerShell library provides support with writing Sitecore PowerShell scripts, decoupled from Sitecore ISE that can be executed once within a CI/CD pipeline. Additionally custom event logging is used to prevent previously executed scripts from unnecessarily running.

Getting started

Prerequisites

  1. SPE (Sitecore Powershell Extensions) must be installed on Sitecore
  2. Download SPE Remoting Library. This must be the same version of the SPE module installed on Sitecore.
  3. SPE Remoting must be enabled. See patch config as an example: https://github.com/ethisysltd/Sitecore-Powershell-Remote-Tools/blob/master/Configs/ShieldsDown.config

The SPE Remoting Library enables PowerShell scripts to be executed from a remote location from the Sitecore CM instance. ~
Get SPE Module and Remoting Library here:

SPE Remote Tools Download

  1. Pull the repository here: https://github.com/ethisysltd/Sitecore-Powershell-Remote-Tools
  2. Extract the SPE Remoting library into the into the PowerShell Extensions folder within its relevant version folder.
    Example: .\Sitecore-Powershell-Remote-Tools\PowershellExtensions\v6.1.1\SPE\SPE.psm1

Overview

The key folders here are explained below;

_RunAlways
All PowerShell scripts (*.ps1) will be run on the remote server for each time this library is executed.

_Current
Only PowerShell scripts (*.ps1) that have not run or have run but have changed since the last run will be executed. *Once per change

Functions
A folder to store reusable functions for any of the scripts that will be executed on the remote server.

This library creates a PowerShell ScriptBlock payload which contains the individual script and reusable functions along with additional configurations.

Archived
Somewhere to archive scripts that have run across all environments and you no longer need them in the _Current folder. An archive could happen once a production release is complete.

The file system should look similar to this.

* Once per change
Each time a script is executed on an environment this is logged with hash value of of the script.

  • If an script has already been executed on an environment and not changed, it won’t run again.
  • If an script has already been executed on an environment and the script contents have been changed, the script will run again.

Execute

To execute the library its simple. Just run the SPE-Executer.ps1 with environment details you wish to execute against.

-SitecoreInstanceUri http://my-sitecore-cm-instance.com `
    -SitecoreUsername "admin" `
    -SitecorePassword "b"
    -PathToSPEModule "{Remoteing-Library-Path}" # Default is .\PowershellExtensions\v5.0\SPE

Example Scripts

Now when writing SPE scripts you don’t need to worry about connections to Sitecore or using Sitecore PowerShell ISE.
Its recommended to create child folders within _Current and _RunAlways to help organise and categories your scripts.

There are a couple examples within the repository in _Current and _RunAlways folders that reference shared functions.
This is _Current\02-TestScripts\01-Home-Content-Update.ps1

# ---------------------------------------------------------------------------------- 
# Sitecore Home
# ---------------------------------------------------------------------------------- 
# Items: 
#   /sitecore/content/Home - {110D559F-DEA5-42EA-9C1C-8A5DF7E70EF9}

$dateTime = Get-Date -Format "dddd MM/dd/yyyy HH:mm"
Update-SitecoreItemContent `
    -ItemId "{110D559F-DEA5-42EA-9C1C-8A5DF7E70EF9}" `
    -FieldUpdates @{
        "Title" = "Title field value updated at $dateTime"
        "Text" = "Text field value updated at $dateTime"
        }

The script above updates the default Sitecore Home item using the shared function Update-SitecoreItemContent.

Summary

This library was originally created to assist with automating content changes across environments, but as this all leverages SPE this could be used to automate anything Sitecore within a CI/CD pipeline.

  • Rebuilding the Search Index
  • Adding a User or Role
  • Performing a Task such as a Site publish.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.

%d bloggers like this: