reconcileElements

Performs individual history updates in MusicMaster. You can use this command to indicate that one or more elements have changed. This would generally be used to report a dropped or inserted song, or a more complex move or swap operation. You can also use this command to report the actual air time that an element started or ended playing.

 

This is a key request from many users since it updates the history and accurately represents what aired. This is important as many users need to create reports for governmental agencies that require this information.

Sample Request

<mmRequest command="reconcileElements" station="ID" [version="1"] [client=""] [userData=""]>
	<contents>
		<elements>
			<element mode="add|drop|playStart|playEnd" [airTime="yyyy-mm-ddThh:nn:ss"]
 			[runTime="mm:ss"] [pos="before|after|replace"] [songId="x"] [cutId="x"]
 			[historyId="x"] [airTimeNew="yyyy-mm-ddThh:nn:ss"] [songIdNew="x"]
			 [cutIdNew="x"] />
		</elements>
	</contents>
</mmRequest>

Request Notes

The elements section contains the actual changes you wish to make. You may specify multiple changes in a single call, with one element tag for each. While a simple add or drop would generally only affect a single element, a move might include a drop and an add, and a swap might include two adds with the mode=replace attribute. Usage for the available tag attributes varies based upon the type of change you wish to perform. Use the mode attribute to indicate the change type: add, drop, playStart and playEnd are currently supported. You must also specify the existing history element you wish to act on. This is done using the following attributes:

 

historyId – the MusicMaster History ID of the element, if known. This can be obtained using getSchedule and is the most exact way to target a specific element. If a valid History ID is specified, this will be used to determine which hour the desired element is located in. (Changed in MusicMaster PRO 5.0 SR-3) If you can specify a valid historyId, none of the other element targeting attributes here are necessary. You may still fill them in, but they will likely not be used.

 

airtime – indicates the starting airtime of the element you wish to target in ISO format. This is required if you do not specify a historyId. When targeting by airTime, the songId, cutId and runtime attributes may be used to find a more exact match. In this case, specifying songId is recommended. (This attribute was required prior to MusicMaster PRO 5.0 SR-3)

 

runtime – the runtime of the specified element

 

songId – the MusicMaster songId of the song you wish to target

 

cutId – the third party unique ID of the song you wish to target, if defined and available

 

 

Once the targeted element is located, an action will be performed based on the specified mode attribute:

 

add – used to add or replace a song element in the log. Use the pos attribute to indicate where to perform the song add. Set pos=“before" to insert before the targeted element or “after" to insert after it. Set pos="replace" to replace the targeted song with a new one. You must also indicate the song to add, or replace using the attribute songIdNew if you wish to supply a MusicMaster Song ID or cutIdNew if you wish to supply a third party unique ID.

 

drop – used to delete a song element in the log. The targeted element will be deleted, if found.

 

playStart – used to adjust the song airtime in the log for reconciliation purposes. Use playStart when you want to reconcile at the time when song airplay begins and use playEnd when you want to reconcile at the time when song airplay ends.

 

playEnd – used to adjust the song airtime in the log for reconciliation purposes. Use playStart when you want to reconcile at the time when song airplay begins and use playEnd when you want to reconcile at the time when song airplay ends.

 

When using playStart or playEnd, you must indicate the new time the playback started or ended. Specify this in the airTimeNew attribute in ISO format. Note that the playEnd mode will automatically subtract the song runtime from airTimeNew to calculate the actual new song airtime for the MusicMaster.

 

Notes:

See also the newer related command modifySchedule

 

When searching for an element by airtime only, the element selected will be the first one from the start of the hour that is scheduled to start at the specified airtime, or the one that starts before and runs through the specified airtime.

 

Even though songIdNew and cutIdNew are both listed as optional, one or the other must be included when performing an add operation.

 

Performance can be maximized by using the MusicMaster historyId to target elements and the MusicMaster songId to add or replace elements.

Sample Reply

<mmReply command="reconcileElements" station="ID" version="1" [userData=""] status="???????">
	[<errors>
		<error>message</error>
	</errors>]
	[<results>
		<result [mode] [songId] [historyId] status="ok|error"></result>
	</results>]
</mmReply>

Reply Notes

This command does not return any schedule data. Instead, the server performs the reconciliation and returns a status code and any error messages. If a non-generic interface is in use, the method used to reconcile the schedule may vary.

Compatibility and Version Info

Available in all versions

 

Changed the histId attribute to historyId in MusicMaster PRO 4.0sr19. histId is still valid here, but historyId is more consistent with other functions.

 

Starting with MusicMaster PRO 5.0sr3, the airTime property is no longer required when you have the history ID of the element you wish to change. It is recommended that you still specify an air time for compatibility with older versions. The history ID value will now take precedence over the specified airtime. [5001]

 

Added the results section to the reply message in MusicMaster PRO5.0sr3. [5001]