You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
State of the world, Tridion Docs 15.1/15.1.0 and ISHRemote v8.0
Continuation of #112 where Add-IShBackgroundTask cmdlet was added to do two things:
Triggering a generic event over ParameterGroup where the parameter -RawInputData allows a knowledgeable user to generate the message towards the BackgroundTask handler
Triggering a SMARTTAG event for all kind of content objects over IshObjectsGroup which in turn triggers a DocumentObj25.RaiseEventByIshLngRefs API call. This parameter group was more friendly as the cmdlet and/or API call did the heavy lifting on what should go in the InputData section of the message which will be put on the BackgroundTask queue.
Future Release Notes Content
The contract of what you put on the BackgroundTask message queue under InputData and how the BackgroundTask handler interprets it is up to the implementer. For the standard product howvever there are only a handful of InputData contracts. An overview where you'll notice that the client triggering the message prefers a minimal contract, so providing the least amount of information as possible.
A. Deprecated, hardly used, commaspace-seperated language (ishlngref). The event that comes to mind here is SMARTTAG. Although technically the BackgroundTask handler uses IshObjectsWithLngRef, so the DocumentObj25.RaiseEventByIshLngRefs API calls takes care of generating the right InputData and submitting it - something to refactor in this issue.
B. Single <ishobject> used by IWrite plugin OnMultiFieldChangeSendEvent to send a message to the BackgroundTask queue for events like DITADELIVERYUPDATEPUBLICATIONMETADATA and now SYNCHRONIZEMETRICS/CLEANUPMETRICS. Up till 15.1/15.1.0 the minimal parameters passed were
Since 15.1/15.1.0 the content object variations where extended with ishversionref and ishlogicalref. And since 15.1/15.1.0 there are Baseline IWrite/IDelete plugins which in turn allow the ishbaselineref variation.
C. Plural <ishobjects> as message variation for events like CREATETRANSLATIONFROMLIST. Since 15.1/15.1.0 this one can be used for SYNCHRONIZEMETRICS where the specific language object identified by ishlngref will be specifically synchronized by the BackgroundTask handler.
D. Plural <ishobjects> as message variation for events like SYNCHRONIZEMETRICS. Since 15.1/15.1.0 this one can be used for SYNCHRONIZEMETRICS where all versions, languages and resolutions of every ishref (LogicalId) would be expanded by the BackgroundTask handler to then synchronize like option C above.
Since the single <ishobject> and plural <ishobjects> variations are important for the standard Tridion Docs product, we would like to add the generation of the InputData in the cmdlet to avoid an outside calculation to pass to the parameter -RawInputData.
Adding parameter -InputDataTemplate with the following options
IshObjectsWithLngRef covers above option A and C, so InputData reads <ishobjects><ishobject ishtype='ISHMasterDoc' ishref='GUID-X' ishlngref='45679'>...
IshObjectWithLngRef covers above option B, so InputData reads <ishobject ishtype='ISHMasterDoc' ishref='GUID-X' ishlogicalref='45677' ishversionref='45678' ishlngref='45679'> or <ishobject ishtype='ISHBaseline' ishref='GUID-X' ishbaselineref='45798'>
EventDataWithIshLngRefs covers aove option E, so InputData reads <eventdata><lngcardids>516316, 516319</lngcardids></eventdata>
Adding optional parameter -HashId with the following options
If not specified, the default, this means that the generated InputData or incoming -RawInputData is passed through the Standard Library 2.0 - SHA256 hash function and will be passed to the BackgroundTask queue as the HashId. In turn messages with an identical hash id will only be executed once by the BackgroundTask service.
Some explicit value, which could be a folder id or user id. An option matching customizations over parameter -RawInputData. Note that the maximal HashId length is 80 characters.
Passing the explicit value empty string so "", means that the parameter will be ignored and an empty value will be passed. The option if you explicitly want to regenerate messages and force multiple asynchronous executions by the BackgroundTask service.
Make sure to add below examples to the Release Notes and Get-Help as well!
Refactor SMARTTAG to use BackgroundTask25.CreateBackgroundTaskWithStartAfter, removing an API call dependency for ISHRemote (still used by Client Tools though). If refactor fails, we could consider adding -InputDataTemplate LngRefs to cover the SMARTTAG commaspace-seperated lngrefs legacy scenario over DocumentObj25.RaiseEventByIshLngRefs.
Remove the DevideListInBatchesBy...(_retrievedIshObjects, IshSession.MetadataBatchSize); functions in this cmdlt. Otherwise you get 2 ZIP files for one FOLDEREXPORT in the below implementations :)
Manually test SMARTAG on a very big folder, larger than IshSession.MetadataBatchSize so 999 by default, because we are removing the DevideListInBatchesBy... code from this cmdlet. If refactor fails, a better code example that aggregates per 999 could be shown in the examples.
Add optional parameter InputDataTemplate with option IshObjectsWithLngRef covering content objects and publication outputs to IshObjectsGroup parameter group.
Add optional parameter InputDataTemplate with option IshObjectWithLngRef covering content objects, publication outputs and baseline to IshObjectsGroup parameter group.
Add optional parameter InputDataTemplate with option IshObjectsWithIshRef covering content objects and publication outputs to IshObjectsGroup parameter group.
Add optional parameter InputDataTemplate with option IshObjectsWithIshRef covering content objects to IshObjectsGroup` parameter group.
Add optional -StartAfter parameter to IShObjectsGroup parameter group if DocumentObj25.RaiseEventByIshLngRefs is rewritten to BackgroundTask25.CreateBackgroundTaskWithStartAfter
Add optional -EventDescription parameter to IShObjectsGroup parameter group if DocumentObj25.RaiseEventByIshLngRefs is rewritten to BackgroundTask25.CreateBackgroundTaskWithStartAfter. Make sure to adapt the example. Make this an optional and use the -EventType as -EventDescription to remain backward compatible.
Add optional parameter -HashId. When not specified, the default, the implicit HashId will calculate a SHA256 (or CRC32) based on the generated InputData to make sure that the BackgroundTask handler only picks up one of the generated messages. When set to empty string "", an empty HashId will be passed downstream, otherwise the give value. Double check what happens if a too long (max is 80 characters on 15.1/15.1.0 release) is passed, probably rethrow the API exception. Add this to IshObjectsGroup and ParameterGroup parameter groups.
Add examples, see lower to enrich Get-Help of this cmdlet
Add Pester test varitions for all of the above. For the InputDataTemplate use event type TESTBACKGROUNDTASK, and retrieve the InputData immediately and check its format. Avoid SYNCHRONIZEMETRICS for testing. Same for HashId.
Examples
EXAMPLE SMARTTAG
Add BackgroundTask with event type "SMARTTAG" for the objects located under the "General\MyFolder\Topics" path. One BackgroundTask message will appear per folder containing a list of all latest version English content objects in the InputData of the message.
EXAMPLE PLURAL SYNCHRONIZEMETRICS
Rebuilding the Metrics subsystem is optimally done in the order of Images, Topics and Publications. Add BackgroundTask with event type "SYNCHRONIZEMETRICS" for the objects located under the "General" path (Data folder). One BackgroundTask message will appear per folder containing a list of LogicalIds in the InputData of the message.
EXAMPLE SINGLE SYNCHRONIZEMETRICS
Add BackgroundTask with event type "SYNCHRONIZEMETRICS" for the objects located under the "General\MyFolder\Topics" path. One BackgroundTask message will appear per content object holding the latest version English content object as single InputData of the message.
State of the world, Tridion Docs 15.1/15.1.0 and ISHRemote v8.0
Continuation of #112 where
Add-IShBackgroundTaskcmdlet was added to do two things:ParameterGroupwhere the parameter-RawInputDataallows a knowledgeable user to generate the message towards the BackgroundTask handlerSMARTTAGevent for all kind of content objects overIshObjectsGroupwhich in turn triggers a DocumentObj25.RaiseEventByIshLngRefs API call. This parameter group was more friendly as the cmdlet and/or API call did the heavy lifting on what should go in theInputDatasection of the message which will be put on the BackgroundTask queue.Future Release Notes Content
The contract of what you put on the BackgroundTask message queue under
InputDataand how the BackgroundTask handler interprets it is up to the implementer. For the standard product howvever there are only a handful ofInputDatacontracts. An overview where you'll notice that the client triggering the message prefers a minimal contract, so providing the least amount of information as possible.A. Deprecated, hardly used, commaspace-seperated language (
ishlngref). The event that comes to mind here isSMARTTAG. Although technically the BackgroundTask handler usesIshObjectsWithLngRef, so the DocumentObj25.RaiseEventByIshLngRefs API calls takes care of generating the rightInputDataand submitting it - something to refactor in this issue.B. Single
<ishobject>used by IWrite pluginOnMultiFieldChangeSendEventto send a message to the BackgroundTask queue for events likeDITADELIVERYUPDATEPUBLICATIONMETADATAand nowSYNCHRONIZEMETRICS/CLEANUPMETRICS. Up till 15.1/15.1.0 the minimal parameters passed wereSince 15.1/15.1.0 the content object variations where extended with
ishversionrefandishlogicalref. And since 15.1/15.1.0 there are Baseline IWrite/IDelete plugins which in turn allow theishbaselinerefvariation.C. Plural
<ishobjects>as message variation for events likeCREATETRANSLATIONFROMLIST. Since 15.1/15.1.0 this one can be used forSYNCHRONIZEMETRICSwhere the specific language object identified byishlngrefwill be specifically synchronized by the BackgroundTask handler.D. Plural
<ishobjects>as message variation for events likeSYNCHRONIZEMETRICS. Since 15.1/15.1.0 this one can be used forSYNCHRONIZEMETRICSwhere all versions, languages and resolutions of everyishref(LogicalId) would be expanded by the BackgroundTask handler to then synchronize like option C above.E.
eventdatacontainer for all...EXPORTtypes likeINBOXEXPORT,REPORTEXPORT,SEARCHEXPORT,PUBLICATIONEXPORT,FOLDEREXPORTSince the single
<ishobject>and plural<ishobjects>variations are important for the standard Tridion Docs product, we would like to add the generation of theInputDatain the cmdlet to avoid an outside calculation to pass to the parameter-RawInputData.Adding parameter
-InputDataTemplatewith the following optionsIshObjectsWithLngRefcovers above option A and C, so InputData reads<ishobjects><ishobject ishtype='ISHMasterDoc' ishref='GUID-X' ishlngref='45679'>...IshObjectWithLngRefcovers above option B, so InputData reads<ishobject ishtype='ISHMasterDoc' ishref='GUID-X' ishlogicalref='45677' ishversionref='45678' ishlngref='45679'>or<ishobject ishtype='ISHBaseline' ishref='GUID-X' ishbaselineref='45798'>IshObjectsWithIshRefcovers above option D, so InputData reads<ishobjects><ishobject ishtype='ISHMasterDoc' ishref='GUID-X'>...EventDataWithIshLngRefscovers aove option E, so InputData reads<eventdata><lngcardids>516316, 516319</lngcardids></eventdata>Adding optional parameter
-HashIdwith the following optionsInputDataor incoming-RawInputDatais passed through the Standard Library 2.0 - SHA256 hash function and will be passed to the BackgroundTask queue as theHashId. In turn messages with an identical hash id will only be executed once by the BackgroundTask service.-RawInputData. Note that the maximalHashIdlength is 80 characters."", means that the parameter will be ignored and an empty value will be passed. The option if you explicitly want to regenerate messages and force multiple asynchronous executions by the BackgroundTask service.Make sure to add below examples to the Release Notes and Get-Help as well!
Implementation Details
The implementation could be inspired through Validators-and-Transforms or Width and Height so 1024x768 Transform. After quick research chose as simpler
-HashIdparameter handling.Minimal Task List
-InputDataTemplate LngRefsto cover the SMARTTAG commaspace-seperated lngrefs legacy scenario over DocumentObj25.RaiseEventByIshLngRefs.DevideListInBatchesBy...(_retrievedIshObjects, IshSession.MetadataBatchSize);functions in this cmdlt. Otherwise you get 2 ZIP files for one FOLDEREXPORT in the below implementations :)IshSession.MetadataBatchSizeso 999 by default, because we are removing theDevideListInBatchesBy...code from this cmdlet. If refactor fails, a better code example that aggregates per 999 could be shown in the examples.InputDataTemplatewith optionIshObjectsWithLngRefcovering content objects and publication outputs toIshObjectsGroupparameter group.InputDataTemplatewith optionIshObjectWithLngRefcovering content objects, publication outputs and baseline toIshObjectsGroupparameter group.InputDataTemplatewith optionIshObjectsWithIshRefcovering content objects and publication outputs toIshObjectsGroupparameter group.InputDataTemplatewith optionIshObjectsWithIshRef covering content objects toIshObjectsGroup` parameter group.-StartAfterparameter toIShObjectsGroupparameter group if DocumentObj25.RaiseEventByIshLngRefs is rewritten to BackgroundTask25.CreateBackgroundTaskWithStartAfter-EventDescriptionparameter toIShObjectsGroupparameter group if DocumentObj25.RaiseEventByIshLngRefs is rewritten to BackgroundTask25.CreateBackgroundTaskWithStartAfter. Make sure to adapt the example. Make this an optional and use the-EventTypeas-EventDescriptionto remain backward compatible.-HashId. When not specified, the default, the implicitHashIdwill calculate a SHA256 (or CRC32) based on the generated InputData to make sure that the BackgroundTask handler only picks up one of the generated messages. When set to empty string"", an emptyHashIdwill be passed downstream, otherwise the give value. Double check what happens if a too long (max is 80 characters on 15.1/15.1.0 release) is passed, probably rethrow the API exception. Add this toIshObjectsGroupandParameterGroupparameter groups.Get-Helpof this cmdletInputDataTemplateuse event typeTESTBACKGROUNDTASK, and retrieve the InputData immediately and check its format. Avoid SYNCHRONIZEMETRICS for testing. Same forHashId.Examples
EXAMPLE SMARTTAG
Add BackgroundTask with event type "SMARTTAG" for the objects located under the "General\MyFolder\Topics" path. One BackgroundTask message will appear per folder containing a list of all latest version English content objects in the InputData of the message.
Get-IshFolder -FolderPath "General\Myfolder\Topics" -FolderTypeFilter @("ISHModule", "ISHMasterDoc", "ISHLibrary") -Recurse | Get-IshFolderContent -VersionFilter Latest -LanguagesFilter en | Add-IshBackgroundTask -EventType "SMARTTAG" -InputDataTemplate IshObjectsWithLngRef # plural content objects...EXAMPLE PLURAL SYNCHRONIZEMETRICS
Rebuilding the Metrics subsystem is optimally done in the order of Images, Topics and Publications. Add BackgroundTask with event type "SYNCHRONIZEMETRICS" for the objects located under the "General" path (Data folder). One BackgroundTask message will appear per folder containing a list of LogicalIds in the InputData of the message.
# First Images Get-IshFolder -BaseFolder Data -FolderTypeFilter @("ISHIllustration") -Recurse | Get-IshFolderContent -VersionFilter Latest | Add-IshBackgroundTask -EventType "SYNCHRONIZEMETRICS" -EventDescription "SYNCHRONIZEMETRICS Images" -InputDataTemplate IshObjectsWithIshRef # plural LogicalIds # Then Topics Get-IshFolder -BaseFolder Data -FolderTypeFilter @("ISHModule") -Recurse | Get-IshFolderContent -VersionFilter Latest | Add-IshBackgroundTask -EventType "SYNCHRONIZEMETRICS" -EventDescription "SYNCHRONIZEMETRICS Topics" -InputDataTemplate IshObjectsWithIshRef # plural LogicalIds # Then Publications Get-IshFolder -BaseFolder Data -FolderTypeFilter @("ISHPublication") -Recurse | Get-IshFolderContent -VersionFilter Latest | Add-IshBackgroundTask -EventType "SYNCHRONIZEMETRICS" -EventDescription "SYNCHRONIZEMETRICS Publications" -InputDataTemplate IshObjectsWithIshRef # plural LogicalIdsEXAMPLE SINGLE SYNCHRONIZEMETRICS
Add BackgroundTask with event type "SYNCHRONIZEMETRICS" for the objects located under the "General\MyFolder\Topics" path. One BackgroundTask message will appear per content object holding the latest version English content object as single InputData of the message.
Get-IshFolder -FolderPath "General\Myfolder\Topics" -FolderTypeFilter @("ISHModule", "ISHMasterDoc", "ISHLibrary") -Recurse | Get-IshFolderContent -VersionFilter Latest -LanguagesFilter en | Add-IshBackgroundTask -EventType "SYNCHRONIZEMETRICS" -InputDataTemplate IshObjectWithLngRef # single content object...EXAMPLE HASH