Libraries and Scripts

https://blog.najmanowicz.com/2014/10/26/sitecore-powershell-extensions-persistent-sessions/Modules may contain PowerShell Script Library items and PowerShell Script items. The following section outlines some of the basic concepts you need to know for the following chapters.

PowerShell Script Library

The library items represent a collection of scripts, and may be structured with one or more levels of libraries.

Naming Convention

You'll find that with the Integration Points some libraries should be created with specific names (i.e. Content Editor, Control Panel).

As a best practice we recommend that the Functions library consist of reusable scripts containing PowerShell functions (i.e. Do-Something) while other libraries contain the solution specific scripts (i.e. MakeScriptingGreatAgain).

Example: The following demonstrates the use of the Functions script library containing Get-DateMessage.

# /sitecore/system/modules/powershell/script library/spe rocks/functions/get-datemessage
function Get-DateMessage {
  "The current date and time is: $(Get-Date)"
}
# /sitecore/system/modules/powershell/script library/spe rocks/alerts/show-datemessage
Import-Function -Name Get-DateMessage

Show-Alert (Get-DateMessage)

Some names we've used included:

  • Beginner Tutorials

  • Content Editor

  • Content Maintenance

  • Content Interrogation

  • Development

  • Event Handlers

  • Functions

  • Internal

  • Page Editor

  • Pipelines

  • Profile and Security

  • Reports

  • Script Testing

  • Tasks

  • Toolbox

  • User Interaction

  • Web API

Many of the libraries are integration points for the module. When the integration point wizard runs, you will see that these can be generated automatically.

Fields

Interactive : The following fields support the two custom rules as well as a variety of out-of-the-box rules.

  • ShowRule (Show if rules are met or not defined) - typically controls visibility of integration points.

    • PowerShell

      • where calling the specific PowerShell script returns $True #1388

      • where calling the specific PowerShell script returns value that compares to value #1388

      • where specific persistent PowerShell session was already initiated #153

        • Pairs with the PersistentSessionId field on the Script item template.

      • where specific persistent PowerShell session was already initiated and has the specific variable defined and not null

        • Pairs with the PersistentSessionId field on the Script item template.

      • where exposed in a specific view #156

        • Used with the command Show-ListView to allow actions to be visible only on views with a corresponding name.

    • PowerShell ISE

      • when length script length is compares to number characters long #383

      • when the edited script is in a state #383

    • PowerShell Security

      • where the current user has delegated access #1283

      • where the current user is a member of the specific role, either directory or through inheritance #1036

    • PowerShell System

      • where the Sitecore.config numeric setting name compares to number #1385

      • where the Sitecore.config string setting name compares to value #1385

      • where the Web.config numeric AppSetting name compares to number #1385

      • where the Web.config string setting name compares to value #1385

  • EnableRule (Enable if rules are met or not defined) - typically controls enabled state of integration points.

    • Same as above

Rules Usage

There are a number of use cases for the EnableRule and ShowRule.

  • If there is a UI component the ShowRule can be used to ensure it appears while the EnableRule can toggle when it can be clicked.

  • If there is no UI component, the EnableRule is used to determine when the script should be executed; useful to limit creation of PowerShell runspaces.

ShowRule
EnableRule

Content Editor Context Menu

Content Editor Context Menu

Content Editor Gutter

Content Editor Insert Item

Content Editor Ribbon

Content Editor Ribbon

Content Editor Warning

DataSources

Event Handlers

ISE Plugin

ISE Plugin

Reports

Reports

Reports List View Action

Reports List View Action

Reports List View Export

Reports List View Export

Page Editor Notification

Page Editor Experience Button

Pipelines

Tasks

Toolbox

Workflow Action

Rule Field Report

Use the below report to help you identify which PoweShell Script and Script Library items contain rules that could alter the behavior or visibility.

<#
    .SYNOPSIS
        Report to find all Script and Script Library items with Show Rules or Enable Rules
    .DESCRIPTION
        This report searches for all items based on Script and Script Library templates
        and identifies those that have Show Rule or Enable Rule fields populated.
#>

function Render-RuleField {
    param(
        $Field
    )
    
    $renderer = New-Object Sitecore.Shell.Applications.Rules.RulesRenderer ($Field)
    $sw = New-Object System.IO.StringWriter
    $renderer.Render($sw)
    
    $sw.ToString()
}

# Define the template IDs for Script and Script Library
$scriptTemplateId = "{DD22F1B3-BD87-4DB2-9E7D-F7A496888D43}"
$scriptLibraryTemplateId = "{AB154D3D-1126-4AB4-AC21-8B86E6BD70EA}"
# Initialize results collection
$results = @()
# Get all Script items
Write-Host "Searching for Script and Script Library items..." -ForegroundColor Green
$scriptItems = Get-ChildItem -Path "master:\sitecore\system\Modules\PowerShell" -Recurse |
    Where-Object { $_.TemplateID -eq $scriptTemplateId -or $_.TemplateID -eq $scriptLibraryTemplateId } |
    Where-Object { ($_.ShowRule -and $_.ShowRule -ne "<ruleset />") -or ($_.EnableRule -and $_.EnableRule -ne "<ruleset />") }

# Display results
if($scriptItems.Count -gt 0) {
    $scriptItems | Show-ListView -Property @(
        @{Label="Item Name"; Expression={$_.Name}},
        @{Label="Template"; Expression={$_.Template.Name}},
        @{Name="ShowRule";Expression={Render-Rule -Rule $_.ShowRule}},
        @{Name="EnableRule";Expression={Render-Rule -Rule $_.EnableRule}},
        @{Label="Item Path"; Expression={$_.ItemPath}},
        @{Label="Item ID"; Expression={$_."Item ID"}}
    ) -Title "Scripts and Script Libraries with Show/Enable Rules" `
      -InfoTitle "Found $($results.Count) item(s)" `
      -InfoDescription "Script and Script Library items that have Show Rule or Enable Rule configured"
} else {
    Show-Alert "No items found with Show Rule or Enable Rule configured."
}

PowerShell Script

The script items represent the code that will be executed.

Naming Convention

There are three conventions that we recommend you follow which are shown with an example below.

  • Title Casing - This should be used when the name will be exposed in places such as the Content Editor, script library names, and Reports root directory.

  • Sentence casing - This should be used when the name is long and will not be visible to the user or is a report with a very long name.

  • Noun-Verb - This should be used when the script is stored within the Functions script library and will be imported using the command Import-Function.

Fields

Interactive : Refer to the description shown for PowerShell Script Library fields.

Scripting

  • Script (Script body) : This is a multi-line text than should be edited using the PowerShell ISE application.

Session Persistency

  • PersistentSessionId (Persistent Session ID) : Context scripts using this ID will execute in a single session and be reused; leaving empty will cause the session to be discarded after execution. This value should be used for rules requesting the session ID.

  • Use this field in combination with the rules related to Persistent Session.

  • Read more about how Adam implemented this feature here: https://blog.najmanowicz.com/2014/10/26/sitecore-powershell-extensions-persistent-sessions/

PreviousModulesNextIntegration Points

Last updated