Replacement Songs
This example will detail the steps required in the API to allow a user to replace and existing song in the log with a different song.
Message Received always means the message Nexus received and Message Sent is always the message Nexus returns.
Scenario
Your air staff is solid, but every once in a while they pick a song that just makes you cringe. You wonder where they dug it up. You really wish they couldn't even consider some songs at all.
Nexus Solution
Multiple steps are required to accomplish this.
With the automation system, a request is made by the user, typically in a nice user interface. As the third-party system, you'll make the request including the historyID number for the scheduled song to be replaced. Our example is going to look for only perfect songs and will return only the top 16 matches it finds. This is done with the "maxSongs" and "testFilter" options. It looks like this. Notice also we are asking for basic field information be returned including Artist, Title and Run Time.
<mmRequest command="getReplacementSongs" station="TestStation" client="AutomationSystem" userData=""> <contents> <element airTime="2016-08-31T11:15:13" pos="replace" historyId="355386"/> <maxSongs>16</maxSongs> <testFilter>perfectOnly</testFilter> <fields> <field name="Title"/> <field name="Cart Number"/> <field name="Category"/> <field name="Artist"/> <field name="Run Time"/> </fields> <query> <filters/> <properties> <property name="filterMatchMode">any </properties> </query> </contents> </mmRequest>
The reply comes back from Nexus indicating it found the items requested and lists all the songs that fit the request. The songID is included along with all the other meta data fields we requested.
<mmReply command="getReplacementSongs" station="TestStation" messageId="2" status="ok"> <contents> <songList recordCount="8"> <song songId="102" cutId="0004"> <field id="102" name="Title">Arrows</field> <field id="107" name="Cart Number">0004</field> <field id="105" name="Category">100</field> <field id="101" name="Artist">Fences F\Macklemore</field> <field id="12" name="Run Time">03:52</field> </song> <song songId="747" cutId="0026"> <field id="102" name="Title">One More Night</field> <field id="107" name="Cart Number">0026</field> <field id="105" name="Category">101</field> <field id="101" name="Artist">Morgan Alexander</field> <field id="12" name="Run Time">03:36</field> </song> <song songId="169" cutId="000W"> <field id="102" name="Title">Ghost</field> <field id="107" name="Cart Number">000W</field> <field id="105" name="Category">101</field> <field id="101" name="Artist">Elle Henderson</field> <field id="12" name="Run Time">03:30</field> </song> <song songId="108" cutId="000D"> <field id="102" name="Title">Rude</field> <field id="107" name="Cart Number">000D</field> <field id="105" name="Category">100</field> <field id="101" name="Artist">Magic</field> <field id="12" name="Run Time">03:40</field> </song> <song songId="101" cutId="0001"> <field id="102" name="Title">Girls</field> <field id="107" name="Cart Number">0001</field> <field id="105" name="Category">100</field> <field id="101" name="Artist">1975</field> <field id="12" name="Run Time">03:25</field> </song> <song songId="434" cutId="001B"> <field id="102" name="Title">Dangerous</field> <field id="107" name="Cart Number">001B</field> <field id="105" name="Category">101</field> <field id="101" name="Artist">Big Data F/Joywave</field> <field id="12" name="Run Time">04:13</field> </song> <song songId="110" cutId="000H"> <field id="102" name="Title">Habits (Stay High)</field> <field id="107" name="Cart Number">000H</field> <field id="105" name="Category">100</field> <field id="101" name="Artist">Tove Lo</field> <field id="12" name="Run Time">03:23</field> </song> <song songId="744" cutId="0308"> <field id="102" name="Title">Son's Gonna Rise</field> <field id="107" name="Cart Number">0308</field> <field id="105" name="Category">IND</field> <field id="101" name="Artist">Citizen Cope</field> <field id="12" name="Run Time">03:52</field> </song> </songList> </contents> </mmReply>
The third party system then requests the Song History for each of the songID's in the above reply with a maximum of 20 history elements. This allows the automation system to display the Last Play, Next Play information in the Automation system if needed.
<mmReply command="getSongHistory" station="TestStation" messageId="3" status="ok"> <contents> <songList> <song songId="102"> <historyList> <history historyId="357062" airDate="2016-09-03" airTime="19:00:00" runTime="03:52"/> <history historyId="356947" airDate="2016-09-03" airTime="13:38:11" runTime="03:52"/> <history historyId="356852" airDate="2016-09-03" airTime="09:00:00" runTime="03:52"/> <history historyId="356737" airDate="2016-09-03" airTime="03:44:51" runTime="03:52"/> <history historyId="356646" airDate="2016-09-02" airTime="23:16:17" runTime="03:52"/> <history historyId="356532" airDate="2016-09-02" airTime="17:58:02" runTime="03:52"/> <history historyId="356422" airDate="2016-09-02" airTime="12:35:33" runTime="03:52"/> <history historyId="356327" airDate="2016-09-02" airTime="08:00:00" runTime="03:52"/> <history historyId="356196" airDate="2016-09-02" airTime="01:58:09" runTime="03:52"/> <history historyId="356121" airDate="2016-09-01" airTime="22:15:25" runTime="03:52"/> <history historyId="356002" airDate="2016-09-01" airTime="16:38:23" runTime="03:52"/> <history historyId="355902" airDate="2016-09-01" airTime="11:54:51" runTime="03:52"/> <history historyId="355792" airDate="2016-09-01" airTime="06:37:14" runTime="03:52"/> <history historyId="355697" airDate="2016-09-01" airTime="02:00:00" runTime="03:52"/> <history historyId="355608" airDate="2016-08-31" airTime="21:59:23" runTime="03:52"/> <history historyId="355529" airDate="2016-08-31" airTime="18:00:00" runTime="03:52"/> <history historyId="355445" airDate="2016-08-31" airTime="14:00:00" runTime="03:52"/> <history historyId="355298" airDate="2016-08-31" airTime="07:00:00" runTime="03:52"/> <history historyId="355167" airDate="2016-08-31" airTime="00:55:29" runTime="03:52"/> <history historyId="355083" airDate="2016-08-30" airTime="20:53:43" runTime="03:52"/> </historyList> </song> <song songId="747"> <historyList> <history historyId="357010" airDate="2016-09-03" airTime="16:41:54" runTime="03:36"/> <history historyId="356898" airDate="2016-09-03" airTime="11:15:52" runTime="03:36"/> <history historyId="356784" airDate="2016-09-03" airTime="05:56:57" runTime="03:36"/> <history historyId="356679" airDate="2016-09-03" airTime="00:59:59" runTime="03:36"/> <history historyId="356590" airDate="2016-09-02" airTime="20:39:16" runTime="03:36"/> <history historyId="356478" airDate="2016-09-02" airTime="15:13:39" runTime="03:36"/> <history historyId="356373" airDate="2016-09-02" airTime="10:15:46" runTime="03:36"/> <history historyId="356243" airDate="2016-09-02" airTime="04:00:00" runTime="03:36"/> <history historyId="356133" airDate="2016-09-01" airTime="22:55:15" runTime="03:36"/> <history historyId="356065" airDate="2016-09-01" airTime="19:40:56" runTime="03:36"/> <history historyId="355953" airDate="2016-09-01" airTime="14:15:56" runTime="03:36"/> <history historyId="355848" airDate="2016-09-01" airTime="09:14:47" runTime="03:36"/> <history historyId="355734" airDate="2016-09-01" airTime="03:59:59" runTime="03:36"/> <history historyId="355634" airDate="2016-08-31" airTime="23:00:00" runTime="03:36"/> <history historyId="355545" airDate="2016-08-31" airTime="18:59:59" runTime="03:36"/> <history historyId="355435" airDate="2016-08-31" airTime="13:41:06" runTime="03:36"/> <history historyId="355323" airDate="2016-08-31" airTime="08:13:59" runTime="03:36"/> <history historyId="355209" airDate="2016-08-31" airTime="02:59:17" runTime="03:36"/> <history historyId="355104" airDate="2016-08-30" airTime="21:53:17" runTime="03:36"/> <history historyId="355008" airDate="2016-08-30" airTime="17:14:40" runTime="03:36"/> </historyList> </song> <song songId="169"> <historyList> <history historyId="357104" airDate="2016-09-03" airTime="21:00:00" runTime="03:30"/> <history historyId="356968" airDate="2016-09-03" airTime="14:40:41" runTime="03:30"/> <history historyId="356905" airDate="2016-09-03" airTime="11:35:33" runTime="03:30"/> <history historyId="356805" airDate="2016-09-03" airTime="06:59:59" runTime="03:30"/> <history historyId="356653" airDate="2016-09-02" airTime="23:39:34" runTime="03:30"/> <history historyId="356553" airDate="2016-09-02" airTime="18:54:38" runTime="03:30"/> <history historyId="356499" airDate="2016-09-02" airTime="16:15:16" runTime="03:30"/> <history historyId="356385" airDate="2016-09-02" airTime="10:58:38" runTime="03:30"/> <history historyId="356322" airDate="2016-09-02" airTime="07:59:55" runTime="03:30"/> <history historyId="356238" airDate="2016-09-02" airTime="03:56:53" runTime="03:30"/> <history historyId="356191" airDate="2016-09-02" airTime="01:39:21" runTime="03:30"/> <history historyId="356070" airDate="2016-09-01" airTime="19:59:29" runTime="03:30"/> <history historyId="355944" airDate="2016-09-01" airTime="13:59:59" runTime="03:30"/> <history historyId="355839" airDate="2016-09-01" airTime="08:57:59" runTime="03:30"/> <history historyId="355755" airDate="2016-09-01" airTime="04:55:11" runTime="03:30"/> <history historyId="355655" airDate="2016-09-01" airTime="00:00:00" runTime="03:30"/> <history historyId="355575" airDate="2016-08-31" airTime="20:15:30" runTime="03:30"/> <history historyId="355477" airDate="2016-08-31" airTime="15:35:54" runTime="03:30"/> <history historyId="355340" airDate="2016-08-31" airTime="09:00:00" runTime="03:30"/> <history historyId="355256" airDate="2016-08-31" airTime="05:00:00" runTime="03:30"/> </historyList> </song> <song songId="108"> <historyList> <history historyId="357108" airDate="2016-09-03" airTime="21:15:13" runTime="03:40"/> <history historyId="357003" airDate="2016-09-03" airTime="16:16:08" runTime="03:40"/> <history historyId="356894" airDate="2016-09-03" airTime="11:00:00" runTime="03:40"/> <history historyId="356789" airDate="2016-09-03" airTime="06:00:00" runTime="03:40"/> <history historyId="356684" airDate="2016-09-03" airTime="01:00:00" runTime="03:40"/> <history historyId="356579" airDate="2016-09-02" airTime="20:00:00" runTime="03:40"/> <history historyId="356474" airDate="2016-09-02" airTime="15:00:00" runTime="03:40"/> <history historyId="356369" airDate="2016-09-02" airTime="10:00:00" runTime="03:40"/> <history historyId="356264" airDate="2016-09-02" airTime="05:00:00" runTime="03:40"/> <history historyId="356159" airDate="2016-09-02" airTime="00:00:00" runTime="03:40"/> <history historyId="356054" airDate="2016-09-01" airTime="19:00:00" runTime="03:40"/> <history historyId="355949" airDate="2016-09-01" airTime="14:00:00" runTime="03:40"/> <history historyId="355844" airDate="2016-09-01" airTime="09:00:00" runTime="03:40"/> <history historyId="355739" airDate="2016-09-01" airTime="04:00:00" runTime="03:40"/> <history historyId="355638" airDate="2016-08-31" airTime="23:17:58" runTime="03:40"/> <history historyId="355533" airDate="2016-08-31" airTime="18:15:25" runTime="03:40"/> <history historyId="355428" airDate="2016-08-31" airTime="13:15:11" runTime="03:40"/> <history historyId="355319" airDate="2016-08-31" airTime="08:00:00" runTime="03:40"/> <history historyId="355214" airDate="2016-08-31" airTime="03:00:00" runTime="03:40"/> <history historyId="355109" airDate="2016-08-30" airTime="22:00:00" runTime="03:40"/> </historyList> </song> <song songId="101"> <historyList> <history historyId="357120" airDate="2016-09-03" airTime="21:56:51" runTime="03:25"/> <history historyId="357083" airDate="2016-09-03" airTime="20:00:00" runTime="03:25"/> <history historyId="356910" airDate="2016-09-03" airTime="11:53:27" runTime="03:25"/> <history historyId="356800" airDate="2016-09-03" airTime="06:40:41" runTime="03:25"/> <history historyId="356695" airDate="2016-09-03" airTime="01:40:23" runTime="03:25"/> <history historyId="356574" airDate="2016-09-02" airTime="19:59:29" runTime="03:25"/> <history historyId="356485" airDate="2016-09-02" airTime="15:36:01" runTime="03:25"/> <history historyId="356380" airDate="2016-09-02" airTime="10:38:05" runTime="03:25"/> <history historyId="356268" airDate="2016-09-02" airTime="05:16:11" runTime="03:25"/> <history historyId="356163" airDate="2016-09-02" airTime="00:16:30" runTime="03:25"/> <history historyId="356033" airDate="2016-09-01" airTime="18:00:00" runTime="03:25"/> <history historyId="355923" airDate="2016-09-01" airTime="12:55:34" runTime="03:25"/> <history historyId="355855" airDate="2016-09-01" airTime="09:37:10" runTime="03:25"/> <history historyId="355750" airDate="2016-09-01" airTime="04:36:54" runTime="03:25"/> <history historyId="355650" airDate="2016-08-31" airTime="23:54:55" runTime="03:25"/> <history historyId="355519" airDate="2016-08-31" airTime="17:37:22" runTime="03:25"/> <history historyId="355424" airDate="2016-08-31" airTime="13:00:00" runTime="03:25"/> <history historyId="355330" airDate="2016-08-31" airTime="08:36:48" runTime="03:25"/> <history historyId="355218" airDate="2016-08-31" airTime="03:14:38" runTime="03:25"/> <history historyId="355113" airDate="2016-08-30" airTime="22:17:30" runTime="03:25"/> </historyList> </song> <song songId="434"> <historyList> <history historyId="357099" airDate="2016-09-03" airTime="20:59:59" runTime="04:13"/> <history historyId="356994" airDate="2016-09-03" airTime="15:54:24" runTime="04:13"/> <history historyId="356884" airDate="2016-09-03" airTime="10:41:18" runTime="04:13"/> <history historyId="356779" airDate="2016-09-03" airTime="05:39:13" runTime="04:13"/> <history historyId="356674" airDate="2016-09-03" airTime="00:40:04" runTime="04:13"/> <history historyId="356569" airDate="2016-09-02" airTime="19:38:11" runTime="04:13"/> <history historyId="356464" airDate="2016-09-02" airTime="14:38:28" runTime="04:13"/> <history historyId="356359" airDate="2016-09-02" airTime="09:39:46" runTime="04:13"/> <history historyId="356259" airDate="2016-09-02" airTime="04:57:37" runTime="04:13"/> <history historyId="356149" airDate="2016-09-01" airTime="23:37:04" runTime="04:13"/> <history historyId="356049" airDate="2016-09-01" airTime="18:55:22" runTime="04:13"/> <history historyId="355939" airDate="2016-09-01" airTime="13:41:48" runTime="04:13"/> <history historyId="355834" airDate="2016-09-01" airTime="08:38:44" runTime="04:13"/> <history historyId="355729" airDate="2016-09-01" airTime="03:41:42" runTime="04:13"/> <history historyId="355629" airDate="2016-08-31" airTime="22:59:59" runTime="04:13"/> <history historyId="355524" airDate="2016-08-31" airTime="17:51:14" runTime="04:13"/> <history historyId="355419" airDate="2016-08-31" airTime="12:52:03" runTime="04:13"/> <history historyId="355314" airDate="2016-08-31" airTime="07:53:58" runTime="04:13"/> <history historyId="355204" airDate="2016-08-31" airTime="02:41:11" runTime="04:13"/> <history historyId="355099" airDate="2016-08-30" airTime="21:35:00" runTime="04:13"/> </historyList> </song> <song songId="110"> <historyList> <history historyId="357125" airDate="2016-09-03" airTime="22:00:00" runTime="03:23"/> <history historyId="357020" airDate="2016-09-03" airTime="17:00:00" runTime="03:23"/> <history historyId="356915" airDate="2016-09-03" airTime="12:00:00" runTime="03:23"/> <history historyId="356810" airDate="2016-09-03" airTime="07:00:00" runTime="03:23"/> <history historyId="356705" airDate="2016-09-03" airTime="02:00:00" runTime="03:23"/> <history historyId="356600" airDate="2016-09-02" airTime="21:00:00" runTime="03:23"/> <history historyId="356495" airDate="2016-09-02" airTime="16:00:00" runTime="03:23"/> <history historyId="356390" airDate="2016-09-02" airTime="11:00:00" runTime="03:23"/> <history historyId="356285" airDate="2016-09-02" airTime="06:00:00" runTime="03:23"/> <history historyId="356180" airDate="2016-09-02" airTime="01:00:00" runTime="03:23"/> <history historyId="356075" airDate="2016-09-01" airTime="20:00:00" runTime="03:23"/> <history historyId="355970" airDate="2016-09-01" airTime="15:00:00" runTime="03:23"/> <history historyId="355865" airDate="2016-09-01" airTime="10:00:00" runTime="03:23"/> <history historyId="355760" airDate="2016-09-01" airTime="05:00:00" runTime="03:23"/> <history historyId="355659" airDate="2016-09-01" airTime="00:16:09" runTime="03:23"/> <history historyId="355554" airDate="2016-08-31" airTime="19:14:11" runTime="03:23"/> <history historyId="355449" airDate="2016-08-31" airTime="14:15:37" runTime="03:23"/> <history historyId="355351" airDate="2016-08-31" airTime="09:40:53" runTime="03:23"/> <history historyId="355235" airDate="2016-08-31" airTime="04:00:00" runTime="03:23"/> <history historyId="355130" airDate="2016-08-30" airTime="23:00:00" runTime="03:23"/> </historyList> </song> <song songId="744"> <historyList> <history historyId="357094" airDate="2016-09-03" airTime="20:41:50" runTime="03:52"/> <history historyId="356989" airDate="2016-09-03" airTime="15:35:32" runTime="03:52"/> <history historyId="356877" airDate="2016-09-03" airTime="10:16:41" runTime="03:52"/> <history historyId="356772" airDate="2016-09-03" airTime="05:16:49" runTime="03:52"/> <history historyId="356667" airDate="2016-09-03" airTime="00:15:54" runTime="03:52"/> <history historyId="356562" airDate="2016-09-02" airTime="19:16:47" runTime="03:52"/> <history historyId="356457" airDate="2016-09-02" airTime="14:14:55" runTime="03:52"/> <history historyId="356352" airDate="2016-09-02" airTime="09:17:12" runTime="03:52"/> <history historyId="356254" airDate="2016-09-02" airTime="04:39:45" runTime="03:52"/> <history historyId="356142" airDate="2016-09-01" airTime="23:13:57" runTime="03:52"/> <history historyId="356044" airDate="2016-09-01" airTime="18:37:05" runTime="03:52"/> <history historyId="355932" airDate="2016-09-01" airTime="13:17:57" runTime="03:52"/> <history historyId="355827" airDate="2016-09-01" airTime="08:15:00" runTime="03:52"/> <history historyId="355722" airDate="2016-09-01" airTime="03:15:57" runTime="03:52"/> <history historyId="355624" airDate="2016-08-31" airTime="22:40:23" runTime="03:52"/> <history historyId="355512" airDate="2016-08-31" airTime="17:14:03" runTime="03:52"/> <history historyId="355414" airDate="2016-08-31" airTime="12:36:30" runTime="03:52"/> <history historyId="355309" airDate="2016-08-31" airTime="07:36:31" runTime="03:52"/> <history historyId="355197" airDate="2016-08-31" airTime="02:15:03" runTime="03:52"/> <history historyId="355092" airDate="2016-08-30" airTime="21:13:03" runTime="03:52"/> </historyList> </song> </songList> </contents> </mmReply>
The third party system displays these results in a GUI or list form for the disc jockey to select the song she wants from the list. The third party system then requests several commands to Drop the scheduled song and Add the selected song.
DROP:
<mmRequest command="reconcileElements" station="TestStation" client="AutomationSystem" userData=""> <contents> <elements> <element airTime="2016-08-31T11:15:13" mode="drop" historyId="355386"/> </elements> </contents> </mmRequest> ---------------------------------------------- Message Sent: 2016-08-31 10:55:42 [ID=4] Element Found: HourID=1022723 (8/31/2016 - 11AM) HistID=355386 (Sir Sly / You Haunt Me) <mmReply command="reconcileElements" station="TestStation" messageId="4" status="ok"> <contents> <results> <result mode="drop" songId="109" historyId="355386" status="ok"/> </results> </contents> </mmReply>
ADD is done through a series of requests, the first being getSongsByQuery to get the songID for the requested song:
<mmRequest command="getSongsByQuery" station="TestStation" client="AutomationSystem" userData=""> <contents> <query> <filters> <filter type="fieldName" target="Cart Number" operator="equals" value="000W"/> <filter type="fieldName" target="Category" operator="equals" value="101"/> </filters> <sortKeys> <sortKey type="fieldName" target="Title" order="asc"/> </sortKeys> <properties/> </query> <properties> <property name="maxRecs">1</property> </properties> </contents> </mmRequest> ---------------------------------------------- Message Sent: 2016-08-31 10:55:43 [ID=5] <mmReply command="getSongsByQuery" station="TestStation" messageId="5" status="ok"> <contents> <songList recordCount="1"> <song songId="169" cutId="000W"/> </songList> </contents> </mmReply>
Then reconcileElements is used to ADD the song into the position in the schedule.
<mmRequest command="reconcileElements" station="TestStation" client="AutomationSystem" userData=""> <contents> <elements> <element airTime="2016-08-31T11:18:44" airTimeNew="2016-08-31T11:15:13" pos="before" songIdNew="169" mode="add" historyId="355387"/> </elements> </contents> </mmRequest> ---------------------------------------------- Message Sent: 2016-08-31 10:55:43 [ID=6] Element Found: HourID=1022723 (8/31/2016 - 11AM) HistID=355387 (Journey / Lights) <mmReply command="reconcileElements" station="TestStation" messageId="6" status="ok"> <contents> <results> <result mode="add" songId="169" historyId="357169" status="ok"/> </results> </contents> </mmReply>
When it's all done, the old song is removed from MusicMaster and the new song is listed in its place.