Binary Event Tracker

The Binary Event Tracker ensures that Multimedia Components in Tridion show the correct publish state, no matter if they've been published explicitly or implicitly or whether they've been removed.

On this page:

  • Implicit and explicit publishing
  • Unpublishing binaries
  • What does this extension change?
  • How does this extension work?
  • How to install this extension

Implicit and explicit publishing

In Tridion, publishing or unpublishing content is most often an explicit action: you select a piece of content in Tridion's Content Manager Explorer and then click on the Publish or Unpublish button. This gives you very direct control over what exactly gets published to your web site.

But in the case of binaries the story isn't always as simple. Certain binaries (such as PDFs) are likely to be published explicitly, requiring you to select the Multimedia Component and click Publish. But many other binaries are published implicitly by your templates or by the Default Template Building Blocks supplied with Tridion. For example: an image that is used in a rich-text field will be automatically added to the output when that rich-text field is rendered. This is a Good Thing´┐Ż, because otherwise your rich-text would show up on your web site with a broken image link in it.

1. PDF is explicitly published

2. JPG is implicitly published

So binaries within Tridion can be published in two ways: explicitly or implicitly. Explicitly published binaries only show on the web site because you selected their Multimedia Component and click Publish. Implicitly published binaries are automatically added by templates during rendering, because they are needed to display the rendered content correctly.

3. HTML, PDF and JPG in Storage

Note that while the binary is added during rendering, the Multimedia Component is never "officially" published. So the Multimedia Component doesn't show as published in the Content Manager Explorer.

Unpublishing binaries

Things get even more interesting when you consider how binaries are removed from your web server. For Multimedia Component that you explicitly publish it is quite simple: once you unpublish the Multimedia Component, the binary file will be removed from your web server. So binaries that were explicitly published before, will also be explicitly unpublished.

4. Unpublish PDF

But for binaries that are implicitly published the process is completely different. Keep in mind: these binaries are "officially" never published, they are just added to the output during rendering. So when you unpublish the content that refers to them, you also want to remove the binaries again. The problem Tridion has to solve here is that the binaries are added during rendering, which is an action that doesn't happen when you unpublish. So while Tridion can simply remove the Page or Component that you unpublished, how does it know that it also needs to remove the binary that is used in that rich-text?

5. Unpublish HTML

To know when to remove a certain binary Tridion Content Delivery keeps track of where binaries are used from. So when you publish the rich-text in the example in the previous section, Content Delivery makes a note that this Component (or Page, depending on your publishing model) uses the binary. And if you later also publish another piece of content that uses the same image, Content Delivery adds a reference from that content to the image too.

With these references in place, it suddenly becomes quite easy to determine when a binary can be removed: if there is no content referring to the binary anymore, that binary can be removed from the web server.

6. Storage removes JPG

So while explicitly published binaries will be removed when you explicitly unpublish their Multimedia Component, implicitly published binaries are removed from the web server when they are not used anymore. It is important to note the terminology here: the binary is never unpublished, it just gets removed from the web server (by Tridion's Storage layer) when it is no longer needed.

What does this extension change?

This extension adds two things to the above process for implicitly published binaries:

  1. Implicitly published binaries show up as published

  2. Binaries that are removed from the web server will show up as unpublished

How does this extension work?

This extension consists of three parts:

  1. Tracking what happens to binaries in the Content Delivery Storage layer

  2. Making this information available in the Content Delivery Web layer

  3. Retrieving this information and updating the Multimedia Component on the Content Manager

Tracking what happens to binaries in the Content Delivery Storage layer

In this first step we extend the Content Delivery Storage layer to "listen in" on actions taken on binaries.

1. Add BinaryEventTracking DAO to Content Delivery

By adding a custom DAO to the Storage layer we can simply track the creation, removal and updating of any binaries. We write these events into a designated directory and make sure to call the original DAO to handle the actual action on the binary.

After this step any action that affects a binary in the Storage layer, will also write an event into our designated directory.

Making this information available in the Content Delivery Web layer

So with the first step we now track information of what happens to the binaries and log that into a specified directory. But we need this information to be available in the Content Manager, so we can update the Multimedia Components.

2. Expose BinaryEvents in Content Delivery web

For this we added a page to an existing web site (JSP or ASPX). The page reads the events from the designated directory and makes them available to anyone that calls it. Once the caller signals that the events have been processed, the page deletes the events from the directory.

So now we track what happens to binaries and expose this information in a web page. Next up is somebody to call this web page and do something with the binary events.

Retrieving this information and updating the Multimedia Component on the Content Manager

With the first two steps we're keeping track of what happens to binaries in the Content Delivery Storage and expose that information in a web page. All that is left is to write a module that runs on the Content Manager machine, retrieves this information and updates published status of the affected Multimedia Components in Tridion.

3. Read BinaryEvents on Content Manager

Since we need to check for binary events at regular intervals, we implemented the Content Manager module as a Windows service. It connects to the page on a URL you configure and reads the binary events that have happened recently. It then calls SetPublishedTo in the TOM API to update the published status for the publication target. Since you may be tracking multiple targets, you can configure a separate URL and corresponding TcmUri for each of them. Since Tridion only tracks publishing of Component Presentations (not of Components) you will also need to specify a Component Template to associate with the events.

That's it: with these three modules in place we can now see in our Content Manager Explorer when a binary has been published, whether that happened implicitly or explicitly.

How to install this extension

Installing this extension consists of three steps:

  1. Installing the Storage layer extension

  2. Installing the Web page

  3. Installing the Windows service

Steps 1 and 2 take place on the Content Delivery server, while step 3 happens on the Content Manager server. 

Installing the Storage layer extension

To track the publishing and unpublishing of binaries you need to install the binaryeventstorage.jar and configure the BinaryEventsLocation in the DAO Bundle configuration file to specify where to store tracking information.

You need to have installed the Content Deployer Server Role as a .NET Web application or Java Web application.

  1. Access the installation media.

  2. Navigate to the PresentationSide\BinaryEventTracker.Storage directory.

  3. Copy binaryeventstorage.jar to your Content Delivery lib directory:

  4. Copy BinaryEventsDAOBundle.xml to one of the following directories:

    • to the classes directory, if your Content Delivery is running in a Java Web application,
    • to the config directory, if your Content Delivery is running in a .NET Web application.
  5. Navigate to the directory where you coped BinaryEventsDAOBundle.xml

    1. Open BinaryEventsDAOBundle.xml in a text editor.

    2. Change the BinaryEventsLocation to an existing directory on your system, for example:
          <BinaryEventsLocation path="C:\tridion\binaryevents" />

    3. Save and close BinaryEventsDAOBundle.xml.

    4. Make sure the user under which the Content Deployer is running has write access to this directory. When Content Deployer is running as a Web application, the user typically is the Application Pool identity.

  6. Configure the Storage Layer:

    1. Open the cd_storage_conf.xml configuration file in a text editor. The file is located in your classes directory (for Java Web application) or config directory (for a .NET Web application).

    2. In the <Storages> element, add the following <StorageBindings>:
             <Bundle src="BinaryEventsDAOBundle.xml"/>

    3. Save and close cd_storage_conf.xml.

  7. Restart the Content Deployer.

After installing the Storage Layer extension, you can see the events being written into the directory you configured as BinaryEventsLocation. Next you need to install and configure the Web page to make this data available for the Content Manager.

Installing the Web page

The binaryeventsync Web page makes the data available to the Content Manager so that the service there can update the status of the Multimedia Components. You can install the Web page in a separate Web application, or in the existing Web application where Content Delivery is running. Most commonly this page will be added to the existing HttpUpload Web site of each publication target.

If you install the Web page in a separate Web application, you first need to have installed the Content Deployer Server Role (as a .NET Web application or Java Web application, depending on your preferred technology).

  1. Access the installation media.

  2. Navigate to the folder PresentationSide\BinaryEventTracker.Web directory.

  3. Copy one of the following Web pages, depending on the Web application technology you are using, to your Web application upload directory if you are using HTTP upload, otherwise to another directory:

    • binaryeventsync.jsp
    • binaryeventsync.aspx
  4. Open the binaryeventsync Web page in a text editor:

    1. In the dir, specify the location specified in the BinaryEventsLocation in the BinaryEventsDAOBundle.xml file. For more information, see Installing the Storage layer extension.

    2. Save and close the binaryeventsync Web page.

  5. Make sure the user under which the Web page is running has read and delete access to the BinaryEventsLocation directory.

After completing these first two steps you will be able to see the list of binary events by connecting to the Web page.

Installing the Windows service

The Binary Event Tracker service retrieves the binary events from all configured publication targets and updates the status of the Multimedia Components in the Tridion Content Manager.

  1. Access the installation media

  2. Navigate to the folder ManagementSide\BinaryEventTracker.Service

  3. Copy BinaryEventTracker.exe and BinaryEventTracker.exe.config into a BinaryEventTracker directory under your %TRIDION_HOME% (typically either C:\Program Files\Tridion or C:\Program Files (x86)\Tridion)

  4. Open the BinaryEventTracker.exe.config file, located by default in your SDL Tridion installation \bin directory, in a text editor and configure the <BinaryEventTrackingTargets>.

    1. For each publication target where you installed the Storage layer extension and the Web page, you need to add a <Target> element
    2. The targetType attribute should identify the publication target that this element corresponds to
    3. The url attribute should contain the full URL that the current machine can read the binaryeventsync Web page on
    4. The componentTemplate attribute should identify a Component Template in the local Content Manager that you want to associate the publish actions with
    5. Save and close BinaryEventTracker.exe.config
  5. Open a command prompt (cmd.exe) on your Tridion Content Manager server

  6. Navigate to the directory where you coped BinaryEventTracker.exe and BinaryEventTracker.exe.config

  7. Run this command to install the service
        BinaryEventTracker.exe -install

  8. Open the Services control panel and verify that the Tridion Binary Event Synchronization service is present and started.

If all went well, the binary events should now be picked up from your Presentation Server and removed from the directory you configured. At the same time the relevant Multimedia Components should start showing the correct publish status. Any problems will show up in the Tridion log in the Windows event viewer after about 15 seconds (the interval at which the service retrieves the binary events).

License agreement
Download package
:   -
:   1.0
:   Yes

About the Author
Frank van Puffelen
Technical Director

Frank joined SDL in 2004 and as a principal developer worked on many of the company's releases until the end of 2012. He is now the technical director of ZyLAB USA.