In this second follow-up blog post of the Tridion Docs webinar 'Automating tasks in SDL Tridion Docs using PowerShell', I will share a short summary of the 'Business Automation part using ISHRemote on the CMS', the resources and the script used during this webinar start @ 17:00 in the below recording.

This blog post assume you are familiar with the first part as described on Automating tasks in SDL Tridion Docs using PowerShell - Getting started with Microsoft PowerShell

Open Source and Easy Install

ISHRemote is a Business automation module on top of SDL Tridion Docs Content Manager (Knowledge Center Content Manager, LiveContent Architect, Trisoft InfoShare). It is fully open-sourced with Pester-based tests on https://github.com/sdl/ISHRemote

ISHRemote is a client-side PowerShell module constructed close to the "Web Services API" to:

  • allow business logic automation ranging from triggering publishing into the continuous integration pipeline over legacy data correction up to provisioning
  • show case code examples and API best practices

ISHRemote can be easily installed as we publish a tested & signed version of this package to the Microsoft-maintained public package management system called https://www.powershellgallery.com/packages/ISHRemote/

Remember that your PowerShell (.PS1) script file is your automation. Thereby avoiding manual routine work, making it trustworthy and repeatable.

Webinar Script

Inside the script, you will also find some comments and additional links to specific online resources.

##
## SETUP
## - Having Windows Management Framework v5 available
## - Run as Administrator on 'Windows PowerShell ISE' in the Start Menu
# Add-windowsFeature powershell-ise  # Only required on Windows Server OS
Set-Executionpolicy -Scope CurrentUser -ExecutionPolicy UnRestricted
Install-Module ISHRemote -Repository PSGallery -Scope CurrentUser
 
##
## FIRST API CALL
##
$ishSession = New-IshSession -WsBaseUrl https://sdldoc01.sdlproducts.com/ISHWS/ -PSCredential ddemeyer
 
##
## USING POWERSHELL ISE COMMANDS AND HELP
## - New-IShSession
## - Show the parameter groups
## - '?' show the examples
## - Common Parameters like '-verbose' per cmdlet or for the PowerShell session
Get-Help New-IshSession -Full
New-IshSession -WsBaseUrl https://sdldoc01.sdlproducts.com/ISHWS/ -PSCredential ddemeyer -Verbose
 
##
## PUBLISH AND DOWNLOAD
##
$ishObject = Publish-IshPublicationOutput -IshSession $ishSession -LogicalId "GUID-48F387A3-28DF-45F2-A1DF-102A703F0E33" -Version 2 -LanguageCombination "en-us" -OutputFormat "PDF (XPP A4)"
Start-Sleep -Seconds 60
Get-IshPublicationOutputData -IshSession $ishSession -IshObject $ishObject -FolderPath "C:\TEMP\Demo\"
 
##
## WHICH CARD TYPES AND FIELDS ARE THERE
##
# demo-friendly, only ask for credentials once per session
if ($credentials -eq $null) { $credentials = Get-Credential ddemeyer }
$ishSession = New-IshSession -WsBaseUrl https://sdldoc01.sdlproducts.com/ISHWS/ -PSCredential $credentials
# retrieve dynamic type and field setup over web services
Get-IshTypeFieldDefinition -IshSession $ishSession
# retrieve List-Of-Values, allowed dropdown values
Get-IshLovValue -IshSession $ishSession -LovId @("DLANGUAGE","DILLUSTRATIONTYPE", "DSTATUS") | Out-GridView
 
##
## CREATE USER
##
# Building the metadata
$metadata = `
Set-IshMetadataField -IshSession $ishSession -Name "FISHUSERDISPLAYNAME" -Value "Frank Demo" |
Set-IshMetadataField -IshSession $ishSession -Name "FISHEMAIL" -Value "Frank.Demo@sdl.com" |
Set-IshMetadataField -IshSession $ishSession -Name "FISHUSERLANGUAGE" -Value "en-us" |
Set-IshMetadataField -IshSession $ishSession -Name "PASSWORD" -Value "demo" |
Set-IshMetadataField -IshSession $ishSession -Name "FUSERGROUP" -Value "Default Department" |
Set-IshMetadataField -IshSession $ishSession -Name "FISHUSERROLES" -Value "Reviewer, Author" |
Set-IshMetadataField -IshSession $ishSession -Name "FISHUSERTYPE" -ValueType Element -Value "VUSERTYPEINTERNAL"
# Creating the internal user
$ishobject = Add-IshUser -IshSession $ishSession -Name "fdemo" -Metadata $metadata
# Verifying the user
Test-IshSession -WsBaseUrl https://sdldoc01.sdlproducts.com/ISHWS/ -IshUserName fdemo -IshPassword demo
# Remove-IshUser -IshSession $ishSession -IshObject $ishObject # To clean up unlinked demo users

##
## REPORTING ON USERS
##
# Auxiliary function to make fields easily retrievable
Function Add-Properties {
param ([Parameter(ValueFromPipeline=$true)]$ishObject)
  foreach($ishField in $ishObject.IshField)
  { $ishObject = $ishObject | Add-Member -MemberType NoteProperty -Name $ishField.Name -Value $ishField.Value -PassThru -Force }
  Write-Output $ishObject
}
# Which USER metadata to retrieve
$metadata = Set-IshRequestedMetadataField -IshSession $ishSession -Name FISHUSERDISPLAYNAME -Level None |
            Set-IshRequestedMetadataField -IshSession $ishSession -Name FISHUSERDISABLED -Level None |
            Set-IshRequestedMetadataField -IshSession $ishSession -Name FISHUSERROLES -Level None
# Retrieve all user objects with the requested metadata and enrich the user objects with properties
$users = Find-IshUser -IshSession $ishSession -RequestedMetadata $metadata | ForEach-Object { Add-Properties $_ }
# Render using the standard Out-GridView cmdlet
$selectedUsers = $users | Select-Object -Property FISHUSERDISPLAYNAME,FISHUSERDISABLED,FISHUSERROLES |
                 Out-GridView -OutputMode Multiple -Title "Select one or more entries..."
# Pass the selected user objects to the standard Export-Csv cmdlet
$selectedUsers | Export-Csv -Path "C:\TEMP\Demo\selectedUsers.csv"
# Show off in Microsoft Excel
 
##
## ITERATING FOLDERS (Find vs Recurse-Folders vs Time-Slice)
##
# Which Folder metadata to retrieve
$metadata = Set-IshRequestedMetadataField -IshSession $ishSession -Name "FNAME"
# Recursively navigate the folders, printing the name of the folder
Get-IshFolder -IshSession $ishSession -RequestedMetadata $metadata -FolderPath "\System\" -Recurse |
Get-IshMetadataField -IshSession $ishSession -Name "FNAME"
# Recursively navigate the folders, printing the returned content objects (DocumentObj-input)
Get-IshFolder -IshSession $ishSession -RequestedMetadata $metadata -FolderPath "\System\" -Recurse |
Get-IshFolderContent -IshSession $ishSession
 
##
## RETRIEVE XML SETTINGS AS FILES
##
Get-Help Get-IshSetting -Examples
 
##
## SYNCHRONIZE USER FROM ACTIVE DIRECTORY INTO TRIDION DOCS PROFILES
##
#See https://gist.github.com/ddemeyer/c80ef8a5a6025eb2267a9c1a91c3a9c4

 

 

Even more appetite to read, hat tip to https://sarafian.github.io/sdl/knowledge-center/content-manager/2016/10/17/introduce-ishremote.html

 

-Dave

Anonymous