IBackgroundTaskHandler - SynchronizeMetrics
Synchronizes the Tridion Docs objects to the Metrics database.
Input data
- a topic
- an illustration
- publication metadata
- FISHMBPRODUCT ( product groups metadata field )
- publish actions & output formats
- baseline metadata
- the list of items in the baseline
- ishobject
-
The input data root element.
- Required: yes
- ishobject @ishref
-
The logical identifier of the object.
- Required: yes
- ishobject @ishtype
-
The object type (for example,
ISHModule,ISHIllustrationorISHPublication) .- Required: yes
- ishobject @ishlogicalref
-
The unique numeric identifier of the logical level of the object (for example, 24163526).
- Required: no
- ishobject @ishversionref
-
The unique numeric identifier of the version level of the object (for example, 24163527).
- Required: no
- ishobject @ishlngref
-
The unique numeric identifier of the language level of the object (for example, 24163528).
- Required: no
- ishfields
-
A container for object metadata fields. The container contains one or more
ishfieldelements.- Required: yes
- ishfield
-
An object metadata field.
- Required: yes
- Possible
ishfieldelements for this background task:VERSIONFTITLECREATED-ONFISHMBPRODUCTFISHPUBLNGCOMBINATIONFISHOUTPUTFORMATREFFISHBASELINE
- ishfield @name
-
The name of the
ishfieldelement.- Required: yes
- ishfield @level
-
The level of the
ishfieldelement.- Required: yes
- Allowed values:
logicalversionlng
- ishfield @ishvaluetype
-
The type of the values for the field.
- Allowed values:
valueidelementlabel
- Allowed values:
- ishchanges
-
A container of the changes that have been made to the object. The
ishchangescontainer has twoishchangechild elements.- Required: no
<ishchanges> <ishchange sequence="2"> <ishfieldchange name="FTITLE" level="logical" ishvaluetype="value">Two butterflies</ishfieldchange> </ishchange> <ishchange sequence="1"> <ishfieldchange name="FTITLE" level="logical" ishvaluetype="value">2 butterflies</ishfieldchange> </ishchange> </ishchanges>
- ishobject
-
The input data root element.
- Required: yes
- ishobject @ishref
-
The logical identifier of the object (for example,
GUID-68A89740-3FF5-4E90-98FF-6E887828ABE9).- Required: yes
- ishobject @ishtype
-
The object type (that is,
ISHBaseline) .- Required: yes
- ishobject @ishbaselineref
-
The unique numeric identifier of the object (for example, 20581348).
- Required: no
- ishfields
-
A container for object metadata fields. The container contains one or more
ishfieldelements.- Required: yes
- ishfield
-
An object metadata field.
- Required: yes
- Possible
ishfieldelements for this background task:NAMECREATED-ON
- ishfield @name
-
The name of the
ishfieldelement.- Required: yes
- ishfield @level
-
The level of the
ishfieldelement.- Required: yes
- Allowed values:
none
- ishfield @ishvaluetype
-
The type of the values for the field.
- Allowed values:
valueidelementlabel
- Allowed values:
- ishchanges
-
A container of the changes that have been made to the object. The
ishchangescontainer has twoishchangeelements.- Required: no
<ishchanges> <ishchange sequence="2"> <ishfieldchange name="NAME" level="none">Baseline of Publication MP330-v7</ishfieldchange> </ishchange> <ishchange sequence="1"> <ishfieldchange name="NAME" level="none">Publication MP330-v7-GUID-789BBB3D-8A09-4916-8857-09A246CB6F59-2023/11/01 13:07:56</ishfieldchange> </ishchange> </ishchanges> - ishbaselineitems
-
A container with the version objects that were added, modified or removed. This container must contain at least one object.
- Required: no
- object
-
An object on the logical level. The object element has the following required attributes:
- ref
- The logical identifier of the object.
- versionnumber
- The version of the object.
- action
-
An action that was performed on a baseline item. Possible values are:
newupdatedelete
- ishobjects
-
The input data root element.
- Required: yes
- ishobject
-
The input element representing one object
- Required: yes
- ishobject @ishref
-
The logical identifier of the object (for example,
GUID-68A89740-3FF5-4E90-98FF-6E887828ABE9).- Required: yes
- ishobject @ishtype
-
The object type (for example,
ISHModule,ISHIllustrationorISHPublication) .- Required: yes
- ishobject @ishlogicalref
-
The unique numeric identifier of the object (for example, 20581348).
- Required: no
- ishobject @ishversionref
-
The unique numeric identifier of the object (for example, 20581348).
- Required: no
- ishfields
-
A container for object metadata fields. The container contains one or more
ishfieldelements.- Required: no
- ishfield
-
An object metadata field.
- Required: yes
- Possible
ishfieldelements for this background task:NAMECREATED-ONVERSIONFTITLECREATED-ONFISHMBPRODUCTFISHPUBLNGCOMBINATIONFISHOUTPUTFORMATREFFISHBASELINE
- ishfield @name
-
The name of the
ishfieldelement.- Required: yes
- ishfield @level
-
The level of the
ishfieldelement.- Required: yes
- Allowed values:
logicalversionlng
- ishfield @ishvaluetype
-
The type of the values for the field.
- Allowed values:
valueidelementlabel
- Allowed values:
Input data example
<ishobject ishref="GUID-BCE979C1-AD4A-43D1-82E1-891DC55DF495" ishtype="ISHModule" ishlogicalref="14766119" ishversionref="24163527" ishlngref="24163528">
<ishfields>
<ishfield name="VERSION" level="version">3</ishfield>
<ishfield name="DOC-LANGUAGE" level="lng">en</ishfield>
<ishfield name="FTITLE" level="logical">Two butterflies</ishfield>
<ishfield name="CREATED-ON" level="logical">2022-10-26T12:24:13.000Z</ishfield>
<ishfield name="CREATED-ON" level="version">2024-04-09T11:59:39.000Z</ishfield>
</ishfields>
<ishchanges>
<ishchange sequence="2">
<ishfieldchange name="FTITLE" level="logical" ishvaluetype="value">Two butterflies</ishfieldchange>
</ishchange>
<ishchange sequence="1">
<ishfieldchange name="FTITLE" level="logical" ishvaluetype="value">2 butterflies</ishfieldchange>
</ishchange>
</ishchanges>
</ishobject>
<ishobject ishref="GUID-FCC45222-956C-4574-85EF-66F43594D5E9" ishtype="ISHPublication" ishlogicalref="2360703" ishversionref="24713218" ishlngref="24713222">
<ishfields>
<ishfield name="VERSION" level="version">3</ishfield>
<ishfield name="FISHPUBLNGCOMBINATION" level="lng">en</ishfield>
<ishfield name="FISHOUTPUTFORMATREF" level="lng">CHM (Compiled Help)</ishfield>
<ishfield name="FISHPUBSTATUS" level="lng" ishvaluetype="element">VPUBSTATUSPUBLISHEDDRAFT</ishfield>
<ishfield name="FISHSTATUSTYPE" level="lng">10</ishfield>
<ishfield name="FISHOUTPUTFORMATREF" level="lng" ishvaluetype="id">6082</ishfield>
<ishfield name="FISHOUTPUTFORMATREF" level="lng" ishvaluetype="value">CHM (Compiled Help)</ishfield>
<ishfield name="FISHOUTPUTFORMATREF" level="lng" ishvaluetype="element">GUID-32058B0B-FD30-4D3D-BC77-685F67167878</ishfield>
</ishfields>
<ishchanges>
<ishchange sequence="2">
<ishfieldchange name="FISHPUBSTATUS" level="lng" ishvaluetype="element">VPUBSTATUSPUBLISHEDDRAFT</ishfieldchange>
</ishchange>
<ishchange sequence="1">
<ishfieldchange name="FISHPUBSTATUS" level="lng" ishvaluetype="element">VPUBSTATUSPUBLISHING</ishfieldchange>
</ishchange>
</ishchanges>
</ishobject>
<ishobject ishref="GUID-68A89740-3FF5-4E90-98FF-6E887828ABE9" ishtype="ISHBaseline" ishbaselineref="20581348">
<ishfields>
<ishfield name="NAME" level="none">Baseline of Publication MP330-v7</ishfield>
<ishfield name="FISHLABELRELEASED" level="none" ishvaluetype="element">FALSE</ishfield>
<ishfield name="FISHBASELINEACTIVE" level="none" ishvaluetype="element">TRUE</ishfield>
<ishfield name="CREATED-ON" level="none">2023-11-01T12:07:56.000Z</ishfield>
</ishfields>
<ishchanges>
<ishchange sequence="2">
<ishfieldchange name="NAME" level="none">Baseline of Publication MP330-v7</ishfieldchange>
</ishchange>
<ishchange sequence="1">
<ishfieldchange name="NAME" level="none">Publication MP330-v7-GUID-789BBB3D-8A09-4916-8857-09A246CB6F59-2023/11/01 13:07:56</ishfieldchange>
</ishchange>
</ishchanges>
</ishobject>
<ishobject ishref="GUID-B8B22CBC-F453-4AE6-A749-914BD3918601" ishtype="ISHBaseline">
<ishfields>
<ishfield name="NAME" level="none">Butterfly publication-v3-GUID-FCC45222-956C-4574-85EF-66F43594D5E9-20240507 12:13:45</ishfield>
<ishfield name="FISHLABELRELEASED" level="none" ishvaluetype="element">FALSE</ishfield>
<ishfield name="FISHBASELINEACTIVE" level="none" ishvaluetype="element">TRUE</ishfield>
<ishfield name="CREATED-ON" level="none">2024-05-07T12:13:45.937Z</ishfield>
</ishfields>
<ishchanges>
<ishchange sequence="2">
<ishfieldchange name="NAME" level="none">Butterfly publication-v3-GUID-FCC45222-956C-4574-85EF-66F43594D5E9-20240507 12:13:45</ishfieldchange>
<ishfieldchange name="FISHLABELRELEASED" level="none" ishvaluetype="element">FALSE</ishfieldchange>
<ishfieldchange name="FISHBASELINEACTIVE" level="none" ishvaluetype="element">TRUE</ishfieldchange>
<ishfieldchange name="CREATED-ON" level="none">2024-05-07T12:13:45.937Z</ishfieldchange>
</ishchange>
<ishchange sequence="1">
<ishfieldchange name="NAME" level="none"></ishfieldchange>
<ishfieldchange name="FISHLABELRELEASED" level="none" ishvaluetype="element"></ishfieldchange>
<ishfieldchange name="FISHBASELINEACTIVE" level="none" ishvaluetype="element"></ishfieldchange>
<ishfieldchange name="CREATED-ON" level="none"></ishfieldchange>
</ishchange>
</ishchanges>
<ishbaselineitems>
<object ref="GUID-0E9EE49A-6FBE-4417-850B-FB542FF12696" versionnumber="2" action="new" />
<object ref="GUID-45F000EB-03F8-4A78-B58B-01E6E61F7381" versionnumber="1" action="new" />
<object ref="GUID-DA9D9A84-F341-439E-B5B0-0FBC6A0CC89B" versionnumber="1" action="new" />
<object ref="GUID-FEA0B28A-98B6-4D35-A164-D0DB46A8CE92" versionnumber="1" action="new" />
</ishbaselineitems>
</ishobject>
<ishobjects>
<ishobject ishtype="ISHPublication" ishref="GUID-41CD5789-A4AB-48D5-866A-B9142A8EDC08" />
<ishobject ishtype="ISHPublication" ishref="GUID-85024008-09CC-4323-B6B8-080B9343E39A" />
<ishobject ishtype="ISHPublication" ishref="GUID-952E64BF-A926-4943-82B6-78AD64D021C0" />
<ishobject ishtype="ISHPublication" ishref="GUID-993F35AF-2F4F-448F-BA61-10F7539EFF38" />
<ishobject ishtype="ISHPublication" ishref="GUID-AF81981B-1026-45AD-ABE0-B0666C3C76A6" />
<ishobject ishtype="ISHPublication" ishref="GUID-F5D5F74A-7E21-4281-8377-E8DF2F3C8D7D" />
</ishobjects>
<ishobjects>
<ishobject ishref="GUID-41CD5789-A4AB-48D5-866A-B9142A8EDC08" ishtype="ISHPublication" ishlogicalref="523798" ishversionref="523799">
<ishfields>
<ishfield name="VERSION" level="version">1</ishfield>
</ishfields>
</ishobject>
<ishobject ishref="GUID-85024008-09CC-4323-B6B8-080B9343E39A" ishtype="ISHPublication" ishlogicalref="523800" ishversionref="523801">
<ishfields>
<ishfield name="VERSION" level="version">1</ishfield>
</ishfields>
</ishobject>
<ishobject ishref="GUID-952E64BF-A926-4943-82B6-78AD64D021C0" ishtype="ISHPublication" ishlogicalref="523802" ishversionref="523803">
<ishfields>
<ishfield name="VERSION" level="version">1</ishfield>
</ishfields>
</ishobject>
<ishobject ishref="GUID-993F35AF-2F4F-448F-BA61-10F7539EFF38" ishtype="ISHPublication" ishlogicalref="523804" ishversionref="523805">
<ishfields>
<ishfield name="VERSION" level="version">1</ishfield>
</ishfields>
</ishobject>
<ishobject ishref="GUID-AF81981B-1026-45AD-ABE0-B0666C3C76A6" ishtype="ISHPublication" ishlogicalref="523806" ishversionref="523807">
<ishfields>
<ishfield name="VERSION" level="version">1</ishfield>
</ishfields>
</ishobject>
<ishobject ishref="GUID-F5D5F74A-7E21-4281-8377-E8DF2F3C8D7D" ishtype="ISHPublication" ishlogicalref="523808" ishversionref="523809">
<ishfields>
<ishfield name="VERSION" level="version">1</ishfield>
</ishfields>
</ishobject>
<attempt>2</attempt>
<totalFailedCount>0</totalFailedCount>
</ishobjects>
Background task configuration
- batchsize
-
The maximum number of items allowed to be processed in one batch. If the number of items to process exceeds this number, the items are split across multiple batches.
- Required: yes
- Default value: 1000
- Allowed values: An integer greater than 0 and less than or equal to 2147483647
- Example: 100
- maximumRetries
-
The maximum number of retries allowed to retry processing a failed background task.
- Required: yes
- Default value: 500
- Allowed values: An integer greater than 0 and less than or equal to 2147483647
- Example: 100
- delay
-
The minimum delay time period that the retry synchronization background task will wait before getting executed.
- Required: yes
- Default value:
00:10:00 - Allowed values: Valid TimeSpan
- maximumTimePerObject
-
The maximum time to process a publication version object. If a publication version object takes longer to process than this configured value, another background task is be created to process the remaining subsequent publication version objects.
The value of this parameter must be smaller than the value of the
maximumTimePerBackgroundTaskparameter.- Required: yes
- Default value:
00:20:00 - Allowed values: Valid TimeSpan
- maximumTimePerBackgroundTask
-
The maximum execution time for synchronizing all objects in a folder. If the processing time exceeds the configured value, another background task is created to process subsequent objects.
The value of this parameter must be smaller than the value of the
timeoutparameter on theexecutiontag of this background task configuration.- Required: yes
- Default value:
00:50:00 - Allowed values: Valid TimeSpan
Default background task configuration example
The following configuration gets and handles a SYNCHRONIZEMETRICS event from the background task queue:<handler eventType="SYNCHRONIZEMETRICS">
<scheduler executeSynchronously="false"/>
<authorization type="authenticationContext"/>
<execution timeout="02:00:00" recoveryGracePeriod="00:10:00" isolationLevel="None"/>
<activator>
<net name="SynchronizeMetrics">
<parameters>
<parameter name="batchsize">1000</parameter>
<parameter name="maximumRetries">500</parameter>
<parameter name="delay">00:10:00</parameter>
<parameter name="maximumTimePerObject">00:20:00</parameter>
<parameter name="maximumTimePerBackgroundTask">00:50:00</parameter>
</parameters>
</net>
</activator>
<errorHandler maximumRetries="98">
<actions>
<add errorNumber="-503004" action="Retry" delay="00:10:00"/>
</actions>
</errorHandler>
</handler>
Flow
Synchronizing a single object
IWrite plugin when, for example, a new object is created or updated:
- Retrieves event data.
- Determines which objects must be processed.
- Reads additional required data for these objects.
- Uses the Metrics API to send data to the appropriate endpoint for storage in the Metrics database.
Synchronizing multiple objects
- Retrieves event data.
- Determines which objects must be processed.
- Reads additional required data for these objects.
- Retrieves version level objects of the logical objects
- For publication versions, also retrieves the following details:
- Baseline
- Baseline Items
- Publication output with status (Draft, Release Candidate or Released)
- Publication versions are processed in separate background task.
- For publication versions, also retrieves the following details:
- Uses the Metrics API to send data in batches to the appropriate endpoint for storage in the Metrics database.