Add-on EPG: Documentation

Find out more about the add-on Electronic Program Guide in order to create a program list including a built-in plausibility check.

Table of Contents

Working with the EPG Add-on

The add-on Electronic Program Guide (EPG) provides a list of available channels and television program data for a particular time period. The show list is a special view in Sophora’s editor that enables searching as well as filtering of shows by program and/or day.

Besides it includes a plausibility check and a real-time presentation of inconsistencies: Sophora proactively detects the occurrence of overlaps and gaps and then marks them accordingly. Free broadcast slots are continually updated and recognizable for the editors at first glance.

This is a paid Sophora add-on. For details, please refer to our website.
different status symbols in epg

Show List

The show list displays all programs of a chosen channel at one day. The programs are named and listed by time. Further information are given about first run or rerun, what the show’s document workflow status is and whether the show is marked as a program tip or program change.

Colored Table Rows

Blue: Broadcasting of regional programs, correct program run.
Bright Red: Gap occur in the show list, incorrect program run.
Red: Overlapping of programs, incorrect program run.

epg program overlap colours

Creating New Documents

  1. Select the icon "New document", listed in the tool bar.
  2. Choose "EPG" and select either "Program" or "Station".
  3. A window to select location and Id stem will be opened. Add a name for the Id stem and confirm your entry with "Finish".
  4. The EPG document has been created.

Station

Compile a station in order to allocate your programs to a specific radio/TV station.

  1. Create a new document as it was described before.
  2. First name your station under "Title".
  3. Afterward you can determine the "Position in EPG View" and the "Structure Node" for programs and templates.
  4. At the end choose the "Start of the Program" and select the "Type" (TV or Radio).
epg new station

Program

Create a program document in order to compile a movie, a show, a news broadcast, an episode of a series or any other program. In the following it will be described in detail.

Broadcast Dates

After creating the program document as it was described before, you need to fill out the Broadcast Dates.

Start: Add date and exact time of the broadcasting program.
End: Add date and exact time of the broadcasting program.
Station: Select one of the existing stations.
First Run: Select first run for initial broadcasting.
Rerun: Select rerun for repetition.
VPS Time: Choose the time for the virtual private server.
TV Tip: Mark if the program is recommended.
External Program Slot Number: Add the single-digit up to nine-digit code for recording.
Live: Mark if the program is a live version.
Program Change: Also select if the program may have changed
Program Replaced: Add the name of the replaced program.

creating new epg document
The selection of broadcast dates are individually convertible. Administrators can make changes in the admin area.

Technical Data and Credits

Genre: Select one or several genres based on the existing ones.
Format: Also you are able to choose a format like documentary, quiz or reality show.
Broadcast: Select the broadcast of the program.
Homepage: Add the webpage of the program.
Production Country: Choose one of the production countries.
Production Year: Add the year of production.
Season: By compiling a series you can name the season of it.
Episode Number: Add the episode number of a series.
Episode Count: Also you can add the episode numbers in total.

EPG Technical Data TV/ Movie

In order to give more technical information for users it is possible to select weather the program is broadcasted in Dolby Surround, 3D or with audio description.

Set a hook into one or several checkboxes.

technical data and credits
The selection of technical data and credits are individually convertible. Administrators can make changes in the admin area.

Participants

Determine the functions of participating staff members. Options can be art director, camera, editor, or producer. By naming actors you can also determine the role title.

epg participants
The selection of the participants’ functions are individually convertible. Administrators can make changes in the admin area.

Editing Program Data

Before editing programs they have to be opened first. By double clicking at the program in the show list the document will be opened. After changing the broadcasting date it is necessary to publish the document afterwards, otherwise the program has to be set offline

For making changes it might be necessary to have the required rights.

Administrating the EPG Add-on

To use the EPG add-on, the following precondition must be fulfilled:

  • At server side, the embedded SOLR must be enabled (see server properties sophora.solr.*)
  • The required nodetypes and mixin types must be registered when activating the EPG add-on in the Deskclient by opening the EPG view (see nodetypes and mixins below)
  • A custom document type e.g. sophora-content-nt:broadcast must have the 'Broadcast Table' specified by the mixin sophora-epg-mix:program


  • Mixin sophora-epg-mix:template and its fields must be configured to sophora-nt:structureNodeDocument to configure program templates
  • Finally at least one station document (sophora-epg-nt:station) must be created
  • Now you can create documents of your custom program node type (e.g. sophora-content-nt:broadcast) with entries in their 'Broadcast Table' for the broadcasting dates and broadcasting station. These documents will appear in the EPG view.

Nodetypes and Mixins

Nodetype sophora-epg-nt:station

A full Sophora document type that represents a broadcasting station. Users can switch to stations in the top drop down of the EPG view to select the program of the station. A station has a title, an index for ordering in the EPG view, a structure node to locate programs created by a template, a structure node to locate templates created by a program of the station, and a daytime that specifies the start time of the station's program each day (e.g. at 6 o'clock in the morning).

Validation of live versions (sophora-epg:numberOfDaysToConsiderProgramLiveVersions)

A program may have multiple broadcasts, and in consequence a program which is taken offline or online might affect the published schedules of multiple days at once. Usually the websites or exports which show programs to the audience are based entirely on the published versions of schedules. It is therefore crucial that the published schedules are valid, which means that there must be no gaps or overlapping broadcasts in a day's schedule

The EPG view can be configured to visualize these kind of "live"-problems by analyzing the published versions of programs and marking those parts of a schedule which are affected by problems.

Showing problems in the published version of the schedule is only useful if most of the programs of the schedule are published. Usually drafts of a station's schedules are planned a signification time ahead. However, they are usually considered "stable" (and are published) only a few weeks ahead. A schedule which contains mostly programs which have not been published yet would show a lot of "live"-problems. Validation of the published versions of programs will therefore only be useful for the number of days that are considered "stable".

This feature can be enabled by specifying the number of days in the future which are considered "stable" in a station's property sophora-epg:numberOfDaysToConsiderProgramLiveVersions:

  • If a positive number is provided, the feature is enabled.
  • If the field is left empty, the field's value will be "inherited" from the parent station, if this is a regional station.
  • If "0" is provided, the feature is disabled.

Nodetype sophora-epg-nt:stationRef

The type for referencing stations in other documents. This is used to reference regional stations in other stations.

Mixin type sophora-epg-mix:program

Mixin for custom document types that represent a program (or broadcast), e.g. for sophora-content-nt:broadcast. Documents with this mixin will be displayed in the EPG view depending on the entries of their 'Broadcast Table' (a dynamic table with valid child node type sophora-epg-nt:broadcastTableRow) and 'Broadcast Segment Table' (a dynamic table with valid child node type sophora-epg-nt:broadcastSegmentTableRow). Since program templates can be created from existing programs (and vice versa) a template target structure node can be specified.

Nodetype sophora-epg-nt:broadcastTableRow

Nodetype for the rows of a program's 'Broadcast Table'. The table holds the broadcasting dates and broadcasting stations of the program and some other optional information like 'rerun', 'live', 'program change' etc. You can remove these optional fields from the base tab if you do not need them for your use case.

Nodetype sophora-epg-nt:broadcastSegmentTableRow

Nodetype for the rows of a program's 'Broadcast Segment Table'. This optional table holds the broadcasting dates of the program when it is broadcasted as a feature story.

Mixin type sophora-epg-mix:template

Mixin type that must be added to sophora-nt:structureNodeDocument (no additional configuration of these fields required). A template is a collection of programs which are located under a structure node. The metadata of the template, i.e. name, station, start date and end date, is stored in the structure node document using the properties defined by this mixin.

You can change the configurations of the above types, e.g. if you do not need the column 'live' of the 'Broadcast Table', but never add custom properties or childnodes to nodetypes and mixins of the 'sophora-epg' namespace directly. If you need additional custom fields then add them by a custom mixin type.

Intermediate Broadcasts

There are use-cases where there is one long-running program and short, intermediate programs which are broadcasted during the long-running program. An example might be a major sports event, with a 6 hour long program showing a live broadcast from the sports event and short news programs every hour. Ordinarily, this would lead to conflicts between the long-running program and the intermediate news programs. While we recommend splitting the long-running program during the import process into shorter programs spaced between the intermediate programs, another option is activating dedicated support for intermediate broadcasts in the EPG add-on.

To use intermediate broadcasts, edit the configuration for the nodetype sophora-epg-nt:broadcastTableRow and add the boolean property sophora-epg:intermediate to the 'Base'-tab. For intermediate broadcasts this property needs to be set to true.

Broadcasts that are marked as intermediate will show a blue arrow before the title in the EPG view. They are exempt from the normal validation of the EPG schedule, will never have conflicts with regular broadcasts and have no influence on the calculation of gaps in the schedule. They can, however, have conflicts with other intermediate broadcasts: intermediate broadcasts are not allowed to overlap.

EPG Intermediate programs

Customization options for the EPG view

The EPG view can be customized using a few configuration options. See "Configuring the Deskclients" for details.

Scripts for mass-operations on programs

By using a button visible in the EPG view of the Deskclient, scripts can be applied to all programs visible in the program list at once. For example, a script could be used to publish all programs, including those which are "hidden" behind regional windows, with a single click.

The scripts are configured per station. At the moment, only one script per station is allowed. For this purpose, the sophora-epg-nt:station node type has a sophora-epg:clientScript property, holding the external ID of the script. If the script is set on a main (non-regional) station, the script is available to all regional stations as well, unless they have a different script explicitly set for themselves. Once a script is configured for a station, a button to run the script is shown in the EPG view next to the station select-box.

Any client script may be used for this purpose if it meets the following requirements:

  • It is configured to accept documents of a program node type, i.e. the node types implementing the sophora-epg-mix:program mixin.
  • It accepts multiple documents as input. Otherwise only the first program in the program list will be affected by the script.

Java Tag Library

We provide a Tag Library to simplify JSP development. It provides support for the concept of programs, which may have multiple broadcast dates (see above).

In the following, we give an overview over the provided tags using examples. A detailed documentation of all the tags is available in the Tag Library Descriptor (TLD) and as TLDDoc.

epg:broadcastSearch

This tag allows searching for broadcast dates (using Solr). Results may be restricted using optional criteria, e.g., a minimal date or the station.

The result is a EpgResultPage. Each entry in the result page represents a single broadcast date and also contains all data of the broadcast itself.

In the following example, we search for all broadcasts in a given time range and within a specific station:

<%@ page pageEncoding="utf-8" contentType="text/html; charset=UTF-8"%>
<%@ taglib uri="http://java.sun.com/jsp/jstl/core" prefix="c"%>
<%@ taglib uri="http://java.sun.com/jsp/jstl/fmt" prefix="fmt"%>
<%@ taglib uri="http://www.subshell.com/sophora/epg" prefix="epg"%>
 
<fmt:parseDate var="minDate" pattern="dd.MM.yyyy HH:mm" type="both" value="12.05.2014 22:00"/>
<fmt:parseDate var="maxDate" pattern="dd.MM.yyyy HH:mm" type="both" value="12.05.2014 22:45"/>
<epg:broadcastSearch
 stationExternalIds="station-externalId"
 var="result" minDate="${minDate}" maxDate="${maxDate}" />
 
total: ${result.totalCount} <br />
size: ${result.entries.size()} <br />
hasNextPage: ${result.hasNextPage} <br />
hasPreviousPage: ${result.hasPreviousPage} <br />
pageSize: ${result.pageSize} <br />
pageNumber: ${result.pageNumber} <br />
<hr />
 
<c:forEach var="entry" items="${result.entries}">
 ${entry.broadcast.startTime['yyyy-MM-dd HH:mm']} - ${entry.broadcast.endTime['yyyy-MM-dd HH:mm']} - ${entry.program.title} - ${entry.broadcast.station.title}
 <hr />
</c:forEach>

Additional search criteria not directly supported by the tag can be given using Solr query fragments. In the following example, we search for a broadcast containing "Hamburg" in its title:

<%@ page pageEncoding="utf-8" contentType="text/html; charset=UTF-8"%>
<%@ taglib uri="http://java.sun.com/jsp/jstl/core" prefix="c"%>
<%@ taglib uri="http://www.subshell.com/sophora/epg" prefix="epg"%>
<%@ taglib tagdir="/WEB-INF/tags/sophora-commons" prefix="sc"%>
 
<sc:getCurrentDate var="now" />
 
<c:set var="programQuery">+title_s:*Hamburg*</c:set>
<epg:broadcastSearch var="result" minDate="${now}" minDateMode="excludeRunning" pageSize="10" programQuery="${programQuery}" />
 
<h1>Title contains "Hamburg"</h1>
<p>
<c:forEach var="entry" items="${result.entries}">
 <hr />
 ${entry.broadcast.startTime['yyyy-MM-dd HH:mm']} - ${entry.broadcast.endTime['yyyy-MM-dd HH:mm']} - ${entry.program.title} - ${entry.broadcast.station.title}
</c:forEach>
</p>

epg:currentBroadcast

This tag is used to determine the broadcast that is currently running on a station.

<%@ taglib uri="http://www.subshell.com/sophora/epg" prefix="epg"%>
 
<epg:currentBroadcast var="result" stationExternalIds="station-externalId"/>
<h1>Current Broadcast:</h1>
<p>
<c:choose>
 <c:when test="${empty result}">
 Currently no broadcast.
 </c:when>
 <c:otherwise>
 ${result.broadcast.startTime['yyyy-MM-dd HH:mm']} - ${result.broadcast.endTime['yyyy-MM-dd HH:mm']} - ${result.program.title} - ${result.broadcast.station.title}
 </c:otherwise>
</c:choose>
</p>

epg:isDaylightSavingTimeTransition

This tag returns whether there is a clock change on a given date.

<%@ page pageEncoding="utf-8" contentType="text/html; charset=UTF-8" import="java.util.*"%>
<%@ taglib uri="http://www.subshell.com/sophora/epg" prefix="epg"%>
 
<%
 Calendar cal = Calendar.getInstance();
 cal.set(cal.get(Calendar.YEAR), Calendar.MARCH, 29);
 Date testDate = cal.getTime()
%>
 
<epg:isDaylightSavingTimeTransition var="result" date="<%=testDate%>" />
<h1><%=testDate%></h1>
<h2>Daylight saving time transition on the given date: ${result}</h2>

epg:getNextDaylightSavingTimeTransition

Returns the next day on which a clock change will happen.

<%@ page pageEncoding="utf-8" contentType="text/html; charset=UTF-8"%>
<%@ taglib uri="http://www.subshell.com/sophora/epg" prefix="epg"%>
 
<epg:getNextDaylightSavingTimeTransition var="nextTransition"/>
 
<h1>Next daylight saving time transition: ${nextTransition}</h1>

epg:flushCacheAtNextBroadcastStart

This tag sets the flush date according to the next future broadcast. No flush date is set if no future broadcast can found.
The following arguments can be provided to the tag:

  • broadcasts: A list of broadcasts (as list of EpgResultEntrys). The flush date will be set to the nearest start or end date of a broadcast in the list.
  • stations: Comma-separated list of externalIds of stations. The flush date will be set to the nearest start date of a broadcast on any of those stations.
  • programUuid: Uuid of a program document. The flush date will be set to the next broadcast start or end of this program.

Exactly one of the arguments must be set.

<%@ page pageEncoding="utf-8" contentType="text/html; charset=UTF-8"%>
<%@ taglib uri="http://java.sun.com/jsp/jstl/fmt" prefix="fmt"%>
<%@ taglib uri="http://www.subshell.com/sophora/epg" prefix="epg"%>
 
<fmt:parseDate var="minDate" pattern="dd.MM.yyyy HH:mm" type="both" value="10.02.2015 09:00" parseLocale="GERMAN"/>
<fmt:parseDate var="maxDate" pattern="dd.MM.yyyy HH:mm" type="both" value="11.02.2015 12:45" parseLocale="GERMAN"/>
 
<epg:broadcastSearch stationExternalIds="station1-externalId" var="broadcasts" minDate="${minDate}" maxDate="${maxDate}" />
<epg:flushCacheAtNextBroadcastStart broadcasts="${broadcasts.entries}"/>
<epg:flushCacheAtNextBroadcastStart stations="station1-externalId,station2-externalId"/>
<epg:flushCacheAtNextBroadcastStart programUuid="${current.uuid}"/>

epg:solrSearch

This tag provides generic EPG Solr search capability.
The Solr query for broadcasts (e.g., to search for broadcast dates that are reruns) can be supplied via the broadcastQuery attribute. In addition, the (optional) programQuery attribute can be set to query for programs (e.g., to do full-text search within the program title).
Furthermore, the tag provides support for all Solr attributes (e.g., fields, pageNumber, pageSize, ...).
The return value is a EpgResultPage.

Configuration

The following properties can be configured using sophora.properties.

PropertyDescription
com.subshell.sophora.delivery.epg.taglib.programNodeTypeThe node type that represents program objects.
com.subshell.sophora.delivery.epg.taglib.defaultSolrCoreThe non-epg-specific Solr core to be used for searching. "default" if not configured.
com.subshell.sophora.delivery.epg.taglib.epgSolrCoreThe epg-specific Solr core. "epgProgram" if not configured.
com.subshell.sophora.delivery.epg.taglib.programModelThe name of the content map model used for program search results.