HOW TO: Send a schedule to OnTheAir Node using the REST API

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 second workflow where the schedule are sent directly to OnTheAir Node. If you want to import the schedule into OnTheAir Manager instead please check the following article: https://softron.zendesk.com/hc/en-us/articles/207694967

Disclaimer

As said above, working directly with the Node REST API to send schedules to it requires more work  than when using OnTheAir Manager as the "middle man" for a few reasons:

• You will have to make sure to show a user interface to the user with the playback status, show which clip is playing, the remaining time, etc. 
• You will have to allow last minute control (skip to next, update schedule, etc...)
• You will have to handle the error management
• As there is no middle man, you are that needs to make sure the schedule you send to OnTheAir Node is correct and have all the required information. Some XML information that are not mandatory in OnTheAir Manager will be mandatory when sent directly with OnTheAir Node. When OnTheAir Manager is the "middle man", he's the one who will make sure that the schedule is properly formatted for OnTheAir Node.

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.

Send the schedule to OnTheAir Node

There are two ways to do that:

• either you send the schedule in json through the REST API.
• or you save the schedule as a .plist (property list) file to a folder and then ask OnTheAir Node to read that plist file.

How to format and send the schedule

Depending on how you will integrate, the formatting of the 2 schedules will be slightly different (one is json, and the other one is plist). A good way to know what should be done is to start with a sample schedule file.

In json to send to OnTheAir Node with the REST API

Attached to this article, the document OnTheAir Node_Schedule_json.txt which is the schedule info  and OnTheAir Node_Schedule_items_json.txt which is the schedule (its items) formatted as json. You will need to send both directly to OnTheAir Node.

Alternatively, if you want to start with a schedule using your own files, you could create a schedule with OnTheAir Manager, send it to OnTheAir Node, and then retrieve the json from OnTheAir Node with the REST API. Check the documentation on how to retrieve the schedule, but you can simply use these (the first one will retrieve the schedule info, and the second one the list of items):

http://127.0.0.1:4001/schedule

http://127.0.0.1:4001/schedule/items

Note that you will have to post both the schedule info (to change the start date and time) as well as the items.

Property list to be read from disk by OnTheAir Node

Attached to this article, the document OTAN_Schedule.plist is the schedule formatted as a plist file that OnTheAir Node will read from file.

Alternatively, if you want to start with a schedule using your own files, you could create a schedule with OnTheAir Manager, send it to OnTheAir Node, and then read the plist file that you can find here: /Library/Application Support/Softron/OnTheAir Node/Node 1/Schedule.plist

About Unique IDs

playbackUniqueID

You will notice that there are many Unique IDs in a schedule. The most important one will be the playbackUniqueID. They must be

• unique within a schedule (you can not have 2 identical uniqueIDs for 2 different items within a schedule).
• 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. IF you fail to do so, OnTheAir Node will not be able to reposition itself and will resume playback at the beginning of the current event instead of continuing the playback.

To understand why playbackUnique IDs are important you should know what happens when you send a new schedule to OnTheAir Node:

1. When OnTheAir Node receives a new schedules it first verifies that it has the mandatory information such as the start time, end time, display name. Note that it will only check that for the schedule info, it will not go through all the items in the schedule.
2. Then it store a path of unique IDs to remember what it was playing: SchedulePlaybackUniqueID/PlaylistPlaybackUniqueID/ItemPlaybackUniqueID
3. Then it will discard the old schedule completely
4. Then it will load the new schedule
5. And try to find in the new schedule the same "path" that it was playing in the old schedule. If it does not find it:
   • AND the schedulePlaybackUniqueID is the same => it will resume the playback at the beginning of the event
   • AND the schedulePlaybackUniqueID is different => it will start playing where it should be.

Other UniqueIDs

The clips have other UniqueIDs:

• clipInfoMediaItemUniqueID: is the unique ID of a media file itself. It is the second most important unique ID. Indeed to find a file, OnTheAir Node will first search at the absolute path indicated. If it can not find the file at the path indicated, it will search using its clipInfoMediaItemUniqueID. A clipInfoMediaItemUniqueID is calculated using 3 things from the file, which allows it to be unique:
  • its last modification date
  • its size
  • its name
• clipInfoMediaFolderUniqueID:  allows the Node to know in which media folder the file will be.
• clipInfoUniqueID: this is more an info coming from OnTheAir Manager where one same media file can have multiple clips (each with their own attributes) in the database. This is the less important of the unique IDs

Send the schedule

Authenticate

In order to prevent anybody from messing up with the Node, destructive (or playout) commands need to be authenticated by a token. That token is received by the "unlock" get command.

Here is how it works with the default "1234" password:

http://127.0.0.1:4001/unlock?password=1234

That will give you a token that will be valid until someone else authenticates (only one person can control the Node at a time). That other person could be authenticating with Manager, Live, Telnet or HTTP RESTful. 

So, if it fails, simply grab another token by repeating the command above.

Send the schedule

Once you have the token (and assuming it is still valid), you can use it to send the schedule to OnTheAir Node.

Send the schedule in json using the REST API

You will first need to POST the new info for the schedule (start and end times) in json (cf formatting in the document  OnTheAir Node_Schedule_json.txt):

POST /schedule?token={token}

Then you will need top POST the items in json (cf formatting in the document OnTheAir Node_Schedule_items_json.txt):

POST /schedule/items?token={token}

 

Ask OnTheAir Node to read the schedule plist file from disk

Once you have written the plist schedule to the disk you can 

POST /file_schedule_url?token={token}

And in the body pass the following json:

{
 "url": "file:///Volumes/data/MySchedule.plis"
}

Note that the url could also be a http url so it can reference a web server file.

More info on the Node REST API:

IF you want to know more about the REST API with OnTheAir Node, the protocol can be consulted at any time with the OnTheAir Node application. Just go on the computer where OnTheAir Node is installed and is running and type in a browser: 

http://127.0.0.1:4001/help.html

This should open a page with the complete protocol and calls you can make.