Overlay Layout API

Hello All!
I have been working through the API document outlined here and have come to the conclusion that I have the API’s and XMR configured correctly.
I know this as I am able to create a layout using the “Layout Create” API.

What I am attempting to achieve is to manually force a layout onto a Xibo player screen.

The first screenshot is of the Auth Header

and the second is of the POST fields

the last screenshot if of the response…

Is there anything else I can check?

I don’t think you made any mistakes there, looking at the code I don’t think this action (OverlayLayoutAction) is suppose to work in its current state - we will look into that obviously.

Now, what you can use, if you want simply change the layout (not overlay per se), then please use ChangeLayoutAction which is very similar to the one you’ve tried.

Currently if you’d like to have an overlay layout (ie layout on top of other currently scheduled layout) you will want to use POST Schedule call with eventTypeId set to 3, something like that:

Now, just to clarify one more thing while we at it.

The campaignId and displayGroupIds[] parameters in this call.

campaignId - it can be an Id of an actual campaign in CMS which you can get by calling [GET Campaigns]
(Swagger UI)

It is also important to understand that each layout has it’s own unique layout specific campaignId, which also can be used in this call, you can get layout specific campaignId with GET Layout call

displayGroupIds[] or displayGroupId in changeLayout

The same logic applies here

displayGroupId - it can be actual displayGroupId visible in web ui or via GET displayGroup call
OR it can be display specific display group, as each display has it’s own unique displayGroupId, which you can see by using GET Displays call

Hi Peter, thank you for this.
Essentially, the reason I wanted to do an overlay was I have a webhook from another service which will trigger the layout change. This is to be an instant change (within circa 15 seconds).
The only issue I thought using the ChangeLayoutAction is that I would then have to revert the layout back to a previous layout. So essentially it would be using the API to momentarily change or overlay the screen with information presented from the webhook. I will have a go with the POST schedule and see how it goes as I might be able to use the fromDt and toDt times to expire the new layout?


Using the changeLayout API, the screen fails to update (through the displayGroupId of the Display Group or the Individual displayGroupId, I have tried both)

Is there anything the GUI side that could be mis-configured which disallows API’s to change layout content?

In changeLayout you can provide the duration for which it should remain on screen - if not provided it should be on the screen for the layout duration.

in schedule, it’s pretty much the same as if you’d create a new schedule event on Schedule page in web ui.

I’d say that should work, change should be pretty much instant ( - time to download content if required)

What do you have in ‘Headers’ seems like there are two lines there?
I assume you perhaps switched between form-data and x-www-form-urlencoded that added second line to header?

Is that on Windows (1.8.2) or android (1.8R102) player?

Oh Duration would be perfect for what I need then… I can see that the Layouts have downloaded to the display by checking the display manage page through the GUI but are just not displaying… You are correct about the form-data and x-www-form-urlencoded, even after removing this, I get the same HTTP response but no layout change. I have also just updated the CMS and rebooted to be sure nothing strange was happening with the VM. Also, currently on Version 1.8.1, should I upgrade?


I believe there was an issue with this call on 1.8.1, although that was mostly regarding Windows player and the duration parameter from what I recall.

There also was issue with some call operating on layout specific campaignId (and other with similar logic).

That being said I believe the call itself (changeLayout) was working on 1.8.1, of course upgrade to 1.8.2 both CMS and player would be recommended as there were quite a few bug fixes between those versions, some of them directly affecting api calls.

When you run this command on Windows player status window you should see something like that:

On Android player I believe it’s {layoutId}(A) under schedule status on player status window.

Could you perhaps run this command against your player and have the status window open to see if it logs any errors?

in CMS → Log page
You can also set the advanced filer with channel set to API, which might contain some helpful log messages as well.

Peter, I am please to report that the upgrade has fixed this! Sorry to not have done my due diligence! I really appreciate your help and responsiveness on this… now to create some really cool work flows! However, now my windows client seems to fall over and the Watchdog kicks in stating there are too many processes (but not every time!)

Thanks again, Alex.

I’m glad to hear that it works now.

Regarding Windows player, you can open windows task manager, make sure there is only one instance of the player running, if there are more close them - in theory there should not be more than one, but perhaps it didn’t fully end the process or something similar and started a new one which is confusing watchdog.