[automation] ISHRemote 0.4 publicly available on www.powershellgallery.com

Introduction...

 All of the source code, issues, releases, milestones is all on https://github.com/sdl/ISHRemote 

ISHRemote is a business automation module on top of SDL Knowledge Center Content Manager (LiveContent Architect, Trisoft InfoShare).

Your first commands could look like

Install-Module ISHRemote -Repository PSGallery -Scope CurrentUser -Force
$ishSession = New-IshSession -WsBaseUrl https://example.com/ISHWS/ -PSCredential Admin
$ishSession

This library is a relatively thin client layer on top of the business API.

  • -WhatIf/-Confirm are implemented on write operations.
  • Add-* cmdlets will immediately create objects in the CMS, and return you an in-memory result holding descriptive identifiers to continue the pipeline.
  • Remove-* cmdlets will not return any in-memory result.
  • Set-*Move-*Publish-* and Stop-* cmdlets will immediately update existing objects in the CMS, and return you an in-memory result holding descriptive identifiers to continue the pipeline. You cannot use Set-* for creation.
  • New-* cmdlets will create in-memory objects to locally update and then potentially pass to Add-* and Set-* cmdlets.
  • Get-* and Find-* cmdlets return existing objects present in the CMS, and return you an in-memory result holding descriptive identifiers to continue the pipeline.
    • The Find-* cmdlets was built on top of the API Find operation, which triggers a query to find all objects matching the filter criteria.
    • The Get-* cmdlets was built on top of the API Retrieve/Get operations, which trigger a query given object identifiers and then potentially extra filter criteria.
  • Supports Enable-ISHIntegrationSTSInternalAuthentication/Disable-ISHIntegrationSTSInternalAuthentication as implemented by ISHDeploy.

Other things worth mentioning

  • Developped Kojak/13.0.0 but will work on 2016/12.0.x and 2014/11.0.x
  • A lot of Pester-based smoke tests, but probably not enough yet.
  • New-IshSession received optional switch -IgnoreSslPolicyErrors. IgnoreSslPolicyErrors presence indicates that a custom callback will be assigned to ServicePointManager.ServerCertificateValidationCallback. Defaults false of course, as this is creates security holes! But very handy for Fiddler usage though.
  • Added Get-IshTypeFieldDefinition and Compare-IshTypeFieldDefinition as web service based alternative for TriDKXmlSetup Full Export, you can even compare setups.

The one where we…

IshSession - New and Changed

  • Add Test-IshSession which wraps New-IshSession and its variation in a simple test resulting in $true or $false. On the side this is a simple cmdlet that checks if ISHWS and ISHSTS (or other STS) is up-and-running. Together with a simple .ASP call all FrontEnd services can be tested. [#12]
    These lines of code activate and hence test the WebServices (ISHWS-activation), SecureTokenServices (ISHSTS-activation) and validates the credentials in the 'InfoShare' database (ConnectionString-activation). The extra .ASP line triggers WebClient (ISHCM-activation) and the COM+ application (Trisoft-InfoShare-Author).

      Test-IshSession -WsBaseUrl "https://example.com/ISHWS/" -IshUserName "admin" -IshPassword "admin" -IgnoreSslPolicyErrors -Verbose
      Invoke-WebRequest -Uri "https://example.com/ISHCM/InfoShareAuthor.asp" -UseBasicParsing
    

IshBaseline - New and Changed

  • Added CRUDF cmdlets for baseline handling. So introducing Add-IshBaselineGet-IshBaselineSet-IshBaselineRemove-IshBaseline and Find-IshBaseline. Allowing you to retrieve you baselines, find the active/inactive ones and toggle their status. [#2]
  • Added CRUD cmdlets for baseline entry handling. [#2]
    • Add Get-IshBaselineItem which allows you to see the versions of the saved baseline entries as you would see them in Publication Manager
    • Add Set-IshBaselineItem which allows you to add and update existing baseline entries. So specifically set version for chosen content objects identified by LogicalId.
    • Add Remove-IshBaselineItem which allows you to remove baselines entries of content objects identified by LogicalId.

More New and Changed

  • New-IshSession uses TLS, TLS11 and TSL12 security protocols. SSL3 is removed. Verified with ELBSecurityPolicy-TLS-1-2-2017-01 [#5]
  • Add parameter argument completion for interactive usage. IshTypeFieldDefinition is now available on every IshSession because of #3. So why not use the field names on ...MetadataField cmdlets and the available LOV on ...LovValue cmdlets when a valid -IshSession is specified. [#11]
    For example the last parameters get assistance by using Ctrl-Space or Tab. Note however that a valid $ishSession needs to be available on the command line already.
    • Add-IshLovValue -IshSession $ishSession -LovId FirstLetterPlusCtrlSpace
    • Set-IshMetadataField -IshSession $ishSession -Name FirstLetterPlusCtrlSpace
  • Get-IshTypeFieldDefinition should warn that custom fields will be missing. If you really want to load your custom fields setup, you can use the -TriDKXmlSetupFilePath parameter. (To get your TriDKXmlSetup file, you should execute C:\InfoShare\App\Database\Common\DatabaseIndependent\Examples\Full-Export\RunSetup.bat on the WebApp server). [#16]
    1. When no -IshSession is provided, the highest local resource is loaded (in practice 12.0.0 standard fields)
    2. When an -IshSession is provided but target system is older than 13.0.0, the highest matching local resource is loaded (in practice 12.0.0 standard fields)
    3. When an -IshSession is provided but target system is 13.0.0 or higher. The Settings25.RetrieveFieldSetupByIshType API call is used, which includes standard and custom fields.
  • Tuned Get-IshTimeZone (without -Count parameter) rendering the application server information like timezone, utc-offset and daylight-savings-time. This allows easy load balancer testing. [#13]
  • The API doesn't allow all fields on the various Create/Read/Update/Delete/Find actions. For example providing a PASSWORD for a user is fine upon Create, but it is not allowed during Read operations. There are many more of these fields where system behavior or business rules are attached. [#4]
    • In the past these were hard coded. Now they are routed over the IshTypeFieldSetup class which on 2016/12.0.x and earlier can be initialized by the implicit default or custom TriDKXmlSetup file or starting from Kojak/13.0.0 there is a new Settings25.RetrieveFieldSetupByIshType API call. Remember cmdlets Get-IshTypeFieldDefinition and Compare-IshTypeFieldDefinition available since 0.3
    • The ISHRemote client library protects you by default, but if you want to trigger API errors by specifying IShSession.StrictMetadataPreference inspired by $DebugPreference with similar values
      • SilentlyContinue Client-side silent filtering of nonexisting and unallowed fields. (e.g Nice for repository folder syncing with mismatching metadata setup)
      • Continue Client-side filtering of nonexisting and unallowed fields displaying a Write-Verbose message but still continues. Default for 13.0.0 as Settings25.RetrieveFieldSetupByIshType API is available.
      • Off Client-side filtering of nonexisting and unallowed fields is turned off. No handling but simply executes the API call, most likely resulting in a Write-Error. This allows api/pester tests like IshUser PASSWORD field should not allowed to be read. Default for 11.0.x and 12.0.x.
    • Set-IshMetadataField that creates metadata fields for Add-*/Set-* cmdlets (Create/Update calls) now removes all value type variations of a field from the collection when adding a new. For example when the collection contains FAUTHOR=VUSERADMIN, a Set-IshMetadataField FAUTHOR=Admin will remove the previous Element value type and add the Value value type. [#14]

Housekeeping

  • It should be easier to compile the project. Refreshed all ServiceReferences to Kojak/13.0.2803.0 test build and normalized to https://ish.example.com/ISHWS/ including STS urls in http and https flavours. Tuned manifest generator. Code Drift, aligning with legacy Trisoft.Automation module changes for Kojak/13.0.0 (inc up to C59893) [#7|#1]
  • Added more Pester Tests, current count is Passed: 497 Failed: 0 Skipped: 2 Pending: 0 Inconclusive: 0 where the skipped are about SslPolicyErrors testing.

Feedback...

Any feedback is welcome. As a comment here, in an email. What do you like, what are you missing, etc

Please log a GitHub issue, make sure you submit your version number, expected and current result,...