XMDS Specification
From Xibo
Contents |
Description
XMDS is a SOAP service run by the Xibo server for communication with clients.
XMDS is self-documenting to some degree via WSDL. The current WSDL can always be accessed at http://your.xibo.server/xmds.php?wsdl The latest XMDS WSDL at the time of writing is attached to this article.
Versioning
Broadly, whenever the client calls the webservice, it will report the schema version for xmds that it support. The servers response will include the schema version that it supports. Should these two revision numbers differ, the client will go in to offline mode and play only currently cached media.
Pseudocode
The order of events for consuming the SOAP service is roughly as follows:
- Client connects and calls registerDisplay
- If display is already registered, xmds returns "Display is active and ready to start."
- If display is new, xmds returns "Display added and is awaiting licensing approval from an Administrator".
- client calls requiredFiles
- client calls getFile on each file returned in requiredFiles, and populates the local blacklist cache with info from the blacklist element.
- client calls schedule to get a list of layouts that should be playing currently, along with their start and finish times.
- client returns log info as required to ReceiveXmlLog as a string o
- client blacklists any media which causes it problems (eg corrupt files, videos with missing codecs) as required with a call to BlackList referencing the media by it's type and ID, along with a reason. This will prevent that media being sent to the client again until the user interviens. The client should keep a local cache of blacklisted items for use between calls to requiredFiles.
The user must now authorise the display in the Maintenance->Displays dialogue in the server interface.
Note: Here client implementations differ. The .net client implements the register routine as a setup task in a GUI run from the start menu. The Java client has no such GUI, so will repeatedly call the XMDS service until it is told that the "Display is active and ready to start".
Note: this call can take place independently of 2 and 3, however no layout should be able to run until all the files in it are available and ready to use, so it simplifies client implementation to put them in this order as shown. The .net client is implemented in this way. The Python client implements a separate thread for points 2,3 and 4 so the interaction is more complex, but this arrangement allows for faster times from scheduling an item on the server to the changes being reflected on the client, especially where large files or large volumes of files are concerned.
Methods
There follows some notes I made while implementing the Java-Client about how to interact with the SOAP service. This is at an abstract level. Exactly the format of the XML passed between the client and the service was left to the Apache Axis library.
registerDisplay()
registerDisplay(serverKey,hardwareID,displayName,schemaVersion)
- serverKey - String. Must match the SERVER_KEY in the server configuration (Menu: Maintenance -> Configuration)
- hardwareID - String. Unique to the client string. Max length 40 characters. Generally implemented as an SHA1 or MD5 hash of some unique data.
- displayName - String. Friendly name for this display.
- schemaVersion - String. The XMDS schemaVersion implemented by this client.
This must be called before any other interaction with the server. It's function is to define a new display keyed on hardwareID - unless a display with hardwareID exists already. Consequently, hardwareID should be unique.
Returns a string - the status of this clients registration.
requiredFiles()
requiredFiles (serverKey,hardwareID,schemaVersion)
- serverKey - String. Must match the SERVER_KEY in the server configuration (Menu: Maintenance -> Configuration)
- hardwareID - String. Unique to the client string. Max length 40 characters. Generally implemented as an SHA1 or MD5 hash of some unique data.
- schemaVersion - String. The XMDS schemaVersion implemented by this client.
This collects an XML structure from the server describing all the files required to play layouts scheduled for this client.
<?xml version="1.0"?>
<files>
<file type="media" path="6.jpg" id="6" size="" md5=""/>
<file type="media" path="8.jpg" id="8" size="" md5=""/>
<file type="layout" path="1" md5="0781e57843b9fe70759b99504278737f"/>
<file type="media" path="7.jpg" id="7" size="" md5=""/>
<file type="media" path="8.jpg" id="8" size="" md5=""/>
<file type="media" path="6.jpg" md5="" size=""/>
<file type="layout" path="2" md5="ef74f46cd4844676494863f84dab2506"/>
<file type="blacklist"/>
</files>
Each file element has a type attribute. "media" types are media files required for the layout (eg jpeg, videos, flash etc), "layout" types are XLF files describing layouts. Each file element provides and MD5 sum and size of the file so the client can check if it already has that version of a file before downloading it. The third type attribute is "blacklist" which is the path to an XML file containing the current list of blacklisted media. The client should use this information to not attempt to play those media items (as they have caused problems previously).
getFile()
getFile (serverKey,hardwareID,filePath,fileType,chunkOffset,chunkSize,schemaVersion)
- serverKey - String. Must match the SERVER_KEY in the server configuration (Menu: Maintenance -> Configuration)
- hardwareID - String. Unique to the client string. Max length 40 characters. Generally implemented as an SHA1 or MD5 hash of some unique data.
- filePath - String. The filename of the media to be downloaded. Given to us by the "path" attribute in requiredFiles for this item. For a media item, this will be a full filename. For a layout, this will be just the layout id number. If the client stores this layout to disc, it should give it an appropriate extension (eg .xlf)
- fileType - String. The type of this file (layout | media | blacklist). Given to us by the "type" attribute in requiredFiles for this item.
- chunkOffset - int bytes. Where to start downloading from. 0 is the beginning of the file. Used to download a section of the file. Always 0 when dealing with a "layout" or "blacklist" type.
- chunkSize - int bytes. How much of the file to download in one go. 512,000 is a sensible number for "media" types. Always 0 when dealing with a "layout" or "blacklist" type - 0 signifies the whole content (only valid when dealing with layouts. Official clients use 512k chunks).
- schemaVersion - String. The XMDS schemaVersion implemented by this client.
Returns a base64 encoded byte array of length chunkSize or size depending on which type we are dealing with. Should be called multiple times for large media type files, incrementing chunkOffset by chunkSize at each call. The returned output can then be concatenated to form the original file.
schedule()
schedule (serverKey, hardwareID, schemaVersion)
- serverKey - String. Must match the SERVER_KEY in the server configuration (Menu: Maintenance -> Configuration)
- hardwareID - String. Unique to the client string. Max length 40 characters. Generally implemented as an SHA1 or MD5 hash of some unique data.
- schemaVersion - String. The XMDS schemaVersion implemented by this client.
Returns an XML structure in a string describing all the layouts that should be playing around now, along with their start and finish times:
<?xml version="1.0"?> <schedule> <layout file="1" fromdt="2050-12-31 00:00:00" todt="2050-12-31 00:00:00" scheduleid=""/> <layout file="2" fromdt="2008-12-08 08:00:00" todt="2008-12-11 21:19:00" scheduleid="1"/> </schedule>
Each layout element represents a layout to be shown. The "file" attribute refers to the filePath parameter from getFile and is also the layoutID number. This identifies the XLF to play. The "fromdt" is a string representing the time the layout should start being shown. The "todt" is a string representing the time the layout should stop being shown. The "fromdt" and "todt" fields are in the following format "yyyy-mm-dd hh:mm:ss".
receiveXmlLog()
receiveXmlLog (serverKey, hardwareID, xml, schemaVersion)
- serverKey - String. Must match the SERVER_KEY in the server configuration (Menu: Maintenance -> Configuration)
- hardwareID - String. Unique to the client string. Max length 40 characters. Generally implemented as an SHA1 or MD5 hash of some unique data.
- xml - String. XML Structure as defined below. This is used for reporting Errors, Audit and Display Statistics.
- schemaVersion - String. The XMDS schemaVersion implemented by this client.
The XML schema for this communication is documented here: Log XML Schema.
Returns true on success and a SOAP Fault on failure.
blacklist()
blacklist (serverKey, hardwareID, mediaID, type, reason, schemaVersion)
- serverKey - String. Must match the SERVER_KEY in the server configuration (Menu: Maintenance -> Configuration)
- hardwareID - String. Unique to the client string. Max length 40 characters. Generally implemented as an SHA1 or MD5 hash of some unique data.
- mediaID - Int. ID of the media being blacklisted.
- type - String (All|Single). If this is All then the media will be blacklisted for ALL displays that use it. If this is Single then it will only be blacklisted for the display described by hardwareID)
- reason - String. The reason for the blacklist. This is generally a short user readable description of the error - and not an error code. But the string can contain both.
- schemaVersion - String. The XMDS schemaVersion implemented by this client.
Returns true on success and a SOAP Fault on failure.
