Scripting Xibo Content Management - A brief tour of the API

Please note: This article refers to Xibo 1.7 only and has been retired from our catalogue of updated Guides. Please refer to the API Introduction Guide 1.8

One common use case people put forward is that they want to update a particular piece of content in a layout automatically on a schedule.

That could take the form of a video being updated on a daily basis, or an image.

Since Xibo 1.5 series, there has been a “work in progress” OAuth authenticated API for scripting actions in the Xibo CMS. As of Xibo 1.6.0-rc1, there are enough API methods implemented to do some basic layout and media management to script tasks such as these.

This article is a basic walk through showing you how to connect to the API, authorise an application to use the Xibo CMS on your behalf, a quick look at some basic API methods, and finally complete code to automatically replace a media item in a layout.

Firstly you must be running Xibo CMS 1.6.0-rc1 or later. Earlier versions may not have the API methods required for this guide.

This guide uses Python as the scripting language. Python is chosen because it’s cross platform, widely available, and it’s what the Xibo project uses to test the API with, so there are existing libraries (XiboAPI) that we can leverage. It’s perfectly possible to connect to the API from other languages. Indeed some example PHP code is provided in the main Xibo repository. The use of the API from other languages however falls outside this scope of this guide.

Most modern Linux installations will come with Python ready-installed. Windows users can download and install Python here: http://www.python.org/getit This guide assumes you have Python 2.7 installed.

You also need the Python OAuth2 library installed. - On Linux, you’ll need to install the “python-oauth2” package (at least on Debian based systems such as Ubuntu).

Python is a white-space delimited language, which means that the amount each line of code is indented defines which code block a line belongs to. It’s therefore very important that you setup your text editor to follow the standard Python convention. Tab characters should not be used, but instead four space characters. On Linux, gedit is a suitable choice, and on Windows I’d recommend Notepad++.

This guide will give you the overview of how to communicate with the Xibo CMS via the API. It is not intended to be a guide on programming in the Python scripting language. There’s a plethora of resources out there aimed at that. I would recommend Dive into Python as a good primer before embarking on this is Python is your chosen language.

So lets make a start! We’ll create a new file called ReplaceVideo.py with the following contents:

So there we’ve defined that the script is Python and that it’s UTF-8 encoded (so we don’t have issues with unicode characters down the line). We then import the os, minidom and XiboAPI libraries. Finally we create an instance of the XiboAPI to communicate with the CMS.

Next we need to register your application with the Xibo CMS. You’ll need an administrative login to your Xibo CMS. - Once logged in as an administrator (eg xibo_admin), go to Administration -> Applications

Click Add Application

Enter your name and email address. You can leave the third and fourth boxes (website and callback URL empty)

Click Register

Note the Key and Secret that have been generated. We’ll need those in the next step.

Next open defaults.cfg in your text editor. We need to point the XiboAPI library at your Xibo CMS.

Edit the file as follows, replacing the consumer_key and consumer_secrets with the values you got from your CMS, and the URL for your Xibo CMS:

That’s the output from my script so far. So hopefully your script will attempt to connect to the Xibo CMS at the URL you configured, and will ask you to authorise it with the CMS. Now before you click the link, it’s important that you log on to the Xibo CMS as the user you want the script to impersonate. So if the script needs to appear to be the user “alex”, log off the Xibo CMS and log in as “alex”. Then follow the link.

You’ll be taken to a page “Xibo API – Authorization Requested”. Click the Allow button. Since we didn’t define a callback URL, the page will refresh lots now. That’s normal and can be ignored. Keep clicking the Allow button until you see a message ‘Request authorized. Please return to your application.’

Go back to your running script and enter “y” to indicate the API request has been authorised.

Excellent, so now we have access to the XiboAPI as your intended user. I appreciate that’s alot of setup work but most of this only ever needs to be done once. You can reuse the same XiboAPI object in more than one project.

Your access tokens will automatically be written to disk in a file called site.cfg. Keep that file safe as the contents allow API access to your Xibo CMS.

Now let’s do something useful with the API! Lets get a list of layouts in the system. Add the following to your ReplaceVideo.py script:

Save the file and run it again. Note this time since we already have API credentials, the access to the API is seemless and no user interaction is required. A list of layouts the user has access to view is shown:

So my example layout (id 5) has two regions on it. The right-most region is the one which will host our video and that’s the second one in the list (we know it’s that one as the Left value is highest putting it further away from the left hand edge of the layout). So we’ll make a note of the region ID (5303e4c0c0973)

Hopefully that’s given a basic overview of how to navigate the API, how to pass in parameters etc. Now we’ll remove most of the code we’ve written and get on with the job in hand of scripting the file upload and replacing that video in the region. We need to remember it’s Layout ID 5, region 5303e4c0c0973 (or the correct values from your CMS). That’s how we’ll identify where we want our video to end up being added, and the old video to delete.

Clearly set layoutId and regionId to the correct values we obtained earlier. Change fileToUpload to be the filename of the video you want to upload. It could be in the same directory as your script (in which case just the name is sufficient), or it could be a full path to the file. It’s up to you.

I’ve included some library functions to do the heavy lifting for you. Add the following to the file and save:

So first up we upload the new file to the CMS. Note here that by upload we mean copy it to the server ready to be added to the library. We add it to the library in a second stage later on. Add the following to upload:

Upload our file to the CMS so it's ready to add # Note this won't make it appear in the library # We do that further down the script uploadId = uploadFile(api,fileToUpload)

Next we need to find the ID of the old video file, remove it from the Region Timeline, and then delete it from the library. Add the following: