<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="chapter.rdlogmanager">
  <title>Generating Logs and Reports with RDLogManager</title>
  <sect1 xml:id="sect.rdlogmanager.generating_logs_and_reports_with_rdlogmanager">
    <note>
      This chapter covers the graphical user interface for RDLogManager.
      For information regarding the command-line interface, see the
      <command>rdlogmanager</command><manvolnum>1</manvolnum> man page.
    </note>
    <title>Overview</title>
    <para>
      RDLogManager is a tool for generating Rivendell logs. It is different
      from RDLogEdit in that, instead of building logs line-by-line,
      it allows log structures to be defined by a series of rules (called
      <emphasis>events</emphasis> and <emphasis>clocks</emphasis>) that
      are then plugged into a time framework
      (called a <emphasis>grid</emphasis>). This grid is then used to
      generate logs automatically
      on an as-needed basis.  Each Rivendell service has its own,
      separately defined grid, thus allowing for separate log generation
      rules for each service. This system of rules allows for very
      powerful, modular features, including the ability to import and use
      scheduling data from various external third party systems, such as
      music schedulers and traffic and billing systems.
    </para>
    <para>
      RDLogManager also includes facilities for generating
      <emphasis>reports</emphasis>. Reports
      are data outputs that detail whether certain events aired as
      scheduled, and under what circumstances. Reports are available in
      various formats. Some are intended to be read by humans, while
      others are intended for use by other, external software systems as a
      means of reconciling exported schedules.
    </para>
    <para>
      When RDLogManager is started, it displays its main menu.
    </para>
     <para>
       <mediaobject>
	 <imageobject>
	   <imagedata align="center" fileref="rdlogmanager.rdlogmanager_screenshot.png" width="36mm" depth="70mm" />
	 </imageobject>
	 <caption><para>The RDLogManager Main Menu</para></caption>
       </mediaobject>
     </para>
  </sect1>
  <sect1 xml:id="sect.rdlogmanager.grids">
    <title>Grids</title>
    <para>
      Each Rivendell service has an RDLogManager grid. To see the list of
      available grids, touch the <computeroutput>Edit Grids</computeroutput>
      button to open the Log Grids dialog.
    </para>
     <para>
       <mediaobject>
	 <imageobject>
	   <imagedata align="center" fileref="rdlogmanager.log_grids_dialog.png" width="65mm" depth="53mm" />
	 </imageobject>
	 <caption><para>The Log Grids Dialog</para></caption>
       </mediaobject>
     </para>
    <para>
      To open a particular grid, select its service name and touch the
      <computeroutput>Edit</computeroutput>
      button.
    </para>
     <para>
       <mediaobject>
	 <imageobject>
	   <imagedata align="center" fileref="rdlogmanager.edit_grid_dialog.png" width="145mm" depth="95mm" />
	 </imageobject>
	 <caption><para>The Edit Grid Dialog</para></caption>
       </mediaobject>
     </para>
    <para>
      Each grid has slots for every hour of every day of the broadcast week
      – 168 slots in all.  By specifying a particular clock to go into each
      of these slots, a set of rules that RDLogManager can use to generate
      a log for any given day of the week is built up. To specify a clock,
      simply touch the particular hour of interest to open up the
      <computeroutput>Select Log Clock</computeroutput> dialog.
    </para>
    <para>
      <mediaobject>
	<imageobject>
	  <imagedata align="center" fileref="rdlogmanager.log_clocks.png" width="96mm" depth="68mm" />
	</imageobject>
	<caption><para>The Log Clocks Dialog</para></caption>
      </mediaobject>
    </para>
    <para>
      Click the desired clock, then touch the
      <computeroutput>OK</computeroutput> button. To clear the
      assignment of any clock to the selected hour, touch the
      <computeroutput>Clear</computeroutput> button,
      then <computeroutput>OK</computeroutput>.
    </para>
    <para>
      It is possible to 'drill down' directly to the underlying
      configuration of a clock (to be covered shortly) by right-clicking on
      the relevant hour in a grid and selecting
      <computeroutput> Edit Clock</computeroutput>.
    </para>
  </sect1>
  <sect1 xml:id="sect.rdlogmanager.clocks">
    <title>Clocks</title>
    <para>
      An RDLogManager clock is a collection of RDLogManager events,
      arranged in terms of their start time (relative to the beginning of
      the hour) and length. It basically can be thought of as the
      &quot;schedule&quot; of an hour – <emphasis>any</emphasis> hour.
      Once defined, a clock
      can be plugged into any hour of a grid of any service, thus making
      for easy modularization and changes to a service's schedule.
    </para>
    <para>
      To see the list of available clocks, touch the
      <computeroutput>Edit Clocks</computeroutput> button in
      RDLogManager's Main Menu to open the Log Clocks dialog.
      Each RDLogManager clock can be assigned a
      three-letter code and color, as an aid in identifying it when
      assigned to grids.  To add a new clock, touch the 
      <computeroutput>Add</computeroutput> button, or to
      edit a clock's parameters, click on it and touch the
      <computeroutput>Edit</computeroutput> button.
      In each case, the Edit Clock dialog will open.
      Clocks can also be deleted by touching the
      <computeroutput>Delete</computeroutput> button or renamed
      by touching the <computeroutput>Rename</computeroutput> button.
    </para>
    <para>
      <mediaobject>
	<imageobject>
	  <imagedata align="center" fileref="rdlogmanager.log_clock_list.png" width="97mm" depth="69mm" />
	</imageobject>
	<caption><para>The Log Clock List Dialog</para></caption>
      </mediaobject>
    </para>
    <para>
      <mediaobject>
	<imageobject>
	  <imagedata align="center" fileref="rdlogmanager.edit_clock_dialog.png" width="145mm" depth="104mm" />
	</imageobject>
	<caption><para>The Edit Clock Dialog</para></caption>
      </mediaobject>
    </para>
    <para>
      The Edit Clock dialog consists of three main sections: a tabular
      list of events in chronological order, a graphical depiction of the
      clock in the traditional “broadcast clock” format, and a series of
      action buttons across the bottom. The clock's three-letter code is
      set by means of the <computeroutput>Code</computeroutput> field
      in the upper right-hand corner of the
      table area. Its color can be set by touching the
      <computeroutput>Color</computeroutput> button. To
      save the clock without exiting the dialog, touch the
      <computeroutput>Save</computeroutput>
      or <computeroutput>Save As</computeroutput>
      buttons. To add a new event to the clock, touch the
      <computeroutput>Add</computeroutput> button, or
      to edit an existing entry touch the 
      <computeroutput>Edit</computeroutput> button. In either case,
      the Edit Event Assignment dialog will open. To
      delete an entry, touch the <computeroutput>Delete</computeroutput>
      button. As in the case of grids,
      it is possible to 'drill down' into the underlying RDLogManager
      event by right-clicking on the respective entry in the clock event
      table and selecting <computeroutput>Edit Event</computeroutput>.
    </para>
    <para>
      <mediaobject>
	<imageobject>
	  <imagedata align="center" fileref="rdlogmanager.edit_event_assignment_dialog.png" width="88mm" depth="26mm" />
	</imageobject>
	<caption><para>The Edit Event Assignment Dialog</para></caption>
      </mediaobject>
    </para>
    <para>
      The Edit Event Assignment dialog simply consists of an
      <computeroutput>Event</computeroutput> field
      for the name of the RDLogManager event and
      <computeroutput>Start Time</computeroutput> and
      <computeroutput>End Time</computeroutput>
      fields for the start and end times relative to the start of the
      hour. A list of available events can be brought up by touching the
      <computeroutput>Select</computeroutput> button to bring up the
      Log Events dialog.
    </para>
    <para>
      Each clock can be designated as being associated with one or more
      services. This can make finding the correct clock for a given
      service much faster, as the
      <computeroutput>Filter</computeroutput> control on the List Clocks dialog
      can then be used. To program these associations, touch the
      <computeroutput>Services List</computeroutput> button in the Edit
      Clock dialog to bring up the Service
      Associations dialog.
    </para>
    <para>
      <mediaobject>
	<imageobject>
	  <imagedata align="center" fileref="rdlogmanager.service_association_dialog.png" width="65mm" depth="39mm" />
	</imageobject>
	<caption><para>The Service Association Dialog</para></caption>
      </mediaobject>
    </para>
    <para>
      To designate a service as being valid for this clock, select the
      services name in the <computeroutput>Available Services</computeroutput>
      list and then touch the <computeroutput>Add &gt;&gt;</computeroutput>
      button.  Likewise, to deselect a service, select its name in the
      <computeroutput>Enabled Services</computeroutput> list and then touch
      the <computeroutput>&lt;&lt; Remove</computeroutput> button.
    </para>
  </sect1>
  <sect1 xml:id="sect.rdlogmanager.events">
    <title>Events</title>
    <para>
      An RDLogManager event is a set of rules that define a series of log
      elements (audio carts, macro carts, markers, etc) that should be
      inserted into a log, along with the appropriate log event parameters
      (transition type, time type, etc) that should be associated with them.
      The actual elements to be inserted can be specified directly within
      the event itself, or imported from a data file generated by an
      external scheduling system.  Up to two such external scheduling
      sources can be defined for each service. While for convenience sake
      these are designated as 'Traffic' and 'Music' within RDLogManager,
      they can each be used anywhere a means of importing external
      scheduling data into the system is needed, regardless of whether such
      data actually references commercial or musical material or not.
    </para>
    <para>
      To see the list of available RDLogManager events, touch the
      <computeroutput>Edit Events</computeroutput> button on the
      RDLogManager Main Menu to open the Log Events
      dialog. It is possible to filter the list of
      available events to only those used for a particular service by
      selecting the service in the <computeroutput>Filter</computeroutput>
      control. To add a new event,
      touch the <computeroutput>Add</computeroutput> button, or to edit
      an event's parameters, click on it
      and touch the <computeroutput>Edit</computeroutput> button.
      In each case, the Edit Event dialog will open.
      Events can also be deleted by touching
      the <computeroutput>Delete</computeroutput> button or renamed by
      touching the <computeroutput>Rename</computeroutput> button.
    </para>
    <para>
      <mediaobject>
	<imageobject>
	  <imagedata align="center" fileref="rdlogmanager.log_events_dialog.png" width="96mm" depth="69mm" />
	</imageobject>
	<caption><para>The Log Events Dialog</para></caption>
      </mediaobject>
    </para>
    <para>
      <mediaobject>
	<imageobject>
	  <imagedata align="center" fileref="rdlogmanager.editing_event.png" width="145mm" depth="114mm" />
	</imageobject>
	<caption><para>The Editing Event Dialog</para></caption>
      </mediaobject>
    </para>
    <para>
      The Edit Event dialog consists of two main parts: a Library cart
      picker widget on the left side, and an area showing the various event
      parameters on the right. Audio contained within audio carts can be
      sampled by selecting the desired cart and then touching the
      <computeroutput>Play</computeroutput>
      button. Programming an event basically consists of specifying four
      things: its log parameters (transition and time types), the list of
      <computeroutput>Pre-Import</computeroutput> events, the event import
      (if any) and the list of
      <computeroutput>Post-Import</computeroutput> events.
      The first matter to be decided is if the event
      should have a hard start time: if so, then the
      <computeroutput>Use hard start time</computeroutput>
      check box in the TIMED START section should be ticked. Ticking this box
      will enable all of the usual hard start parameters to be specified.
      If an automatic timed start is not desired, then it is possible to
      check the <computeroutput>Cue to this event</computeroutput> checkbox
      in the <computeroutput>PREPOSITION LOG</computeroutput> section.
      This will cause RDLogManager to place a hard time with a 'Make Next'
      attribute on the first item of the event – effectively, causing the
      event to be automatically “cued up” at the scheduled time – something
      that can be particularly handy for keeping spot breaks in sync when
      &quot;overscheduling&quot; music.
    </para>
    <para>
      Next, if it is desired to have RDLogManager try to insert
      material automatically from the Autofill List to ensure that the event
      has the length indicated by its parent clock, the
      <computeroutput>Use Autofill</computeroutput> box in
      the <computeroutput>ENFORCING LENGTH</computeroutput> section
      should be checked.  (Configuring the
      Autofill List is covered in detail in the Rivendell Technical and
      Administration Guide).  If Autofill is enabled, it is also possible
      to tick the
      <computeroutput>Warn if fill is under or over</computeroutput> checkbox
      to have RDLogManager
      generate a warning if it was unable to properly fill the event when
      the log was generated.
    </para>
    <para>
      Next, the list of log events (if any) to be inserted before the data
      import should be placed in the
      <computeroutput>PRE-IMPORT CARTS</computeroutput> list. For audio or
      macro carts, these can be simply dragged and dropped from the Library
      cart list on the left-hand side of the dialog. Meta events can be
      inserted by right-clicking on the list and selecting the desired
      element. It is also possible to edit or delete elements and set the
      transition type of each element through the right-click menu.
    </para>
    <para>
      The <computeroutput>IMPORT</computeroutput> section then defines
      which (if any) source will be used
      for importing external scheduling events into the log.  Either
      <computeroutput>Music</computeroutput>,
      <computeroutput>Traffic</computeroutput> or
      <computeroutput>None</computeroutput> can be selected.  If 
      <computeroutput>Music</computeroutput> or
      <computeroutput>Traffic</computeroutput> is selected,
      then RDLogManager will import any events from those sources that fall
      within the start and end times of the event (as supplied by the
      parent clock). These start and end times can be further broadened by
      means of 'slop factors' entered into the Import carts scheduled
      controls (this is sometimes necessary to get the import to work
      properly with certain external scheduler systems). The transition
      types to be used for the first and subsequent imported elements can
      be specified with the <computeroutput>First cart has a</computeroutput>
      and <computeroutput>Imported carts have a</computeroutput>
      controls.  If <computeroutput>Music</computeroutput> has been selected
      as the import source, it is
      also possible to specify the event to use to import traffic breaks
      embedded in the music log with the 
      <computeroutput>Import inline traffic</computeroutput> with the
      control.  (Configuration of the actual parser parameters for data
      importation is covered in the Rivendell Technical and Administration
      Guide).
    </para>
    <para>
      Finally, the list of log events (if any) to be inserted after the
      data import should be placed in the
      <computeroutput>POST-IMPORT CARTS</computeroutput> list.
      Configuration of the events works very similarly to that of the
      <computeroutput>PRE-IMPORT CARTS</computeroutput> list.
    </para>
    <para>
      The color of the event (as seen in the Edit Clock dialog) can be set
      by touching the <computeroutput>Color</computeroutput> button.
      The list of services for which this
      event is valid can be edited by touching the
      <computeroutput>Services List</computeroutput> button.
      To save the event without exiting the dialog, touch the
      <computeroutput>Save</computeroutput> or
      <computeroutput>Save As</computeroutput> buttons.
    </para>
  </sect1>
  <sect1 xml:id="sect.rdlogmanager.generating_logs">
    <title>Generating Logs</title>
    <para>
      After all of the appropriate hours have been populated in a service's
      grid, it's time to start generating logs. To do this, touch the
      <computeroutput>Generate Logs</computeroutput> button in
      RDLogManager's Main Menu to open the Generate Log dialog.
    </para>
    <para>
      Depending upon how many external scheduling sources are involved,
      generating a log involves one, two or three steps. Before performing
      any of the steps, it is first necessary to select the relevant
      service for which to generate the log (using the
      <computeroutput>Service</computeroutput> control)
      and the log date (either by entering the date in the
      <computeroutput>Date</computeroutput> control
      or by touching the <computeroutput>Select</computeroutput> button
      and picking it off of the calendar).
    </para>
    <para>
      <mediaobject>
	<imageobject>
	  <imagedata align="center" fileref="rdlogmanager.generate_log_dialog.png" width="39mm" depth="48mm" />
	</imageobject>
	<caption><para>The Generate Log Dialog</para></caption>
      </mediaobject>
    </para>
    <para>
      In all cases, a new log is initially generated by touching the
      <computeroutput>Create New Log</computeroutput> button.
      If the log for the selected date and service does not
      already exist, it will be created at this point (becoming visible in
      RDLogEdit). It the log already exists, it will be overwritten.
      (NOTE: if completed voicetracks exist in the old log, they will be
      deleted when the log is overwritten!)
    </para>
    <para>
      When generating a log, RDLogManager will look for possible problems
      (such as scheduled carts that are missing in the Library) and
      generate an exception report if it finds any.
    </para>
    <para>
      Once generated, the status lights in the Generate Log dialog indicate
      which (if any) additional import data are needed to complete the log.
      Two types of status light exist:
      <computeroutput>Available</computeroutput>, which indicates if the
      required data file is available to RDLogManager, and
      <computeroutput>Merged</computeroutput>,
      indicating whether the data has been merged into the log as yet.
      Each light can show one of three different colors:  GREEN, meaning
      &quot;yes&quot;, RED, meaning &quot;no&quot; and WHITE, meaning
      &quot;not required&quot;.
    </para>
    <para>
      <mediaobject>
	<imageobject>
	  <imagedata align="center" fileref="rdlogmanager.generate_log_dialog_music_merge_required.png" width="39mm" depth="48mm" />
	</imageobject>
	<caption><para>The Generate Log Dialog (music merge required)</para></caption>
      </mediaobject>
    </para>
    <para>
      For an example, see the figure above. This is showing a log that has
      been generated and has music data available but not yet merged. To
      perform the merge, touch the
      <computeroutput>Merge Music</computeroutput> button. The dialog now
      changes to that shown below, indicating that Music data
      has been merged but that traffic data is still needed.
    </para>
    <para>
      <mediaobject>
	<imageobject>
	  <imagedata align="center" fileref="rdlogmanager.generate_log_dialog_traffic_merge_required.png" width="39mm" depth="48mm" />
	</imageobject>
	<caption><para>The Generate Log Dialog (traffic merge required)</para></caption>
      </mediaobject>
    </para>
    <para>
      Once a log
      has reached this state – that of having any necessary music data
      merged – it can be voicetracked without having to wait for traffic
      data to become available. Traffic data can be merged at any time
      before, during or after the generation of voicetracks. The actual
      traffic merge is performed by touching the
      <computeroutput>Merge Traffic</computeroutput> button,
      resulting in a dialog as illustrated. (NOTE:
      the configuration of the various data file names and parser parameters
      needed for data import is done in the RDAdmin module and is covered
      in the Rivendell Technical and Administration Guide).
    </para>
    <para>
      It is important to note that the sequence of operations from the
      example above is typical, but may vary depending upon how the system
      administrator has configured RDLogManager at each site.  Some services,
      for example, will have no music data, only traffic, so the music
      indicator lights will be &quot;whited out&quot; accordingly.
    </para>
    <para>
      <mediaobject>
	<imageobject>
	  <imagedata align="center" fileref="rdlogmanager.generate_log_dialog_fully_merged.png" width="39mm" depth="48mm" />
	</imageobject>
	<caption><para>The Generate Log Dialog (fully merged)</para></caption>
      </mediaobject>
    </para>
 </sect1>
 <sect1 xml:id="sect.rdlogmanager.generating_reports">
   <title>Generating Reports</title>
   <para>
     A Rivendell report is a data output that details whether certain
     events aired as scheduled, and under what circumstances. Reports are
     available in various formats.  Some are intended to be directly read
     by humans, while others are intended for use by other, external
     software systems as a means of reconciling exported schedules.
   </para>
   <para>
     Rivendell has the ability to filter the data that go into any
     particular report on the basis of the type of material played (traffic
     spots, music or all), the playing service(s) and the originating
     host(s).  The configuration of reports is done in the RDAdmin module
     and is covered in the Rivendell Technical and Administration Guide.
     Once configured however, reports are actually generated by the
     RDLogManager module.
   </para>
   <para>
     To generate a report, touch the
     <computeroutput>Manage Reports</computeroutput> button on the
     RDLogManager Main Menu to open the Select Service dialog.
   </para>
   <para>
     <mediaobject>
       <imageobject>
	 <imagedata align="center" fileref="rdlogmanager.rivendell_services_dialog.png" width="64mm" depth="54mm" />
       </imageobject>
       <caption><para>The Rivendell Services Dialog</para></caption>
     </mediaobject>
   </para>
   <para>
     The dialog will show each service on the system.
     Touch the <computeroutput>Generate Reports</computeroutput>
     button to open the Select Report Dates dialog.
   </para>
   <para>
     <mediaobject>
       <imageobject>
	 <imagedata align="center" fileref="rdlogmanager.select_report_dates_dialog.png" width="64mm" depth="30mm" />
       </imageobject>
       <caption><para>The Select Report Dates Dialog</para></caption>
     </mediaobject>
   </para>
   <para>
     The desired report can be
     selected with the <computeroutput>Report</computeroutput> control,
     and the start and end dates of the
     report specified with the
     <computeroutput>Start Date</computeroutput> and
     <computeroutput>End Date</computeroutput> controls,
     respectively (NOTE: not all reports are capable of being generated so
     as to span more than one day).
   </para>
   <para>
     <mediaobject>
       <imageobject>
	 <imagedata align="center" fileref="rdlogmanager.select_date_dialog.png" width="39mm" depth="43mm" />
       </imageobject>
       <caption><para>The Select Date Dialog</para></caption>
     </mediaobject>
   </para>
   <para>
     Once the parameters are set, touch the
     <computeroutput>Generate Report</computeroutput> button to write out
     the report.
   </para>
   <sect2 xml:id="sect.rdlogmanager.purging_old_report_data">
     <title>Manually Purging Old Report Data</title>
     <para>
       Rivendell keeps the raw data used to generate reports indefinitely
       until purged out of the system. Periodic purging of old
       data is a good idea from the standpoint of minimizing the amount of
       system resources utilized, and can be done manually by selecting the
       desired service and then touching the
       <computeroutput>Purge Data</computeroutput> button in the Select
       Service dialog, opening up a calendar dialog.
       Each date that has data eligible for purging will be shown in bold.
       To purge a particular day, select it and the touch the
       <computeroutput>Purge Data</computeroutput>
       button.
     </para>
     <warning>
       Once ELR data for a particular service and date are purged it will
       be impossible to generate reports for that service/date.
       Be sure that all required reports have been produced before purging!
     </warning>
     <note>
       It is recommended that the system be configured to purge report data
       automatically after it reaches a certain age (30 days is typical).
       See <xref linkend="sect.rdadmin.manage_services.general.purging_log_and_elr_data_automatically"/>
       for information on configuring automatic data purging in RDAdmin.
     </note>
   </sect2>
 </sect1>
</chapter>
