HOW TO: Create and Import a Schedule in OnTheAir Manager

Introduction

There are 2 ways to integrate with OnTheAir Node's schedule feature:

• A schedule is created in a third party application, exported to XML, and this XML is imported in OnTheAir Manager which then sends it to OnTheAir Node. User can then do last minute actions in OnTheAir Manager directly.
• A schedule is created in a third party application, which directly sends the XML to OnTheAir Node using a RESTfull API. That third party application will then have to take full control of OnTheAir Node and OnTheAir Manager will not be used. As OnTheAir Manager will not be used, the third party application will need to also show the playback status, allow to send modifications, and handle everything. This type of integration requires more work than simply importing in OnTheAir Manager.

This article explains the first workflow where the schedule is imported in OnTheAir Manager. If you want to control directly OnTheAir Node please check the following article: https://softron.zendesk.com/hc/en-us/articles/360003128994

Explaining the Workflow

Create the Schedule in third party application

The first step is of course to create the schedule in the third-party application, and export it to the format explained below.

Import the schedule in OnTheAir Manager

Once the schedule has been created by the third party application, you can either manually import the schedule in OnTheAir Manager or work with a watch folder, so that as soon as the schedule is created in that folder, it is automatically imported in OnTheAir Manager and sent to OnTheAir Node.

Manual import

• The third party creates a schedule with the keys explained in the samples attached to this article
• The schedule is saved into a folder
• The user imports the XML Schedule in OnTheAir Manager using the File > Import XML Schedule... menu
• The user clicks on the "Send Schedule" arrow in OnTheAir Manager to send the schedule to OnTheAir Node. Only a portion of that schedule to OnTheAir Node (the duration of schedule sent is configured in the Node Control / Validation preference).

Automatic Import

• The third party creates a schedule with the keys explained in the samples attached to this article
• The schedule is saved into a folder
• OnTheAir Manager monitors the folder
• It sees that a new xml schedule file has been created and imports the new schedule without any operation from the user
• If the option is enabled OnTheAir Manager can then send the schedule to OnTheAir Node automatically. If it is disabled, the user will have to send the schedule manually. Only a portion of that schedule to OnTheAir Node (the duration of schedule sent is configured in the Node Control / Validation preference).

Last minute modification

After the import, the user is then able to do last minute changes in the schedule in OnTheAir Manager (delete clips, skip to next, resync, etc...). 

Conformation

After the broadcasting, the third party then retrieves the as-run-logs to know what has been really played. In the as-run logs, it can retrieve the UIDs it eventually set (playbachUniqueID).

 

 

Setting up the applications

OnTheAir Manager for auto-import

In OnTheAir Manager, open the preferences window and select the "Auto-Import" tab:

Then enable the option to "Automatically import schedules in folder". And select the folder where the XML Schedules will be exported.

You can also enable 2 options:

Erase successfully imported schedule files

As its names implies, OnTheAir Manager will delete the xml files from the folder when they have been successfully imported. If the third party application monitors the folder, it will then be able to show in its UI if there is a problem to import the schedules. If you see that the new files are not deleted, it means we could not import them, and the user should have a look at OnTheAir Manager. 

Automatically send the new schedules to Node

Once imported, OnTheAir Manager will send the schedules to the Nodes (Master and Backup if there is a backup Node). A few things to know here too:

• users need to store the password to access the Node in the keychain.
• the schedule (with same UID) must be running on the target Nodes.

If any of this condition is not met, we will show a blocking window that will need a user action to start automatically importing and sending again.

OnTheAir Node

To be able to test the import of a schedule, you must have enabled at least one Node in OnTheAir Manager preferences. Because when a schedule is imported, we check that all files that are within the schedule belong to a media folder that exists in the Node enabled in OnTheAir Manager. If you do not have any Node enabled, the import of schedules will fail.

 

To setup OnTheAir Node, you can follow the QuickSetup Guide. The most important part for you is Page 5 where we explain how to add Media Folders. Make sure to add all the Media Folders of the clip you use in your Schedules. 

 

Then enable the Node you have setup in OnTheAir Manager.

 

How to format the schedule XML

Note: in the text below, we will talk a lot about schedule obviously, to dfifferentiate between a Schedule XML file that is created by a third party and a schedule in OnTheAir Manager here is the convention:

• a "Schedule" is a schedule within OnTheAir Manager
• a "XML Schedule" is the XML schedule that is created by the third party and imported in OnTheAir Manager.

Attached to this article, you have 2 sample schedules that you can download and read with a text editor as each key of the XML is explained:

• OTAM_RecommendedSchedule_ToImport.plist : is a schedule sample with only the recommended keys. It is the minimal schedule if you want.
• OTAM_CompleteSchedule_ToImport.plist: is a schedule sample with also the optional keys that you can add to set for example the in/out points, the attributes, etc...

About Unique IDs - which ones are important ?

You will notice that there are many Unique IDs in a schedule. There is an important distinction between 2 types of unique IDs:

• uniqueID : are what allow us to store in our database clips and playlists and to reuse them multiple times. 
• playbackUniqueID : are always unique and only exist in events. they must be consistent in between the imports. This is VERY important. If a user exports from the third party the same schedule a second time, the playbackUniqueID must be identical. If there is one clip that has been added for example, all the other playbackUniqueIDs must remain identical too.

To explain better the difference, consider this: 

• you can have one media (one file on your disk), that you can duplicate in the Media Browser (if for example you want to split a movie in 2 => each clip has its own set of in and out points) each of this occurrence will be stored with its own uniqueID.
• Then all these clips can be reused multiple times in different playlists or even in the same playlist. To differentiate those, we use the playbackUniqueID. Every time a clip (with its uniqueID) is used in a playlist, it will have a different playbackUnique ID

Here are the important ones in a schedule and why:

• Schedule uniqueID (MANDATORY) = this is what allow us to know in which schedule we need to import the items. If the UID don't match any of the existing schedule uniqueID, we will create a new schedule
• Sub-playlist uniqueIDs are important (not the events uniqueID) if you are doing a lot of import. If no Unique ID is set for your sub playlists, OnTheAir Manager will create a new playlist in the playlist browser every time a new schedule is imported. Note that only sub-playlists can be seen by users. The event's playlists can not be seen in the UI of OnTheAir Manager. BUT make real sure that you don't reuse the same unique ID 2 times, as the last playlist imported will delete the previous playlist with the same uniqueID.
• Live items (Type=External) must have a clipInfoUniqueID as well, otherwise, a new one will be created on each import
• All the playbackUniqueID are not mandatory but are strongly recommended (and will be useful for you as you will find them in the as-run-logs). If you choose to use playbackUniqueIDs, they must be absolutely unique and consistent on each import. The playbackUniqueID is used for 2 main things:
  • to allow OnTheAir Manager to display which clip/playlist is currently playing on Node. If you are not consistent between your imports, we might not be able to display which clip is currently playing as we won't find its playbackUniqueID in the new schedule that was imported.
  • to allow OnTheAir Node to reposition itself in a new schedule that it receives. When a new schedule is received, OnTheAir Node checks which clip/playlist playbackUniqueID it si currently playing, will try to find it in the new schedule and position itself there. If it can't find the same playbackUniqueID in the new schedule, it will position itself according to the new schedule timing. 
  • the PlaybackUniqueID will also be logged in the as-run-logs, and so you can know exactly what has been broadcasted.?-

Events or Playlists?

You have surely noticed that in OnTheAir Manager, you can have events and playlists. And there can be some confusion about what each one does, so let's try to sum it up:

• a playlist is simply a list of clips (and sub playlists) to be broadcasted. It has no start/end date, and thus no duration set. It will last for the duration of the clips that are inside, or until an event interrupts it.
• an event is a playlist with a fixed start date and time. It can hold clips or playlists. The most important thing is its start date/time. An event will always start at the specified date/time and interrupt what was playing before, and will not start earlier if the previous event ends earlier. Also the playback is not stopped at the end of an event (for as long as there are media to play), but only at the start of a new event.

We often have the question: could we have an event that starts when the previous one ends. Our typical answer is: that's what a playlist is for!

We recommend having 2-3 events per day as every time that there is an event, you must make sure that it ends correctly without creating a black (underrun), or cutting a program in the middle. At the end of an event we also recommend adding a small playlist or clip in Loop just in case some programs went missing. So there is always something playing.

What happens when a schedule is imported in OnTheAir Manager ?

When a user selects File > Import XML schedule, or if it is done automatically using the "watch folder", OnTheAir Manager will:

• Verify that the XML Schedule uniqueID matches one of the existing schedules in the database
• If it does not exist yet, it will create a new Schedule in database with:
  • the name set by the displayName value  of the XML schedule
  • the start date time of the new schedule set by the "startDateTime" value of the XML Schedule
  • the end date time is one year later (endDateTime value of XML Schedule is not used) => all schedules created automatically have a one year duration.
• If the XML Schedule uniqueID already exists in our database, we will check that:
  • the startDateTime of the XML Schedule is < to the endDateTime of the Schedule
  • the endDateTime of the XML Schedule is > to the startDateTime of the Schedule
• Delete from the current Schedule all events that are between the startDateTime and the endDateTime of the XML Schedule.
• Import all events between the XML Schedule start date/time and the end date/time => all events before and after these times are ignored.
• If it finds a playlist with the same uniqueID as one in its database, it will modify it with the new content and attributes of the imported playlist.

!!! IMPORTANT Note: you will notice, that it is not an update, a section of the schedule is deleted, and reimported. This is why you must make sure of your schedule startDateTime and endDateTime so you don't delete a portion of the schedule that is important to the user. Only set the value that you want to update.

Also if you don't pay attention, sub-playlists use in other events or schedules might be modified if you reuse the same uniqueID.