Unexpected alert about my DITA content - Fluid Topics - 3.5

audience
public
Product
Fluid Topics
FT_Version
3.7
3.6
3.5
Category
Tips

Managing last edition date for alerts on DITA topics

Fluid Topics provides a powerful alerting mechanism which allows your end-users to save a search and get notified when content changes.

When end-users create an alert, they expect to receive a weekly email if any content (topics, books, unstructured documents or articles) matching their saved search has been added or updated.
Sometimes, however, they may get notified that every topic in a DITA book (or in another proprietary format of structured content) has changed when, in reality, only several have been updated.

Let’s have a look under the hood to understand what is going on when an alert is set up and how to troubleshoot if necessary.

How does it work?

An alert is a search query (with filters, keywords, etc.) that is executed every week. It includes only the topics, maps, unstructured documents or articles that have been updated since the previous alert, i.e. content with an ft:lastEdition date after the previous alert date.
This leads us to the question, "what is the ft:lastEdition metadata, and how can it be modified?"

As described in our documentation, if no information about the date of last edition is provided in the content itself, ft:lastEdition will be the publication date by default.
However, it is possible to set the date of last edition in DITA 1.3 by adding the revised metadata to your content:
<critdates>
<revised modified="yyyy-mm-dd">
</critdates>


To set up alerts for topics correctly, it is important to understand the difference between the map level and the topic level.
Since metadata defined at the map level are inherited at the topic level, including a revised metadata element at the map level would overwrite the revised metadata element at the topic level, and all the topics of an updated map would be considered as modified topics (and thus be included in the next alert).
To prevent this from happening, this metadata should not be used at the map level, but only at the topic level.

To sum things up:
  • Do not add a revised metadata element at the map level.
  • Add a revised metadata element to all topics and set the attribute modified to the current date.
  • Each time a topic is updated, update the modified attribute accordingly: this is what will trigger an alert on this topic and this topic only.

Example

Let's illustrate this tip with a real-life example.
As an end-user, your goal is to create an alert that informs you when the Release Notes (books or topics) are modified.
You prepare an alert and select these filters:
  • product = Fluid Topics
  • category = Release Note
As the tech writer, I'll need to add a revised/@modified attribute at the topic level (and not at the map level) so that the end-user is notified whenever the topic gets updated.
The end-user will receive an alert if:
  • A book is created or modified, for example, a new version or minor release note is published
  • A topic is modified


Let's say that the last alert was sent on July 8th, and the latest Release Note was published on July 14th.


Example #1 - revised/@modified is set at the map level and the topic level

If no ft:lastEdition date is set at the topic level, Fluid Topics will use the publication date to fill ft:lastEdition. ft:lastEdition at the topic level comes from ft:lastEdition at the map level.
Consequently, if the tech writer publishes a map and all its topics (the v3.7 book including a new Release Note for v3.7.2), the whole book and all the topics will show up in the alert. This will occur even if only one topic has actually changed, because the publication dates of the map and topics will have changed.

revised/@modified ft:lastEdition Content of the alert
Map July 14 July 14 map in next alert => OK
Unchanged topic July 7 July 14 topic in next alert => KO
Updated or added topic July 14 July 14 topic in next alert => OK



Example #2 - revised/@modified is set ONLY at the topic level

If you expect only updated topics to show up in alerts, you will need to add revised/@modified to all the topics and update it whenever a topic gets updated.
revised/@modified should not be used at the map level since its values will overwrite all topic-level values.
Note: this means that a map that does not have revised/@modified will always have ft:lastEditionDate=publicationDate and will thus always show up in alerts.
This is normal, as at least one topic has changed or has been added in the meantime (the minor Release Note). If this were not the case, the map would not have been published again.

revised/@modified ft:lastEdition Content of the alert
Map Not revised/@modified July 14 map in next alert => OK
Unchanged topic July 7 July 7 topic not in next alert => OK
Updated or added topic July 14 July 14 topic in next alert => OK