Documentation Center

IBackgroundTaskHandler - SynchronizeMetrics

Synchronizes the Tridion Docs objects to the Metrics database.

Input data

The input data XML identifies changes made to one of the following:
  • a topic
  • an illustration
  • publication metadata
    • FISHMBPRODUCT ( product groups metadata field )
  • publish actions & output formats
  • baseline metadata
  • the list of items in the baseline
The input data XML that identifies a single topic, illustration or publication specifies the following:
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, ISHIllustration or ISHPublication) .
  • 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 ishfield elements.
  • Required: yes
ishfield
An object metadata field.
  • Required: yes
  • Possible ishfield elements for this background task:
    • VERSION
    • FTITLE
    • CREATED-ON
    • FISHMBPRODUCT
    • FISHPUBLNGCOMBINATION
    • FISHOUTPUTFORMATREF
    • FISHBASELINE
ishfield @name
The name of the ishfield element.
  • Required: yes
ishfield @level
The level of the ishfield element.
  • Required: yes
  • Allowed values:
    • logical
    • version
    • lng
ishfield @ishvaluetype
The type of the values for the field.
  • Allowed values:
    • value
    • id
    • element
    • label
ishchanges
A container of the changes that have been made to the object. The ishchanges container has two ishchange child 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>
The input data XML that identifies a baseline specifies the following:
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 ishfield elements.
  • Required: yes
ishfield
An object metadata field.
  • Required: yes
  • Possible ishfield elements for this background task:
    • NAME
    • CREATED-ON
ishfield @name
The name of the ishfield element.
  • Required: yes
ishfield @level
The level of the ishfield element.
  • Required: yes
  • Allowed values:
    • none
ishfield @ishvaluetype
The type of the values for the field.
  • Allowed values:
    • value
    • id
    • element
    • label
ishchanges
A container of the changes that have been made to the object. The ishchanges container has two ishchange elements.
  • 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:
  • new
  • update
  • delete
The input data XML that identifies multiple topics, illustrations or publications specifies the following:
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, ISHIllustration or ISHPublication) .
  • 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 ishfield elements.
  • Required: no
ishfield
An object metadata field.
  • Required: yes
  • Possible ishfield elements for this background task:
    • NAME
    • CREATED-ON
    • VERSION
    • FTITLE
    • CREATED-ON
    • FISHMBPRODUCT
    • FISHPUBLNGCOMBINATION
    • FISHOUTPUTFORMATREF
    • FISHBASELINE
ishfield @name
The name of the ishfield element.
  • Required: yes
ishfield @level
The level of the ishfield element.
  • Required: yes
  • Allowed values:
    • logical
    • version
    • lng
ishfield @ishvaluetype
The type of the values for the field.
  • Allowed values:
    • value
    • id
    • element
    • label

Input data example

This example shows typical event input data for this background task when a topic has changed:
<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>
This example shows typical event input data for this background task when the metadata of a publication has changed:
<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>
This example shows typical event input data for this background task when the metadata of a baseline has changed:
<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>
This example shows typical event input data for this background task when the list of items in a baseline has changed:
<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>
This example shows typical event input data for this background task when synchronizing multiple logical object during intial data load of Metrics database :
<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>
This example shows typical event input data for this background task when synchronizing multiple version object during intial data load of Metrics database :

<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

The background task has the following configurable parameters:
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 maximumTimePerBackgroundTask parameter.

  • 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 timeout parameter on the execution tag 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

This flow is triggered by an IWrite plugin when, for example, a new object is created or updated:
  1. Retrieves event data.
  2. Determines which objects must be processed.
  3. Reads additional required data for these objects.
  4. Uses the Metrics API to send data to the appropriate endpoint for storage in the Metrics database.

Synchronizing multiple objects

This flow is triggered by, for example, the initial data synchronization from the Content Manager database to the Metrics database:
  1. Retrieves event data.
  2. Determines which objects must be processed.
  3. Reads additional required data for these objects.
  4. Retrieves version level objects of the logical objects
    1. For publication versions, also retrieves the following details:
      1. Baseline
      2. Baseline Items
      3. Publication output with status (Draft, Release Candidate or Released)
    2. Publication versions are processed in separate background task.
  5. Uses the Metrics API to send data in batches to the appropriate endpoint for storage in the Metrics database.