Rivendellaudio/docs/opsguide/rdlogmanager.xml
Fred Gleason 242167c3d6 2017-11-03 Fred Gleason <fredg@paravelsystems.com>
* Refactored the XML source for the Operations Guide up into
	per-chapter files.
2017-11-03 14:20:22 -04:00

548 lines
25 KiB
XML
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<chapter xmlns="http://docbook.org/ns/docbook" xml:id="chapter.rdlogmanager">
<title>Generating Logs with RDLogManager</title>
<sect1 xml:id="sect.rdlogmanager.generating_logs_with_rdlogmanager">
<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" scale="45"/>
</imageobject>
<caption><para>The Log Grids Dialog</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" scale="45"/>
</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" scale="40"/>
</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" scale="45"/>
</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" scale="45"/>
</imageobject>
<caption><para>The Log Clock List Dialog</para></caption>
</mediaobject>
</para>
<para>
<mediaobject>
<imageobject>
<imagedata align="center" fileref="rdlogmanager.edit_clock_dialog.png" scale="40"/>
</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" scale="45"/>
</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" scale="45"/>
</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" scale="45"/>
</imageobject>
<caption><para>The Log Events Dialog</para></caption>
</mediaobject>
</para>
<para>
<mediaobject>
<imageobject>
<imagedata align="center" fileref="rdlogmanager.editing_event.png" scale="40"/>
</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" scale="45"/>
</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" scale="45"/>
</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" scale="45"/>
</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" scale="45"/>
</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" scale="45"/>
</imageobject>
<caption><para>The Rivendell Services Dialog</para></caption>
</mediaobject>
</para>
<para>
The dialog will show each service on the system,
along with the date of the oldest data available for generating
reports. 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" scale="45"/>
</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" scale="45"/>
</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>Purging Old Report Data</title>
<para>
Rivendell keeps the raw data used to generate reports indefinitely,
until manually 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 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. (NOTE: once purged, no reports can be generated for that
particular service/date, so be sure that all required reports have
been produced before purging!)
</para>
</sect2>
</sect1>
</chapter>