Documentation Center

IWriteMetadataPlugin - OnFieldChangeSendEvent

Sends an event if a certain metadata field is changed. Optionally you can specify that the event should only be sent if the metadata field changed from a certain value to a certain value.

Plugin Configuration

The following workset fields need to be configured:
Fields
The name and level of the field specified in the ConditionMetadataField and ConditionMetadataFieldLevel parameters
The names and levels of the fields specified in the RequestedMetadata parameter
The following parameters can be configured:
ParameterRequiredDefault valueAllowed valuesDescription
ConditionMetadataFieldYesnone The metadata field that needs to be checked for changes. Only string fields are supported, number and date fields are not.
ConditionMetadataFieldLevelNolnglogical, version, lngThe metadata field level that needs to be checked for changes.
ConditionMetadataFieldValueTypeNovaluevalue, elementThe metadata field value type.
ConditionMetadataFieldFromValueNonone The current database value of the metadata field (= original value, so the value before change) should match one of the given values before SendEvent happens. Multiple values can be comma-space separated. No value provided means that the database value can be anything.
ConditionMetadataFieldToValueNonone The current value of the metadata field should match one of the given values before SendEvent happens. Multiple values can be comma-space separated. No value provided means that the database value can be anything.
EventTypeYesnone The event type indicates which handler executes the background task. So, the value must match the event type of the handler specified in the Background Task Configuration XML.
RequestedMetadataNononeishFields metadata XML structureDefines the names and levels of the fields to pass as additional metadata of the event.
ForceLegacyDateTimeNonoyes, noIndicates whether to consider legacy Datetime format for date type fields or Zulu format. For example, with ForceLegacyDateTime set to no, dateTime is, say, 2023-12-31T23:12:31.789Z, otherwise dateTime is, say, 01/01/2024 01:12:31.

Event data

The event data XML sent with the event contains:
  • an ishfields part with the current field values
  • an ishchanges part with the original and current values of the changed field that was specified in the ConditionMetadataField parameter
Example:
<ishobject ishref="GUID-..." ishtype="..." ishlogicalref="123454" ishversionref="123455" ishlngref="123456">
    <ishfields>
      <ishfield name="DOC-LANGUAGE" level="lng">en</ishfield>
      <ishfield name="VERSION" level="version">1</ishfield>
      <ishfield name="FRESOLUTION" level="lng">Low</ishfield>
    </ishfields>
    <ishchanges>
      <ishchange sequence="2">
        <ishfieldchange name="[ConditionMetadataField]" level="[ConditionMetadataFieldLevel]" ishvaluetype="[ConditionMetadataFieldValueType]">[ConditionMetadataField Current Value]</ishfieldchange>
      </ishchange>
      <ishchange sequence="1">
        <ishfieldchange name="[ConditionMetadataField]" level="[ConditionMetadataFieldLevel]" ishvaluetype="[ConditionMetadataFieldValueType]">[ConditionMetadataField Original Value]</ishfieldchange>
      </ishchange>
    </ishchanges>
  </ishobject>  

where the strings enclosed in [] are replaced by their actual values.

This plugin only executes if language level fields are changed (note the condition on ISHLevel):
<plugin name="ISHSYSSENDSTATUSRELEASEDEVENT" handler="OnFieldChangeSendEvent" ishcondition="ISHLevel='lng'">
  <description>Raises an event if the FSTATUS field is changed from 'Draft' or 'Reviewed' to 'Released'</description>
  <workingset>
    <ishfields>
      <ishfield name="FSTATUS" level="lng" />
      <ishfield name="FTITLE" level="logical" />
    </ishfields>
  </workingset>
  <initialize>
    <parameters>      
      <parameter name="ConditionMetadataField">FSTATUS</parameter>
      <parameter name="ConditionMetadataFieldLevel">lng</parameter>
      <parameter name="ConditionMetadataFieldValueType">element</parameter>
      <parameter name="ConditionMetadataFieldFromValue">VSTATUSDRAFT, VSTATUSREVIEWED</parameter>
      <parameter name="ConditionMetadataFieldToValue">VSTATUSRELEASED</parameter>
      <parameter name="EventType">STATUS_RELEASED</parameter>
      <parameter name="RequestedMetadata">
        <ishfields>
          <ishfield name="FTITLE" level="logical" />          
        </ishfields>
      </parameter>
    </parameters>
  </initialize>
</plugin>   
For the above plugin the eventdata looks like this:

  <ishobject ishref="GUID-9CE31359-BBB9-41D6-9848-E2E3874D4AF1" ishtype="ISHModule" ishlngref="253987" >
    <ishfields>
      <ishfield name="DOC-LANGUAGE" level="lng">en</ishfield>
      <ishfield name="VERSION" level="version">1</ishfield>
      <ishfield name="FTITLE" level="logical">Title example</ishfield>
    </ishfields>
    <ishchanges>
      <ishchange sequence="2">
        <ishfieldchange name="FSTATUS" level="lng" ishvaluetype="element">VSTATUSRELEASED</ishfieldchange>
      </ishchange>
      <ishchange sequence="1">
        <ishfieldchange name="FSTATUS" level="lng" ishvaluetype="element">VSTATUSDRAFT</ishfieldchange>
      </ishchange>
    </ishchanges>
  </ishobject>