> This is part 1 of 3 of the full documentation (pages 1–100 of 219). > The content is paginated: fetch every part to see all of it. > Next part: https://docs.xibosignage.com/llms-full.txt/1 > Page index: https://docs.xibosignage.com/llms.txt # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation This site has an agentic ask interface you may use to query the documentation dynamically by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.xibosignage.com/index.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. --- # Xibo User Manual Welcome to the Xibo User Manual. Whether you are a first time user or a user who wants to delve a bit deeper, the User Manual will help you maximise the full potential of all that Xibo has to offer. ## First Time User * Enter the web address **(URL)** of your CMS. * Use the **Username** and **Password** provided to you. * Click **Login**. We recommend changing the **Password** after first log in from the **User Profile** located in the top right of the CMS: * Click **Edit Profile** and enter your current Password. * Enter a **New Password** and repeat in the **Retype New Password** field. * Click to **Save**. Here you can also set your email address to ensure that notifications, password reminders etc. can be sent. The **User Profile** has a number of **Preferences** that can be set as well as a link to **Reshow welcome** at anytime. ### Strengthen login security with Two Factor Authentication Configure **Two Factor Authentication** options for either a code to be sent via **email** or enter the code as shown via the **Google Authenticator** app. Once enabled and saved, you will need to generate **Recovery Codes** to be used if access the email or Google Authenticator app is lost: * Click on **Generate**. * **Copy** the codes and store them in a safe place like Password Manager. * Click **Save** to make the codes active. If you need to view the generated codes at anytime, click on **Show**. ### Notifications User created messages and system events will be shown as **Notifications**, accessed from clicking the alarm bell icon located next to the **User Profile**. To add a Notification, click on **Notification Centre** and select **Add Notification** and complete the form fields. ## Showing content on Displays * If you have image and video content created outside of the \[\[PRODUCTNAME]] CMS, follow the guidance in the **Getting Started** section to start uploading and scheduling content to your Displays. * If you are going to create your content using the \[\[PRODUCTNAME]] CMS, begin with the **Layouts** section to start creating your own Layout designs either by modifying pre-designed **Templates** or by starting from a blank canvas. If you have yet to create a **Display** in the CMS, take a look at the **Displays** section to **Connect** and **Authorise** Displays to start showing content. ## FAQs ***Are training materials available for a new user?*** We have a selection of videos which complement our user documentation, more information is available from our [Training](https://xibosignage.com/training) page. ***I cannot retrieve my recovery codes, what should I do?*** If a User no longer has access to their email address/generated codes, an Administrator can reset these from the User grid. Once reset, take the steps to enable from the User Profile. ***What are My Applications from the User Profile?*** These are 3rd party applications that a User has authorised to act on their behalf within the CMS. An Administrator can add and configure Applications from the Administration section of the main CMS. ***I cannot see the Notification Drawer, to view or create?*** Notifications are enabled by an Administrator for a User using Features, tick to enable options for the appropriate access. Please ensure that a Sending Email address has been included on the Network tab from the Settings page, under the Administration section of the main CMS menu. ***What does the interrupt option do for Notifications?*** Using this option will automatically redirect Users to a page to view the notification in full. Please ensure that the Enable Email Alerts option has been enabled from the Maintenance tab from the Settings page, under the Administration section of the main CMS menu. ## Further Reading {% content-ref url="/pages/L8ste2vjohsdskhuMbDm" %} [Layout Editor](/layouts/layouts_editor) {% endcontent-ref %} {% content-ref url="/pages/uaWBSfMNEVm35oxtBGlb" %} [Using Templates](/layouts/layouts_editor_using_templates) {% endcontent-ref %} # Showing an Image on Displays Add an Image file to your Media Library and Schedule to play on Displays. You may have image content created outside of the Layout Editor, e.g. created by an agency, in house marketing team etc, ready to be shown full screen on your Display network. Image files are first added to the Library by upload or by URL. For this example an Image file will be uploaded to the CMS Media Library. ## How-to Video Showing an Image {% embed url="" %} ### Add Media 1. Click on **Media** under the **Library** section of the main CMS menu 2. Click the **Add Media** button 3. Drag and drop, provide a URL or click Add files to select the image file to upload 4. Provide a new **Name** or leave this field blank to keep the original file name 5. Click **Done** {% hint style="warning" %} Caution should be taken when uploading very large images. Users should check the **Resolution** of the Image and keep it within the intended screen size for best results. {% endhint %} ### Select Media * From the **Media** grid use the filters to make it easier to find the uploaded **Image** file if required * Use the row menu and select **Schedule** * Select which **Displays** to show the Image on * If you want to use the default **Always** schedule, and happy with the default settings and have no further advanced scheduling options to set, you can click **Finish** to complete the schedule * If you want to select alternative created **Dayparts** or **Custom** dates, select **Next** * If you don't need to apply any further scheduling options and are happy with the defaults set for **Duration in Loop**, **Resolution** etc, click to **Finish** {% hint style="success" %} **Duration in loop** determines how long this Image should be shown each time it appears in a **Schedule Loop**. {% endhint %} The CMS will now update a Schedule change and the Image will be shown on Displays for the timings set in the schedule. ## Further Reading {% content-ref url="/pages/PGDGhvmOXnQCsLtVYM5C" %} [Show a Playlist](/getting-started/getting_started_showing_a_playlist) {% endcontent-ref %} {% content-ref url="/pages/L8ste2vjohsdskhuMbDm" %} [Layout Editor](/layouts/layouts_editor) {% endcontent-ref %} ## FAQs ***What are Schedule Loops?*** A Schedule Loop is how media content will play when in schedules with other media content. For example, if you have scheduled 2 media items each with a 10 second duration to be shown at the same time for 1 hour, both items will play for their 10 second durations in fair rotation for the scheduled time. ***What file extensions are supported on upload?*** Valid file extensions: jpg,jpeg,png,bmp,gif,webp. ***Can I upload an animated gif?*** Animated gif's are not supported. # Showing a Video on Displays Add a Video file to your Media Library and Schedule to play on Displays. You may have Video content which has been created to showcase product promotions or show company updates to employees, ready to be shown full screen on your Display network. Video files are first added to the Library by upload or by URL. For this example a Video file will be uploaded to the CMS Media Library. ## How-to Video Showing a Video {% embed url="" %} ### Add Media 1. Click on **Media** under the **Library** section of the main CMS menu 2. Click the **Add Media** button 3. Drag and drop, enter a URL or click **Select files** and locate the Video file to upload 4. Click on the thumbnail and use the scroll bar to select a frame to use to make it easier to identify in Media Library lists 5. Click the Capture button in the top right of the screen 6. Provide a new **Name** or leave this field blank to keep the original file name 7. Click **Done** to return to the Media grid ### Select Media 1. From the **Media** grid use the filters to make it easier to find the uploaded video file if required 2. Use the row menu and select **Schedule** 3. Select which **Displays** to show the video on 4. If you want to use the default **Always** schedule, and happy with the default settings and have no further scheduling options to set, you can click **Finish** to complete the schedule 5. If you want to select alternative created **Dayparts** or **Custom** dates, select **Next** 6. To configure advanced scheduling options and override the duration of the video for example, click **Next** 7. **Duration in loop** determines how long this video should be shown each time it appears in a **Schedule Loop** 8. You can specify a **duration** here and provide a lower duration to cut the video short. When setting a higher duration, the video will loop back to the beginning and play to satisfy the duration applied 9. Click to **Finish** once all relevant fields have been completed The CMS will now update a Schedule change and your Video will be shown on Displays for the timings set in the schedule. ## Further Reading {% content-ref url="/pages/L8ste2vjohsdskhuMbDm" %} [Layout Editor](/layouts/layouts_editor) {% endcontent-ref %} ## FAQs ***What are Schedule Loops?*** A Schedule Loop is how media content will play when in schedules with other media content. For example, if you have scheduled 2 media items each with a 10 second duration to be shown at the same time for 1 hour, both items will play for their 10 second durations in fair rotation for the scheduled time. ***Which file format is recommended for Videos?*** We recommend H264 MP4 file format. # Showing a Playlist on Displays Create a Playlist of content and Schedule to show on Displays. You may have a set of content collated to meet a specific requirement which need to be shown in a rotating sequence on Displays. Playlists allow users to streamline resources and organise multiple content types to play in the order they need to be displayed. Playlists can have content added by automatic assignment based on selected criteria or by manual selection. For this example Image content already uploaded to the CMS Media Library will be added to a Playlist manually. ## How-to Video Showing a Playlist {% embed url="" %} ## Add Playlist * Click on **Playlists** under the **Library** section of the main CMS menu. * Click the **Add Playlist** button. * Provide a **Name** for easy identification in the CMS. * Click Save and the **Playlist Editor** will open. ## Adding Content * Using the Toolbox, click on **Library image search** to add Images from the CMS Library. * Use the filters to locate the **Images** to add. * Drag and drop images to add to the **Timeline**. * Re-order the sequence by drag and drop. You can view the total duration of the Playlist at the top of the Timeline. * To change the duration of items in the Playlist, click to highlight and select the **Advanced** tab in the **Properties Panel**. * Tick the **Set a duration** box and provide a new duration in seconds. * Click the **Save** button to update the total duration of the Timeline. * Select **Exit** to return to the Playlists grid. ## Select Playlist * From the Playlists grid use the filters to locate the Playlist. * Use the row menu and select **Schedule**. * Select which **Displays** to show the Playlist on. * If you want to use the default **Always** schedule, and happy with the default settings and have no further advanced scheduling options to set, you can click **Finish** to complete the schedule. * If you want to select alternative created **Dayparts** or **Custom** dates, select **Next**. * If you don't need to apply any further scheduling options and are happy with the defaults set for **Resolution**, **Background Colour** etc. click to **Finish**. The CMS will now update a Schedule change and the Playlist will be shown on Displays for the timings set in the schedule. ## Further Reading {% content-ref url="/pages/8UGAt6TKFG2DxAbXlD0C" %} [Show an Image](/getting-started/getting_started_showing_an_image) {% endcontent-ref %} {% content-ref url="/pages/L8ste2vjohsdskhuMbDm" %} [Layout Editor](/layouts/layouts_editor) {% endcontent-ref %} ## FAQs ***Can I add Widgets to a Playlist?*** Yes, Widgets can be added using the Playlist Editor using the top button from the Toolbox. ***I don't see any Global or Data Elements to add to my Playlist?*** Elements are not available in the Playlist Editor. Data Widgets have a selection of Static Templates to choose from to display your data. ***Do I have to upload the files I want to use to the CMS Media Library before creating a Playlist?*** No, you can upload media directly to a Playlist by dragging the Upload card for a selected media type to the Timeline and use the file uploader. # Sorting and Filtering Page information within the CMS is presented as tabular data in a grid format. Grids have a number of features that when combined create a flexible tool for Users making it easier to visualize and understand presented information. ## How-to Video Sorting and Filtering {% embed url="" %} Using the Filters button, multiple filter fields can be used to restrict criteria for returned results. * Use the checkbox to apply advanced filtering options for Names using Regex and provide AND/OR criteria using comma separated terms. Results are populated into columns, which can be sorted by clicking on the column header or by using the Shift key to sort multiple columns that contain up/down arrows. * Hold shift and click on the column headings to sort in the order selected. The **Columns** button is used to select/de-select which columns are needed in the data table, making it an extremely useful tool for Users to customise which columns should be visible for each grid. With multiple columns selected, use the scroll bar at the bottom of the grid to view all columns. Use the row menu to access a set of actions for a selected item. Selected row menu actions across grids have an 'auto submit' capability. Once ticked the action will be automatically submitted without any further confirmation requirements when next selected. Easily perform bulk actions when selecting multiple items. Use the tick box and select a bulk action, such as Deleting, Sharing and moving items into Folders. # Layout Editor Overview The Layout Editor is used to create new Layout designs and when an existing Layout needs a Design change. A Layout presents content to be shown on Displays and are made up of just 1 or multiple content items. Designs can include a combination of **Elements**, **Widgets** and **Library Media** and can be added to be shown in different sections of the Layout to show simultaneously. The Layout Editor gives Users a range of tools to add and arrange a variety of content, regardless of skill level, to easily create eye catching Layouts to capture attention on Displays. ## How-to Video Create a Layout {% embed url="" %} ## Creating Layouts Layouts are created from the **Layouts** page under the **Design** section of the main CMS menu. Clicking the **Add Layout** button will open the **Layout Editor** used to add content to design Layouts. ## Navigating the Layout Editor ![Layout Editor Overview](https://2811002782-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fj0uXhtBdyPyW40TfKTZd%2Fuploads%2Fgit-blob-fa2b0cd31be528aea4a5884c5b213b22d8854dc1%2Flayout_editor_overview_explainer.png?alt=media) To **Rename** the Layout, click the "Untitled" text at the top of the Layout Editor. From here, also view the **Status** and total **Duration** of the Layout as you build your design. The total Layout duration is always based on the item added to the Layout with the highest set duration. Layouts will function best when shown on a Display with a matching resolution. To change the **Dimensions** of a Layout, select the **Resolution** to use from the drop down menu in the **Properties Panel**. Using the **Properties Panel**, select a **Colour** or add a static **Image** from the **Toolbox** or upload a new file to use as a **Background** for the Layout. All content is added to the canvas from the **Toolbox**. ### Adding and Arranging Content The **Toolbox** contains a variety of content types, which when selected will open the items to add. Content is added to the canvas using the flexibility of drag and drop, along with rotation and resizing tools to enable Users to position items exactly where they are needed. On adding an item to the Canvas, "Snap to" buttons are available from the bottom right under the canvas, which allow for easier positioning when moving items around the canvas. ### Properties Panel As items are added, the **Properties Panel** will show the configuration options available for the selected item. The **Advanced** tab can be used to override the duration of an item. * Click in **Set a duration** and provide the new **Duration** in seconds. If this item now has the longest duration on the Layout, it will also update the total Layout duration shown at the top of the Layout Editor. ### Layout Preview The full Layout can be played to preview how your design will look when showing on Displays. * Click out of any selected items by clicking on the background. * Select the **Play** button icon at the bottom left under the canvas. {% hint style="success" %} Play a preview in full screen by using the icon in the top right of the canvas before selecting the Play button! {% endhint %} ### Publishing Layouts Layouts need to be **Published** in order to be shown correctly on Displays when included in Schedules. Use the 3 line menu located in the top right of the Layout Editor to select the **Publish** option. Layouts can be Published straight away or a **Publish Date** can be set, by unticking the **Publish Now** option to determine a specified date and time in the future to Publish. Once Published or after setting a Publish Date, the Layout can now be Scheduled to Displays. ## Further Reading {% content-ref url="/pages/pSESDYbFR7grwuhFKYlm" %} [Global Elements](/layouts/layouts_editor_global_elements) {% endcontent-ref %} {% content-ref url="/pages/DGNlhd48EjOLsIF6D99D" %} [Library Search](/layouts/layouts_editor_library_search) {% endcontent-ref %} ## FAQs ***When should a User create a new Layout?*** The recommended usage for a Layout is for it to only contain the design and media required for a set of related content that should be shown at the same time. Keeping your content concise will make it easier for your audience to understand your messaging! ***Are there any restrictions to the amount of Layouts I can have?*** There are no limits to the number of Layouts in the system or the number a User can have. ***My Layout status is always showing as an orange exclamation mark, I how do I make it a green tick?*** The orange exclamation mark is an expected status to have if your Layout contains online content, such as a Webpage. In this situation, the CMS cannot determine what the Display will play as this type of content is not sent directly from the CMS and is instead assessed Player side. The Layout should still be Published and Scheduled to Displays, which will need to have a reliable internet connection in order to successfully show this content. ***I want to divide my Layout and have static content on one side and a carousel of content fill the other side, how do I achieve that?*** Add and position a Playlist to the side you want to show a rotation of items and resize to fit the area as needed. ***How do I make design changes to an existing Layout?*** Use the row menu for the Layout you need to make changes to and select Design to open the Layout Editor. If the Layout has been Published you will need to first Checkout the Layout which will create a draft copy of the Layout so as to not disrupt any current schedules the Layout is in. # Using Templates Use Templates to speed up the design process so that Users can customise content rather than having to start from scratch building Layout designs. Streamline content creation with pre-designed Layouts to allow Users to concentrate on the core content whilst maintaining company/industry visual set standards and guidelines. ## How-to Video Using Templates {% embed url="" %} ## Published Layouts as Templates Layouts created in the Layout Editor can be saved for future selection as a Template after Publishing: 1. From the **Layout Editor**, open the top menu 2. From the drop down, select **Save Template** 3. Complete all the relevant form field, opting to include all Widgets to the Template design if required 4. **Save** Published Layouts can also be saved as a Template from the **Layouts** grid: 1. Navigate to **Layouts** under the **Design** section of the main CMS menu 2. Use the row menu for a Published Layout and select **Save Template** 3. Complete form fields and **Save** {% hint style="success" %} Layouts with the tag 'Template' will also add the Layout to your list of Template designs! {% endhint %} ## Using Templates to create new Layout designs Create a new design for your Layout using a Template from inside the Layout Editor: 1. Click to open the **Toolbox** 2. Select the **Search for Layout Templates** button 3. Use the filters to narrow down search results 4. Drag and drop the selected Template to the canvas 5. Customise or add items as required 6. Use the top menu to **Publish** once happy with the design ## Xibo Exchange Templates Select from an updated catalogue of Xibo Template designs. Each Template has been created using established design standards and can serve as a great starting point to create professional looking content without extensive design skills. Templates are fully customisable and can be adapted to suit content needs. Xibo Templates are available from inside the Layout Editor: 1. Click to open the Toolbox 2. Select the **Xibo Exchange** button 3. Use the filters to narrow down search results 4. Drag and drop the selected Template to the canvas 5. Customise / adapt as required 6. Use the top menu to **Publish** once happy with the design {% hint style="warning" %} Selecting a Template will replace the Layout design you are currently working on with the selected Template. This action is irreversible and so must be used with caution. {% endhint %} ## Further Reading {% content-ref url="/pages/L8ste2vjohsdskhuMbDm" %} [Layout Editor](/layouts/layouts_editor) {% endcontent-ref %} {% content-ref url="/pages/LAZhfByQTb66EO4x8XyF" %} [Editing Tools](/layouts/layouts_editor_editing_tools) {% endcontent-ref %} ## FAQs ***Where can I view/edit my saved Templates?*** Layouts which have been saved as Templates are viewed and managed from the Templates page under the Design section of the main CMS menu. ***I don't see the Xibo Exchange button from the Toolbox?*** These Templates are enabled by default for new Xibo Cloud Hosting customers. If you are upgrading from an earlier version you will need to enable the **Xibo Exchange Connector** found under the **Administrator** section of the main CMS menu. Self-hosted installations do not have these Templates enabled by default. Enable the **Xibo Exchange Connector** found under the **Administrator** section of the main CMS menu. # Using Library Searches Xibo supports a variety of file based Media types. Along with Image, Video and Audio files, show PDF's, PowerPoints as well as complete HTML Packages on your Displays. File based Media can be first uploaded to the **CMS Library** ahead of time, or added directly using the file uploader when creating **Layouts** and **Playlists**. ## How-to Video Using Library Searches {% embed url="" %} Media already saved to the Library, can be easily selected by using a **Library Search** function. Available from the **Toolbox**, each **Media** file type can be viewed and added from here. When using the **Other Media** search, use the **Type** drop down to select from the available options. * Use filters to limit returned results for searches and make it easier to find the content to use. New Media files can be directly uploaded and added by using the file uploader for a selected Media type. * Drag and drop or click to add the uploader. Once uploaded, the file will be added to the **CMS Library** and will be shown for future selection in relevant Library Searches. {% hint style="success" %} Try using the expander function by clicking the icon at the bottom of the **Toolbox** for easier media assignment! {% endhint %} ## Pixabay Pixabay integration gives Users easy access to additional Image and Video resources from within the CMS. Any Images/videos used from Pixabay will automatically be added to your CMS Library and made available for future use from the Image/Video Library Search functions. Clicking in the top right of a thumbnail will play a preview in a separate window. This window can also be enlarged using the arrow in the top left and can be added to the canvas from here by clicking the `+` button at the top. ## Further Reading {% content-ref url="/pages/L8ste2vjohsdskhuMbDm" %} [Layout Editor](/layouts/layouts_editor) {% endcontent-ref %} {% content-ref url="/pages/PGDGhvmOXnQCsLtVYM5C" %} [Show a Playlist](/getting-started/getting_started_showing_a_playlist) {% endcontent-ref %} ## FAQs ***I don't see Pixabay in the Toolbox?*** Pixabay is enabled from the **Administration** section of the CMS by clicking **Applications**. Scroll down to the **Connectors** section and select **Configure** to enable. Self hosted customers will need to enter an API Key from signing up for a Pixabay account: [PixabayAPI Documentation](https://pixabay.com/api/docs/) to enable. ***I don't see all 4 levels when I click the expander?*** It will only expand to a sensible level dependent on the screen size you are working on. When using on screens with less than 1600px it will limit the total number of available levels to view. m ***How do I show a PowerPoint on my non-Windows Displays?*** Use the option on the file menu inside the PowerPoint application to convert to Video and export to upload to the CMS as a Video file. # Using Global Elements Xibo has a variety of tools available for Users to add to Layouts from the Toolbox when using the Layout Editor. Global Elements give Users an easy way to add **Text**, **Dates and Times**, **Lines** and a variety of **Shapes** to Layouts to create eye-catching content from within the CMS. ## How-to Video Using Global Elements {% embed url="" %} Global Elements give Users great flexibility, with precise positioning and customisable options its easy to create visually impactful designs. Use them on their own or add them to your designs to further enhance and complement other content. ## Adding Global Elements Global Elements are added to Layouts from the **Layout Editor**: * Click on the **A button** from the **Toolbox** to open. * Drag and drop a selected item into position on the canvas. * Or click to highlight and select an item and click on the canvas to add. * Resize and position. * Use the available configuration options to style each element from the Properties Panel. {% hint style="success" %} Edit Text directly on the canvas by double clicking the Text Element. Click again to highlight the "Text" and overwrite! {% endhint %} Global Elements are compatible with all Widgets/Data Elements and Library Media added to the canvas and are a great to use to draw attention to other content on your Layouts. ## Further Reading {% content-ref url="/pages/L8ste2vjohsdskhuMbDm" %} [Layout Editor](/layouts/layouts_editor) {% endcontent-ref %} # Data Widgets Data Widgets rely on an external data source to show information on Layouts by using Elements. ## Overview * Data source driven content. * Separate Elements allow for flexibility. * Provide fallback data to show. * Control paging of data with Data Slots. * Create Groups for easy duplication. * Pull data from an alternative source on the same Layout. * Utilise pre-made designs. Each Data Widget has a set of **Elements** which are fed by a data source which allow a User flexibility in the placement of returned data rather than being bound by a rigid **Static Template** design: * Click on a **Data Widget** to show all available **Elements**. ![Data Elements](https://2811002782-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fj0uXhtBdyPyW40TfKTZd%2Fuploads%2Fgit-blob-c35571a9d1123239cfc531b57deb1547a633bcdd%2Fv4_layouts_data_elements.png?alt=media) {% hint style="warning" %} Data Elements are only available from the Layout Editor and are not available in the Playlist Editor. Users can however add Data Widgets using Static Templates. {% endhint %} ### Configure Each Element has a set of configurable options available from the **Properties Panel** once added: ![Element Properties](https://2811002782-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fj0uXhtBdyPyW40TfKTZd%2Fuploads%2Fgit-blob-829b3271615edeffc877c9a2b500bd8997786e93%2Fv4_layouts_element_properties.png?alt=media) {% hint style="warning" %} An exclamation icon will be shown to prompt a User as to what needs to be actioned. The above example has yet to have a URL entered for an ICS feed! {% endhint %} Options set from the **Configure** tab will apply to all Elements added to the Layout of the same Widget type. {% hint style="success" %} Create a **New Configuration** to select data from alternative data sources associated with the Widget! {% endhint %} ### Appearance The **Appearance** tab includes options to configure how the data returned from the Element should look and includes transition effects and Data Slot configuration. ### Fallback Data Create **Fallback Data** for selected Data Widgets and specify under what conditions it should be shown: ![Fallback Data](https://2811002782-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fj0uXhtBdyPyW40TfKTZd%2Fuploads%2Fgit-blob-3b6a1f535ebaf87367c659ad281d2007bc582755%2Fv4_layouts_editor_data_widgets_fallback.png?alt=media) * Click **Add New**. * Complete the form fields with the required information. * Save. {% hint style="warning" %} Fallback Data options will vary dependent on the Data Widget selected! {% endhint %} ### Advanced The Advanced tab is used to set Naming, provide specific durations, set the collection level of proof of play stats and enable items to be repeated to fill all Data Slots. ### Positioning Use the **Positioning** tab (grid icon) to set precise positioning and Layering. {% hint style="info" %} Elements have their own Canvas Layer, which can be used to determine where they appear in relation to other natively rendered Elements such as Playlists and Videos! {% endhint %} ## Data Slots When adding more than one of the same **Element**, handle the paging of returned data by specifying a **Data Slot** to use for each Element: ![Data Slots](https://2811002782-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fj0uXhtBdyPyW40TfKTZd%2Fuploads%2Fgit-blob-4bdd6c66b57e3f5a462f77d9e294f4055f04b721%2Fv4_layouts_editor_data_slots.png?alt=media) For example, the image above shows 2 **Description Elements** from the **Calendar Widget** have been added. One has a **Data Slot of 1** the other a **Data Slot of 2.** If 10 (Calendar Events) items were returned, Data Slot 1 would show items 1,3,5,7,9 with Data Slot 2 showing items 2,4,6,8,10. Data Slots are set from the **Appearance** tab of the **Properties Panel** for the selected Element. In addition Elements have the option to **Pin this slot** so that the first data item to appear in that slot will remain for the entire duration of the Widget and won't cycle through data items. {% hint style="info" %} Users can set whether to **Repeat items** in order to fill all data slots to ensure there are no empty slots by using the checkbox on the **Advanced** tab of the Properties Panel! {% endhint %} ## Grouping Elements Group Elements of the same Data Widget together to make it easier to build designs: * Add Elements to the Layout, position and style using the **Appearance** tab. * Hold down the shift key and click into each Element you wish to group. * Once selected, release the shift key and right click. * Select **Group elements**. ![Grouping Elements](https://2811002782-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fj0uXhtBdyPyW40TfKTZd%2Fuploads%2Fgit-blob-aa83b97c070c3b6f4da756d3174ff666aae9d7c1%2Fv4_layouts_grouping_elements.png?alt=media) {% hint style="success" %} Groups can also include **Global Elements** {% endhint %} {% hint style="warning" %} All Data Elements need to share the same **Data Slot** and **Effect** when grouping {% endhint %} Groups can be easily duplicated: * Right click and select **Duplicate**. ![Duplicated Elements](https://2811002782-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fj0uXhtBdyPyW40TfKTZd%2Fuploads%2Fgit-blob-25b34c1647ec3fa8da64c4db3d7dc0cdf456d6a5%2Fv4_layouts_duplicated_elements.png?alt=media) Edit **Data Slots** for each group to control data paging: ![Data Slots Groups](https://2811002782-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fj0uXhtBdyPyW40TfKTZd%2Fuploads%2Fgit-blob-8d7e47d02a333784e4fe111e04e4d943afdfa75d%2Fv4_layouts_data_slots_groups.png?alt=media) Make edits to the **Appearance** of each Element in a group: * Click the pencil icon in the top right corner. * Click in each Element and use the Appearance tab to make changes. * Click out of the group or click the X to exit editing. Edits can be made to the **Configuration** but it will apply to all Elements added. Ungroup elements from the right click menu! ## New Configurations New Configurations can be created in order to have alternative configuration options/different data source associated with the Widget: * Right click an Element or Element Group and select **New Configuration** from the menu. * Select an alternative data source / alternative configuration from the **Configure** tab. ## Stencils Selected Data Widgets include pre made designs of Element Groups called **Stencils** to assist Users with creating content simply and quickly: * Stencils are added in exactly the same way, positioned and resized. * Complete the fields to **Configure**. * Edit the **Appearance** by clicking on the pencil icon in the top right of the group. * Select an Element in the group to make edits. {% hint style="success" %} Right click to ungroup to customise further! {% endhint %} ## Static Templates Static Templates are included for specific Widgets. Templates can be configured to affect the behaviour of returned results as well as alter styling options. # Editing Tools Xibo has a variety of editing tools to assist Users when using the Layout Editor to build and create designs to show on Displays. ## How-to Video Editing Tools {% embed url="" %} ## Rectangle Selector Multiple items can be moved together to maintain alignment in a block by using the **Rectangle Selector** tool: 1. Click on the canvas background 2. Hold and drag over the area you want to select to create an outline 3. Ensure that all items to be moved together are contained 4. Drag all items to position on the canvas 5. Once in position, click outside to exit the rectangle selector ## Grouping Elements Make it easier to build designs in the Layout Editor by **Grouping Elements** together: * Add Elements to the canvas When grouping Data Elements, they must be of the same Data Widget type (all Weather Elements for example) and share the same Data Slot and Effect. * Position and style each Element using the **Appearance** tab * Holding down the shift key, click in each **Element** to select to group together * Once selected, release the shift key and right click * From the menu, select **Group elements** The group can now be moved around the canvas to re-position and re-size. {% hint style="success" %} Grouped Elements can be easily duplicated using the Context Menu! {% endhint %} * To make further edits to individual Elements whilst grouped, click the **Edit Group** icon in the top right corner of the group. * Click in an Element to make changes in the Properties Panel. * Select **X** to exit editing the group. To **Ungroup**, use the Context Menu. ## Layer Manager View and manage the layer and durations of all items added to the Layout using the **Layer Manager** located at the bottom left of the Layout Editor: * Use this list to drag and drop the order to show items in front or behind other content. * Alternatively right click a selected item to use the **Send/Bring** options from the **Context Menu**. Elements have their own Canvas Layer which can be used to determine where they appear in relation to other natively rendered Elements such as Playlists and Videos. ## Context Menu Right click items that have been added to a Layout or Playlist to select from a menu of further options (relevant to the selected item). When clicking on a **Widget**, further options are available, shown under the Widget name/type. ## Options Menu Use to show/hide **Tooltips** as well as provide a **Delete confirmation** warning for all items added to the Layout. From here select to **Clear Canvas** to start your design over or **New** to create a brand new Layout. ## Further Reading {% content-ref url="/pages/L8ste2vjohsdskhuMbDm" %} [Layout Editor](/layouts/layouts_editor) {% endcontent-ref %} {% content-ref url="/pages/pSESDYbFR7grwuhFKYlm" %} [Global Elements](/layouts/layouts_editor_global_elements) {% endcontent-ref %} ## FAQs ***Why can't I group a Currency Element with a Menu Board Element?*** Data Elements must be of the same Data Widget type in order to group. They must also share the same Data Slot and any set Effects! ***Can Global Elements be grouped with Data Elements?*** Yes, including Global Elements in groups is a great way to easily compliment Data Elements by adding text, shapes and lines! # Layout Design Changes From time to time, Layouts may need design changes/updates to keep content fresh and relevant. Xibo will continue to show the Published Layout design already in Display Schedules allowing Users to make important changes to a checked out draft version of the Layout. Only approved changes will overwrite the existing design once a User selects to Publish. ## How-to Video Design Changes {% embed url="" %} Layouts that are in a **Draft** status are simply edited by using the row menu and selecting **Design** to open the Layout Editor. Selecting **Design** for a **Published Layout** will show that it is locked for editing. * Click **View** to see all the components of the Layout in a read only mode. * Click **Checkout** to create a draft of the Layout to enable editing. Once a Layout has been "checked out", a copy of the Layout is made in a draft status. This draft Layout will not reflect any changes to the published version. Any **Display** schedules will continue to show the **Published** version of this **Layout** allowing Users to take their time with any design changes that need to be made. {% hint style="success" %} Layouts can also be "checked out" from the row menu ahead of a User needing to make design changes. Select the 'auto submit' checkbox to send the form automatically without the additional approval window every time Checkout is selected. {% endhint %} ## Layout Lock To prevent multiple Users making edits to the same Layout concurrently, the Layout will lock. The Layout will remain locked to other Users for the time specified in the lock message. The Layout can be unlocked by the current User by using the Options menu and selecting **Unlock**. Once unlocked, the current user will be redirected back to the Layouts grid. To revert the Layout back to it's original published state, use the **Options** menu and select **Discard Draft**. ## Publish options To make the changes permanent and overwrite the existing Published Layout, select **Publish**. Layouts can be published straight away using the **Publish Now** checkbox, or unticking this options provides the User to set a date and time as a **Publish Date**. {% hint style="warning" %} Setting a **Publish Date i**s not an alternative to creating an event in a schedule! {% endhint %} Once published the CMS will update a Layout change so that the approved design changes will be shown on Displays. ## Further Reading {% content-ref url="/pages/L8ste2vjohsdskhuMbDm" %} [Layout Editor](/layouts/layouts_editor) {% endcontent-ref %} ## FAQ's ***Can I remove the automatic submission of Checkout forms?*** Forms which have been enabled to 'auto submit' can be viewed and managed from the User Profile settings ***Can I set Layouts to automatically Publish?*** There is a default setting which can be set to automatically Publish all Draft Layouts 30 minutes after the last User edit. This is found in the Settings page under the Administration section of the main CMS menu. # Playlists Playlists are used to show a sequence of media items, such as an image slideshow. There are two ways to create a Playlist: * Add Playlists directly to a Layout from the Layout Editor. Local Playlists can be converted to be saved for re-use as a global Playlist. Saved Playlists will be shown in the Layout Editor to add to Layouts. * Create Playlists independently to a Layout. Global Playlists can be scheduled to Displays without the creation of a Layout. Playlists created outside of the Layout Editor are still shown for selection from the Add Playlist function from the Layout Editor. ## Add Playlists Create new or select existing Playlists to use from the **Layout editor** to create a timeline of content to show on a Layout. ## Feature Overview: * Create and configure directly on a Layout. * Convert a Playlist created on a Layout to a Global Playlist to save for future use. * Easily display a 'slide-show' of content held in one or more Playlists. * Sync with Playlists on other Layouts which are part of a Synchronised Event. * Combine content from a variety of Playlists to be shown. * Set the maximum number of items to be shown from a Playlist. * Control how long each item on a Playlist should show before moving onto the next item. * Set Expiry Dates for media items added to a Playlist. * Play one item per cycle for a specified Play Count. * Select a Random Widget to play at each cycle. * Cycle through items contained on a Playlist in the viewer to easily see the sequence. ## Adding Playlists to a Layout * From the Layout Editor, click on **Add Playlists** from the **Toolbox**: ![Add Playlists](https://2811002782-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fj0uXhtBdyPyW40TfKTZd%2Fuploads%2Fgit-blob-6830621f616a1a4adb0dc899f9124a1f810564ca%2Fv4.1_layouts_editor_add_playlists.png?alt=media) * Click to Add or drag on a **New Playlist** or a named Playlist which has already been created. * Resize and position: ![Content Synchronisation Key](https://2811002782-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fj0uXhtBdyPyW40TfKTZd%2Fuploads%2Fgit-blob-25023330ef13eeef88f544652756a5a946b7e287%2Fv4.1_layouts_editor_synchronisation_key.png?alt=media) From the **Properties Panel**, use the **Content Synchronisation Key** to sync with Playlists on other Layouts. Playlists with the same key will be synchronised when the Layout is scheduled as a Synchronised Event. **Scenario:** You have a Synchronised Event with 3 Displays and 3 different Layouts. Each Layout has some Text at the top and a Playlist in the middle which all 3 need to play in sync. You could also set two different Playlists to sync differently which you could set to `sync_1` and `sync-2` for example. {/tip} * Optionally set **Transitions** for items on a Playlist from the Properties Panel. {% hint style="info" %} When default Transitions have been applied, the properties panel will be blank. Only manually entered Transitions will show on forms. Defaults can be overridden by unticking the **Automatically apply Transitions** check box from the Properties Panel for the Layout. {% endhint %} * Click the icon in the right hand corner of the Playlist to open the Playlist Editor to add and configure content. {% hint style="info" %} The Playlist Editor includes **Spacer** and **Rich Text** Widgets that are only available for use with Playlists.\ Media added to a Playlist can also have Start and End times using Expiry Dates. {% endhint %} {% hint style="warning" %} If you add a named Playlist which has already been created, any edits made to the Playlist will be applied everywhere the Playlist is being currently used! {% endhint %} * Click the **Back** button at the top to exit the Playlist Editor and return to the Layout Editor. View all the content that has been added to the Timeline of the Playlist by using the arrows in the bottom right of the Playlist on the Layout. * Cycle through the order of content: ![Preview Timeline Content](https://2811002782-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fj0uXhtBdyPyW40TfKTZd%2Fuploads%2Fgit-blob-29303aa6541eaab3bff98e555f1d0d7a84a2e7eb%2Fv4.1_layouts_editor_playlists_preview_content.png?alt=media) ## Convert Playlist If you add a **New Playlist** to the Layout you can opt to convert this into a saved Playlist. Converted Playlists will be shown for Playlist selection in the Layout Editor and from the Playlists grid. * Click the Playlist on the Layout to select and give it a **Name** from the **General** tab of the **Properties Panel**. * Right click and select **Convert Playlist** from the menu. ![Convert Playlist](https://2811002782-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fj0uXhtBdyPyW40TfKTZd%2Fuploads%2Fgit-blob-44be470f095417fd964af06a46b4717c86a6a1a9%2Fv4.1_layouts_editor_convert_playlist.png?alt=media) You will see a pop up message at the bottom of the Layout Editor to say that the Playlist has been saved as a Global Playlist. {% hint style="success" %} Click the **Show more** button to see your Playlist added to the list of available Playlists! {% endhint %} Converted Playlists will be saved to the Playlists Grid. ## Add to Playlist If you have a **New Playlist** on a Layout, you can add a new or global Playlist to the Timeline to open further options in the Properties Panel for configuration: ![Playlist Spots](https://2811002782-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fj0uXhtBdyPyW40TfKTZd%2Fuploads%2Fgit-blob-c925989239a2c0c93bc2f099d5bd217e2aef4146%2Fv4.1_layouts_editor_playlist_spots.png?alt=media) * Select Playlists, Spot Options and Playlist Ordering, when selecting more than one Playlist to Embed from the Properties Panel. Adding a **Playlist** to a **New Playlist** on a Layout has additional Cycle Based Playback options which includes a Random Widget feature. {% hint style="info" %} If you want to add more than one Playlist to combine the play order, we recommend that you should only add one Playlist to the Timeline and then use the options in the Properties Panel to select the additional Playlists and configure. {% endhint %} * ### Cycle Based Playback Once enabled all Playlists selected will be treated as one "list" and will only show one Widget each time the Layout is played, cycling through the content from all Playlists added: * Tick Enable cycle based playback from the Properties Panel. * Provide a **Play Count** to determine how many plays each Widget on the Playlist should have before moving onto the next Widget in the timeline. ![Cycle Playback](https://2811002782-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fj0uXhtBdyPyW40TfKTZd%2Fuploads%2Fgit-blob-c4b130b7584e497b6f39dfcdb4d9f6690e025ed8%2Fv4.1_layouts_editor_playlist_cycle_playback.png?alt=media) Using the **Random Widget each cycle** option will play a Widget from the timeline at random for each cycle. {% hint style="warning" %} These additional options are **not** available when adding one or more Playlists to a Global Playlist timeline, which has been added directly to the Layout! {% endhint %} {% hint style="success" %} Did you know [Playlists](https://github.com/xibosignage/xibo-manual/tree/master/source/en/media_playlists.html) created and managed independently to Layouts do not require further user access rights to Layouts or the Layout Editor to add and manage content! {% endhint %} # Widgets Widgets are a core component and are used to display content on a Layout or in a Playlist. ## Overview * Selection of powerful Widgets to choose from. * Create content quickly and easily. * Integrated content from third parties. * Show dynamic content on screens. * Select which Modules to make available to other users of the CMS. All Widgets have an associated Module which tells Xibo what information is required from the User for configuration as to how it should be displayed. {% hint style="info" %} Widgets can be disabled/enabled by an Administrator in the **Modules** section of the CMS. {% endhint %} Widgets are available from the **Toolbox**: * Click the top button to view available Widgets. ![Widgets](https://2811002782-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fj0uXhtBdyPyW40TfKTZd%2Fuploads%2Fgit-blob-0d808d70f5cd570e01884a9f43b384b202dfe146%2Fv4_layouts_editor_widgets.png?alt=media) Widgets can be marked as **Favourites** to appear in their own section for easier selection: * Click the star icon at the top left of a Widget card. ![Favourite Widgets](https://2811002782-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fj0uXhtBdyPyW40TfKTZd%2Fuploads%2Fgit-blob-46e3b7ca8ebb40f0acb6bbdfce58a64d74dd3344%2Fv4_layouts_editor_widgets_favourites.png?alt=media) {% hint style="success" %} Click the star to deselect from the Favourites section. {% endhint %} Widgets that have an `>` need to be opened to select from additional Widget templates: ![Widget Clock](https://2811002782-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fj0uXhtBdyPyW40TfKTZd%2Fuploads%2Fgit-blob-5083af28508dbd2cfd9a28e67ff47c796a699bef%2Fv4_layouts_editor_widgets_clock_example.png?alt=media) Add to Layouts by drag and drop or click in the Widget card to highlight then click on the canvas to add: * Position and resize. * Configure from the available options in the **Properties Panel**. ![Clock Configuration](https://2811002782-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fj0uXhtBdyPyW40TfKTZd%2Fuploads%2Fgit-blob-e5eefc18f983855d211039b0601f5cd8136cce3f%2Fv4_layouts_editor_clock_configuration.png?alt=media) ## Further Reading {% content-ref url="/pages/xuQhXczom7IZrMi4xBws" %} [Data Widgets](/layouts/layouts_editor_data_widgets) {% endcontent-ref %} # Interactive actions Create Interactive actions on Layouts to trigger content changes to show on your Displays. You could have a product display that includes an 'internet of things' device, such as a light sensor, which could be used to trigger a webhook. Product specific information could be included on a Layout to show on Displays for the specific product that has been interacted with by a customer. You could use touchscreens to show specific information triggered from pressing a button on a Layout, shown on the Display, or by pressing a key, which has been defined as a trigger type, from an attached keyboard. Actions are created for: * A complete **Layout** * Individual **Widgets** on a Layout * An **Image within a Playlist** on a Layout These actions can be triggered by **Touch/Click**, by pressing a **key** on a keyboard or programmatically by a **Webhook**. ## Create an interactive layout 1. Create and design a Layout, adding **Widgets** to configure as interactive **Triggers** and **Targets**, if required. Further **Interactive Widgets** are available from the **Toolbox**. {% hint style="success" %} Toggle Interactive Mode to OFF to open the Toolbox {% endhint %} 1. Click the **Widgets** button at the top of the Toolbox 2. Click on **Interactive** to open: * **Button** can be used as a Trigger which can be fully customised to suit your designs * **Link** can be added to provide text to be used as a Trigger * **Interactive Zone** to define an area on the Layout to be used as a Target or Trigger ## Adding and editing actions on a layout 1. Toggle **Interactive Mode to ON**, using the button at the top of the Layout Editor The design elements will be locked to focus on adding and editing **Actions** only. 2. Use the drop-down menu to select the **Action Type**: * **Next/Previous Layout** to show the next or previous Layout in the schedule for the selected Display(s) * **Navigate to Layout** using a **Code** to identify the Layout Use the **Search for Layouts** button at the bottom of the canvas, to easily search for Layouts by code. Ensure that Layouts to be used as Interactive Targets have a **Code Identifier** entered in the **Edit Layout form** * **Next/Previous Widget** to show content from inside a **Playlist** for the next/previous item shown on the timeline * **Navigate to Widget** to specify which Widget to Load, or click to **Create Widget** and select an item from the Toolbox to add to the specified Target 3. From the Layout, click on an item to select the **Trigger Type** Alternatively, use the drop-down menu from the Properties Panel * Selecting **Touch/Click**, requires devices that will be used as a touch screen to have touch capabilities enabled * To use a **Webhook** a **Trigger Code** needs to be entered which must be present in the URL \`\`trigger=\` parameter * **Key Press**, requires an attached keyboard with a key selected as the **Trigger Key** 4. Draw an arrow to a **Target** item, or use the drop-down menu 5. Click **Save** on the Properties Panel {% hint style="warning" %} Fields shown are dependent on the Action Type selected. {% endhint %} ## Further reading {% content-ref url="/spaces/U3Fd23vkclHlMLAaxiyE/pages/5ac148dbe6169a56f78c0626ee2d894965232181" %} [Webhooks](/developer/player-control/local-player-api/webhooks) {% endcontent-ref %} {% content-ref url="/pages/L8ste2vjohsdskhuMbDm" %} [Layout Editor](/layouts/layouts_editor) {% endcontent-ref %} ## FAQs ***Where do I enable Touch capabilities for my Android device?*** From Display Settings under the Displays section of the main CMS menu and use the row menu to select Edit. From the Advanced tab, check the Enable touch capabilities on the device setting at the bottom of the form. ***How can I use an image as a trigger?*** You need to add a Playlist to a Layout from the Toolbox, and then add the image to the Playlist Timeline. ***Why do I not see key press as a trigger type?*** Assigning a keyboard key as a trigger type was introduced in v4.4. Update your CMS to benefit from this feature! # Templates Use Templates to speed up the design process and ensure a corporate standard is maintained. ## Overview: * Use existing published Layout designs to easily save as Templates. * Create and manage Templates from a dedicated page for easier management. * Add Zones to Templates to act as content placeholders on a Layout. * Set Share options to restrict User access to selected zones on a Template. * Show Published Templates for selection in the Layout Editor. * Speed up the entire Layout design process for all Users. * Apply a standardised look to all Layouts. Create new Templates or save your existing Layout designs to use as Templates for future Layouts. {% hint style="info" %} Select from one of our designed templates from the Xibo Exchange by clicking the button below Templates from the Toolbox. {% endhint %} {% hint style="warning" %} Selecting a Template will replace the current Layout design to the chosen Template. This action is irreversible and so must be used with caution. {% endhint %} ## Create Template Templates are created by selecting **Templates** under the **Design** section of the main CMS menu 1. Select the **Add Template** button and complete the form fields 2. Give your Template a **Name** for easy identification in the CMS 3. Select the **Resolution** On **Saving**, the Layout Editor will automatically open with one full size **Zone**. Zones are used to define areas on a Layout which content can be added to. {% hint style="info" %} If you don't want to include any Zones and add content directly to the Template, remove the Zone from the canvas by right clicking and selecting **Delete**. Add content in the same way as creating a Layout. {% endhint %} ### Adding Zones {% hint style="warning" %} Zones are only available for use with Templates! {% endhint %} * Click anywhere on the zone to resize and position: ![Template Layout Editor](https://2811002782-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fj0uXhtBdyPyW40TfKTZd%2Fuploads%2Fgit-blob-2d37810eac45fc4a2b97595515ea554595515939%2Fv4_layouts_templates_editor.png?alt=media) {% hint style="success" %} Use the buttons, in the bottom right to select to **Snap to Grid**, **Snap to Borders** or **Snap to Elements** for easier positioning when adding items. {% endhint %} **Zones** can be added from the toolbar: * Click on the top **Widget** button. ![Add Zone](https://2811002782-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fj0uXhtBdyPyW40TfKTZd%2Fuploads%2Fgit-blob-a78b45034c442bdeb81c4d4b010a33fae8dfbb0e%2Fv4_layouts_templates_add_zone.png?alt=media) * Select the Zone and drag and drop or click to add. * Resize and Position. {% hint style="warning" %} Set to **Loop** only if the Zone contains a Widget that needs to update periodically (e.g. RSS Ticker) and it needs to update more frequently than the duration of the overall Layout. {% endhint %} ### Layering From the Properties Panel, select the Positioning tab to set Layering for overlapping Zones/ added content. Add both content from the Toolbox and Zones to build your Template design. Once your Template is complete, use the menu at the top of the editor to **Publish**: ![Publish Template](https://2811002782-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fj0uXhtBdyPyW40TfKTZd%2Fuploads%2Fgit-blob-9e23966aa5c03b8a0776dd6ad0146128a21d4c91%2Fv4_layouts_templates_publish.png?alt=media) Published **Templates** will show for selection from the Toolbox of the Layout Editor. ## Save Layout as Template Published Layouts can be saved as a **Template** from two locations: * From the Layout Editor: * After **Publishing** go back to the menu and select **Save Template**: ![Save Template Editor](https://2811002782-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fj0uXhtBdyPyW40TfKTZd%2Fuploads%2Fgit-blob-f96aa04cb65b3c994b4ad0f8725bc9ad1646291c%2Fv4_layouts_templates_save_as_template.png?alt=media) * From the Layouts grid: * Use the row menu for a **Published** Layout and **select Save Template**. Complete all relevant form fields to save the selected Layout as a Template. {% hint style="info" %} Optionally use the tick box to also include all added **Widgets** to the Template. {% endhint %} * **Save** Layouts that are saved as a Template can be viewed and edited from the **Templates** grid under the **Design** section of the main CMS menu. {% hint style="success" %} **Tagging** a Layout as a 'Template' will also add your designs to your Template list. {% endhint %} ## Row Menu All Templates have a row menu where Users can access a list of actions/shortcuts. * Notable settings are listed below: #### Alter Template Select to make design changes to the Template in the Layout Editor. #### Checkout To make edits to a Published Template click to **Checkout** and create a draft. Once edited the Template can be published to make the changes permanent overwriting the existing Template. Discard will revert the Template back to its original published state. {% hint style="info" %} Take your time with any edits you need to make as using **Checkout** ensures that no changes are made to your published version or shown on scheduled **Displays** until you choose to do so. **Publish** confirms changes have been made and will overwrite your published version. **Discard** will delete the draft with the published version remaining untouched. {% endhint %} #### Publish Publish will ensure that the Template is shown for selection from the Toolbox. #### Share Set Share options for User/User Group access to individual Templates. #### Discard Discard all changes made to a draft and revert back to the previous Published version. #### Export Export the Template including all associated Widgets/Media/DataSet structures to a ZIP file, so it can be easily shared. When exporting a Template, all assigned **Layout**, **Playlist** and **Media Tags** will be exported. Select the **Import Tags** option to add these Tags on Layout Import. {% hint style="success" %} Select multiple Templates and use the short cut actions at the top of the grid to perform bulk actions for multiple Templates. {% endhint %} # Media Library Xibo supports a wide variety of media types, from Widgets which are created and stored directly on Layouts and Playlists to file-based media that is uploaded and stored in the CMS Library. {% hint style="danger" %} Xibo takes no measures to control what content is put on your Displays. It is your responsibility to ensure that your content is appropriate material for your desired audience. Content must be appropriately attributed if you do not own the rights to it. {% endhint %} Manage all file based media by selecting **Media** under the **Library** section of the main CMS menu. Use the buttons on the right hand side of the grid to switch between a **grid** or **thumbnail** view: ![Grid View](https://2811002782-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fj0uXhtBdyPyW40TfKTZd%2Fuploads%2Fgit-blob-65cede2986fec3ff6b3f41c5dfb7be138fdc6d55%2Fv4.5_media_grid_view.png?alt=media) ![Thumbnail View](https://2811002782-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fj0uXhtBdyPyW40TfKTZd%2Fuploads%2Fgit-blob-630afd29775d2fb726aaa4595267c887bb116b26%2Fv4.5_media_thumbnail_view.png?alt=media) Use the **Filters** button to apply filters to restrict criteria for returned results. {% hint style="success" %} Use the **OR/AND** option for **Names** and to filter items that have been assigned multiple **Tags**. {% endhint %} {% hint style="info" %} Images and Videos that have a set thumbnail can also be filtered by **Orientation** once set:\ 1\. Use the row menu for the item and select **Edit** for an Image/Video file\ 2\. Scroll down to the bottom of the form and set the intended **Orientation** {% endhint %} ## Adding Library Media Library media is added using the **Add Media** button to either drag and drop files, using **Select Files** to upload or by providing a **URL**. {% hint style="info" %} Add Media to the CMS Library and save to Folders to have media ready for use for the appropriate Users/User Groups {% endhint %} {% hint style="success" %} Files added to the CMS Library can be easily added to Layouts and Playlists using a Library Search {% endhint %} ### Add Media * Select the **Add Media** button * Use the drop down to select an alternative folder location if required * Drag and drop files or click **Select Files** or provide the remote URL for the file * Files will start automatically uploading * Files can be re-named or leave blank to keep the original file naming * Click **Done** once added and the files will continue to upload in the background {% hint style="info" %} Default thresholds and limits can be specified which are then considered in the event an Image should be resized when uploading an image for example. Further information can be found in **CMS Settings**. {% endhint %} ## Row Menu Each item in the **Library** has a row menu where Users can access a list of actions/shortcuts ## Edit Select **Edit** to make changes to **Folder** locations, **Durations** and **Tags** and other settings. * Notable settings are listed below: ### Expiry Dates Set an Expiry Date for Library Media to remove the file from any Layouts/Playlists it has been used on. ### Retire Media Ticking **Retire this Media** will keep the media file assigned to any existing Layouts/Playlists but will not be made available for further selection to add to Layouts/Playlists. ### Enable Media Stats Collection * Set the collection of Proof of Play statistics to On / Off / Inherit for the selected media file. {% hint style="warning" %} Ensure that **Enable Stats Reporting** has been ticked in Display Settings in order to collect Proof of Play stats! {% endhint %} ### Update Media Use the check box **Update this Media in all Layouts it is assigned to** so that any edits are reflected in Layouts/Playlists that this media file is currently assigned to. {% hint style="warning" %} Edits will only be updated in Layouts/Playlists which you have access to edit! {% endhint %} ### Replace File It may be necessary to upload a new revision of an existing file: * Click **Select File** and choose the media file to replace the existing * Optionally select to: * **Delete** the old file version completely from the CMS * **Update** the replacement file to all Layouts/Playlists it is currently assigned to. ## Delete Media files can only be deleted from the CMS if they are **not** being used on any existing **Layouts/Playlists**. {% hint style="danger" %} The option to force a delete must be used with caution as deleting a file cannot be reversed. {% endhint %} {% hint style="info" %} Retiring Content rather than deleting it will keep the media file in any existing Layouts/Playlists it has been assigned to, with any scheduled content unaffected. Media will not be available to add to any new Layouts/Playlists. {% endhint %} * Tick in the box to enable a hard push using XMDS to completely remove the file from a Players local storage. ### Usage Report This report is great to use to make final checks prior to tidying media files. This will show if the selected **media file** is directly assigned/scheduled to **Displays**. * Use the Layout tab to see what **Layouts** the media file is currently included in. ### Schedule Image and Video Library media files can be directly Scheduled to a Display as full screen content from the row menu. ## Tidy Library As the CMS is used and Layouts/Playlists and Media are added, over time the Library can become cluttered with old content that is no longer in use. The Library can be *tidied* by a User or Super Administrator so that it is kept clean and small. **Actions cannot be reversed so this must be used with caution.** {% hint style="success" %} This might be particularly useful if the CMS is installed on a web server that has quotas or if Users have been assigned their own quotas! {% endhint %} There are two places where the Library can be tidied: 1. From **CMS Settings**, **General** section - available to all Super Administrators only. 2. From the **Library** - for all Users when **Enable Library Tidy** is ticked. {% hint style="danger" %} The Tidy Library function is turned off by default for **Xibo Cloud Hosting** customers as it can be potentially destructive if the options are not fully understood. Use the checkbox to enable if required. {% endhint %} Once enabled Users can click on a **Tidy Library** button located at the top of the Library page. The form will show the number of files that will be deleted and how much space those files take up. {% hint style="info" %} This will only delete files that are owned by the logged in User which are no longer in use on a Layout or Assigned to a Display Group/Display. {% endhint %} ## Further Reading {% content-ref url="/spaces/OD5P6BGYveuzkbhjZRsq/pages/cnQlwnsnrG3phlsvoiI8" %} [Using MongoDB to store Proof of Play and other time series data.](/setup-docs/cms-configuration-and-integration/using-mongodb-to-store-proof-of-play-and-other-time-series-data) {% endcontent-ref %} # Playlists Playlists are used to show a sequence of media items, such as an image slideshow. There are two ways to create a Playlist: * Create Playlists independently to a Layout. Global Playlists can be scheduled to Displays without the creation of a Layout. Playlists created outside of the Layout Editor are still shown for selection from the Add Playlist function from the Layout Editor. * Add Playlists directly to a Layout from the Layout Editor. Local Playlists can be converted to be saved for re-use as a global Playlist. Saved Playlists will be shown in the Layout Editor to add to Layouts. ## Overview: * Create and configure independently to Layouts. * Add and maintain content dynamically. * Update Playlist content without accessing Layouts. * Schedule directly from the Playlist grid without the need to add to a Layout. * Combine content from a variety of Playlists to be shown. * Set the maximum number of items to be shown from a Playlist. * Control how long each item on a Playlist should show before moving onto the next item. * Set Expiry Dates for media items added to a Playlist. ## Creating a Playlist Streamline resources and save time by creating Playlists to hold multiple items of content to be shown on Displays. Create Playlists to target and collate content for specific requirements, locations, subject categories etc. Playlists that are created independently to Layouts and do not require additional User access to Layouts or the Layout Editor in order to add or manage content on Playlists. Any changes made to a Playlist will be updated in all Layouts/Schedules that already contain that Playlist. 1. Select **Playlists** under the **Library** section of the main CMS menu 2. Click the **Add Playlist** button and complete the form fields 3. Give your Playlist a **Name** for easy identification in the CMS There are two options for adding Media content to Playlists: * Automatically assigning Library based media on criteria using the Dynamic option. * Manually assigning media using the Playlist Editor, which will open on saving the form. ## Dynamically adding Media * Once ticked, click on the **Filter** tab and set the required criteria in order to populate matching Library Media. * Provide a **maximum number** of Library Media files to limit the number that can be automatically assigned. Media already in the CMS Library that matches the criteria set will be shown: ![Dynamic Assignment](https://2811002782-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fj0uXhtBdyPyW40TfKTZd%2Fuploads%2Fgit-blob-cb853815a158deff318499ba3d5d3e3e67d6e503%2Fv4_media_playlists_dynamic.png?alt=media) Any future media files that are added to the Library that satisfy the set criteria for this Playlist will be automatically added to this list. {% hint style="info" %} Library Media can also be prepopulated as a one-time assignment to a Playlist by setting criteria but leaving the Dynamic option unticked! {% endhint %} * Click to **Save**. {% hint style="success" %} Did you know a Dynamic Playlist can be scheduled to be shown on Displays full screen without first adding it to a Layout? Use the row menu for the Playlist and select Schedule! {% endhint %} ## Playlist Editor * From the Toolbox, select content to add to the Playlist. * Configuration options will load in the properties panel. ![Playlist Timeline](https://2811002782-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fj0uXhtBdyPyW40TfKTZd%2Fuploads%2Fgit-blob-f5b1039a3413605e2c0f8889542993e533d415cd%2Fv4_media_playlists_timeline.png?alt=media) {% hint style="success" %} The **Playlist Editor** contains two additional Widgets, a **Rich Text Editor** to provide text, Html or JavaScript and a **Spacer** to create an empty 'slot' within a Playlist. {% endhint %} Durations will update to show the minutes/seconds as items are added to the Playlist timeline. * Re-order the sequence by drag and drop. * Click the ruler icon to **Change Scale mode**: ![Scale Mode](https://2811002782-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fj0uXhtBdyPyW40TfKTZd%2Fuploads%2Fgit-blob-8ef278dc8c843743965e5d151d26fc74724c04c3%2Fv4_media_playlists_scale_mode.png?alt=media) Use the scale options to zoom in and out to decrease/increase the visible time span. Items can be added to a specific point in the list, drag or click to add content to a position marker within the Playlist. ![Add to Timeline](https://2811002782-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fj0uXhtBdyPyW40TfKTZd%2Fuploads%2Fgit-blob-d11cba8997cb5335c81ab3b71aa14c8f616affc0%2Fv4_media_playlists_add_timeline.png?alt=media) {% hint style="success" %} Use the Undo button at the bottom of the toolbar to revert a change. {% endhint %} An additional Context Menu of options can be accessed by right clicking on an item which includes setting Widget Expiry Dates and Playlist Transitions. {% hint style="warning" %} When Transitions are applied to a Widget by default, the properties panel will be blank. Only manually entered Transitions will show on forms! {% endhint %} Use the **Select Multiple Widgets** button at the bottom of the Playlist Editor to delete multiple selections with one click: ![Mutli Select](https://2811002782-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fj0uXhtBdyPyW40TfKTZd%2Fuploads%2Fgit-blob-9af4c41f17cc9dbd07d4e026ce902538fbd5d25a%2Fv4_media_playlists_multi_select.png?alt=media) {% hint style="success" %} Did you know you can create a Playlist and schedule to be shown on Displays full screen without first adding it to a Layout? Use the row menu for the Playlist and select Schedule! {% endhint %} ## Widget Expiry Dates Items added to a Playlist have an additional option of setting Start and End times. * Right click on an item in a Playlist to **Edit Expiry Dates** or set when uploading media directly to a Playlist. Uploading from a Library Search will have an additional **Set Expiry Date** option: ![Expiry Dates](https://2811002782-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fj0uXhtBdyPyW40TfKTZd%2Fuploads%2Fgit-blob-71aa510917ad3ddbb5fd63ff6a5ba8c572c39c67%2Fv4_media_playlists_upload_expiry.png?alt=media) When uploading multiple media files, clicking the **Start upload** button will upload all files with the same date/time and Folder location set. {% hint style="info" %} Items can also be uploaded individually using the **blue upload** button at the end of the row for a file to have different set Expiry Dates and Folder locations for each file uploaded. {% endhint %} Any items on a Playlist that have **Expiry Dates** set show an icon, which when moused over will show further information: ![Expiry Dates](https://2811002782-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fj0uXhtBdyPyW40TfKTZd%2Fuploads%2Fgit-blob-a2923c3f094d30667cf3dacafb9a3dae5125eb80%2Fv4_media_playlists_expiry_dates.png?alt=media) {% hint style="warning" %} Once the End date has passed the item will be removed from the Playlist. Expired items that have not been set to Delete on Expiry will remain visible in the Playlist Editor only so that Start and End times can be re-adjusted if needed. {% endhint %} * Click on an icon to open to make any changes/remove from the item. ## Embedding Playlists Playlists can be added to other Playlist timelines in order to define how much content should be shown, for how long as well as determine a play order. * From the Playlist Editor select to add a New or select from the list of available 'global' Playlists from the Toolbox. * Options for configuration are shown in the Properties Panel: ![Embedding Playlists](https://2811002782-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fj0uXhtBdyPyW40TfKTZd%2Fuploads%2Fgit-blob-59fd8b1653232137212051a2d8ad8b46e823f7ea%2Fv4.1_media_playlists_embedding.png?alt=media) * Use the dropdown menu to select **Playlists** using the `+` button to add and configure multiple Playlists if required. * **Spot** options are used to define how much content from Playlists should be shown and for how long. Spots also have an option to use a Playlists content as filler only and add content from this Playlist to **Fill** or **Pad** other selected Playlists: * This Playlist must be the **first** added Playlist in the list. * Enter a **0** in the **Spots** field so that the entire Playlist will be ignored and omitted from the play order. Select how the content from this Playlist should be distributed with the other Playlists using **Spot Fill** options. {% hint style="danger" %} Please be aware that by setting **Start Dates** to Widgets may cause fewer Spots to be shown than the total amount specified! {% endhint %} Use the drop-down menu for the **Spot Fill** field to select how any remaining Spots should be filled in the event that there are not enough Widgets on the selected Playlist to fulfil the specified play spots. {% hint style="info" %} **Spots**, **Spot Length** and **Spot Fill** are all optional and can be left blank if this functionality is not required! {% endhint %} Use the drop-down for **Playlist Ordering** to select how all Playlists should be ordered to play. {% hint style="info" %} **Auto** uses the total count of items in each list and divides it by the smallest list to determine how often to take items from each list to ensure an even play from each Playlist. {% endhint %} Select from the **Remaining Widgets** options to handle any content that is left unordered at the end of a Playlist. {% hint style="info" %} Adding Playlists to a **New Playlist** on a Layout has an additional Cycle Based Playback option which includes a **Random Widget** feature. Cycle based playback is not supported when adding Playlists to a global Playlist! {% endhint %} ## Playlist Grid Saved Playlists can be viewed from **Playlists** under the **Library** section of the main CMS menu: ![Playlist Grid](https://2811002782-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fj0uXhtBdyPyW40TfKTZd%2Fuploads%2Fgit-blob-57e9ec3165a0a4cd746fb180cd474aa75a9155b6%2Fv4.5_media_playlists_grid.png?alt=media) Each Playlist has a row menu which is used to access a menu of actions/shortcuts, notable settings are listed below: * **Timeline** - open the Playlist Editor to make changes to content on the timeline. * **Edit** - use the Filter tab for Dynamic Playlists to view the list of dynamically assigned media and make changes to criteria. * **Usage Report** - view where Playlists are being shown and what Layouts they have been included on. * **Schedule** - directly Schedule a Playlist to be shown full screen on Displays. {% hint style="success" %} Any changes made to a Scheduled Playlist will be automatically pushed to Players as they are made. {% endhint %} # DataSets DataSets are used to design and store tabular data which are created and managed independently to Layouts and Playlists. Once created, DataSets are added to Layouts and Playlists using the DataSet Widget. {% hint style="success" %} DataSets can also be used to create your own RSS Feeds to add to the Ticker Widget. {% endhint %} ## Overview: * Define the data structure. * Data can be manually added. * Import data from a CSV file. * Use a JSON formatted data source via the API. * Sync from a 3rd party data source remotely on a schedule. * Maintain content without accessing Layouts/Playlists. * Re-use across multiple Widgets/Layouts/Playlists. * Create an RSS feed from a DataSet. DataSets have been designed to be versatile so that they can be configured in a number of ways with the DataSet Widget as well as a source of data for a custom Module. A DataSet provides a convenient way to import and display data from other systems. Examples of where DataSets could be utilised: * A drinks menu at a bar * Tee times at a golf club * Meeting room bookings * Bus timetables DataSets are created and managed independently to Layouts and Playlists and therefore do not require user access to Layouts the Layout Editor or Playlists to add or manage the data held within a DataSet. ## Creating a DataSet DataSets are created and managed by selecting **DataSets** under the **Library** section of the main CMS menu. * Select the **Add DataSet** button and complete the form fields to create a new record * Give your DataSet a **Name** for easy identification in the CMS. Provide an optional internal **Description** and enter a **Code** if referencing this DataSet via the API. If the DataSet is going to be connected to sync with a **Remote** data source, tick to enable and continue with the Creating Remote DataSets configuration. If the DataSet is **not Remote**, click to Save the DataSet record and continue from the Create and Configure Columns section. ### Creating Remote DataSets Remote DataSets are a special type of DataSet which will periodically sync from a 3rd party data source. \[\[PRODUCTNAME]] will call the URL at a chosen time period and parse the data according to instructions set on the DataSet record and any Columns that have been defined as **Remote**. On selecting Remote, additional tabbed fields are made available so that the Remote DataSet record can be fully completed: ![Remote DataSet Options](https://2811002782-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fj0uXhtBdyPyW40TfKTZd%2Fuploads%2Fgit-blob-c142d9f5c6a4745b1f07f655ca469a41181e8f15%2Fv4.5_media_dataset_remote.png?alt=media) * #### Remote Set the type of request method and enter the URL for the remote data source. * #### Authentication Provide authentication information. Custom Headers are available to provide an optional string of custom HTTP headers. * #### Data Set the remote data source: ### JSON Source JSON data is populated according to the Columns defined as Remote types. When specifying a **Remote Column** a 'data path' needs to be entered which is the JSON syntax path to the data for that column, in respect to the **Data Root** specified. Consider an example JSON data source: ```json { "base": "EUR", "date": "2017-12-22", "rates": { "GBP": 0.88568, "THB": 38.83, "USD": 1.1853 } } ``` If we wanted two columns to capture the currency **Symbol** and **Value**, we would need to set the **Data Root** to `rates` and have Columns for: * **Symbol** - data path = 0 * **Value** - data path = 1 Use the **Test data URL** to ensure that the desired structure is returned. ### CSV Source The remote data source can be selected as a CSV. If the CSV source contains headers, tick to ignore the first row. Use the **Test data URL** to ensure that the desired structure is returned. #### Advanced * Set how often the remote data should be fetched and imported. {% hint style="warning" %} The fetch remote DataSet task is run hourly by default. Remote DataSets are intended for data which updates infrequently and not in real time. {% endhint %} * Set a timescale to Truncate data. * Use the drop down to select a DataSet if using dependants. * Optionally set a row limit and what should happen if this limit is exceeded. If no **Row Limit** is set here, the Row Limit applied in the **CMS Settings** will be used for non Cloud customers. If no **Row Limit** is set here the default will apply which is 10,000 rows per DataSet for Cloud customers. * Click to **Save**. ## Create and Configure Columns Columns define the structure of your data: * Use the row menu for a DataSet record and select **View Columns** {% hint style="success" %} By default, all new DataSets will have a **Col1** added. This should be edited or removed using the row menu for Col1. {% endhint %} * Delete Col1 from the row menu and click on the **Add Column** button to create a new column ​ or * Use the row menu for Col1 and select **Edit**. ![DataSet Columns Form](https://2811002782-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fj0uXhtBdyPyW40TfKTZd%2Fuploads%2Fgit-blob-980a270860bf21aa7962f113e4181e20f1627619%2Fv4.5_media_columns_form.png?alt=media) * Include a **Heading** to identify this Column. * Use the drop down to select a **Type** of Column to use. ### Column Types: #### Value Enter a list of items to be presented in a combo box. * Use the drop down to select the **Data Type**. * Provide a comma-separated list of values that can be selected for this column. * Set the position this Column should appear when viewing/editing Data. * Provide an optional tooltip message to display when entering data for this column. Use the additional options to enable **Filters**, **Sorting** and **Required Values** for this column. #### Formula Enter a MySQL statement. * Use the drop down to select the Data Type. * Set the position this Column should appear when viewing/editing Data. * Provide a MySQL statement suitable to use in a 'SELECT' statement or a string to format a date field. {% hint style="info" %} `$dateFormat(,,)` Ensure that ``has a date and time specified for the date format to work. If the language has not been set, it will default to English. {% endhint %} {% hint style="info" %} Two substitutions are available for Formula columns: `[DisplayId]` and `[DisplayGeoLocation]` which will be substituted at run time with the Display ID / Display Geo Location (MySQL GEOMETRY). {% endhint %} Use the additional options to enable **Filters** and **Sorting** for this column. #### Remote Provide a JSON syntax string. * Use the drop down to select the Data Type. * Enter a JSON syntax string showing how to access the data from a 3rd party data source. * Set the position this Column should appear when viewing/editing Data. Use the additional options to enable **Filters** and **Sorting** for this column. Continue to add and configure Columns as required. There is no theoretical limit to the number of Columns Xibo can support, although a smaller DataSet is often easier to manage and display. Columns can be viewed/added and edited by using the row menu for a DataSet record from the DataSets page. The ordering and list content of Columns can be changed after Data has been collected. ## Adding Data to Columns Once Columns have been defined, data needs to be added. This can be achieved a number of ways: * Manually through the CMS User interface * Imported via a CSV file * Using the API * Remotely Sync ### Manually Data is added using the **View Data** button located next to the Add Column button. {% hint style="success" %} Data can be viewed/added and edited by using the row menu for a DataSet record from the DataSets page! {% endhint %} * Add a new row of data by clicking on the **Add Row** button and complete for each non-formula Column type. * Click **Next** to continue adding data to add more rows. * When all data has been completed, click **Save** {% hint style="success" %} Select multiple rows and use the Delete Selected action to delete in bulk. {% endhint %} ### Importing a CSV The CMS has a DataSet CSV importer that can be used to extract data from a **CSV file** and put it into a DataSet. The **Import CSV** function can be accessed through the row menu of any DataSet record (with the exception of DataSets configured for Remote data sources). The importer has options to overwrite the existing data held in the import file as well as an option to ignore the first row of the CSV when importing if your file has headings. The Remote Columns in the DataSet will be listed with a field next to them to indicate the column number in the CSV file that corresponds with the listed Column Header. {% hint style="warning" %} It is important to ensure that your CSV file has the correct file encoding if you are using non-ASCII characters. Non-ASCII characters are very common for languages outside of English. The file encoding most commonly used is UTF-8.\ If you have edited your CSV file using Excel, you will need to make sure you select "Unicode (UTF-8)" from the Tools -> Web Options -> Encoding tab on the 'Save as' dialogue. {% endhint %} ### Through the API You can write your own application which syncs data into a DataSet using the Xibo API. Data can be added row by row or by importing whole JSON structures. Further discussion on the API can be viewed in the [Developer documentation](https://docs.xibosignage.com/developer/). ### Remotely Remote DataSets are kept in sync with a Task called **Fetch Remote DataSets**. This task is configured by default and runs once per minute. * #### Dependents A remote DataSet can depend on another DataSet to formulate its request. Each row in the dependent DataSet will be used to create a request using the parent DataSet's request parameters. ## Row Menu Each DataSet has a row menu where Users can access a list of actions/shortcuts. * Notable settings are listed below: ### View RSS Create your own RSS feed using the data held in a DataSet. * Select **View RSS** from the row menu of a DataSet. * Click on the **Add RSS** button. ![Add RSS](https://2811002782-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fj0uXhtBdyPyW40TfKTZd%2Fuploads%2Fgit-blob-a88b3f44bd7efa5925a104302f7f11ec0eae0096%2Fv4.5_media_datasets_add_rss.png?alt=media) * Complete the form fields, selecting the Columns to use. * On Saving a URL will be generated which can be copied and added to the Ticker Widget. ### Delete DataSets can only be deleted if they are not in use. Multiple DataSets can be selected and deleted in bulk using the With Selected option at the bottom of the DataSets grid. ### Share Set Share options for User/User Group access to individual DataSets. # Menu Boards The Menu Boards interface provides a simple way for users to create and manage 'categories' and 'product' information independently to Layouts. Once created, Menu Board data can be added anywhere on a Layout using Elements from the Menu Board: Category and Menu Board: Products Widgets available in the Layout Editor. {% hint style="danger" %} Menu Board Widgets are not available to add to a Playlist! {% endhint %} ## Overview * Create and define Categories * Include detailed product information * Select Images to use from your Library * Maintain content without accessing Layouts * Re-use across multiple Widgets/Layouts Menu Boards are created and managed independently to Layouts and therefore do not require user access to Layouts or the Layout Editor to add or manage categories/product data held within a Menu Board. ## Creating a Menu Board Menu Boards are created and managed by selecting **Menu Boards** under the **Library** section of the main CMS menu: 1. Select the **Add Menu Board** button and complete the form fields to create a new record 2. Give your Menu Board a **Name** for easy identification in the CMS. Provide an optional internal **Description** and enter a **Code** if referencing this Menu Board via the API 3. Click to **Save** ## Create and Configure Categories Categories define the structure of your data: 1. Use the row menu for a Menu Board record and select **View Categories** 2. Click on the **Add Category** button and complete the required form fields 3. Click **Next** to repeat this process to add the required **Categories** for the Menu Board Select **Save** when entering the last Category to use. {% hint style="info" %} **Code** is for advanced use when referencing the API. {% endhint %} ## Add Products Product data is added to Categories to provide all key information which can be selected to be shown on Displays. 1. Use the row menu for a Category and select **View Products** 2. Create new Product data by clicking the **Add Product** button and complete all relevant form fields {% hint style="info" %} The Menu Boards: Products Widget can be configured to dim products that are marked as unavailable to show on Displays. {% endhint %} ### Product Options Use this tab to provide further product options. {% hint style="success" %} Use Options to provide special offers, limited deals etc for this particular product. {% endhint %} Repeat the process to add further Products/Product Options to the Category. Menu Board data is added to Layouts using the Menu Board: Category Widget which has data elements which are primarily used to add 'header' information and the Menu Board: Products Widget which allows for precise placement of Product details on Layouts. {% hint style="success" %} Menu Boards are edited independently to Layouts, so there is no need to access or edit the Layout(s) the Menu Board has been added to. Changes will be available in the system straight away ready to be picked up by Players on their next collection, with no need to make any edits to Layouts! {% endhint %} # Dashboard Service This service is a commercial feature allowing users to securely display dashboard services; Microsoft Power BI, Grafana and Matomo, on Layouts with automation and authentication handled by Xibo. {% hint style="warning" %} This commercial feature requires an API for configuration.\ Once the Connector has been configured, add dashboards to display in Layouts using the Dashboards Widget {% endhint %} ## Configure Connector From the CMS: ![Dashboard Connector](https://2811002782-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fj0uXhtBdyPyW40TfKTZd%2Fuploads%2Fgit-blob-7cf52cae85f5a163655c4a84c591ef77c700be62%2Fv4.5_media_dashboard_connector.png?alt=media) 1. Click on **Connectors** under the **Administration** section of the main menu 2. Click the **Configure** button for the **Xibo** **Dashboard Service** connector 3. Enter the API key you have been given (available in My Account) {% hint style="success" %} Customers on a Business or Enterprise Plan will have their API key pre-filled! {% endhint %} 1. Tick to **Enable** to start providing the dashboard services 2. Click to **Save** 3. Click the **Configure** button again for the Xibo Dashboard service connector 4. Using the **Credentials** section of the form, select the dashboard service(s) you wish to use Enter the following credentials: * Username * Password * Two Factor Secret (if required) * URL (if required) {% hint style="warning" %} Grafana does not support multi factor authentication, so please leave the **Two Factor** **Secret field empty** when configuring this integration.\ Please see the following page for further information on obtaining a URL to use with this service, supported authentication mechanisms and possible limitations [Xibo Dashboard Service](/setup-docs/cms-configuration-and-integration/xibo-dashboard-service) {% endhint %} * Click to **Save** and wait a few moments whilst those credentials are successfully registered. Your Dashboard is ready to be added to Layouts using the Dashboard Widget # Modules Management All displayed content is served by a Media Module managed from the Modules page under the Administration section of the main CMS menu ![Modules Grid](https://2811002782-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fj0uXhtBdyPyW40TfKTZd%2Fuploads%2Fgit-blob-9dfebc1a0881f068c8382fd02a816aa5032891ee%2Fv4.5_media_modules_grid.png?alt=media) * Use the row menu and click **Configure** to control if it should be accessible for Users to use. {% hint style="warning" %} At times it may be necessary to add or remove the allowed extensions on a particular Library file based Module (Image, Video, Flash etc.) A typical use case would be if a Player is being used which does not support that particular type of file. {% endhint %} {% hint style="success" %} Fonts can be added and managed from the Fonts page under the **Administration** section of the main CMS menu. {% endhint %} ## Caching and external access The core Modules are designed to have their data cached and served from the CMS so that they can be played back without an active connection and/or without direct access to external resources that might be required. The CMS also uses this mechanism to be a *good citizen* when requesting 3rd party data. {tip} For example, a Ticker Widget with the address `http://anexternal.com/feed` would only be accessed by the CMS and only once per `updateInterval`. The Players showing the Layout would not need to access that address directly. {/tip} All of the core Modules adopt this approach, exceptions noted below: * The **Web Page Module** does not cache from the CMS and will always attempt to open the specified web page address using the browser on the Player. This means that the Player must have network access to the web address at all times. * The **Embedded Module** can be cached using library references, however, the User that creates the Module is free to specify external resources should they require them. * The **Local Video Module** is rendered by the video decoder on the Player and can reference an external stream. * **Flash** Files have the capability to reference an external file and will be run on the Player. ## Generic File The Generic File Module is used to send **additional files** to the Player that can then be used for other purposes. {% hint style="success" %} This could be useful for providing supplementary files to be used as relative paths (e.g. An up and down arrow that is dynamically shown in the embedded HTML based on the results of stock data) as an example. {% endhint %} # Connectors Management From the Connectors page under the Administration section of the main CMS menu, view all third party services which can be enabled and configured. Click Configure for a Connector to Enable/Disable and to provide configuration options. {% hint style="success" icon="cloud-check" %} API keys are configured as part of the service for all modules that rely on a third party service. {% endhint %} {% hint style="warning" icon="cloud-xmark" %} You will need to create an account and obtain an API key for the third party service you wish to use and provide those details in the relevant Connector. {% endhint %}
# Simple Scheduling Xibo has a variety of scheduling tools in order to deliver the right content at the right location at the right time. All content to be shown on authorised Displays must be included in a Schedule. Displays check for new scheduled content periodically and will download any new items in advance of playback ready to be shown. You may have a Layout created by a member of your team, in order to share an important announcement within a company, which is now Published and ready to be shown on Displays. ## How-to Video Simple Scheduling {% embed url="" %} ## Creating a Schedule * Click on **Schedule** from the main CMS menu. * Click the **Add Event** button. Follow the steps in the schedule wizard: * Use the **Event Type** drop down to select the type of Event to Schedule. For this example, select **Layout**. * Use the drop down to select the **Layout** to show, click **Next**. * Select which **Displays** to show the Layout on. * If you want to use the default **Always** schedule, can click **Finish** to complete. * If you want to select alternative created **Dayparts** or **Custom** dates, select **Next**. * With **Custom** selected, use the Relative time option to show the Layout straight away. Provide how long it should remain showing on displays by entering the hours and minutes. * Click to **Finish** or **Next** to access further scheduling options such as **Priority, Display Order** and **Repeats**. The CMS will now update a Schedule change and show the Layout on Displays for the specified time. The Scheduled Event can be viewed/edited from the **Schedule Grid** and **Calendar** views. ## FAQs ***Can I create Schedules from other parts of the CMS?*** Yes, Schedule Events from the row menu for Layouts, Campaigns, Playlists and the Media grid for Images and Videos. Once a Layout has been published, it can also be Scheduled directly from the Layout Editor. ***How do I remove an Always Event from the Schedule?*** From the Schedule, use the row menu for the Event in the Grid view and select Delete, or click on the Event icon from the Calendar to open the Edit Event form and Delete. ***How can I see what will be shown on a Display at a specific point in time?*** Use Agenda to see a precise representation of what Layouts/Campaigns will be shown on a selected Display. Click on an event icon in the calendar and use the slider to pinpoint the exact time of day to view. # Repeat scheduling Set up recurring Events to repeat at specified intervals. **Repeating Events** is an efficient way to create the same Event details, to be shown multiple times without the need to manually duplicate information over and over. It could be useful for content that needs to shown regularly on Displays such as recurring room bookings and meeting events and reduces the need to manually keep schedules updated. ## How-to Video Using Repeats {% embed url="" %} ## How-to create repeats Once an Event has been created with start and end times, an appropriate repeat (Minute, Hourly, Daily, Weekly, Monthly or Yearly) can be configured from the **Repeats** tab under **Optional**. For example selecting a **Weekly Repeat** you could select Wednesday and Friday as the days of the week to Repeat the Event, and by entering a 2, it would Repeat Every other week on those days. **Monthly Repeats** can be configured by the Event date or by which day in the month the Event falls on. An Event which is scheduled on Thursday 19/06 can be set to Repeat every month on the 3rd Thursday for example. Use **Until** to control when the repeated event should finish. {% hint style="warning" %} Ensure the time selected here is after the final repetition of the defined Event so as to not cut the play back of content short. {% endhint %} **Recurring Events** can be removed from the Schedule in their entirety by right clicking the event from the calendar view or from the grid view and using the row menu to select delete. Alternatively, remove only an instance of a recurring event from the Calendar view: * Locate the Recurring Event by date * Right click the event and select to remove this instance only. All other instances will remain scheduled. {% hint style="danger" %} Care should be taken if amendments are made to a recurring Schedule after deleting an individual Event instance. Previously deleted Event instances could be recreated when making edits to an existing recurring Schedule! {% endhint %} ## Schedule Reminders Create a set of Reminders to help you keep track of your schedules. Reminders can be sent to the Notification Center of the CMS or emailed to the address as set for your User Profile. {% hint style="warning" %} Check to make sure that a **Sending Email address** has been set in the CMS Settings before using this feature! {% endhint %} # Using Priority and Display Order Xibo has a number of scheduling tools to allow for the simple creation of schedules across one or more Displays/Display groups. These tools allow users to define the order of scheduled items to tailor how content should be shown as well as flagging high-priority Events to display those at the top of schedule lists. ## Priority Priority pushes important content to the front of any existing schedules and overrides all other non priority events of the same Event Type (Layouts/Campaigns/Video/Images and Playlists) on the schedule. Schedules with a higher priority take precedence over those with lower priorities, with 0 considered the lowest. For example, you might have an important announcement with information about a fire alarm test which needs to be the only thing to show on Displays at a specific time. Assigning the highest Priority to this Event would ensure that it is the only content to be shown. On reaching the end time of the priority event, the normal schedule will resume on displays. ## Display Order Use Display Order to determine the play order of multiple Events which have been scheduled to show at the same time. Ordering is a simple numerical sort, lowest to highest numbers, Events marked with a 1 will be played before any Events marked with a 2 for example. Leaving the Display Order field blank will default to the order that the Event was first added. {% hint style="info" %} To ensure Layouts play in a defined order we recommend adding and ordering them into a Layout List Campaign. The Display Order can then be used to determine the order in which entire Campaigns should play.\ If Layout List Campaigns have the same Display Order set or this field is left blank, Layouts assigned to the Layout List Campaign will play according to the **Play List order** set. {% endhint %} ### Maximum Plays per Hour There is an additional setting when scheduling Events to limit the number of times the Event should be shown per hour on Displays. You may have a promotional Image which should only be shown once an hour for example. * Set a number here or leave as 0 for unlimited plays. ## FAQs ***What is considered the same Event Type for Priority?*** Layouts/Campaigns/Images/Videos and Playlists will be treated as the same Event Type when taking Priorities into consideration. ***What would happen if I ticked the Run at CMS time checkbox for an event?*** With this ticked, the Event time would be determined by the CMS time rather than using the local Display time for the selected Displays. Scenario: * CMS Time = GMT * Display 1 = GMT * Display 2 = GMT -4 If an event was scheduled to start at 11:00hrs, content would start to show on these Displays at 11:00hrs according to their time zones. These two Displays will not show the same content at the same time as Display 2 is 4 hours behind Display 1. If Run at CMS time was ticked, Display 1 will start to show at 11:00hrs, as it is on the same time zone as the CMS. Display 2 will start to show content at 07:00hrs as it is 4 hours behind the CMS time zone. # Scheduling Available Event Types in scheduling. ### Command Select a Command to be executed by the Player at a specific point in time ### Overlay Layout Layouts that have been designed as an Overl ay Layout will be scheduled at the same time as existing Layouts to create an overlay of content when displayed. ### Interrupt Layout An Interrupt Layout will schedule a selected Layout to play **in-between** other Layouts in the 'usual schedule'. Xibo will work out when it will be played using how many **seconds per hour** or as a **Percentage** entered on the schedule. {% hint style="success" %} This can be useful if you have Announcements that need to be shown for a particular amount of time within the usual schedule! {% endhint %} * Select **Interrupt Layout** as the Event Type from the drop down menu when adding an Event. * Complete the form fields to create the schedule. #### Share of Voice Enter the amount of time the Layout should be shown in seconds per hour or as a percentage (0 - 100%) of the events duration (the difference between the from date and the to date) that the **Interrupt Layout** should occupy the usual schedule. {% hint style="warning" %} If your 'main' Layout has a long duration, the Interrupt Layout may show in a block in order to satisfy the SoV criteria entered! {% endhint %} ### Action **Scheduled Actions** listen for a Trigger Code coming in on a webhook to Navigate to a Layout or to run a Command. * **Navigate to Layout** - enter the code identifier for the Layout the Player should navigate to when triggered. This code is created when adding a new Layout or from editing an existing from the Layouts grid. * **Command** - select the Command to run. ## Synchronised Events Synchronised Events are used in conjunction with Sync Groups to show mirrored or a video wall configuration across 2 or more Displays. {% hint style="warning" %} Ensure you have created and configured a **Sync Group** prior to scheduling! {% endhint %} Click on the **Add Synchronised Event** button at the top of the schedule grid to open the **Add Synchronised Event** form. Select a Sync Group from the drop down menu. * Use the **Layout** drop down to select which content should be shown on each Display within the group. When selecting different content to show in a wall configuration on Displays, the total duration will be enforced by the content on the Lead Display. {% hint style="info" %} The Lead Display will issue instructions to change the sequence based on its assigned content. Please bear in mind that other Displays within the group could fall out of sync if their content is not similar in design (same number of items, durations etc). {% endhint %} * Select **Mirror** to automatically set the same item on each Display within the group automatically. {% hint style="success" %} Sync Playlists on different Layouts by using a **Content Synchronisation Key**! {% endhint %} ### Dayparts * Events are scheduled using **Dayparting** information: * Select **Custom** to enter your own start and end times. Use the **Relative time** checkbox to input the Hours and Minutes when creating a Scheduled Event (not available for Synchronised Events). * Select **Always** to have the content always scheduled on the selected Display. {% hint style="success" %} Create your own defined Dayparts to select for even easier scheduling! {% endhint %} * Use the drop down to select what needs to be scheduled from the list. # Layout List - Campaign Create a Campaign containing a list of ordered Layouts so that they play in a controlled sequence. Think of a Layout as a single slide in a presentation deck, a Layout List Campaign is the entire presentation. ## How-to Video Layout List {% embed url="" %} ## Creating a Layout List Campaign * Go to **Campaigns** under the **Design** section of the main CMS menu. * Click the **Add Campaign** button. * Use the **Type** drop down and select **Layout List**. * Give your Campaign a **Name** for easy identification in the CMS. * Optionally use the checkbox to enable **Cycle Based Playback**, and provide a number to determine how many 'plays' a Layout should have before moving onto the next Layout in the Campaign. {% hint style="info" %} If a 2 was set as the Play Count, the same Layout would be shown twice each Schedule loop before moving onto the next Layout in the sequence. {% endhint %} * Leave Cycle based playback blank and use the **List Play Order** menu to select how Layouts will play when scheduled concurrently with another Campaign with the same Display Order: * Select **Round Robin** to interleave Layouts from each Campaign or **Block** to play Layouts in their set sequence from one Campaign before moving onto the next Campaign. * Click to **Save**. On saving, the form will re-open with an additional Layouts tab: * Select the **Layouts** which should be added to the **Campaign**. * Use the `+` icon to for each Layout to add. * Added Layouts will be shown at the top of the **Edit Campaign** form. Layouts can be re-ordered from here by drag and drop to ensure they play in the correct sequence. * Click to **Save**. ## Further Reading {% content-ref url="/pages/L8ste2vjohsdskhuMbDm" %} [Layout Editor](/layouts/layouts_editor) {% endcontent-ref %} ## FAQs ***Is there an easy way to create multiple Campaigns?*** Make copies of selected Campaigns by using the row menu in the Campaign grid. Once a copy has been created use the row menu to select Edit to make changes to the Layout selection. ***Can I assign Layouts to a Campaign from anywhere else in the CMS?*** Directly assign Layouts to Campaigns from the Layout grid. Use the row menu for a selected Layout and click Assign to Campaign. Once added the Layout will be added at the end of the sequence of other added Layouts by default. # Ad Campaigns Create Advertising Campaigns where Xibo will work out how many plays are needed to satisfy entered criteria and handle the scheduling automatically for you. {% hint style="info" %} Enable the **Access to Ad Campaigns** Feature for each User/User Group who should have full access to this feature! {% endhint %} ## Create an Ad Campaign 1. Click on **Campaigns** under the **Design** section of the main CMS menu 2. Click the **Add Campaign** button at the top of the grid 3. Select **Ad Campaign** from the drop down menu and complete the form fields 4. Give your Ad Campaign a **Name** for easy identification in the CMS including optional Tags 5. Use the drop down to set the **Target Type** for this Ad Campaign as **Plays**, **Budget** or **Impressions** 6. Include the total **Target** number for this Ad Campaign in relation to its selected Target Type 7. Click to **Save** Next, criteria needs to be set to allow Xibo to work out the play frequency. From the grid, use the row menu for the **Ad Campaign** and select **Edit**: ![Edit Ad Campaign](https://2811002782-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fj0uXhtBdyPyW40TfKTZd%2Fuploads%2Fgit-blob-9650b8ff4e42bec692669f33920d88dc10b10d26%2Fv4.5_campaigns_edit_ad_campaign.png?alt=media) 1. Provide **Start** and **End** Dates and Times for the Ad Campaign. (This is required information and **cannot** be left blank) 2. Select from available **Displays** and **Display Groups** to play this Ad Campaign on. (This is required information and **cannot** be left blank) 3. Click to **Save** {% hint style="warning" %} Ensure that Displays have had **Display Details** correctly entered for the selected Displays which play this Ad Campaign, ensuring that **Cost per play** and **Impressions per play** fields have been completed. {% endhint %} {% hint style="danger" %} **Proof of Play** needs to be set to **ON** for all Displays/Display Groups selected here, to ensure accurate reporting and plays! {% endhint %} * Assign a Layout using the **Layout** drop down menu. Once a Layout is selected further scheduling options are available: ![Assign Layouts Ad Campaign](https://2811002782-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fj0uXhtBdyPyW40TfKTZd%2Fuploads%2Fgit-blob-9b4d342c285e9d6e9412ad9c7d52702dd8983e3d%2Fv4.5_campaigns_assign_layouts_ad_campaign.png?alt=media) * Select which **Days of the Week** this Layout should be active in this Ad Campaign. * Choose from existing Dayparts if this Layout is only to be shown at selected predefined times. {% hint style="info" %} Ad Campaigns can include multiple instances of the same Layout with different Dayparts assigned if required.\ For example, If you needed to show the same Layout for a defined 'Morning' daypart as well as a defined 'Evening' daypart add the Layout twice and define the required dayparts individually for each! {% endhint %} * Draw areas on the map to provide **geo fenced** based plays for any mobile displays, with content to be shown on entering a defined area. {% hint style="success" %} You can have multiple areas defined on the same map! {% endhint %} * Click to **Save**. The Layout will be added to the Campaign which can be edited/deleted if required using the row menu: Continue to build your Ad Campaign by selecting Layouts and defining scheduling options. {% hint style="success" %} Xibo will schedule automatically to fulfil the required play criteria to meet entered Targets. {% endhint %} Ad Campaigns can be viewed on the **Schedule** as locked entries which cannot be edited from the scheduler itself. **Agenda** can be used to see a more detailed play view of the Ad Campaign and preview included Layouts. The Ad Campaign progress will be shown in the Campaigns grid and on opening the Ad Campaign, providing that Proof of Play has been set to ON for all Displays and Layouts selected for the Campaign. As well as Cost per play and Impressions per play fields are completed for all selected Displays. {% hint style="danger" %} If the above information is omitted the reporting cannot update to reflect Plays, Spend, Impressions and Target which will all show a 0 value. The Ad Campaign itself will also try and catch up to increase the Target which will result in Layouts being played more and more frequently until its the only content shown in order to fulfil the target. {% endhint %} {% hint style="info" %} The Reference tab can be used to provide reference information for the selected Campaign. Once added, this information can be viewed in the Campaign grid and via the API. {% endhint %} # Overlay Layouts An Overlay Layout will show on top of other Layouts once Scheduled. {% hint style="success" %} Overlay Layouts can also be Scheduled to be used with Layouts inside a Layout List Campaign. {% endhint %} Overlay Layouts remain on top while your normal scheduled content changes underneath. This is particularly useful for logos, important information or emergency notices for example. ![Overlay Layout](https://2811002782-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fj0uXhtBdyPyW40TfKTZd%2Fuploads%2Fgit-blob-2d95900ba5458e40c3a74c89e7bd3eaed239fdf4%2Fv4_layouts_overlay.png?alt=media) ## Create an Overlay Layout Overlay Layouts are created in exactly the same way as all other **Layouts**. Add content to fit around your existing designs so that your Overlay Layout can "sit on top" of other Layouts that are **Scheduled** at the same time as the Overlay. Your Overlay Layout will display its all important content whilst the Layouts "underneath" play in rotation. {% hint style="info" %} Xibo will not render the background on Players when a Layout is scheduled as an Overlay Layout. {% endhint %} {% hint style="danger" %} Layouts that contain Widgets / Media that use the Edge browser cannot be used with an Overlay Layout as content cannot sit on top of other content under these circumstances. This would include HLS and Embedded YouTube. If your content is not a video then the CEF browser can be used instead. {% endhint %} Overlay Layouts behave in a different way to Layouts when scheduled and will only render media content once so will not show any refreshed content. If your Overlay Layout includes content which needs to be refreshed, Calendar or Ticker Widgets for example, a Playlist should be added to the Layout and the media added to the Playlist. Then when it loads the next item in the Playlist it will reload the other items to show refreshed content. # Geo Scheduling Scheduled Events can be configured to be location aware with locations displayed on a map view. ## Define Location 1. From the Add/Edit Event form, click on the **Optional** tab and select the **Geo Location** tab 2. Tick in the **Geo Schedule** box to enable and define the location * Use the buttons in the top left of the map to Zoom in and out * Click on the search icon to enter details for a particular area {% hint style="info" %} On opening, the map will default to what is entered for DEFAULT\_LAT and DEFAULT\_LONG in **CMS Settings**, under the Displays tab. {% endhint %} ![Geolocation Search](https://2811002782-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fj0uXhtBdyPyW40TfKTZd%2Fuploads%2Fgit-blob-680696d2e42831bf26a61fd37d8bd1bed958eeb3%2Fv4.5_schedule_geolocation_search.png?alt=media) * Define an area by drawing a Polygon or Rectangle layer on the map. ![Layer](https://2811002782-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fj0uXhtBdyPyW40TfKTZd%2Fuploads%2Fgit-blob-1730f066e979b7632dc48009a2782a91b0f64831%2Fv4.5_schedule_rectangle.png?alt=media) ## Edit * Once an area has been defined, click on the edit icon, at the top right of the map, to to drag the markers to make adjustments to the existing Layer. * Click on the grey **Save** button located here to ensure that edits are saved. ![Edit Layer](https://2811002782-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fj0uXhtBdyPyW40TfKTZd%2Fuploads%2Fgit-blob-0a0cd015e8aeba123a3477188f357709a3188cbb%2Fv4.5_schedule_edit_layer.png?alt=media) ## Delete * To remove the area, use the bin icon and click into the area to delete * Click the grey **Save** button to save the removal of the layer. {% hint style="success" %} Edit this schedule by clicking the icon in the Calendar or by using the row menu in the Grid view! {% endhint %} # Dayparting Dayparting allows Displays to show relevant content based on the immediate needs of your audience allowing you to tailor content without manual intervention. Xibo supports the creation of multiple Dayparts, to allow you to define distinct blocks of time (e.g. Breakfast, Lunch, Evening) which can include defined exceptions. This means that a single day can be split into as many **pre-defined** parts as necessary. {% hint style="info" %} A typical use case would be a hospitality User who has different content to display for Breakfast, Lunch and Dinner. Dayparting allows that User to create a Breakfast, Lunch and Dinner daypart, each of which starts and ends on a different day, simplifying day to day scheduling. {% endhint %} ## Add Daypart Dayparts are created and administered from **Dayparting** on the main CMS menu. * Select the **Add Daypart** button. * Complete the form fields to configure. {% hint style="info" %} Include **Exceptions** to define different start and end timings for selected days! {% endhint %} On Saving, the Daypart will be available for selection in the **Dayparting** drop down menu of the schedule form when adding an Event. The below Daypart form shows an example Breakfast Daypart: ![Example Breakfast Daypart](https://2811002782-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fj0uXhtBdyPyW40TfKTZd%2Fuploads%2Fgit-blob-9d2e114f8dfb94efc3ca8fcdd063dfd69d92c8ac%2Fv4.5_scheduling_daypart_form.png?alt=media) Saturday and Sunday have been configured as exceptions so that breakfast starts and ends at different times on those days: ![Daypart form exceptions tab](https://2811002782-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fj0uXhtBdyPyW40TfKTZd%2Fuploads%2Fgit-blob-994ba05a73f5b2c0d4eece703a5e63f201fd4b8a%2Fv4.5_scheduling_daypart_form_exceptions.png?alt=media) On Scheduling, the **Breakfast** Daypart will appear in the drop-down for selection. On selecting, the from/to date time selectors will change to date only selectors and the time will be taken from the Daypart configuration - according to the day of the week the Event occurs on. ## Edit Dayparts Make edits to existing Dayparts using the row menu. {% hint style="info" %} Add Sharing options for Dayparts to Share with other Users/User Groups! {% endhint %} Updating the start/end times or exceptions for a Daypart will cause existing future events to be updated with the newly defined times. Existing recurring Schedules, set to recur beyond the current time, will have new Schedules created to reflect the updated information. ## Further Reading Create Display Operating hours using Dayparts: {% content-ref url="/pages/HzctJ5tR2JXRU5u1ojua" %} [Display Settings](/displays/displays_settings) {% endcontent-ref %} # What is a Display? Xibo shows content on your screens; whether you have existing content or need to create your own, to show on 1 screen or a 100.000, Xibo makes it easy! Xibo uses the concept of Displays which are managed from the CMS to control when and how content is shown as well as provide device management tools for Users. A **Display** is an essential part of digital signage as is it bridges the communication between the **CMS** software (Content Management System) and **Media Player App**. ## How-to Video What is a Display {% embed url="" %} The **Player App** is installed onto a **Media Player**, which can be a separate physical hardware device attached to a screen or an integrated Media Player found in supported System on Chip (SoC) professional signage monitors. A hardware key is generated on installing the Player App which creates a unique **Display** record in the CMS. Once installed, the Player App must be **Connected** to the CMS by using a **Code** or by providing a **CMS Key**. Once connected a **Display** will be registered awaiting **Authorisation** in the CMS before it will become a managed device and start displaying content from the CMS. ## Creating a Display 1. **Download** the Player App 2. **Install** to the Player device. Some supported (SoC) System on Chip models will already have the Player App installed. 3. **Connect** the Player App to the CMS. 4. **Authorise** the Display using the row menu from the **Displays** page in the CMS. The Display will regularly connect to the CMS to check for any updated schedule information or any new content to download. The Displays grid will update to show the status, indicate if the Display has logged in recently, show the date and time stamp of when the Display was last accessed etc, to help you manage your network. {% hint style="success" %} Any updates will be downloaded and saved to the Player App. This means that if a connection issue were to arise between the Display and CMS, the Display would continue to show scheduled content offline until the connection was restored. {% endhint %} Manage **Displays** from the CMS to and use the range of device management tools to effectively control your network. ## FAQs ***Which Players can connect to the CMS using code?*** All Players, at the latest version support connecting via a code, with the exception of the Linux Player. ***Can I easily transfer a Display to another CMS?*** First you need to ensure that you have Two Factor Authentication set up, from the User Profile to use Transfer to another CMS setting from a Display row menu. Multiple Displays can be transferred using the With Selected option at the bottom of the Displays grid. ***Do the Player and CMS versions have to match?*** Our recommendation is that your CMS and Players should be of the same major version for the best results. ***What does it mean to Assign Files / Assign Layouts?*** Library files and Layouts can be directly assigned to a Display so that they are always available in the local library of the Player. This is useful for pre-loading a Layout ahead of time when the Layout will be used for some API integration to trigger a change for example. Content will still need to be scheduled to show on Displays. # Configuration of Displays Once Displays have been connected, they are configured and managed from the Displays page inside the CMS. ## How-to Video Display Configuration {% embed url="" %} In order to start showing content, **Displays** must be **Authorised** with the CMS. Check the Displays grid to make sure the right Displays are showing as **Authorised**, as a first step. * Give the **Display** a friendly name for easier identification within the CMS by using the **Edit** option from the row menu. Now is a great time to assign your Display a **Default Layout**. * Scroll down the form to select a Layout to use as the default .This Layout will be shown when there is no content scheduled or an issue arises that prevents scheduled content from showing on your Display. {% hint style="warning" %} When creating your own Default Layouts, keep in mind that designs should be kept simple, avoiding any complex media and web content! {% endhint %} * Click on the **Details** tab to provide further information about your Display. * Setting the **Latitude** and **Longitude** of the Display, will show its location on the map view. The **Displays** map can be viewed by clicking the icon at the top right of the grid. * Set **Timezones** to ensure that content is shown at the right time for your Display location. Each Display is assigned a default profile which will automatically apply its settings to all Displays of the same type. For example, you edit the Collect Interval for your Android Display Profile. Once saved, the new collection time will be applied to all Displays assigned this as a Display Profile. **Display Setting Profiles** can be customised for automatic management and configuration of your Display Network. ## FAQs ***What happens if I have no content scheduled, and my default layout has an issue with downloading it's content?*** The splash screen will be shown until the issue with the default layout is resolved or content is scheduled to show on the Display. ***What does the Cloud Icon in the Status column of the Display Grid indicate?*** The Cloud Icon shows that the Player has not logged in and content is waiting to be downloaded. A Cross indicates that the Player is yet to complete the download and a Tick shows the Player is up to date. # Display Settings Display Setting Profiles offer a powerful way to centrally configure Player settings from the CMS. Settings can vary depending on the platform/media player type, using **Display Setting Profiles** you can easily apply different settings to **Displays** of the same platform or type. When a Player connects to the CMS, it will receive any default assigned 'Profile' created and reconfigure to those settings automatically. Profiles can be customised or new ones added to suit Display requirements. For ease use the row menu and **Copy** an existing **Profile** to quickly create new Profiles with the required settings. Use Display Profiles to provide your **Licence Pool Code** to all of your Displays centrally for easier licensing which is less prone to error than entering codes manually per device. Create Display Profiles to cater for Landscape and Portrait **orientations** or to apply different **operating hours** or a Display Profile for devices that require **multiple decoders** enabled for example. If individual Displays require different settings from those set in a Display Profile, override settings by editing the Display from the Displays grid. ## Further Reading Define Operating Hours using Dayparts: {% content-ref url="/pages/JmeIuT4kth7m4lvwO34k" %} [Dayparting](/scheduling/scheduling_dayparting) {% endcontent-ref %} ## FAQs ***I have a Display that should use an alternative Profile from the set default?*** Override individual Displays from the Displays grid. Click to Edit and use the Settings tab to select an alternative Settings Profile to use for the selected Display. ***Can I use Portrait Displays?*** Android, webOS and Tizen can control rotation if your device supports screen rotation. Orientation can be selected from the appropriate Display Settings profile using the Location tab. # Display Groups Group together specific Displays to allow content and schedules to span multiple Displays with just one configured Event, saving time and reducing errors, Grouping Displays makes it easier to manage an expanding network. Simply add newly connected **Displays** to an existing **Display Group** to inherit schedules and to quickly start showing content. Group Displays by industry or location to make it easier to update and target content which differs by areas or purpose. Display Groups can contain a mix of singular **Displays** as well as other **Display Groups** to allow you to easily target the right Displays to show your content. For example, you could have Displays located within stores over different levels, intended to reach differing audiences so could have Display Groups that contain: * All Displays in store A * All Displays in store B * All Displays that are street facing * All Displays on level 1 * All Displays on level 2 * All internal Displays * All external Displays **Create Display Groups** and automatically assign **Displays** with matching criteria **dynamically** or **manually** selecting Display membership. * Click on **Add Display Group** from the Display Groups grid. ## Dynamic Groups To assign members dynamically, tick the **Dynamic Group** checkbox. * Set the **filter criteria** to use in the format of regular comma separated expressions or simple string comparisons. * Prefix expressions with a `-` to exclude from filters. For example, all Displays containing `a` but not `b` in the name would be `a, -b` * **Criteria Tags** can also be filtered using additional OR/AND filters for Displays with multiple Tags assigned. ## Manual Groups To assign members manually, leave the checkbox unticked and click to Save the form: * Use the row menu for the new Display Group record and select **Members** using the checkbox for each Display. The Relationship Tree shows the ancestors and descendants. Parent Display Groups, shown above the selected Group will pass their schedule down to the Displays groups underneath. ## Nested Groups Display Groups can be nested to simplify scheduling to allow sub-groups to inherit permissions from a parent group. # Sync Groups Sync Groups contain the Displays that will show synchronised content. Content can be synchronised to play across 2 or more Displays in a mirrored or video wall configuration when scheduling a Synchronised Event. {% hint style="success" %} Sync Playlists on different Layouts using the **Content Synchronisation Key**. {% endhint %} Displays first need to be assigned to a **Sync Group**. {% hint style="danger" %} A Display can only belong to one Sync Group at the same time. {% endhint %} 1. Click on **Sync Groups** under the **Displays** section of the main CMS menu 2. Select the **Add Sync Group** button 3. use the **Manage Membership** form to select which Displays to include in this Group Sync Groups can be saved to Folders to easily control User/User Group levels of interaction for Displays as well as provide an additional way to organise. {% hint style="warning" %} All Displays in a Sync Group need to communicate using their LAN IP address over TCP on the publisher port specified. This is defaulted to 9590 but can be changed if that port is reserved.\ We recommend using a wired network and high-powered similar devices for the best Synchronisation. {% endhint %} * Once saved, Edit form use the drop down to select which Display should be the **Lead Display** for the Sync Group. * Click to **Save** Content can now be scheduled to the Sync Group by clicking **Schedule** from the main CMS menu and selecting the Add Synchronised Event button. ## Edit / Manage Membership Manage a Sync Group by using the row menu: * Select **Edit** to set an alternative Lead Display * Select **Members** to manage which Displays are members of the group. ## Further Reading Scheduling Synchronised Events: {% content-ref url="/pages/pz3SO4uMg4iKCzgOlJsX" %} [Scheduling](/scheduling/scheduling_events) {% endcontent-ref %} # Reporting Xibo has a variety of reports to help users assess network health and uptime and Display statistics. Proof of Play data offers further insights into content performance shown across your Display network to reveal trends to enable stakeholders to refine content scheduling and placement for improved targeting and audience engagement. Reports can be viewed in real time, emailed as a PDF to users and saved for future reference as well as scheduled to run on a Daily, Weekly, Monthly or Yearly basis. Available metrics can be found by selecting **All Reports** under the **Reporting** section of the main CMS menu. Similar Reports are grouped together to make it easier to find the data you need, which are presented as Charts as well as Tabular data so you can easily identify patterns and trends. ## FAQs ***Can I remove the logo shown on exported reports?*** Go to Settings under the Administration section of the main CMS menu and select the General tab to control whether the logo should be shown. ***Can I set a collection of proof of play stats by default for Displays?*** From Settings under the Administration section of the main CMS menu, select Displays to enable Stats/Layout Stat Collection and Aggregation Level default for Displays. # Command Functionality Configure a set of commands for users to select and send via the CMS, schedule from the CMS or include in Layouts. Create commands to apply for all Players or create command strings per Players, particularly useful if your have a mixed network. Commands provide easy access to functionality for RS232 and Android Intents. ## Creating Commands Commands should have the following structure: * Code * Command string * Validation string * Create Alert On string (never, always, success, error) ### Parameters Command strings can have parameters separated by the | pipe character, e.g. mute|1. Where this is the case the command string should be separated by | and the first element be used to determine the type of command to run. ### Helpers Command Helpers are prefixes that can be added to the Command String in order to take a more advanced action. Commands without a prefix are executed in the shell of the operating system which runs the Player. `cmd.exe` on Windows and `shell` on Android. ### Validation The **Validation String** is used as a comparison to the **Command** output and if it matches then the Command is considered a success. The Validation String must be an exact match. ## Supported Commands | Command | Command String | Parameters | | ---------------------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Show status window | showStatusWindow | Timeout in seconds (int) default 60 | | Send status | status | | | RS232 | rs232 |

1. Connection
2. Command
See RS232 section below for further details

| | Android Intent | intent | See Android Intent section below for further details | | Ping | ping | | | Set Timezone | timezone | 1. IANA timezone ID | | Set Auto Time | time\_auto | | | Set Ntp | time\_ntp | | | Set Auto Timzeone | timezone\_auto | | | Philips control | tpv |

1. Operation
screenon
screenoff
backlighton
backlightoff
mute
unmute

| | Philips LED control | tpv\_led |

1. Colour
off
red
white
green
blue
on

| | Sony Screen Control | sony |

1. screenOff
2. screenOn

| | Mute | mute |


1. Operation
1 = on
0 = off

| | Screen On | screenOn | | | Screen Off | screenOff | | | Screen Input Source | screenInputSource |

1. Source
hdmi1

| | Reboot | reboot | | | Refresh | refresh | | | Resize | resize |

1. Percentage
2. Quadrant
top-left
top-right
bottom-left
bottom-right

| | Orientation | orientation |

1. Rotation degrees
(0, 90, 180, 270)

| | Licence Check | licenceCheck | | | Current Geo Location | currentGeoLocation | | | Make a HTTP request | http |

1. URL
2. Content Type
3. Details (JSON)
method
body

| | Configure Wifi | wifi |

1. ssid
2. path
3. identity
4. password
5. domain
6. saveRoot (true/false, default: false)
7. rootCaFileName
8. rootCaAlgo (default: pkcs12)

| | Restart Wifi if disconnected | restartWifiIfDisconnected | | | Generic Command | Any unmatched code | | | Power off | poweroff | | | Panel off | displayoff | | | Panel on | displayon | | | Set picture property | picture\_property | picture value | {% hint style="warning" %} Not all player platforms support all types of command. {% endhint %} {% hint style="success" %} webOS and Tizen have a set of additional commands which if are used as Scheduled commands there is no requirement to set for the display profile. {% endhint %} See the Device Compatibility sheet for full information: [Device Compatibility](https://docs.google.com/spreadsheets/d/e/2PACX-1vRMlLA1A40YBipC4Vx8bEjoQflGNy0AKtXa2Uc7e2UlZGnTvN5Mut7aTfbU9-6uAPvoZI3cbAc3Xdsm/pubhtml) ### HTTP HTTP commands allow triggering or interacting with web based endpoints by defining pre-set commands to make HTTP calls to external services (such as a queue management counter or a sensor) to trigger Layout changes, durations of widgets or activate conditional content in real time. Commands can be triggered on demand via XMR, scheduled at specific dates/times or tied to an interactive touch or click action on a Layout. ### RS232 Commercial displays often have a serial interface for turning the monitor panel on and off. Xibo can use the RS232 Command helper to send these Commands by using the `rs232` prefix in the Command String. The format of the command is `rs232||`. The connection string should be provided in the following format on Windows: ``` ,,,,,, ``` **Please note:** If you need to send your Command in HEX format, you should specify the byte string in the Command String, for example: `7E 00 00 FF 00 00 00 00 00 00 00 00 00 00 00 00 00 FF` , this will be converted to a byte stream by the player. You will need to set the `HexSupport` element of the connection string to `1`. The connection string should be provided in the following format on Android: ``` ,,,,, ``` Each setting is represented by a corresponding number: ``` DATA_BITS_5 = 5; DATA_BITS_6 = 6; DATA_BITS_7 = 7; DATA_BITS_8 = 8; PARITY_NONE = 0; PARITY_ODD = 1; PARITY_EVEN = 2; PARITY_MARK = 3; PARITY_SPACE = 4; STOP_BITS_1 = 1; STOP_BITS_15 = 3; STOP_BITS_2 = 2; FLOW_CONTROL_OFF = 0; FLOW_CONTROL_RTS_CTS = 1; FLOW_CONTROL_DSR_DTR = 2; FLOW_CONTROL_XON_XOFF = 3; ``` The Command itself is a string which gets sent over RS232 using the connection details. ### Android Intent Android Display Profiles can use the `intent` helper to specify an intent that should be called when the Command executes. The format of the Command is `intent|||[]` . `[]` is an optional parameter available from **Android v2 R206** used to provide additional data to the Intent. This must be a JSON formatted string containing an array with at least one object. The object format is below and must be on one line. ```json { "name": "", "type": "", "value": } ``` For example, on some devices you can program the firmware to set on/off times. ``` [{ "name": "timeon", "type": "intArray", "value": [2018, 7, 28, 8, 40] }, { "name": "timeoff", "type": "intArray", "value": [2018, 7, 28, 21, 40] }] ``` This would be set on the command as: ``` intent|broadcast|activity|[{ "name": "timeon", "type": "intArray", "value": [2018, 7, 28, 8, 40] }, { "name": "timeoff", "type": "intArray", "value": [2018, 7, 28, 21, 40] }] ``` Commands containing an intent helper are only available on devices running the Android operating system. ## Adding Commands to the CMS 1. Go to **Commands** under the **Displays** section of the main CMS menu 2. Click the **Add Command** button 3. Give the Command a **Name** 4. Enter a **Code** (such as the command string) to easily identify 5. Use the Command drop down field and select **Free Text** 6. Enter a **Command String** 7. Click to **Save** ## Send Commands from the CMS 1. Navigate to **Displays** from the main CMS menu 2. Use the row menu for a Display and select **Send Command** 3. Use the drop down menu to select the command to use 4. Click to **Save** ## Schedule Commands from the CMS 1. Navigate to **Schedule** from the main CMS menu 2. Click the **Add Event** button 3. Use the Event Type drop down and select **Command** 4. Select the command to use from the list 5. Click **Next** and set the **Displays** 6. Click **Next** and set timings 7. Click **Finish** if no further actions (such as Repeats) are required Scheduled commands are executed once and only require a **Start** date and time. The Command can be executed up to 10 seconds after the time selected. ## Shell Command Widget Use the **Shell Command Widget** to run external Commands based on the Layouts activity. Shell Commands with a Command as their source act in the same fashion as normal shell commands. The Command is executed when the Widget is shown on the Layout. A Shell Command can also be a Command String with options for all Players provided. This allows Users to add Commands ‘ad-hoc’ for one-time use. ## HDMI-CEC HDMI-CEC is a bus that is implemented on nearly all new large-screen commercial displays that have HDMI connectors. This bus (which is physically connected within normal HDMI cables) supports control signals that can perform power-on, power off, volume adjusts, selection of video source and many of the features that are accessible via the remote control. It can also control most other hardware on the HDMI bus. {% hint style="warning" %} Xibo doesn’t provide a direct interface to HDMI-CEC as there are many different manufacturer specifications, however, it is possible to control HDMI-CEC via a batch file. {% endhint %} # User Management Xibo has different User types, each allowing a varying level of access across the CMS for efficient collaboration. Administrators are encouraged to assign **Users** to **User Groups** to determine what the Users should access within the CMS and share **Folders** with the User to control the interaction (View, Edit, Delete) of items contained within the Folder. ## How-to Video Creating Users {% embed url="" %} ## Creating Users Users are created and managed by clicking **Users** under the **Administration** section of the main CMS menu. * To add new Users, click on the **Add User** button * Use the drop down to select the User Type A **User** will only have access to the parts of the CMS assigned to the User Group they belong to as well as full editing rights to their own items and the ability to share those with other Users. Some Users may need additional access rights in order to perform the correct tasks, such as a **Group Admin**, who in addition to having access to the parts of the CMS as assigned to the User Group they belong to, they will also get access to all items of all Users belonging to the User Group. * Select from one of the pre-configured User Groups These groups already have appropriate Features set so that common functions match the described role or create your own User Groups which would could then be selected from here. Users are also assigned a dashboard which serves as a **Homepage**: * The **Status Dashboard** is a high level view for **Super Admin Users** which shows information relating to Library and Bandwidth usage as well as Display Activity. * The **Icon Dashboard** is the default **User** view and is intended as a launcher into other areas of the CMS. * The **Media Manager Dashboard** gives an overview of the status of Library Media in the CMS. * The **Playlist Dashboard** is only assigned to the **Playlist Dashboard User Group** which gives a restricted view of the CMS with a User only able to select specific Playlists to manage. To make changes to a Users default homepage, use the row menu and select **Edit**, use the drop down menu for **Homepage**. * Create a User Name and Password to share with the User for login credentials. * Select Folders which need to be shared with the User so that they can have access items they need to fulfil their role from the start. Set a default folder to act as a Home Folder for the User. ## Deleting Users Deleting a User is irreversible and will remove all their owned items including; Media, Layouts and Schedules, even if these items are being used by other Users in the system. **Reassign items** to another User to make them the new owner of all the items currently owned by the User you wish to delete. Alternatively, use the **Retired** checkbox at the bottom of the **Edit User** form so that the items remain in use in the CMS. {% hint style="danger" %} Please ensure that the default user account named `xibo_admin` / `cms_admin` is not modified or removed so that our helpdesk agents can assist you with your CMS as and when required. {% endhint %} ## Further Reading {% content-ref url="/pages/Wa4g7h5yxgefT5d9nV8w" %} [Folders](/configuration-and-organisation/configure_folders) {% endcontent-ref %} ## FAQs ***Is there a way to ensure Users change their password within the system?*** Edit a User from the row menu and select the Options tab to find the setting "Force Password Change." Users will be redirected to a page to reset their password, the next time they log in. ***I have a user who has lost access to their Google Authenticator app and has no access to email or any saved recovery codes?*** Edit the User from the row menu and use the checkbox to Reset Two Factor Authentication. The User can now set up two factor authentication from their User Profile. ***How can I add a User to a User Group?*** Use the row menu and select User Groups to manage group membership. # User Groups and Features User Groups make it easier to onboard new Users and manage system access. Users that belong to a group will inherit any Features that have been enabled for the User Group. ## How-to Video Creating User Groups {% embed url="" %} ## Creating User Groups User Groups are created and managed by clicking **User Groups** under the **Administration** section of the main CMS menu. Pre-configured groups are available which have been created to serve common functions within the CMS and have the required **Features** already enabled to allow Users to carry out their role. * To add a new group, click on the **Add User Group** button and complete the form fields. * **Save**. You can easily make a **Copy** of a User Group from the row menu and make changes to the **Feature** access to suit requirements without the need to create a new group from scratch! ## Members Users are added to a User Group by using the row menu: * Click **Members**. * Select which **Users** should belong to the selected User Group. * **Save**. ## Features **Features** control what a User can see and do within the CMS, by restricting pages and page functionality. When combined with **Share** options, View, Edit and Delete options for user items such as Folders, Media, Display Groups. These concepts ensure that only the relevant parts of the CMS are visible to Users with the appropriate level of User interaction applied. * Features are configured from the row menu for a **User** or **User Group** and are grouped into logical tabs. It is recommended to set the required feature access to user groups and add users to the group to inherit enabled Features for an easier and safer work flow with less room for error. If specific Users require further access then these can be assigned directly to the User. A `-` indicates that selected Features within that Feature Set have been enabled. * Use the arrow to expand the Feature Set to see all options available. A tick indicates that all Features within that set are enabled. {% hint style="warning" %} In order for a User to have the ability to Share items with other Users, the option "Allow Sharing capabilities for all User objects" within the User functions subset of User Features needs to be enabled. {% endhint %} ## Further Reading {% content-ref url="/pages/Wa4g7h5yxgefT5d9nV8w" %} [Folders](/configuration-and-organisation/configure_folders) {% endcontent-ref %} ### FAQs ***If a User belongs to the Display Manager User Group why can't they add and authorise new Displays?*** This is deemed a high level Administration function. An Admin can add new Displays to a Folder and give access rights to that Folder for the Display Manager Group to manage. ***Can a User only belong to one User Group?*** Users can be assigned to one or more User Groups for ease of sharing and collaboration. # CMS Administrator Settings Once your CMS is installed, there is some additional set up required to enable all functionality. Please see the following guidance: [CMS Post Installation Set up](/setup-docs/cms-installation/cms-post-installation-set-up) The Xibo CMS comes with a number of configurable options. These are located from the **Settings** page under the **Administration** section of the main CMS menu. {% hint style="success" icon="cloud-check" %} **Xibo Cloud** hosted customers will have some of these fields pre-populated as part of the service. Some can be changed with others locked to disable editing. For further information please refer to this page: [Xibo Cloud CMS Defaults and Restrictions](/setup-docs/cms-installation/cloud-hosted-cms/xibo-cloud-cms-defaults-and-restrictions). {% endhint %} Settings are split into related categories: ![CMS Settings](https://2811002782-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fj0uXhtBdyPyW40TfKTZd%2Fuploads%2Fgit-blob-0bf2c705050f7f0ecb87b9a4f3f387fa69d13ba0%2Fv4.5_configuration_cms_settings_admin.png?alt=media) ## Configuration From here, view the **CMS Secret Key** which is used to authenticate Players with the CMS and apply a **Theme** to pages (if applicable) as well as setting the default positioning for the **Navigation Menu**. Use this tab to apply defaults to all Media files and set default Transitions. {% hint style="success" %} You can also set Layouts to **automatically Publish** 30 minutes after the last recorded edit by enabling the checkbox for this setting. {% endhint %} ### Resizing Images Default thresholds and limits can be specified which are then considered in the event an image should be resized. This could be when uploading an image or an image being downloaded by a Widget - NASA RSS in a Ticker Widget for example. * #### Resize Threshold Set a maximum threshold (based on the longest side) that should be considered for resizing an image. {% hint style="info" %} If you set a Resize Threshold of 1920 and you upload/download an image which is 800, this image would not need resizing. If you uploaded/downloaded an image which was 2400, this would then be resized to 1920. {% endhint %} * #### Resize Limit Set a limit (based on the longest side) for uploaded/downloaded images. Images that exceed this limit will not be processed and should be replaced with another image that is within the limit. This setting will determine whether the image file is too large to be processed. * #### DataSet maximum number of Rows Set the maximum permitted number of rows a User can create in a DataSet. {% hint style="warning" icon="cloud-check" %} The default for Cloud customers is set at 10,000 rows per DataSet. {% endhint %} ## **Displays** Set defaults for **Latitude** and **Longitude** for all Geo aware previews throughout the CMS. ### Default Layout The Default Layout set here will be automatically assigned to all Displays to be shown when no other content is scheduled or if there is an issue which prevents a scheduled Event from being shown. {% hint style="info" %} You can create your own Layout to replace the pre-set default, but keep in mind that designs should be kept simple with no complex media or web content. {% endhint %} This global Default Layout can be overridden for individual Displays by selecting an alternative Default Layout to be used. ### Proof of Play Default Settings Set the **Aggregation level** of collection of Proof of Play statistics to be applied to all **Layouts** / **Media** and **Widget items** as default. * **Individual** - statistics are recorded at the start and finish of each item individually and sent back to the CMS at each collection interval. * **Hourly** - records each item once, and includes the total number of times played and the length of time played during the hour and is sent back to the CMS on the next collection interval after the hour period has expired. * **Daily** - records each item once, and includes the total number of times played and the length of time played during the day and is sent back to the CMS on the next collection interval after the day has expired. {% hint style="warning" %} Players aggregate ‘completed records’ only, with collection made at the end of the Widgets duration so if a Widget has a duration of 3 hours, the stat will be recorded once the Widget has expired! {% endhint %} * Use this box to **enable the collection** of Proof of Play statistics to all **Displays** as default. {% hint style="success" %} This can be toggled on/off by editing Display Setting Profiles. {% endhint %} * Tick the box to set the default to on for the collection of Proof of Play statistics for all newly added **Layouts**. {% hint style="success" %} Collection can be disabled by unticking the box on the **Add/Edit** Layout form. {% endhint %} Use the settings to enable the collection of Proof of Play statistics to apply to all **Media**, **Playlist** and **Widgets** (Off/On/Inherit). {% hint style="warning" %} It is intended to have **Widget** always set to Inherit so that Layout and Media options control the collection! {% endhint %} ## General View/set the address for the **User Manual** and tick to send **anonymous statistics** to help improve the software. ### Tidy Library (Global) The Library can be *tidied* by a Super Administrator or User so that it is kept clean and small. **Actions cannot be reversed so this must be used with caution.** {% hint style="info" %} This might be of particular interest if the CMS is installed on a web server that has quotas or if Users have been assigned their own quotas. {% endhint %} Administrators can initiate a system-wide Library tidy operation by clicking the **Tidy Library** button in the right hand corner of the Settings page: As this functionality is system-wide and therefore operates on **ALL** User files, confirmation is required to remove unused and old revisions. This option is more comprehensive and removes: * Temporary files * Orphaned files * Thumbnails * Media revisions that aren't used anywhere * Media that isn't used anywhere (on any Layouts / Display Groups / Displays) * Generic files uploaded to the CMS #### Orphaned files Orphaned files are a rare occurrence where a file stored on disk in the Library folder is not deleted when the Media item is deleted from the Library. This means that the file exists but the CMS doesn't know anything about it. ### Tidy from User Library {% hint style="danger" icon="cloud-check" %} The Tidy Library function is turned off by default for **Xibo Cloud Hosting** customers as it can be potentially destructive if the options are not fully understood. {% endhint %} Allow a User to tidy files from the [Library](https://github.com/xibosignage/xibo-manual/tree/master/source/en/media_library.html#content-tidy-library) page by using the checkbox to **Enable Library Tidy**. ## Maintenance From here **Enable Maintenance** and **Email Alerts** to be sent and set the maximum retention ages for **Logs** and **Statistics**. ## Network From the Network tab complete an **Admin email address** for the overall CMS administrator. All email notifications generated by the CMS will be sent to this address. Ensure that the **Sending email address** and **name** is completed prior to setting up any further email notifications throughout the CMS. {% hint style="info" icon="cloud-xmark" %} You can also provide Proxy Server information (if your CMS is behind a proxy) force **HTTPS** and set monthly **Bandwidth** and **Library** size limits. {% endhint %} ## Sharing Use the dropdown to change how Widget colour appears in Playlists for Users. * **Media Colouring** will use the colours from the **theme** for each Widget. * **Sharing Colouring** will show the Widget colour based on **User access** from **Sharing** options. (Green = editable) From here you can set if Users should have the ability to schedule to Displays when Share options are set to View for the User as well as being able to set whether Users should be able to see the names of Layouts in schedules that have not been shared with them. Tick to allow Users to save their content into the top level Root Folder or disable to force Users to select a Folder to save to. ## Regional From this tab set the **Language** and default **Timezone** and **Date Format** to use across the CMS. {% hint style="success" %} Select the nearest major city in your timezone! {% endhint %} Use the checkbox to detect the **browser language** to use for the CMS and select which type of **Calendar** should be used. ## Troubleshooting This tab is used to to set Log Levels which are useful for capturing php errors and environment issues. ## Users Select the System User and set the Default User Group and User Type when onboarding new Users. {% hint style="success" %} We recommend that the **Default User Type** is set to **User**! {% endhint %} ### Password Policy Enter any valid regular expression in the **Password Policy Regular Expression** field so all password change requests and newly created passwords are tested against this. {% hint style="success" %} A text description will be shown to Users when their passwords do not meet the required policy as a prompt! {% endhint %} {% hint style="warning" icon="cloud-check" %} Customers with Xibo Cloud Hosting have a **set default policy** which requires a password of at least 10 characters. {% endhint %} ### Password Reminder Enable to provide a **Forgotten your Password** reset link for **Users** at login so they can easily regain access to the CMS. {% hint style="danger" %} Ensure that a valid **Sending email address** has been entered on the **Network** tab before enabling this functionality! {% endhint %} The User will be shown a link which once clicked will send a **Password Reset Notification** to their email address as recorded on their User Profile. {% hint style="success" %} **Users** can also change their own passwords, once logged into the CMS, from their **User Profile**. {% endhint %} ## Two Factor Authentication Two Factor Authentication can be set by a User for added security once logged in. Once configured, a User would need to enter the code sent via email or as displayed in the Google Authenticator app to complete login to gain access to the CMS. {% hint style="warning" %} Ensure that an Email address has been provided by the user to receive the generated email! {% endhint %} Set a valid **Sending email address** has been entered on the **Network** tab and a name has been entered in the **Two Factor Issuer** field to make it clear on the Google Authenticator app and email when authenticated codes are generated for login to the CMS. Reset Two Factor Authentication for Users from their User Profile. ## Applications Xibo contains an API that allows 3rd party applications to connect and consume its data. Applications are added and configured from **Applications** under the **Administration** section of the main CMS menu. {% hint style="warning" %} Before using an Application, each User must authorise the application to act on their behalf within the CMS. Users can view authorised Applications from the My Applications section of their **User Profile**. {% endhint %} At the current time the CMS does not provide individual Users with a method of revoking access to an application. Only an Administrator can remove an application completely. ## Fonts Xibo comes with a set of standard fonts which can be set on many Widgets: * Aileron Heavy Regular (Aileron-Heavy.otf) * Aileron Regular (Aileron-Regular.otf) * Dancing Script Regular (DancingScript-Regular.ttf) * Railway Regular (Railway.ttf) * Linear Regular (linear-by-braydon-fuller.otf) {% hint style="warning" %} It is possible to set a custom font on many Widgets, either via a property called **Font Family** or via the visual editor **Font** select list. If a font is not chosen the Player will show its own default "sans-serif" font, referred to as the system font. E.g. on Android this is usually Roboto.\ We recommend always choosing a font where available to avoid Players showing differing fonts. {% endhint %} Manage from the **Fonts** page under the **Administration** section of the main CMS menu. * Use the row menu to view a Fonts **Details** and see an example of the font style: Additional fonts can be added by clicking the **Upload Font** button and using the file uploader tool. {% hint style="warning" %} If the new font does not show in the text editor after upload, try clearing the browser cache! {% endhint %} Fonts have preferences built into them known as **OS/2 tags**. Xibo checks for OS/2 preferences and can use **fonts with OS/2 tags 0 or 8**. {% hint style="danger" %} Fonts with other OS/2 tags may produce an error on uploading and may not display correctly. {% endhint %} # Tags Tags are used throughout the CMS in order to easily organise and categorise items to make it easier for Users to locate and use. Tags act as keywords or labels which when assigned to items enhances the search functionality for Users. ## How-to Video Managing Tags {% embed url="" %} Tags can be created by Users from various forms throughout the CMS, as well as created and managed by Administrators from the Tags page under the Administration section of the main CMS menu. Create and assign **Tags** to items throughout the CMS using the Tag field on forms. As text is entered, an auto-complete helper will show possible matches to make it easier for Users to see what Tags are already available to select from: * Select a **Tag** from the list or create a new one by directly typing in the Tag field. Tags can also be be created by Administrators from the **Tags** page under the **Administration** section of the main CMS menu. * Click the **Add Tag** button and give it a **Name**. Tags can optionally have Tag Values associated with them. For example, you could have a Reception Tag, with reception areas across multiple sites. These could be differentiated using Values by creating a comma separated string of numbers, 1,2,3. The **Required Value** checkbox is used to ensure that a User ***must*** select a Value in order to successfully assign the Tag to the item. Once enabled, when the Tag is selected by Users, any associated Values will be shown for selection. A warning message will be shown to Users who do not select a Value to prompt them to do so. Users can also add associated Values to Tags using the **Tag Value** field in forms. Administrators can view all **System Tags** from the Tag management page and view Usage reports using the row menu for each individual Tag. Select multiple tags using the checkbox in the grid and delete in bulk. ## FAQs *Can I use filter options to exclude Tags from searches?* * Enter `-Tag` to exclude the tag from search results. * Enter `-|Value` to exclude the value from search results. * Enter `-Tag|Value` to exclude both tag and value from search results. You can have a comma separated mix of all the above! * If you want to show all items that have **not** got a tag then enter `--no-tag` # Folders Folders are used throughout the CMS and provide a great way to organise and easily locate user items within the CMS. Folders can have view, edit, delete sharing options applied which will apply to all items saved to the Folder, making it an efficient way to control User/User Group permissions for User items. Administrators are encouraged to assign User Groups to their Users, and then use Folder Share options to give these Users appropriate access to each other's content. Folders can be assigned to new Users from the on-boarding wizard to ensure that they are up and running from the start. Folders are managed from the Administration section of the main CMS menu where administrators can see detailed information including who the Folder has been shared with and a breakdown of its contents. ## How-to Video Managing Folders {% embed url="" %} ### Creating Folders Only administrators can create **Folders** under the **Root Folder**. * Right click the **Root Folder** and select **New Folder** to add a new Folder to the tree. * Further options are available from the context menu by right clicking a Folder. * Configure View, Edit and Delete **Share** options to apply to Users/User Groups for individual Folders. Once set, all items contained or moved to that Folder will inherit the applied options. {% hint style="warning" %} Only Administrators can set Share options for Folders. All elements of an item that need to be shared should also be moved to the Folder. This includes Media files contained on Layouts, and Layouts within Campaigns, as an example, if Users also require access to those. {% endhint %} Users can be granted access via the **Feature** functionality, to create sub-folders under parent folders they have been given access to. Sub-Folders added to a Folder will inherit any applied Share options from the Main Folder. ### Home Folder Assign a Home Folder to existing Users: * Go to **Users** under the **Administration** section of the main CMS menu. * Use the row menu and select **Set Home Folder**. * Select a Folder to use, or right click to create a new Folder. {% hint style="warning" %} If you want Group Administrator to have the ability to set Home Folder for Users, ensure that they have the appropriate **Feature** enabled! {% endhint %} If a Folder is not selected, new content will automatically save into a Users default Home Folder location. ### Force Saving to a Folder Administrators can prevent Users from saving into the Root Folder and instead force them to select a Folder before saving by disabling the user of the Root Folder as a default: * Navigate to **Settings** under the **Administration** section of the main CMS menu. * Click on the **Sharing** tab. * Untick **Allow saving in the root folder** option. * Click the **Save** button at the bottom. Once configured a User ***must*** select a named Folder. ### Move Folder Folders can be moved to another Folder location and added as a Sub-Folder using the **Move Folder** option from the context menu for a Folder. The Folder and any contained sub-folders will be moved as a new sub-folder within the new Folder location maintaining the original Folder structure. Moving a Folder that does not have any Share options set, will inherit any applied **Share** options of the destination Folder. You can also select the **Merge** option to add the original Folder contents to the selected location, with the original Folder being deleted from the Folder tree. ## Folder Management Administrators can view, create and manage all Folders of the CMS from the Folders page under the Administration section of the main CMS menu. This management page will show the Folders that have been shared with Users as well as folder contents. When viewing sub-folders from here, only the directly assigned share options will be shown, inherited options will not be shown. As only empty folders can be removed, move, merge or delete contents before removing the folder. ## FAQs ***Where can I find the Feature set for Folders to configure for Users/User Groups?*** Features are applied to a User/User Group by using the row menu for a selected User/User Group. ***What steps should I take take to allow Users the ability to Create their own Folders?*** 1. Enable **Allow users to create Sub-Folders....** from the Content tab of the **Folders Feature** set. 2. Enable **View** from the **Share options** for the parent folders(s) that can have sub-folders created under them by the User/User Group. ***What steps should I take to allow Users access to rename Folders within the menu?*** 1. Enable **Rename and Delete existing folders** from the Content tab on the **Folders Feature** set. 2. Enable **Edit** from the **Share options** for the folder(s) that can be renamed by the User/User Group. ***What steps should I take to allow Users access to delete Folders from the menu?*** 1. Enable **Rename and Delete existing Folders** from the Content tab on the **Folders Feature** set. 2. Enable **Delete** from the **Share options** for the folder(s) that can be removed by the User/User Group # Transition Management Transitions are managed from the **Transitions** page under the **Administration** section of the main CMS menu. Configure which Transitions should be available to Users for assignment to Media items: ![Transitions Grid](https://2811002782-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fj0uXhtBdyPyW40TfKTZd%2Fuploads%2Fgit-blob-7645ddaacd1e812ae42a8676df135a5f1e6a3993%2Fv4.5_configuration_transitions_grid.png?alt=media) * **Fade In** - Increase Opacity from 0 to 100. * **Fade Out** - Decrease Opacity from 100 to 0. * **Fly** - Fly in or out on a compass point. ## Transition Defaults {% hint style="success" %} Global default settings can be set for Transitions by Administrators from the CMS Settings page. {% endhint %} Default Transitions can be easily enabled for all Widgets added to a Layout by ticking the **Automatically apply Transitions?** box from the Layout property panel: ![Transitions Layout](https://2811002782-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fj0uXhtBdyPyW40TfKTZd%2Fuploads%2Fgit-blob-a8d20f6d4a5ff00a9cf40355d2d968acb4a29207%2Fv4_tour_transitions_layout.png?alt=media) **NOTE:** When Transition Defaults have been applied, the Widget Transition fields will show as blank entries: ![Transitions Widget](https://2811002782-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fj0uXhtBdyPyW40TfKTZd%2Fuploads%2Fgit-blob-8b2e7c0d021fa5b1aee28dbb1abd8be7665a8555%2Fv4_tour_transitions_widget.png?alt=media) This is because only **manually** entered Transitions for a Widget will be shown in the form fields. ## Playlist Transitions These are the Transitions between **Media items** on a Playlist and are set as **In** and **Out** transitions. {% hint style="info" %} The Transition form adapts depending on the Transition selected and the options available for that transition. In most cases it is necessary to select a duration for the Transition in Milliseconds and in the case of Fly, a direction must also be selected. {% endhint %} ## Playlist Exit Transition A Playlist Exit Transition happens when the last Media Item to be displayed on a Playlist is shown and allows for a different Exit Transition to be set. # User Support All of our plans include access to our support desk by opening a ticket via My Account. To get the best support from our help desk ensure that you provide the specific information, listed below with your support request: * The version of the software that you are using * Version and type of Players that you are using * Detailed description of the issue you are experiencing * The exact steps to take so that the issue can be recreated by our team in order to troubleshoot * Screenshots of any error messages/codes {% content-ref url="/spaces/OD5P6BGYveuzkbhjZRsq/pages/DpcgDGZ3nEk3ej8RBDSk" %} [Request Player Status](/setup-docs/troubleshooting/request-player-status) {% endcontent-ref %} {% content-ref url="/spaces/OD5P6BGYveuzkbhjZRsq/pages/RDW3wiKvmDhzS6B1mR7f" %} [Troubleshooting](/setup-docs/troubleshooting/cms-error-logs) {% endcontent-ref %} # Setup Documentation View Xibo CMS recommended setup and configuration for cloud hosted and self hosted digital signage deployments. Use these resources to setup, configure, and manage Xibo software. The documentation covers the core tasks for Xibo digital signage deployments. Start here if you need Xibo CMS installation guidance, configuration help, or deployment options. ### Get Started * Install a Xibo Cloud hosted CMS or self host * Connect media players to your Xibo CMS * Configure to suit your deployment #### Choose your installation path * [Xibo Cloud Hosted CMS](/setup-docs/cms-installation/cloud-hosted-cms)— use a managed Xibo CMS service * [Self hosted CMS](/setup-docs/cms-installation/self-hosted-cms)— deploy Xibo CMS with Docker on your own infrastructure
#### Install the Player App * [Installing and Upgrading the Player App](/setup-docs/player-app-installation-and-upgrades/player-app-installation-and-version-upgrades)
How many media Players can I connect to Xibo? Xibo itself doesn’t impose a hard limit on the number of media players that can connect to a single CMS. We know of production instances of Xibo running many hundreds of media players against a single server. The limitations come from the hardware you choose to deploy your CMS on. Asking what hardware is required is a little like asking how long the proverbial piece of string is. Everyone’s display workloads are very different depending on the frequency and content of the media updates made to the layouts the CMS is hosting, the frequency with which "Displays" connect to the CMS and how aggressively media items such as RSS feeds are set to be cached. For most small to medium deployments, quite modest server hardware should be sufficient. For larger deployments, take the time to simulate some production workloads and then scale out from there to work out the resources you’ll need to service your media players.
# Supported Versions and Environments Xibo can be deployed on Xibo Cloud Hosting or self-hosted in a Docker environment ## CMS Releases The current stable version and previous major release are both supported, details shown below. | Version | Status | Release Updates | Xibo Cloud Hosting | | ------- | ------------------ | ---------------------------- | ------------------ | | **4.5** | **Stable** | **Maintenance** | **Current** | | 4.4 | End of Life | No further updates | Existing Supported | | 4.3 | End of Life | No further updates | Existing Supported | | 4.2 | End of Life | No further updates | Existing Supported | | 4.1 | End of Life | No further updates | Existing Supported | | 4.0 | End of Life | No further updates | Existing Supported | | 3.3 | Existing Supported | Critical Xibo security fixes | Existing Supported | {% hint style="warning" %} CMS versions earlier than 3.3 are all End of Life with no further updates or support. 3.3 does not receive updates to PHP or other dependencies. {% endhint %} {% hint style="success" %} We strongly recommend installing/upgrading to the **Current** CMS release to take full advantage of latest features, improvements, bug fixes and the latest security updates. {% endhint %} {% hint style="danger" %} Customers who choose to self-host their CMS, do so with the knowledge that helpdesk support is not provided. {% endhint %} {% hint style="success" %} Customers who choose to host their CMS with us or add their self-hosted CMS to our Enterprise Plan are subject to Supported Environments, as outlined below to access helpdesk support to open tickets regarding your CMS or Players (provided that they are a supported version). {% endhint %} ## Player Releases Our general recommendation is that your CMS and Players should be of the same major version for best results. For example a version 4 Player with a version 4.x CMS. The current stable Player version is supported and recommended, and support is offered for the most recent previous major Player version too. Anything outside of that is unsupported and you will need to upgrade to a supported version to access support. ### Windows | Major Version | Status | Release Updates | Required OS | Recommended OS | | ------------- | ----------- | ------------------------ | ----------------------------------- | ------------------------------------------- | | 4 | Current | Features and Maintenance | Windows 10 or later | Windows 10 Professional build 1909 or later | | 3 | Supported | Security | Windows 10 or later | Windows 10 Professional build 1909 or later | | 2 | End of Life | No further updates | Windows 7 or later (up to v2 R203 ) | Windows 10 Professional build 1909 or later | | 1 | End of Life | No further updates | | | Not compatible with ARM-based CPUs ### Linux | Major Version | Status | Release Updates | Required OS | Recommended OS | | ------------- | ------- | ------------------------ | ----------------------------------------------------------- | ----------------------------------------------------------- | | 4 | Current | Features and Maintenance | 64 bit Linux supporting the Snapcraft distribution platform | 64 bit Linux supporting the Snapcraft distribution platform | 64 bit AMD/Intel CPU required. Not compatible with 32 bit or ARM based CPUs ### Android | Major Version | Status | Release Updates | Required OS | Recommended OS | | ------------- | ----------- | ------------------------ | ----------- | -------------------- | | 4 | Current | Features and Maintenance | Android 7 | Android 9 or later | | 3 | Supported | Security | Android 6 | Android 7.1 or later | | 2 | End of Life | No further updates | Android 4.4 | Android 7.1 or later | | 1 | End of Life | No further updates | Android 4.4 | Android 7.1 or later | ### webOS | Major Versions | Status | Release Updates | Required OS | | -------------- | ----------- | ------------------------ | ------------------ | | 4 | Current | Features and Maintenance | webOS 3.2 or later | | 3 | Supported | Security | webOS 3.0 or later | | 2 | End of Life | No further updates | webOS 3.0 or later | | 1 | End of Life | No further updates | webOS 3.0 or later | ### Tizen | Major Versions | Status | Release Updates | Required OS | | -------------- | ----------- | ------------------------ | --------------------------------------- | | 4 | Current | Features and Maintenance | Samsung signage monitors SSSP6 or later | | 3 | Supported | Security | Samsung signage monitors SSSP5 or later | | 2 | End of Life | No further updates | Samsung signage monitors SSSP5 or later | | 1 | End of Life | No further updates | Samsung signage monitors SSSP5 or later | ### ChromeOS | Major Versions | Status | Release Updates | | -------------- | ------- | ------------------------ | | 4 | Current | Features and Maintenance | ## Supported Environments The following lists the recommended environment that is required for a self-hosted CMS to be included and supported as part of an Enterprise Plan, or to be covered under a legacy Enterprise Support Contract, or for the Xibo team to offer paid per-incident support via the Helpdesk. Should you choose to install the Xibo CMS outside of this supported configuration, support is not included. ### **Supportable Configuration** * Ubuntu Server 64 bit running on an x86-64 architecture CPU - any current LTS release (24.04, 26.04) or the Debian equivalent * Minimum 4GB RAM. * Minimum 20GB free storage space (SSD/NVMe ideally), plus however much storage you will need to upload your content to the CMS, and to store any logs and proof of play data you might want to collect. * Access to the server running the CMS via SSH/HTTPS or TeamViewer, or TeamViewer access to a workstation with SSH/HTTPS access to the CMS. Access must be possible as the user `root` or as a user with full `sudo` permissions to become `root`. * Server must have access to the Internet to download the provided container images. * Installation with Docker using the docker-compose files we provide for the CMS installation * Optionally (but recommended) an nginx or Apache reverse proxy infront of the CMS handling TLS termination * One each of a cms-web, one cms-db, one cms-xmr container, and with memcached enabled * No modifications to the contents of the provided containers * Any white labelling must be applied by the use of a theme. We reserve the right to temporarily disable the theme to see if a custom theme is the cause of any issues with the CMS * Any custom code must be in the form of a separate custom module or middleware. We reserve the right to temporarily disable any custom code to see if it is the cause of any issues with the CMS. Any custom code falls outside the scope of support. ## Helpdesk Support Helpdesk support is for the installation, configuration and licensing of our Commercial Players (Android, webOS, Tizen and ChromeOS) only, except where Players are connected to a Xibo Cloud Hosted CMS, or a self-hosted CMS covered on the Enterprise Plan, or under a legacy Support Contract. Customers with Perpetual Player licenses may need to purchase upgrades and upgrade their Player version to be able to access Helpdesk support. # Make the most out of your Xibo Trial! Take a free 14 day trial of the CMS and Player App so that features and functionality can be fully tested from uploading media and creating content to scheduling to show content on your test Displays. ## Sign up Click on a **Free Trial** button from the website and create an account or login: ![Trial signup form](https://2149703612-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOD5P6BGYveuzkbhjZRsq%2Fuploads%2FYzRQkf9ge5lNQdzsYLeX%2Ftrial_sign_up.png?alt=media\&token=8e7eb575-c721-454d-abc3-078e45b32ad2) 1. Complete the form as these are required to create your trial CMS instance and click the **Start Trial** button. 2. Next, activate your **Xibo Account** by clicking the link included in the Welcome email, sent to the email address provided. 3. Once activated, go to **My Account** to check the status of your CMS by clicking the **In Progress** button. 4. Once your CMS is ready, your **CMS login** information will be shown. ## Testing the CMS Follow the steps below to see the features and functionality the Xibo CMS has to offer. If you don’t intend to trial a Player App, you can still take a look at the scheduling capabilities of Xibo by creating a test **Display Group**, to view scheduled events in Schedule Lists and Calendar views: 1. Click on **Display Groups** under the **Display** section of the main CMS menu 2. Click the **Add Display Group** button 3. **Name** your Display Group (Test for example) 4. **Save** ### Uploading an Image If you have content created outside of the Xibo CMS, by an outside agency for example. Xibo allows you to easily upload and show on your display screens. Directly upload Image and Video files to the media Library and schedule to play full screen on Displays. {% embed url="" %} * Click on **Media** under the **Library** section of the main CMS menu. * Select the **Add Media** button. * Click **Add Files** and select the image file to upload. * Rename or leave as the default file name on upload. * Click **Start Upload**. * Select **Done**. The uploaded Image will now show in your Library. From here you can **Schedule** directly to your Displays, using the row menu: * Select **Schedule** from the row menu. * Select your **Test Display Group**. * Click **Finish**. By following these steps, you will have successfully uploaded an image and scheduled it to play on your test Display at all times as an Always (which is set as the default) schedule. See the **Showing an Image on Displays** page for more information and to view further reading links. [Showing an Image on Displays](https://account.xibosignage.com/manual/en/getting_started_showing_an_image) ### Create a Playlist You may need to show multiple items in rotation, a slideshow of images to showcase certain products for example. Playlists contain multiple items which when scheduled to play on Displays will show a carousel of content. {% embed url="" %} 1. Click on **Playlists** under the **Library** section of the main CMS menu 2. Select the **Add Playlist** button 3. Provide a **Name** 4. On saving the **Playlist Editor** will open to add content 5. Use the **Toolbox**, located on the left hand side of the designer, and click on **Library image search** to add Images from the CMS Library 6. Drag and drop images to add to the **Timeline** 7. You can drag and drop **Upload Image** to the timeline to add more images to your Library to use 8. Click on **Pixabay** from the Toolbox to add images directly from Pixabay’s library 9. Re-order the sequence by drag and drop 10. Click **Exit** The created Playlist will now show in the Playlists grid. From here you can **Schedule** directly to your Displays, using the row menu: 1. Select **Schedule** from the row menu 2. Select your **Test Display Group** 3. Click **Finish** By following these steps, you will have successfully created a Playlist and scheduled it to play on your test Display at all times as an Always (which is set as the default) schedule. See the **Showing a Playlist on Displays** page for more information and to view further reading links. [Showing a Playlist on Displays](https://account.xibosignage.com/manual/en/getting_started_showing_a_playlist) ### Create your own content using the Xibo Layout Editor Create your own content to show on Displays from inside the Xibo CMS. The Layout Editor is at the heart of content creation in the Xibo CMS. With a variety of features, users can easily create eye-catching designs to show on their Displays. {% embed url="" %} 1. Click on **Layouts** under the **Design** section of the main CMS menu 2. Select the **Add Layout** button 3. If you want to give your Layout a **Name** now, click on the “**Untitled**…” text shown in the top left of the Layout Editor 4. Using the **Toolbox** to the left of the Layout Editor, click on **Search for Templates available from the Xibo Exchange** 5. Select a template using the filters and drag and drop to the canvas 6. Click in elements of the template to open available options from the **Properties Panel** to customise and re-style the appearance 7. Once happy with your design, click on the three line **Options** menu at the top right of the Layout Editor (next to the alarm bell icon) 8. Select **Publish** 9. Keep **Publish Now** ticked and click the **Publish** button Once the Layout is Published it will be locked for editing and can be scheduled to Displays: 1. Return to the **Options** menu 2. Select **Schedule** 3. Select your **Test Display Group** 4. Click **Next** 5. From **Dayparting** select **Custom** 6. Tick **Use Relative** 7. Enter **2** Hours 8. Click **Finish** Following these steps, you will have successfully created a Layout utilising a pre-designed template, published and scheduled to play for 2 hours on your test Display. The Layout Editor has many features which allow you to create your own designs from scratch. Take a look at the **Layout Editor Overview** page for more information and to view further reading links. [Layout Editor Overview](https://account.xibosignage.com/manual/en/layouts_editor) ### Schedule All content to be shown on Displays needs to be included in a schedule. {% embed url="" %} Created schedules can be viewed as a list or in the form of icons: 1. Click on **Schedule** from the main CMS menu 2. Using the filters, select the **Test Display Group** created for the trial 3. The **Grid** tab will show a detailed list of created events 4. Use the row menu and click **Edit** to re-open schedule options 5. The **Calendar** tab will show schedule events represented as icons, which when clicked will re-open schedule options See the **Simple Scheduling** page for more information on creating schedules. [Simple Scheduling](https://account.xibosignage.com/manual/en/simple_scheduling) ## Further Guidance The User Manual contains further guidance on all available CMS features. Visit our Training page to access a collection of helpful training videos to assist new users in getting started. [User Manual](https://xibosignage.com/manual/en/) [Training for new users](https://xibosignage.com/training) ## Convert your trial You can convert to a paid plan at any point during your trial via My Account. If after the 14 day trial you do not wish to continue, your Xibo Account will be automatically deleted from our system after 30 days. ### Testing beyond the 14 day trial period… For the majority of users this time frame gives ample time to trial all of Xibo’s functionality, but we do understand that this may not be the case for all users. If you feel like you need more time to assess Xibo for your organisation then please contact our Sales team who will be happy to assist you further. ## Want to trial a Player Application with the CMS? If you want to see content on your Displays to fully test the CMS and Player App capabilities combined, **Download** the Player App you would like to trial and use the installation quick start guide link for your chosen Player, from the **Player Comparison** table and follow the steps: 1. **Prepare** device (if applicable) 2. **Download** Player Software 3. **Install** Player Software 4. **Connect** to the CMS 5. **Authorise** your Display {% hint style="warning" %} Leave the field for **Code for Licence Pool** blank and click **Skip** to activate the 14 day player trial! {% endhint %} If you have set up a **Test Display Group**, add your new **Display** to this to start seeing scheduled content: 1. Click on **Display Groups** under the **Displays** section of the main CMS menu 2. Use the row menu for the **Test Display Group** and select **Members** 3. Use the plus icon to add **Displays** 4. Click to **Save** Your Display will now be added to the Test Display Group and inherit any schedules already created for this group. The trial includes support with our expert team so if you do experience any issues with installation and set up, please go to the **Tickets** section of **My Account** to open a ticket. ### Quick Links [Plans](https://xibosignage.com/pricing) [Downloads](https://xibosignage.com/downloads) [Player Comparison Table](https://docs.google.com/spreadsheets/d/e/2PACX-1vRMlLA1A40YBipC4Vx8bEjoQflGNy0AKtXa2Uc7e2UlZGnTvN5Mut7aTfbU9-6uAPvoZI3cbAc3Xdsm/pubhtml) # Xibo Cloud Hosted CMS Xibo Cloud Hosting gives you a professionally managed service direct from the Xibo project creators. Simply sign up for a plan and complete the required form fields to create your own private Xibo CMS ### Creating your Xibo Cloud CMS {% hint style="success" %} This information will be used to generate your Xibo URL, for example {% endhint %} 1. Choose a name for your instance 2. Choose a domain name 3. Select your Region {% hint style="success" %} The region closest to where you and your connected Displays will be located, will give the best performance! {% endhint %} The provisioning system will now get to work and set everything up in a matter of minutes. Once completed, view your CMS login information from the **My Plan** section from your dashboard in My Account. {% hint style="success" %} Access CMS login details by clicking the padlock icon! {% endhint %} All Xibo Cloud hosted CMS instances are backed up on a daily basis as part of the service provided. ### Connecting a Media Player Xibo supports a variety of Media Player hardware and Player Apps which can be mixed and matched as required. Installation guidance for all our recommended Media Players can be found at the following link: [Installing and Upgrading the Player](/setup-docs/player-app-installation-and-upgrades/player-app-installation-and-version-upgrades) # Xibo Cloud CMS Defaults and Restrictions Certain settings are pre-configured with Xibo Cloud hosting, some can be optionally changed whilst others are locked to prevent editing. ## **Default Settings** The following default settings can be optionally changed
CMS Password Policy The default **Password Policy** requires a password of at least 10 characters in length. Our view is that password policies that require certain levels of complexity are great, but that length is the single most important factor when choosing a secure password. * Change from the **Users** tab.
Force HTTPS connections to the CMS For a new CMS, all connections are required to be made over HTTPS, otherwise, they’re redirected. You can turn this off at your option, but please be aware it will make your access to the CMS less secure. * Disable from the **Network** tab.
Strict Transport Security Strict Transport Security forces browsers connecting to a website to connect only to the encrypted HTTPS version of the website for a fixed period of time, to prevent downgrade attacks on your connection. For a new CMS, we disable strict transport security by default as it can conflict with some older Player devices. You can turn this on at your option, and configure the time that the restriction should be in place for. * Enable from the **Network** tab from the **Settings** page.
Default CMS Email Send From address If you hold a CMS White Label theme, we change the default email address the CMS will send email to you based upon your preferences expressed when you created the theme. * Change from the **Network** tab from the **Settings** page.
Library Tidy The Library Tidy function is off by default. This can be potentially destructive if you don’t understand the implication of running it with all options selected. * Enable from the **General** tab from the **Settings** page.
Xibo Exchange Xibo Exchange templates are enabled by default. * Disable from the **Connectors** page from the main CMS menu.
Pixabay Pixabay integration is enabled by default. * Disable from the **Connectors** page from the main CMS menu.
## Restricted Settings In certain cases, our support team may be able to make adjustments on your behalf if there is a valid use case and it won't negatively impact the security or performance of our Cloud environment.
Periodic Screenshot This function can use very large amounts of bandwidth very quickly so is disabled.
Currently Playing Layout This setting generates a high number of requests to the Cloud platform and is designed to be used only in a LAN environment.
Proxy Settings No proxy is required to access the internet from the Cloud Platform. Player side proxy settings on devices can be configured as required to access our platform.
Dataset Size (Row Limit) We limit datasets to 10,000 rows per dataset.
Task Configuration The system task configuration is locked as these have been optimally configured for you. {% hint style="warning" %} The fetch remote DataSet task is run hourly by default. Remote DataSets are intended for data which updates infrequently and not real time. {% endhint %}
Modules We prevent the installation of your own third party modules with Xibo Cloud hosting.
XMR Configuration We pre-configure, lock and hide the XMR configuration as you don’t need to set that up yourself. * If you want to turn XMR off for one or more Players, you can do so at the **Display Profile** settings by entering **DISABLED** in to the XMR Public Address field.
File Download Mode and associated settings These settings are pre-configured for you to give the best performance.
System Limits We limit the number of Displays that can be authorised on the CMS, the size of the CMS library, and the total amount of bandwidth that can be consumed based upon what you have purchased.
Maximum File Upload Size This is fixed at 1999MB or 4GB.
Loadbalancer Whitelist We fix and hide the loadbalancer whitelist setting as there is no need to change this value on our Cloud Platform.
Log Retention We fix general system log retention at 4 days. Error messages etc are rarely useful after that time period. Old log messages are deleted.
Audit log Retention Audit log messages are automatically deleted according to plan limits.
Disable Import The database import function is disabled as this could be used to circumvent restrictions described in this article. If you would like to bring an existing database with you when moving to Xibo Cloud hosting, please discuss with our Support team so they can make the necessary arrangements.
Themes The theme settings are hidden in the CMS. On Cloud, you will use the standard Xibo theme unless you’ve purchased a CMS white label from us. In that case, we pre-configure the theme settings for you.
Library Directory The CMS library directory is pre-configured and cannot be modified.
API / XMDS Rate Limits To ensure that the Xibo Cloud hosting service remains performant for all our users, we do impose some basic rate limiting on your connections to the CMS. Where you interact with the CMS API, you may receive an error 429 if you exceed the rate limit. In that case, you should slow your overall request rate down.
# Self hosted CMS Docker is an application to package and run any application in a pre-configured container. This makes it much easier to deploy a Xibo CMS following the recommended configuration. Containers provided are for x86-64/AMD64 architecture only which are suitable for most servers: [Docker](https://docker.com/)​ ### Getting Started * You will need a Linux host machine * Docker must be installed and working ​[Install Docker docs ](https://docs.docker.com/engine/install/#server)​[Docker Compose READ ME](https://github.com/docker/compose#linux)​ #### Download and extract the Xibo Docker archive To install Xibo, you’ll need to be the `root` user in your command line shell by: * running sudo su * or logging in as root directly Download the latest Docker Installation: [Docker Installation Download](https://xibosignage.com/api/downloads/cms)​ The archive should be extracted in a suitable location on your host machine. We suggest `/opt/xibo`, your library content and database will be written under this folder.Please note that the archive already contains a sub-folder called `xibo-docker-n.n.n`, which is ‘best practice’ for archives.For the subsequent instructions, please make sure you are *inside* the sub-folder contained in the archive. #### Check and edit configuration The first time Xibo is installed, a configuration file is needed to tell Docker how the environment is configured. This file is called `config.env` This file covers where you want files to be stored, email config, etc. A template file with detailed instructions is provided in the release archive and is called `config.env.template` * Take a copy of this file, renaming it to `config.env` and then edit the file in a text editor, e.g. nano, gedit, etc. If you don’t want Xibo to have the ability to send email messages, then you can opt to not configure those options. Docker will map data folders to contain database data and any custom files for the CMS. These will appear by default in the folder containing the release archive in a shared sub-folder. #### Installing the CMS containers Once you’ve made your changes to `config.env` and have saved the file, open a terminal/command window in the folder where you extracted the archive. As a user who has permissions to run the docker command, run: ``` docker compose up -d ``` {% hint style="warning" %} You may experience a delay whilst the CMS finishes setting up after the command is run. {% endhint %} This will bootstrap and start your Xibo CMS. The CMS will be fully installed with the default credentials: * **Username**: xibo\_admin * **Password:** password Log in to the CMS and change the password on that account. You can log on to the CMS at `http://localhost`. {% hint style="warning" %} If you configured an alternative port number then be sure to add that to the URL, for example, `http://localhost:8080`. {% endhint %} #### Configuration adjustments If you are running an iptables based firewall on your computer you will need to allow the ports you’ve configured the CMS to run on inbound. If you haven’t specifically configured alternative ports, then the following is required: * Inbound TCP Port 9505 (for XMR Push Messaging) * Inbound TCP Port 80 (for HTTP Traffic) AND/OR * Inbound TCP Port 443 (for HTTPS Traffic - if you are using SSL) Docker installs come with XMR running automatically for you, and with most of the configuration in place. However, you do need to adjust a few settings, on first log in, as detailed below: #### XMR WebSocket Address The XMR web socket address of the CMS defaults to empty, which means players will try to connect to your CMS at `/xmr`. The Apache container provided will handle web socket requests at that URL, but if you run Xibo from a sub-folder, or wish to run XMR separately you should adjust the XMR web socket address to suit. We recommend including this address in your reverse proxy configuration so that it can handle SSL termination. #### XMR public address The XMR public address of the CMS is how any player which does not support web sockets will connect to XMR for push messaging. This only needs to be done on the first bootstrap: * Navigate to the **Settings** page under the **Administration** section of the CMS main menu and select the **Displays** tab. The XMR public Address field defaults to `tcp://cms.example.org:9505` which needs to be adjusted to be suitable for your network. The format of the address needs to be: `tcp://:` The default \ is 9505 and should be set to that unless you have specified a custom port in your docker-compose configuration. If your CMS is available by a DNS name - for example, if your CMS web page is available at [https://mydomain.com](https://mydomain.com/), then simply swap `cms.example.org` for `mydomain.com` . If your CMS is only available by an IP address, then enter the IP address instead. #### Reverse Proxy - HTTPS/SSL Xibo should be run over SSL if running on anything other than a secure private network. The Docker containers do not provide SSL and this must be provided by an external web server which handles SSL termination and reverse proxy into the `cms-web` container. There are many good resources for achieving this architecture, for example: [nginx-proxy container](https://github.com/jwilder/nginx-proxy) If you already have a web server running on your Host machine, configuring a reverse proxy should be straightforward. The CMS will need to be configured to trust your reverse proxy; add the reverse proxy IP to your `custom/settings-custom.php` file: ``` // Set to a single IP, CIDR or wildcard $trustedProxyIps = '10.0.0.5,172.18.0.0/16'; ``` ### Starting and Stopping Xibo Once the CMS containers have been initialised with `docker compose up -d`, it is possible to start and stop them without removing the underlying container. The stop command will stop the Xibo CMS services running. If you want to start them up again, issue the start command. ``` docker compose stop docker compose start ``` ### Uninstalling / removing The CMS installation and its associated containers can be completely removed by issuing the `down` command. Before running docker compose down, please be sure that your media and database files are being correctly written to the `shared` directory. To do so, upload for example an image into the CMS, and check that the same image appears in the `shared/cms/library` directory. Another good check is to make sure that `shared/backup/db/latest.tar.gz` was created within the last 24 hours. If either of those checks fail, please do not run `docker compose down` as this will lead to data loss. Seek support to resolve the situation. If your intention is to remove all traces of Xibo you may delete the `/opt/xibo` folder *after* running the `down` command. ``` docker compose down ``` ### Backing up your CMS/Database As with any system containing user data, it is vital to maintain regular backups of your Xibo CMS. Docker installations automatically take a daily database backup for you, as well as one as part of the upgrade routine. * As part of your backup plan, you should regularly take a backup of at least the following files/directories: ``` shared/backup/db/latest.sql.gz shared/cms config.env *.yml ``` ### Custom Scripts and Pages If you want to use the environment provided by Docker to run custom developments, themes, modules or standalone files you can do so using the /shared folders. The following locations are available: * `/shared/cms/custom` : Used for custom middleware * `/shared/cms/web/theme/custom` : Used for custom themes * `/shared/cms/web/userscripts` : Use for standalone files, will be served as `http://localhost/userscripts` ### Other shared folders Docker also makes the library and backup available as shared folders: * `/shared/backup` * `/shared/cms/library` ### Community Resources * [Xibo CMS with Docker on Ubuntu 22.04](https://community.xibo.org.uk/t/xibo-cms-with-docker-on-ubuntu-22-04/9392) * [Windows 10 64bit](https://community.xibo.org.uk/t/xibo-for-docker-on-windows-10-64-bit/16298) * [Windows 64bit, other than Windows 10](https://community.xibo.org.uk/t/xibo-for-docker-on-windows-64bit-other-than-windows-10/16300/2) # CMS Installation Service We provide an installation service for the Xibo CMS onto a VPS as included in our Enterprise Plan and also as an additional paid service. Customers who would like to take advantage of our **CMS Installation Service** must provide information regarding their on-premise environment, the server and operating system and whether it is accessible publicly over a VPN. A suitable VPS needs to be purchased for us to install Xibo onto for you. VPS offerings come in all different shapes and sizes. We have picked a few providers who have good global coverage and who we know work well with Xibo and our Docker-based installation.
DigitalOcean According to Wikipedia, DigitalOcean are the second largest hosting company in the world in terms of public facing computers. They host KVM-based virtual machines, which they call “Droplets”. If you’re looking to use DigitalOcean, then you’ll need a Droplet with at least 2GB of RAM. You should pick Ubuntu 26.04 LTS 64 bit server from the list of available operating systems. DigitalOcean will install the operating system for you, and then email you login credentials for your new server. You’ll need to pass these to us for us to perform the installation. You should enable the backup option on your Droplet so that DigitalOcean take regular backups of your data. Note however that these are whole-system backups. You may wish to investigate alternative backup software in addition. Note also that the system backups taken by DigitalOcean do not currently backup any Block Storage volumes. If you opt for Block Storage, then you will need to have an alternative backup strategy. If you wish, you can use the following referral link to get a free $10 USD credit when you sign up. The project also gets a small commission from that. [Sign up with DigitalOcean 2](http://www.digitalocean.com/?refcode=c281d6b06bab) If you’d prefer to sign up without the referral code, and the free $10USD credit, you can do so by using the following link: [Sign up with DigitalOcean](http://www.digitalocean.com/)
Linode Linode host KVM-based virtual machines and have a greater choice of locations than DigitalOcean. If you’re looking to use Linode, then you’ll need a Linode with at least 2GB RAM. Linode also offer block storage to increase the available storage on your server should you require it later. You should pick Ubuntu 26.04 LTS as the OS for the server from the list of available operating systems. Linode will install the OS for you and share credentials to access it. You should enable the backup option so that Linode automatically backup your data. These do not include any block storage volumes which must be backed up separately. These are whole-system backups and whilst it’s good to have them, you should also investigate alternative backups in addition. If you wish you can use the following referral link to sign up for Linode’s service. Xibo receives a referral credit if you do so, and you will get the current amount of promotional free credit to use with Linode for doing so. [Sign up with Linode](https://www.linode.com/?r=783e6381f3ee7af3118f8be3d3256f777250faaa)
Vultr Vultr host KVM-based virtual machines. They have a greater choice of locations than DigitalOcean and are typically a little cheaper. If you’re looking to use Vultr, then you’ll need a server with at least 2GB of RAM. If you’ll need more than around 25GB of library storage, you’ll need to opt for the next size VPS up to get the additional storage. You should pick Ubuntu 26.04 LTS 64 bit server from the list of available operating systems. Vultr will install the operating system for you, and then email you login credentials for your new server. You’ll need to pass these to us for us to perform the installation. You should enable the backup option on your server so that Vultr take regular backups of your data. Note however that these are whole-system backups. You may wish to investigate alternative backup software in addition. If you wish you can use the following referral link to sign up for Vultr’s service. Xibo receives a referral fee on these assuming you go on to become a paying customer. [Sign up with Vultr](https://www.vultr.com/?ref=9086476-8H)
### Alternatives There are many alternatives. If you would prefer to use an alternative provider, please be in touch with the specification of the VPS you intend to use (operating system, RAM, storage), and importantly the hypervisor type (eg KVM, Xen), before making a purchase. We will attempt to identify any issues ahead of agreeing to the work, however as providers do vary significantly, it may be that it isn’t possible in every case. **Please note:** Container-based VPSes (eg OpenVZ) are normally unsuitable due to the complexities of running Docker containers inside an existing container. ### SSL We are happy to enable SSL on the installation for you as part of the install service, with certificates issued by LetsEncrypt - the free SSL certificate authority. In order to do so, we will need a DNS name pointing to the server before we can start work. So for example, if the server you’ve purchased were on the IP address `1.2.3.4`, then you’d need to set up a DNS entry on a domain you control to point `cms.mydomain.com` to `1.2.3.4`. These are sometimes referred to as DNS `A` records. # CMS Post Installation Set up Additional setup required to enable all functionality and to keep things running smoothly. {% hint style="info" %} Xibo Cloud hosting includes the pre-configuration of some features with minimal additional set up. {% endhint %} {% hint style="warning" %} If you are running with [Docker](typora://app/docs/setup/xibo-for-docker), please ensure that you have uploaded a test file (such as an image) to your CMS, and ensured that the same image then appears in the shared/cms/library directory on your local filesystem. If not, please **do not proceed** as your changes may not be saved. {% endhint %} ### Setting the correct Time
Xibo Cloud This is configured as part of the service.
Docker It’s very important that the time is correct on your CMS, and that the **CMS Timezone** setting is set correctly for the timezone you’re working in. You may want to consider setting up your Operating System to sync time automatically from the Internet so that the time is always correct. ntp.org provide free access to time servers you can use to synchronise your CMS clock. Instructions for configuring access to their servers are provided here
### Setting the Timezone The installer attempts to make an intelligent guess from the timezone that your OS has been set up to use, but it’s not always able to make the best choice. From the CMS: * Go to the **Settings** page under the **Administration** section of the main menu * Click the **Regional** tab * Use the drop-down menu to select the nearest major city in your timezone * Click **Save** at the bottom of the page. ### Setting up Email Alerts Optionally configure **Email Alerts** to be sent when Players stop connecting properly, and when they come back online after a period of downtime. {% hint style="info" %} Xibo Cloud hosting customers will have some settings pre-populated with some available to change, with others locked for editing. {% endhint %} From the **Settings** page, click on the **Maintenance** tab: * Tick to **Enable Email Alerts**. `MAINTENANCE_EMAIL_ALERTS` * **Max Display Timeout** `MAINTENANCE_ALERT_TOUT` - enter a time in minutes for a **Player** to be considered as gone "offline" from the last time you saw the Player connect to the CMS. This can be overridden on a per Player basis should you need that. Do not set this value lower than your normal Player collection interval. If in doubt, set it higher. The default is 30 minutes. * **Send repeat Display Timeouts** `MAINTENANCE_ALWAYS_ALERT` - if this is set to **On**, for each offline Display you’ll receive an email every time the `maintenance.php` routine is run. Most people will want this set to **Off** which means that you’ll be notified only once per downtime period. * Click **Save** at the bottom of the page. Information needs to be provided in order to send emails from the CMS. From the **Settings** page, click on the **Network** tab: * **Admin email address** `mail_to` - enter the email address that should receive an email when a Display goes offline or comes back online. * **Sending email address** `mail_from` - enter the email address alerts from the CMS should come from. (**Please note:** This field needs to be completed before configuring any email notifications). * Click **Save** at the bottom of the page. In some cases, it’s also useful to alert **Users/User Groups** if a Display goes offline. * Go to **Users** under the **Administration** section * Use the row menu for a User record * Click **Edit** * Click on the **Notifications** tab * Tick the box to **Receive Display Notifications** * Click to **Save** {% hint style="success" %} This can also be set for User Groups! {% endhint %} Next, select which Displays should receive alerts: * Go to **Displays** from the CMS menu * Use the row menu for a Display * Click **Edit** * Click on the **Maintenance** tab * Ensure that **Email Alerts** is set to **Yes** * Click to **Save** If you are not using **Display Setting Profiles**, ensure that you tick **Use Global Timeout?** so that the value set earlier, for the time a Display needs to be offline, before being alerted is used. If you are using **Display Settings Profiles**, then if that box is unticked, the **Collect Interval** from the **Display Profile** will be used instead. With Email Alerts configured, if you turn off one of your Displays, you should be notified by email. The email will be sent once the **Global Timeout** or Display Profile **Collection Interval** has elapsed since the Player last connected, on the subsequent run of the maintenance script. {% hint style="info" %} **Example:** If the Global Timeout is 10 minutes and your maintenance script is set to run every 5 minutes, then you may not be notified for up to 15 minutes after the Player last connects. {% endhint %} When the Player comes back online, you will be notified instantly via email. {% hint style="warning" %} Multiple recovery emails are sent if the **Player** in use makes multiple simultaneous calls to the CMS when it starts up. {% endhint %} #### Further Reading [Display Setting Profiles](https://account.xibosignage.com/manual/en/displays_settings) ### Important Note On Collection Intervals Xibo comes with XMR (Xibo Message Relay) push technology, which means that by default when you make changes to content assigned to Displays in the CMS, the Players are notified to connect and download that update straight away. It’s therefore strongly advisable to set relatively long Collection Intervals for your Display since those only really serve as a failsafe for any missed push messages. {% hint style="danger" %} You do not want CMS and Displays with 1-minute collection intervals. 5 minutes is the absolute minimum for normal operation, and we strongly advise setting this value to **30 minutes** or longer. {% endhint %} ### Log and Statistic Retention
Xibo Cloud These settings are pre-configured and cannot be modified
Docker The CMS generates log output when it’s running, and also receives log output from the Players connected to it for the purposes of debugging and checking the system’s state. It can also collect [Proof of Play Statistics](https://account.xibosignage.com/manual/en/displays_metrics). All these records are held in the database and should be purged periodically to keep the size of the database manageable and to prevent system performance problems. The maintenance script performs that function. From the **Settings** page, click on the **Maintenance** tab: * **Max Log Age** `(MAINTENANCE_LOG_MAXAGE)` controls how many days logs should be retained in the CMS database before being automatically deleted. A setting of `5` would keep logs for 5 days which is reasonable for most debugging purposes. * **Max Statistics Age** `(MAINTENANCE_STAT_MAXAGE)` controls how many days proof of play statistics are retained in the CMS database before being automatically deleted. A setting of `30` would keep statistics for 30 days. If you need to keep them for audit purposes, they can be exported from the `Statistics` page in the CMS and archived for later use.
### Language Detection By default, the CMS will use the language preferences set in your web browser to auto-detect which language to display the CMS interface in. In some instances, where only small parts of the CMS have been translated into a particular language, for example, it may be desirable to disable language detection and enforce a specific language instead. From the **Settings** page, click on the **Regional** tab: * Untick **Detect Language** `(DETECT_LANGUAGE)` * Select a suitable **Default Language** * Click to **Save** #### Default Language If you disable language detection, the CMS will need to know which language file to take its translations from. From the **Regional** tab: * The Default Language is `en_GB` which will give you English (British) translations. You can select a different code using the drop-down menu, for example for Spanish select `es` ### Regionalised Date Formats By default the Xibo CMS shows dates in `Y-m-d H:i` format (eg 2026-03-29 10:00:00) * The date format used throughout the CMS can be adjusted using the **Date Format setting** on the **Regional** tab. ### Proxy Settings
Xibo Cloud N/A
Docker The CMS will need to be able to contact external servers to pull in **RSS feeds** from outside your local network, or for certain integrations. If your network uses a proxy server then you’ll need to tell the Xibo CMS about it so it knows where to look. {% hint style="warning" %} Complete the proxy server details for your network. Your network administrator will help you if you are not sure what these are. {% endhint %} From the **Settings** page click on the **Network** tab: * `Proxy URL (PROXY_HOST)` should be the http URL of your proxy server (eg `http://proxy.example.com` or `http://192.168.1.8`) * `Proxy Port (PROXY_PORT)` should be the port number that your proxy server is listening on (eg `3128` or `8080`) * `Proxy Credentials (PROXY_AUTH)` should be any username and password required to use the proxy server, in the format `username:password` eg `jdoe:secretPassword`. Leave this blank if your proxy does not require authenticated access. * `Proxy Exceptions (PROXY_EXCEPTIONS)` are any host or keyword that should be excluded from being sent to the proxy server. For example, if you have an intranet server then you could exclude it by entering `intranet.example.com`. Multiple entries can be included by separating them with commas. * In order for XMR to work add `cms-xmr,cms-quickchart` * Leave this blank if you don't require any proxy exceptions. * Click to **Save.**
# Maintenance for the CMS Maintenance is an important part of any system and should always be configured to keep the database and files in trim condition, give alerts when there are errors and run in the background. {% hint style="info" %} **Please note:** Xibo Cloud Hosted customers and CMS instances that have **XTR** configured can skip the Maintenance Enabled / Maintenance Key sections as the Maintenance Tasks are run securely from the command line in XTR. {% endhint %} {% hint style="warning" %} If the environment is not compatible with XTR it is necessary to arrange a 3rd party service to call the maintenance web route. {% endhint %} When Xibo is running, logs and statistics slowly accumulate on the server and consume disk space. In extreme cases the sheer volume of those records can cause the CMS web interface to slow and become unresponsive. It is also reassuring to know that if there is a problem with a **Display** and it stops checking in with the Xibo server, you will be notified by email so you can take action to resolve the problem. The maintenance script can be scheduled to run periodically and perform background clean-up tasks such as deleting old logs and statistics and checking the status of the displays. ## Configuration * Maintenance is configured from the **Settings** page under the **Administration** section of the main CMS menu, from the **Maintenance** tab. There are several options associated with the maintenance script: * **Maintenance Enabled**( `MAINTENANCE_ENABLED` ): * **Off** - All maintenance functionality is disabled. * **On** - All maintenance functionality is enabled. You can use any of the methods below to call the maintenance script on a schedule without specifying a key. * **Protected** - All maintenance functionality is enabled. You must specify the correct key when calling the maintenance script. This is to prevent unauthorised persons from repeatedly calling the script and generating large amounts of alert email. * **Maintenance Key** (MAINTENANCE\_KEY) - The secret key required to allow the maintenance script to run when “Maintenance Enabled” is set to “Protected” mode. * **Email Alerts** (MAINTENANCE\_EMAIL\_ALERTS) - Globally enable or disable the sending of email alerts. You can enable/disable alerts for individual displays in Display Management. {% hint style="info" %} For Xibo Cloud Hosting customers, Max Log Age and Max Statistics Age are set and locked. {% endhint %} * **Max Log Age** (MAINTENANCE\_LOG\_MAXAGE) - How many days worth of log messages to keep. Logs older than specified will be deleted. Set to 0 to keep all logs indefinitely. * **Max Statistics Age** (MAINTENANCE\_STAT\_MAXAGE) - How many days worth of statistics to keep. Statistics older than specified will be deleted. Set to 0 to keep all statistics indefinitely. * **Max Display Timeout** (MAINTENANCE\_ALERT\_TOUT) - Globally configure how many minutes after a display lasts connects to the server we should consider it to have a problem and cause an alert to be sent. You can override this default for individual displays in Display Management. You should make sure this time is longer than the collection interval you have configured on your players to avoid false positive alerts. Set email address information to send emails generated by the CMS from the **Network** tab: * **Admin email address** (mail\_to) - The overall CMS administrator email that you want to receive all copies of email notifications to be sent to. * **Sending email address** (mail\_from) - The address to show who the alert emails are from. (e.g. ) * **Sending email name** - The name you want to show as the sender. # Player App Installation and Version Upgrades Once you have chosen your Media Player hardware, install the Xibo Player app in just a few steps. 1. **Configure** your device (steps dependent on your choice of media player hardware) 2. **Download and Install** the Xibo Media Player app (some hardware types have the Player app pre installed) 3. **Connect** the device to the CMS 4. **Authorise** as a Display in the CMS 5. **Activate** a Player licence (additional step for non-plan customers only) | **Media Player Hardware** | **Quick Set up Guide** | | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | | Amazon Signage Stick | [View/Save as PDF](/setup-docs/player-app-installation-and-upgrades/player-app-installation-and-version-upgrades/amazon-signage-stick-install-guide) | | Amino H Series | [View/Save as PDF](/setup-docs/player-app-installation-and-upgrades/player-app-installation-and-version-upgrades/amino-install-guide) | | DSDevices DSDA1 / DSDX5 | [View/Save as PDF](/setup-docs/player-app-installation-and-upgrades/player-app-installation-and-version-upgrades/dsdevices-dsda1-dsdx5-install-guide) | | DSDevices 9X/95 | [View/Save as PDF](/setup-docs/player-app-installation-and-upgrades/player-app-installation-and-version-upgrades/dsdevices-9x-95-install-guide) | | Google ChromeOS | [View/Save as PDF](/setup-docs/player-app-installation-and-upgrades/player-app-installation-and-version-upgrades/googlechromeos-install-guide) | | Hisense SoC | [View/Save as PDF](/setup-docs/player-app-installation-and-upgrades/player-app-installation-and-version-upgrades/hisense-install-guide) | | LG webOS SoC | [View/Save as PDF](/setup-docs/player-app-installation-and-upgrades/player-app-installation-and-version-upgrades/lg-webos-install-guide) | | Philips SoC | [View/Save as PDF](/setup-docs/player-app-installation-and-upgrades/player-app-installation-and-version-upgrades/philips-install-guide) | | Samsung Tizen SoC | [View/Save as PDF](/setup-docs/player-app-installation-and-upgrades/player-app-installation-and-version-upgrades/samsung-tizen-install-guide) | | Sharp ME432 | [View/Save as PDF](/setup-docs/player-app-installation-and-upgrades/player-app-installation-and-version-upgrades/sharp-me432-install-guide) | | Sony Bravia | [View/Save as PDF](/setup-docs/player-app-installation-and-upgrades/player-app-installation-and-version-upgrades/sony-bravia-install-guide) | #### **Display Setting Profile (recommended)** Once connected to the CMS, each Display will be assigned a default **Display Profile** which will apply all settings to all Displays assigned with that profile. Using Display Profiles to control versions and licensing is our recommended way in order to minimise potential errors across multiple Displays. ### **Upgrading a Player app version** As new Player app releases are made available we recommend upgrading your Player app to the latest version in order to take advantage of all security and bug fixes which may have been included. Our recommended Media Players can be upgraded from the CMS. Take a look at our device [comparison chart](https://docs.google.com/spreadsheets/d/e/2PACX-1vRMlLA1A40YBipC4Vx8bEjoQflGNy0AKtXa2Uc7e2UlZGnTvN5Mut7aTfbU9-6uAPvoZI3cbAc3Xdsm/pubhtml) to see which Media Players can be upgraded in this way: 1. **Download** the latest Player release 2. From the CMS, navigate to **Player Versions** under the **Displays** section of the main CMS menu 3. Click **Add Version** 4. **Upload** the downloaded Player release file 5. Go to **Display Settings**, use the row menu to select the **Display Profile** for the Player 6. Click **Edit** and open the **General** tab 7. Use the **Player Version** drop-down menu and select the new version 8. Click to **Save** Displays which have the Display Profile assigned will now download the chosen version and install during their set download/upgrade window. {% hint style="danger" %} If you are not on a plan you will need to purchase a Player Licence in order to upgrade to a new major version! {% endhint %} # Amazon Signage Stick Install Guide ### You will need * [ ] Amazon Signage Stick and in box accessories * [ ] A wireless internet connection, including your Wi-Fi name and password * [ ] An Amazon account (create an amazon account) * [ ] Amazon Signage Mobile App * [ ] Xibo CMS login * [ ] Android Player Licence (Users not on a Xibo Plan) {% stepper %} {% step %} ### Install the Player App * Plug the Amazon Signage Stick into the HDMI port of the screen * Download and open the Amazon Signage Mobile IOS App store/Play Store * Log into the app with your Amazon account to automatically create a company/organisation as an admin user * Follow the onboarding process and enter the pairing code shown on the screen * Select the Xibo option from the CMS dropdown menu {% hint style="success" %} The screen will display instructions on how to connect your CMS after installation has successfully completed {% endhint %} {% endstep %} {% step %} ### Connect to the CMS * Login to the CMS and navigate to the **Displays** page * From the Amazon Signage App, select **Use Code** to show a 6 character activation code * From the Displays page in the CMS, select the **Add Display** button at the top of the grid
* Enter the activation code as shown on the Player screen * Click to **Save** {% hint style="success" %} The Activate Player page will automatically close once successfully connected. {% endhint %} {% endstep %} {% step %} ### Authorise the Display * From the CMS, navigate to the **Displays** page * Use the row menu for the newly registered entry and select **Authorise** * Click **Yes** to confirm {% hint style="success" %} If you are on a Xibo Plan, the Display is now ready to start showing content from the Xibo CMS {% endhint %} {% hint style="info" %} If you have purchased a licence separately, follow the steps to licence your Display. {% endhint %} {% endstep %} {% endstepper %}
Licence your Display For customers not on a Xibo plan, a Licence code must be provided in order for the Display to start showing content: * Navigate to the **Display Settings** page from the main CMS menu * Select the row menu for the appropriate Display Profile and click **Edit**
* Provide the **Licence Code** in the form field * Click to **Save** {% hint style="success" %} The Display is now ready to start showing content from the Xibo CMS. {% endhint %}
### RDM for the Amazon Signage Stick Integration with the Amazon Signage Stick allows users to take advantage of advanced remote device management capabilities. Once set-up, use the following guidance to utilise RDM capabilities from inside the CMS using Commands. {% hint style="warning" %} Skip the Add Commands section if you already have commands created for Android devices. {% endhint %}
Add Commands to the CMS 1. Go to **Commands** under the **Displays** section of the main CMS menu 2. Click the **Add Command** button 3. Give the Command a **Name** 4. Enter a **Code** (such as the command string) to easily identify 5. Use the Command drop down field and select **Free Text** 6. Enter a **Command String** 7. Click to **Save** | Command Name | Command String | | ------------ | -------------- | | Reboot | **reboot** | | Mute | **mute\|1** | | Unmute | **mute\|0** | | Screen On | **screenOn** | | Screen Off | **screenOff** |
Send Command from the CMS 1. Navigate to **Displays** from the main CMS menu 2. Use the row menu for a Display and select **Send Command** 3. Use the drop down menu to select the command to use 4. Click to **Save**
Schedule Command 1. Navigate to **Schedule** from the main CMS menu 2. Click the **Add Event** button 3. Use the Event Type drop down and select **Command** 4. Select the command to use from the list 5. Click **Next** and set the **Displays** 6. Click **Next** and set timings 7. Click **Finish** if no further actions (such as Repeats) are required
#### Additional RDM Functionality Further remote device management capabilities can be found from the Displays page of the CMS.
Identify your Display Use the row menu for a Display and select **Edit** to view the **Display Hardware Key**
Capture MAC address Shown in the MAC address column of the Displays grid
Capture IP address Shown in the IP address column of the Displays grid
Capture Screenshot Use the row menu and click **Request Screen Shot**. On saving, an Image will be retrieved and shown in the Thumbnail column of the Displays grid.
# Amino Install Guide ### You will need * [ ] Latest Android player release from Xibo * [ ] Orchestrate login, supplied after purchase by Amino * [ ] Xibo Settings file, [download here](https://xibosignage.com/hubfs/docs/media-player/amino/Xibo-H200-Default-Parameters.csv) * [ ] Xibo CMS login * [ ] Android Player Licence (Users not on a Xibo plan) ### Initial Set-up - Uploading Apps into Orchestrate * Login to Orchestrate * Using the left hand menu, click **Applications** * Click the **Add Application** button * Provide the **Application Name** * Click **Choose File** to upload the Android APK * Click **Save** ### Orchestrate Configuration * Using the left hand menu, click **Configurations** * Click the **Add Configuration** button * Provide a **Configuration Name** * Click the **Submit** button * From the **Applications** tab, **Add Action** * Use the drop-down and select **Xibo for Android** * Click to **Save Changes** * From the **Parameters** tab, select the firmware * Set the **Upgrade Type** * Click the **Import from** file button and upload the Xibo Settings file (downloaded from the link) This will provide standard System Settings as well as provide Advanced Parameters. * Use the drop-down for the **Home App** setting and select **Xibo for Android** * Check **Language** and **Timezone** fields to ensure that these are correct * Click to **Save** ### Test Connectivity Run an **Orchestrate Connectivity Test** to make sure that Orchestrate is accessible: * Using the screen Remote Control Unit click the following:\ **Menu - Network - Orchestrate Connectivity Test** {% hint style="info" %} Once you have uploaded the Xibo Player Application and created Configuration(s) in Orchestrate, you do not need to re-do this each time you want to add a device. Adding a device is a three step process, as detailed below. {% endhint %} {% stepper %} {% step %} ### Adding devices in Orchestrate * Click **Devices** from the left hand menu * Click **Device list** * Click **Add Device** * Provide the **Serial Number** of the device found on the nameplate sticker * Use the drop down menu to assign a **Configuration** * Click **Submit** {% endstep %} {% step %} ### Connect to the CMS * Power on/restart the Amino device * Login to the CMS and navigate to the **Displays** page * A 6 character activation code will be shown on screen (keep this screen open) * From the Displays page in the CMS, select the **Add Display** button at the top of the grid
* Enter the activation code as shown on the Player screen * Click to **Save** {% hint style="success" %} The Activate Player page will automatically close once successfully connected. {% endhint %} {% endstep %} {% step %} ### Authorise the Display * From the CMS, navigate to the **Displays** page * Use the row menu for the newly registered entry and select **Authorise** * Click **Yes** to confirm {% hint style="success" %} If you are on a Xibo Plan, the Display is now ready to start showing content from the Xibo CMS {% endhint %} {% hint style="info" %} If you have purchased a licence separately, follow the steps to licence your Display. {% endhint %} {% endstep %} {% endstepper %}
Licence your Display For customers not on a Xibo plan, a Licence code must be provided in order for the Display to start showing content: * Navigate to the **Display Settings** page from the main CMS menu * Select the row menu for the appropriate Display Profile and click **Edit**
* Provide the **Licence Code** in the form field * Click to **Save** {% hint style="success" %} The Display is now ready to start showing content from the Xibo CMS. {% endhint %}
# Sharp ME432 Install Guide ### You will need * [ ] Latest Android player release from Xibo * [ ] USB flash drive * [ ] Xibo CMS login * [ ] Android Player Licence (Users not on a Xibo plan) {% stepper %} {% step %} ### Install Player App * Download the Android APK and save to a USB flash drive * Plug the drive into the device USB port * Open the browser on the monitor and click the USB flash drive * Click on the `.apk` file and select Install * Once installed, click open or launch {% endstep %} {% step %} ### Connect to the CMS * Login to the CMS and navigate to the **Displays** page * A 6 character activation code will be shown on screen (keep this screen open) * From the Displays page in the CMS, select the **Add Display** button at the top of the grid
* Enter the activation code as shown on the Player screen * Click to **Save** {% hint style="success" %} The Activate Player page will automatically close once successfully connected. {% endhint %} {% endstep %} {% step %} ### Authorise the Display * From the CMS, navigate to the **Displays** page * Use the row menu for the newly registered entry and select **Authorise** * Click **Yes** to confirm {% hint style="success" %} If you are on a Xibo Plan, the Display is now ready to start showing content from the Xibo CMS {% endhint %} {% hint style="info" %} If you have purchased a licence separately, follow the steps to licence your Display. {% endhint %} {% endstep %} {% endstepper %}
Licence your Display For customers not on a Xibo plan, a Licence code must be provided in order for the Display to start showing content: * Navigate to the **Display Settings** page from the main CMS menu * Select the row menu for the appropriate Display Profile and click **Edit**
* Provide the **Licence Code** in the form field * Click to **Save** {% hint style="success" %} The Display is now ready to start showing content from the Xibo CMS. {% endhint %}
# DSDevices 9X/95 Install Guide ### You will need * [ ] DSDevices 9X/95 Media Player (stable Wifi or wired internet connection) * [ ] Xibo CMS login * [ ] Android Player Licence (Users not on a Xibo Plan) {% stepper %} {% step %} ### Device Set-up * Connect the Player device to your Display using the supplied HDMI cable * Connect power to the Player device * Connect a USB mouse to the Player device to help with the set-up * Connect to your local network using a wired or Wi-Fi connection {% tabs %} {% tab title="Wi-Fi Connection" %} * Select the **Settings** app (cog icon) on the device * Choose **Network and Internet** from the menu * Set the **Wi-Fi** option to **On** * Choose the network from the **Available Networks** section and enter the password for the network to establish a connection * Select the **Settings** app (cog icon) * Choose **Device Properties** * Select **Date & Time** * Set **Automatic Date & Time**\ The device will set the correct date and time when an internet connection is established. {% endtab %} {% tab title="Wired Connection" %} * Plug in the ethernet cable/LAN cable into the port on the back of the device {% endtab %} {% endtabs %} {% endstep %} {% step %} ### Connect to the CMS * Open Xibo in the app drawer of the device * Login to the CMS and navigate to the **Displays** page * Select **Use Code** to show a 6 character activation code (keep this screen open) * From the Displays page in the CMS, select the **Add Display** button at the top of the grid
* Enter the activation code as shown on the Player screen * Click to **Save** {% hint style="success" %} The Activate Player page will automatically close once successfully connected. {% endhint %} {% endstep %} {% step %} ### Authorise the Display * From the CMS, navigate to the **Displays** page * Use the row menu for the newly registered entry and select **Authorise** * Click **Yes** to confirm {% hint style="success" %} If you are on a Xibo Plan, the Display is now ready to start showing content from the Xibo CMS {% endhint %} {% hint style="info" %} If you have purchased a licence separately, follow the steps to licence your Display. {% endhint %} {% endstep %} {% endstepper %}
Licence your Display For customers not on a Xibo plan, a Licence code must be provided in order for the Display to start showing content: * Navigate to the **Display Settings** page from the main CMS menu * Select the row menu for the appropriate Display Profile and click **Edit**
* Provide the **Licence Code** in the form field * Click to **Save** {% hint style="success" %} The Display is now ready to start showing content from the Xibo CMS. {% endhint %}
# DSDevices DSDA1 / DSDX5 Install Guide {% hint style="info" %} ### Please note: This guidance is for the DSDA1 and DSDX5 Media Player. {% endhint %} ### You will need * [ ] DSDevices DSDA1 / DSDX5 Media Player (stable Wifi or wired internet connection) * [ ] Xibo CMS login * [ ] Android Player Licence (Users not on a Xibo Plan) * [ ] Check [device chart](https://docs.google.com/spreadsheets/d/e/2PACX-1vRMlLA1A40YBipC4Vx8bEjoQflGNy0AKtXa2Uc7e2UlZGnTvN5Mut7aTfbU9-6uAPvoZI3cbAc3Xdsm/pubhtml) for firmware version {% stepper %} {% step %} ### Device Set-up * Connect the Player device to your Display using the supplied HDMI cable * Connect power to the Player device * Connect a USB mouse to the Player device to help with the set-up * The device will check for internet connection {% tabs %} {% tab title="Wi-Fi Connection" %} * Choose **Network and Internet** from the menu * Set the **Wi-Fi** option to **On** * Choose the network from the **Available Networks** section and enter the password for the network to establish a connection {% endtab %} {% tab title="Wired Connection" %} * Plug in the ethernet cable/LAN cable into the port on the back of the device {% endtab %} {% endtabs %} * Click to agree terms for the DSD selector * Select Language * Select Timezone * Ensure Date is correct, select OK * Ensure Time is correct, select OK * Select Xibo and click Install * Once installed, click Finish {% hint style="info" %} Click on the settings cog to enter system settings to turn off autoboot so that DSD Selector will not launch on next boot! {% endhint %} {% endstep %} {% step %} ### Connect to the CMS * Open Xibo in the app drawer of the device * Login to the CMS and navigate to the **Displays** page * Select **Use Code** to show a 6 character activation code (keep this screen open) * From the Displays page in the CMS, select the **Add Display** button at the top of the grid
* Enter the activation code as shown on the Player screen * Click to **Save** {% hint style="success" %} The Activate Player page will automatically close once successfully connected. {% endhint %} {% endstep %} {% step %} ### Authorise the Display * From the CMS, navigate to the **Displays** page * Use the row menu for the newly registered entry and select **Authorise** * Click **Yes** to confirm {% hint style="success" %} If you are on a Xibo Plan, the Display is now ready to start showing content from the Xibo CMS {% endhint %} {% hint style="info" %} If you have purchased a licence separately, follow the steps to licence your Display. {% endhint %} {% endstep %} {% endstepper %}
Licence your Display For customers not on a Xibo plan, a Licence code must be provided in order for the Display to start showing content: * Navigate to the **Display Settings** page from the main CMS menu * Select the row menu for the appropriate Display Profile and click **Edit**
* Provide the **Licence Code** in the form field * Click to **Save** {% hint style="success" %} The Display is now ready to start showing content from the Xibo CMS. {% endhint %}
# GoogleChromeOS Install Guide ### You will need * [ ] Latest ChromeOS player release from Xibo * [ ] Google Admin Console * [ ] Kiosk and Signage upgrade licence (purchased from your local Google reseller) * [ ] Xibo CMS login * [ ] ChromeOS Player Licence (Users not on a Xibo plan) {% stepper %} {% step %} ### Upload Player release file * From the CMS, click on **Player Versions** under the Displays section of the main CMS menu * Click the **Add Version** button and upload the `.zip.chrome` file for the latest version * Click on **Display Settings** and locate the default profile for ChromeOS * Using the row menu click **Edit** * From the **General** tab, set the uploaded **Player Version** {% endstep %} {% step %} ### Prepare Google admin console * Use the plus button, located at the bottom right of the Kiosks view, using the world icon select **Add by URL** * Enter https\://**\**/pwa * Located at the top, adjust the Auto-launch app to **Xibo Digital Signage** * Enrol your device as a **Kiosk** {% hint style="success" %} Xibo will open on the device and display a code which can be used to connect to the CMS. {% endhint %} {% endstep %} {% step %} ### Connect to the CMS * Login to the CMS and navigate to the **Displays** page * From the Displays page in the CMS, select the **Add Display** button at the top of the grid * Enter the activation code as shown on the Player screen * Click to **Save** {% hint style="success" %} The Activate Player page will automatically close once successfully connected. {% endhint %} {% endstep %} {% step %} ### Authorise the Display * From the CMS, navigate to the **Displays** page * Use the row menu for the newly registered entry and select **Authorise** * Click **Yes** to confirm {% hint style="success" %} If you are on a Xibo Plan, the Display is now ready to start showing content from the Xibo CMS {% endhint %} {% hint style="info" %} If you have purchased a licence separately, follow the steps to licence your Display. {% endhint %} {% endstep %} {% endstepper %}
Licence your Display For customers not on a Xibo plan, a Licence code must be provided in order for the Display to start showing content: * Navigate to the **Display Settings** page from the main CMS menu * Select the row menu for the appropriate Display Profile and click **Edit**
* Provide the **Licence Code** in the form field * Click to **Save** {% hint style="success" %} The Display is now ready to start showing content from the Xibo CMS. {% endhint %}
# Hisense Install Guide ### You will need * [ ] Latest Android Player release from Xibo * [ ] Stable Wifi or wired internet connection * [ ] Xibo CMS login * [ ] Android Player Licence (Users not on a Xibo plan) {% stepper %} {% step %} ### Install Player App * Navigate to the home screen of the Hisense Player and open the built-in web browser app * Type [https://xibosignage.com/downloads ](https://xibosignage.com/downloads)into the browser’s address bar * Click **Download** for the latest version of the Android Xibo Player app * Click to install from the download notification or select the Android Apk download from the file manager app, and choose **Open** to start installation {% hint style="success" %} Once the installation process is complete, click the back button on the remote control. {% endhint %} {% endstep %} {% step %} ### Connect to the CMS * Login to the CMS and navigate to the **Displays** page * From the menu shown on the Player screen, select **Apps** and click on the Xibo for Android tile * Select **Use Code** to show a 6 character activation code (keep this screen open) * From the Displays page in the CMS, select the **Add Display** button at the top of the grid
* Enter the activation code as shown on the Player screen * Click to **Save** {% hint style="success" %} The Activate Player page will automatically close once successfully connected. {% endhint %} {% endstep %} {% step %} ### Authorise the Display * From the CMS, navigate to the **Displays** page * Use the row menu for the newly registered entry and select **Authorise** * Click **Yes** to confirm {% hint style="success" %} If you are on a Xibo Plan, the Display is now ready to start showing content from the Xibo CMS {% endhint %} {% hint style="info" %} If you have purchased a licence separately, follow the steps to licence your Display. {% endhint %} {% endstep %} {% endstepper %}
Licence your Display For customers not on a Xibo plan, a Licence code must be provided in order for the Display to start showing content: * Navigate to the **Display Settings** page from the main CMS menu * Select the row menu for the appropriate Display Profile and click **Edit**
* Provide the **Licence Code** in the form field * Click to **Save** {% hint style="success" %} The Display is now ready to start showing content from the Xibo CMS. {% endhint %}
# LG webOS Install Guide ### You will need * [ ] Latest webOS Player release from Xibo * [ ] Stable Wifi or wired connection * [ ] Recommended Firmware Version * [ ] Xibo CMS login * [ ] webOS Player Licence (Users not on a Xibo Plan) ### Monitor Preparation * Use the **Settings** button (cogwheel icon) on the remote control to access the **General** menu * Select **Time & Date** * Use **Set Automatically** or use the drop down to set the correct Time and Date * Click **Time Zone** and set the **Continent, County/Territory** and **City** {% stepper %} {% step %} ### Install Player App Follow the steps below to access SI Server or Server as appropriate for the webOS version running on the monitor. {% tabs %} {% tab title="SI Server Settings webOS 3.2 and later" %} * Using the remote control, press **Settings** * Choose the option **EZ Settings** * Select **SI Server Setting** * Select **SI Server Setting** again on the next page {% endtab %} {% tab title="Server Settings webOS 3.0" %} * Using the remote control, press and hold **Settings** until a message is shown to notify your input has been received * Enter **8080** and press the **OK** button to open the Settings Menu {% endtab %} {% endtabs %} Remotely install the Player IPK into the SI Server/Server menu by entering the following: * **Application Launch Mode** - Local * **Fully Qualified Domain Name** - On * Enter the **URL** to the app package - **** * **Application Type** - IPK * **Local Application Upgrade** - REMOTE {% hint style="success" %} Once installed, restart the monitor to show the Connect to CMS screen. {% endhint %} {% endstep %} {% step %} ### Connect to the CMS * Using the remote control, click the yellow button to open the action bar menu * From the Connect to CMS screen, select **Use Code** to show a 6 character activation code (keep this screen open) * Login to the CMS and click on Displays from the main CMS menu * Select the **Add Display** button at the top of the grid
* Enter the activation code as shown on the Player screen * Click to **Save** {% hint style="success" %} The Activate Player page will automatically close once successfully connected. {% endhint %} {% endstep %} {% step %} ### Authorise the Display * From the CMS, navigate to the **Displays** page * Use the row menu for the newly registered entry and select **Authorise** * Click **Yes** to confirm {% hint style="success" %} If you are on a Xibo Plan, the Display is now ready to start showing content from the Xibo CMS {% endhint %} {% hint style="info" %} If you have purchased a licence separately, follow the steps to licence your Display. {% endhint %} {% endstep %} {% endstepper %}
Licence your Display For customers not on a Xibo plan, a Licence code must be provided in order for the Display to start showing content: * Navigate to the **Display Settings** page from the main CMS menu * Select the row menu for the appropriate Display Profile and click **Edit**
* Provide the **Licence Code** in the form field * Click to **Save** {% hint style="success" %} The Display is now ready to start showing content from the Xibo CMS. {% endhint %}
# Philips Install Guide ### You will need * [ ] Latest Android player release from Xibo * [ ] Xibo CMS login * [ ] Stable Wifi or wired internet connection * [ ] USB Stick. * [ ] Android Player Licence (Users not on a Xibo plan) {% stepper %} {% step %} ### Install the Player App * Download the latest Android APK player release and copy to the root folder of a USB stick * Power on the Philips Player and connect the USB stick * Press the **Home** button on the Philips remote control wait for the menu to appear and press **1888** * Select **Storage** from the new menu shown * Select the connected USB stick * Select the Android APK download and choose **Open** to start installation {% hint style="success" %} Once the installation process is complete, click the back button on the remote control {% endhint %} {% endstep %} {% step %} ### Connect to the CMS * Login to the CMS and navigate to the **Displays** page * From the menu shown on the Player, select **Apps** and click the Xibo for Android tile * Select **Use Code** to show a 6 character activation code (keep this screen open) * From the Displays page in the CMS, select the **Add Display** button at the top of the grid
* Enter the activation code as shown on the Player screen * Click to **Save** {% hint style="success" %} The Activate Player page will automatically close once successfully connected. {% endhint %} {% endstep %} {% step %} ### Authorise the Display * From the CMS, navigate to the **Displays** page * Use the row menu for the newly registered entry and select **Authorise** * Click **Yes** to confirm {% hint style="success" %} If you are on a Xibo Plan, the Display is now ready to start showing content from the Xibo CMS {% endhint %} {% hint style="info" %} If you have purchased a licence separately, follow the steps to licence your Display. {% endhint %} {% endstep %} {% endstepper %}
Licence your Display For customers not on a Xibo plan, a Licence code must be provided in order for the Display to start showing content: * Navigate to the **Display Settings** page from the main CMS menu * Select the row menu for the appropriate Display Profile and click **Edit**
* Provide the **Licence Code** in the form field * Click to **Save** {% hint style="success" %} The Display is now ready to start showing content from the Xibo CMS. {% endhint %}
# Sony Bravia Install Guide ### You will need * [ ] Wired internet connection * [ ] Xibo My Account login * [ ] Xibo CMS login * [ ] Android Player Licence (Users not on a Xibo plan) {% stepper %} {% step %} ### Register * Log in to your Xibo **My Account** dashboard * From the **Hardware** page, scroll down to the Remote Management device table located under the hardware purchases section * Click the **Register Sony Bravia** button * Using the form, enter a friendly Name for your player * Enter the **ethernet MAC address**, which can be found on the back of the device or by navigating to: * Settings * Networking and Internet * Network Status {% hint style="warning" %} Make sure your device is connected via ethernet and you supply the ethernet/wired MAC address using - instead of : as the separator, e.g. 00-00-00-00-00-00. {% endhint %} * Select a **Group** to use for this device. If you have no groups or do not select a group to use, one will be created/assigned by default * Click **Save** {% hint style="success" %} Your device is now registered and will show in the Remote Management table of your Xibo account. {% endhint %} {% endstep %} {% step %} ### Provision the device with Sony's cloud * Power the device on {% hint style="info" %} If you powered the device on before registering you will need to do a factory reset following these steps: Settings > System > About > Reset **The screen will reboot. You may see a list of languages to select, ignore this and wait for a 6 digit code to be shown.** {% endhint %} * From the Remote Management table, click **View Details** for your device * Enter the **one time code** as shown on your device * Click **Submit** {% hint style="success" %} The status will change to Activated in the Remote Management table, once the provisioning process is complete. The device will enter Pro Mode and automatically open the Player app to connect to the CMS. {% endhint %} {% endstep %} {% step %} ### Connect to the CMS * Login to the CMS and navigate to the **Displays** page * Select **Use Code** to show a 6 character activation code (keep this screen open) * From the Displays page in the CMS, select the **Add Display** button at the top of the grid
* Enter the activation code as shown on the Player screen * Click to **Save** {% hint style="success" %} The Activate Player page will automatically close once successfully connected. {% endhint %} {% endstep %} {% step %} ### Authorise the Display * From the CMS, navigate to the **Displays** page * Use the row menu for the newly registered entry and select **Authorise** * Click **Yes** to confirm {% hint style="success" %} If you are on a Xibo Plan, the Display is now ready to start showing content from the Xibo CMS {% endhint %} {% hint style="info" %} If you have purchased a licence separately, follow the steps to licence your Display. {% endhint %} {% endstep %} {% endstepper %}
Licence your Display For customers not on a Xibo plan, a Licence code must be provided in order for the Display to start showing content: * Navigate to the **Display Settings** page from the main CMS menu * Select the row menu for the appropriate Display Profile and click **Edit**
* Provide the **Licence Code** in the form field * Click to **Save** {% hint style="success" %} The Display is now ready to start showing content from the Xibo CMS. {% endhint %}
# Samsung Tizen Install Guide ### You will need * [ ] Latest Tizen Player release from Xibo * [ ] Stable Wifi or wired connection * [ ] Recommended Firmware Version * [ ] Xibo CMS login * [ ] Tizen Player Licence (Users not on a Xibo Plan) ### Monitor Preparation * Use the **Menu** button on the remote control to access the **System** menu * Select **Time** * Go to **NTP Settings** to set automatically, or Clock Set to manually set * **Timezone** can be found in the NTP Settings menu * Set the **DST** settings to the correct daylight saving setting for the location Dependent on the SSSP/Tizen OS version, perform the following addtional steps: {% tabs %} {% tab title="SSSP 10 Models" %} * Select **Custom App** during the setup process when first switching on the Display {% endtab %} {% tab title="Models Earlier than SSSP 10" %} * Press the **Cog** button on the remote and go to **System** * Locate the **Play Via** setting and set to **Custom App** {% endtab %} {% endtabs %} {% stepper %} {% step %} ### Install the Player App * Login to the **Xibo CMS** and navigate to **Player Versions** under the **Displays** section of the main CMS menu * Select the **Add Version** button * Click **Add files** and select the downloaded WGT Player file * Select **Start Upload** * Once the upload is complete, click **Done** to close * From **Displays Settings** in the CMS, use the row menu for the default Tizen profile to set the **Player Version** * Click **Save** to confirm * Click the **Home** button on the remote control for the Samsung display * Select **URL Launcher Settings** from the menu {% hint style="warning" %} If you see MagicInfo Player instead of the URL Launcher Settings, click the Menu button and go to the System Menu option. Choose Play Via and set this to URL Launcher, exit the menus.
{% endhint %} * Select the Install Web App option and enter the URL of the CMS. For example ** or ** * Click **Done** to confirm {% hint style="success" %} The Player will open automatically once installed. Press the Cog button on your remote and select Xibo Player from the menu to open the Connect to your CMS page. {% endhint %} {% endstep %} {% step %} ### Connect to the CMS * From the Connect to CMS screen, select **Use Code** to show a 6 character activation code (keep this screen open) * Login to the CMS and navigate to the Displays page * Select the **Add Display** button at the top of the grid
* Enter the activation code as shown on the Player screen * Click to **Save** {% hint style="success" %} The Activate Player page will automatically close once successfully connected. {% endhint %} {% endstep %} {% step %} ### Authorise the Display * From the CMS, navigate to the **Displays** page * Use the row menu for the newly registered entry and select **Authorise** * Click **Yes** to confirm {% hint style="success" %} If you are on a Xibo Plan, the Display is now ready to start showing content from the Xibo CMS {% endhint %} {% hint style="info" %} If you have purchased a licence separately, follow the steps to licence your Display. {% endhint %} {% endstep %} {% endstepper %}
Licence your Display For customers not on a Xibo plan, a Licence code must be provided in order for the Display to start showing content: * Navigate to the **Display Settings** page from the main CMS menu * Select the row menu for the appropriate Display Profile and click **Edit**
* Provide the **Licence Code** in the form field * Click to **Save** {% hint style="success" %} The Display is now ready to start showing content from the Xibo CMS. {% endhint %}
# Windows Player Installation The Xibo Windows Player is distributed as a windows installer file (MSI) which is a standard "double click" installation. ## Minimum Requirements **Xibo** does not require many resources to run, however with the advance of technology it has been necessary to set out some minimum requirements. The installation process will check these for you, but they are listed below for convenience: * A network connection to the CMS (possibly over the Internet) * Microsoft Windows 10 or later (see note below) * **Please note** that starting with Windows 10 it is advisable to use the "professional" variant of the operating system. The "home" version no longer has the ability to fully control the schedule of automatic updates which may cause messages to interrupt your signage playback. * .NET Framework v4.7.3 * Visual C++ Redistributable for Visual Studio 2015-2019 x86 (will be downloaded if not present) * Internet Explorer 8+ ( *recommended IE11 or higher* ) * Flash Player Version 9 or later (if Flash support required) * Windows Media Player 11 or later * For PowerPoint support; Microsoft PowerPoint 2003 or later. *PowerPoint viewer is not suitable*. * For `edge` browser tags and HLS support the Webview2 runtime is required. [Download here](https://developer.microsoft.com/en-us/microsoft-edge/webview2/#download-section) We recommend Windows 10 build 1909 or later. Enterprise LTSB is known to have issues with video playback. {% hint style="warning" %} Installing the Windows Player App on a device that does not meet our minimum requirements will not qualify for helpdesk support when on one of our plans. {% endhint %} ## Installing the Windows Player App * Download [Windows Player app](https://xibosignage.com/xibo-for-windows) and double click on the `Xibo msi` file. The installer will take you through a number of screens, which are outlined below. **Please note:** You may see a security warning or a message asking if you allow an app from an unknown publisher to make changes, during the installation stage. Please accept by clicking on "Run" or "Yes" to continue with the installation. * The installer presents a **Welcome** screen, click "Next". ![Welcome Screen](https://2149703612-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOD5P6BGYveuzkbhjZRsq%2Fuploads%2Fgit-blob-ee0211578fe623752e2f7c2208c793470acf7aa3%2Fwindows_installation_welcome_screen.png?alt=media) * Read the **Read me** file and click "Next": ![Read Me File](https://2149703612-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOD5P6BGYveuzkbhjZRsq%2Fuploads%2Fgit-blob-3ffc9ab31b7aff42f2b08bb2cf81693a63c15285%2Fwindows_installation_read_me.png?alt=media) * Read the **End-User License Agreement** and click to accept these terms, click "Next". ![End Licence Agreement](https://2149703612-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOD5P6BGYveuzkbhjZRsq%2Fuploads%2Fgit-blob-c8a03e65407babaf196e35cb204dffb1a88efdae%2Fwindows_installation_end_user_agreement.png?alt=media) * Click "Install" or click "Back" to review: ![Begin Install](https://2149703612-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOD5P6BGYveuzkbhjZRsq%2Fuploads%2Fgit-blob-f11eb0533ea38585bacd6b9b8cdd485806401819%2Fwindows_installation_begin_install.png?alt=media) The Setup Wizard will start to install the Xibo Player, which may take several minutes. * The Installation is now complete, click "Finish" to exit the Setup Wizard: ![Finish Setup](https://2149703612-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOD5P6BGYveuzkbhjZRsq%2Fuploads%2Fgit-blob-bdff880f584097c28c00202827f411c94677d13a%2Fwindows_installation_finish_setup.png?alt=media) {% hint style="info" %} The folder will be installed by default to `C:\Program Files(x86)\Xibo Player\` {% endhint %} ## Connect to CMS Newly installed Players must be configured and registered with the **Xibo CMS** before they can be used using **Player Options**. {% hint style="info" %} The **Player Options** window is accessed from the Player using the Start Menu and selecting All programs. Most of the Player options are set on the CMS and delivered over the network to the Player. This keeps the Player configuration to a minimum on each new installation. {% endhint %} Before any options can be sent from the CMS it is necessary to register the **Display** using one of the two methods available: 1. Use Code or 2. Manual Configuration #### Use Code * From the Player Options, select the **Connect** tab and click on **Use Code** to show a 6 character Activation Code. ![Use Code](https://2149703612-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOD5P6BGYveuzkbhjZRsq%2Fuploads%2Fgit-blob-9f818ea86e04e6d1effde883c8885a588c66f9f4%2Fwindows_installation_use_code.png?alt=media) {% hint style="info" %} Ensure that the form remains open until you have entered the code in your **Displays** page and the Player launches automatically. Closing this form will hide the code and will stop the configuration process. {% endhint %} * Now in the CMS, navigate to the **Displays** page and click on **Add Display (Code)**. ![Add Display Code](https://2149703612-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOD5P6BGYveuzkbhjZRsq%2Fuploads%2Fgit-blob-d1341ae8182aef297654f340a42fdd2b58e04ab1%2Fwindows_installation_add_display_code.png?alt=media) * Enter the code as shown on on the Player Options window. ![Enter Code](https://2149703612-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOD5P6BGYveuzkbhjZRsq%2Fuploads%2Fgit-blob-9c00a73f60d1473e6d4a646967fb10a80fa69434%2Fwindows_installation_add_enter_code.png?alt=media) * **Save** Once successfully configured, the activate Player page will automatically close. The Display will be registered, proceed to the **Display Authorisation** step to continue the set up. #### Manual Configuration Complete the required fields in the **Player Options** window, from the **Connect** tab: * **CMS Address:** This is the fully qualified address of your CMS installation. For example `https://cms.example.org or http://example.org/cms` * **CMS Key:** The secret CMS Key that will authenticate this Display with the CMS. {% hint style="info" %} The **CMS Key** can be viewed from the CMS using the Settings page located under the **Administration** section of the main menu, from the **Configuration** tab. {% endhint %} * **Local Library**: The location for the Player to store its local files. Files are downloaded from the CMS so that the Player will still function if it loses connection with the CMS. * Once all the fields have been completed click on the bottom **Connect** button. ![Manual Player Options](https://2149703612-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOD5P6BGYveuzkbhjZRsq%2Fuploads%2Fgit-blob-433affc76a1e91ede85c15b0ec8b6c4ece2f3d44%2Fwindows_installation_manual_player_options.png?alt=media) {% hint style="success" %} A message will be shown for the first successful connection! {% endhint %} Assuming there are no errors with the communication between the CMS and the Player, the Display will be registered and awaiting authorisation as detailed in the **Display Authorisation** step below. ### Advanced Player Options There are a few other settings that can only be set on the Player side from the **Advanced** tab, as explained below: The Player needs to have access to the CMS during the registration process and also to get new content. If the Player is behind a proxy server, the details of that server can be entered using the fields below. #### Proxy settings: * **Username** used to authenticate with the Proxy Server. * **Password** used to authenticate with the Proxy Server. * **Domain** used to authenticate with the Proxy Server. #### Other settings: * **Display ID** - The unique ID for this Display. An automatically generated unique ID will be assigned at installation but can be modified if appropriate. * **Splash Screen** - Optionally override the Splash Screen with an image stored locally on the Player PC. ## Display Authorisation Before the Player can receive Scheduled Events and display Layouts/Campaigns, you will need to **Authorise** the Display to connect to the CMS. * Click on "Display Admin" from the **Player Options** window or log in to the CMS and click on **Displays** from the main menu to see your newly registered Player in the list. * Use the row-menu for the newly added Player and select **Authorise** from the list: ![Display Row Menu](https://2149703612-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOD5P6BGYveuzkbhjZRsq%2Fuploads%2Fgit-blob-b686b9bf217826428d60bb5be3349ce70ec99938%2Fwindows_installation_display_authorise.png?alt=media) * Click **Yes** to confirm the authorisation of this Display. {% hint style="success" %} At this point, you may want to select a **Default Layout** for your new Player to run! {% endhint %} ### Display Setting Profiles Once registered, the Player will be given a default **Display Setting Profile**. ## Launch Xibo Player You can now select "Launch Player" from the **Player Options** window or go to all programs and click on Xibo Player. It should display the Xibo Splash Screen while the Default Layout and its media contents (and anything else you have Scheduled) are downloaded. The Player will then begin playing Layout contents. ## Windows Modifications Here are some suggested settings for Windows / PowerPoint for a Windows Display: * Turn off all screensavers. * Turn off screen power saving. * Load the "No Sounds" Sound Scheme (Control Panel -> Sounds and Audio Devices Properties) * Set a plain wallpaper (Hopefully nobody will see it, but you might need to reboot the Player, or restart Xibo and a sane wallpaper is a help). * If the Player is accessible from where you manage your Displays from, you might want to install UltraVNC server so you can connect in and check on the Player from time to time. Use the "View only" option in the VNC client to avoid disturbing the Display. * Set Windows to log on as your Xibo Player automatically. * Disable balloon tips in the notification area. ## HTML5 Xibo uses the Web Browser provided by Windows to display web content, tickers, text, etc. This browser component defaults to Internet Explorer 9 on most systems. ## PowerPoint Displays that will show **PowerPoint** should follow the Prepare your Windows Players section of the [PowerPoint](https://github.com/xibosignage/docs-admin/blob/master/manual/en/media_module_powerpoint.html) User manual page to confirm that the registry has been modified correctly for their version of Windows / PowerPoint. ## Thumbnail Database Windows automatically creates thumbnails for content in the User folder and will try to do so for the Xibo local Library. In some cases, this interferes with the normal operation of the Player and should be disabled. This can be achieved with the following registry settings: ``` [HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Policies\Explorer] "NoThumbnailCache"=dword:00000001 "DisableThumbnailCache"=dword:00000001 [HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Explorer\Advanced] "DisableThumbnailCache"=dword:00000001 "NoThumbnailCache"=dword:00000001 ``` **Please ensure you know what you are doing and have appropriate backups in place before modifying the registry!** # Multi Install - Windows Player Multiple instances of the **Windows Player** can be configured to run together on a single PC. This might be desirable if you have 1 PC that drives multiple screens which are not in an extended desktop configuration. **Please note:** Before choosing this route you should consider whether or not you want to show content spanning both screens - if you do, you must use the **extended desktop route** (and not run multiple instances). Please refer to our guide on [Creating a Video Wall with Xibo for Windows](https://community.xibo.org.uk/t/creating-a-video-wall-with-xibo-for-windows/15946) on how to accomplish this. ## Installing the Players You will need to install 1 copy of the Player normally following the [Installation instructions](https://xibo.org.uk/docs/setup/xibo-for-windows-installation). * ### Installing another Player using an Installer Package Starting with Xibo for Windows v2 R201, we have provided a "Screen Two" and "Screen Three" installation package on the [releases](https://github.com/xibosignage/xibo-dotnetclient/releases) page. We do not recommend running more than 3 instances of the player on one PC, but if you wish to do so you should follow the "Installing another player using an installer package manually" instructions for screen 4 onward. Follow the instructions for installing 1 player, but using the `XiboScreenTwo_v...` or `XiboScreenThree_v...` msi downloaded from the releases page. Before starting the Player, create a **Display Profile** in the CMS, see Positioning the Player section below. * ### Installing another Player Manually If you choose to manually create multiple instances of the Player application, then some leg-work is required in order to get the files in the correct place. Please follow the steps below: * Navigate to the Player installation folder. * Copy the entire folder and rename to something unique (for example a 2 at the end). * Navigate inside the new folder, rename XiboClient.exe to XiboClient2.exe. * Create a start-up shortcut to the new XiboClient2.exe file and right click. In the 'Target' field enter `o` after the `"` on the default path. (Providing the letter `o` in the startup arguments indicates that the options form should be opened instead of the main application). * Double click the shortcut and configure the second Player as normal making sure that you choose a **different library folder**. * Navigate inside the Watchdog subfolder, edit the `app.config` file, set the `ClientLibrary` to be the library folder you've configured above and set the `ProcessPath` to be the path to the renamed XiboClient2.exe. * Before starting the Player, create a display profile in the CMS to position the second Player - see below. * Double click the EXE and the Player should start. ## Configuring each player Your second player will have special configuration considerations to ensure it runs smoothly. ### Positioning the Player A Player by default will position itself on the Primary monitor in a full-screen configuration. You will want to change this behaviour for the second Player so that it does not appear underneath the first. This is done using a [Display Settings Profile](https://xibo.org.uk/manual/en/displays_settings.html) from the CMS. * Open a CMS connection and log in * Navigate to the **Display Settings** page, located under the Displays section of the main CMS menu and create a new **Windows Profile** called "Second Screen" or similar. * In the new profile configure the **Location** tab so that your left, top, width and height represent the second screen in your PC configuration. For example, if you have two 1920x1080 panels the second one would be at left=1920, top=0, width=1920, height=1080. You would enter different coordinates if the monitors are not 'side by side' or have different resolutions. You should, therefore, adjust the coordinates according to your setup. {% hint style="info" %} **Please note:** 0 width / 0 height means top left will be ignored and will be shown full screen. By specifying a width or height here will prevent entering full screen mode. {% endhint %} ### Embedded Web server The Player uses an embedded Web Server to show some content and it will be necessary to adjust the port that this web server listens on so that it does not conflict with the other Player. * Use the **Display Settings Profile** created when you positioned the Player and set the **Embedded Web Server** address, incrementing the port number on the one that is already there. ### Hardware Key You should make sure that the hardware key generated is different for each player installed on the same PC. * You can do this in player options. # Screen Saver - Windows Player Run Xibo as a screen saver. The Windows Player installs a `Xibo.scr` file in the installation program files. The Screen Saver can be installed by navigating to the Installation folder and right clicking on the `Xibo.scr` file, and selecting “Install”. This will present a windows screen saver configuration dialogue box, as shown below: ![Screen Saver](https://2149703612-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOD5P6BGYveuzkbhjZRsq%2Fuploads%2Fgit-blob-a9b86327f4b1341f3ae496dbfb4d38f05c39b9c6%2Fwindows_installation_screensaver.png?alt=media) ## Settings The Player options can be configured by clicking **Settings** in the screensaver dialogue. {% hint style="info" %} These settings will be independent of the settings configured on any existing Player on the same PC. {% endhint %} # Windows Player Watchdog The Watchdog is an optional component which can be used to monitor the stability of the main application and restart it where necessary. The Watchdog is installed into the same folder as the Windows Player during the Windows Player installation. ## Configuration file Configuration is managed though a configuration file located in the watchdog installation folder. The contents of the file is as below: ```
C:\Users\username\Documents\Xibo Library 120 300 C:\Program Files\Xibo\XiboClient.exe log.xml ``` The important part of the above configuration file is the settings between the `` element. ### Client Library The library location as configured in the Player. ### Polling Interval How often the watchdog should check for application activity. ### Threshold The threshold in seconds that the application has to be inactive before the watchdog will restart it. ### Process Path The fully qualified pathname to the application EXE that should be monitored. This will be used to restart the application when it is detected as being inactive. ### Log File Name This is the name of the log file as configured in the Player that is being monitored. Downtime events and restarts will be added to the end of the usual error log. ## Start with Windows A short cut to the watchdog EXE should be created and added to the Windows start up program group in the Start Menu. # Linux Player Installation The Linux Player app is released as a snap package, distributed via the Snap Store, which will provide updates to the Player. ## Minimum Requirements * Linux: Ubuntu LTS, x86-64 (for other Debian based distributions, ensure that they are piloted before an estate rollout) * Windows: 64-bit * Architecture: x86-64 only * Intel Core i3 or AMD equivalent, 8GB RAM, integrated graphics, 128GB SSD * Commercial-grade hardware rated for 24/7 operation * Minimum CMS version 4.5.2 * Outbound HTTPS to the CMS, and a web socket connection to XMR * Inbound on the embedded server port (default 9696), localhost only unless WAN access is explicitly enabled in the display settings profile {% hint style="warning" %} Installing the Linux Player App on a device that does not meet our minimum requirements will not qualify for helpdesk support when on one of our plans. {% endhint %} ## Installing the Linux Player App {% stepper %} {% step %} ### Install the Player App * Run: `snap install xibo-player --channel=stable` Or visit: or use the button below. [![Get it from the Snap Store](https://snapcraft.io/static/images/badges/en/snap-store-white.svg)](https://snapcraft.io/xibo-player) * select the Linux Player from the desktop/app drawer or open a terminal and run: `xibo-player` {% endstep %} {% step %} ### Connect to the CMS * Login to the CMS and navigate to the **Displays** page * From the Displays page in the CMS, select the **Add Display** button at the top of the grid * Enter the activation code as shown on the Player screen * Click to **Save** {% hint style="success" %} The Activate Player page will automatically close once successfully connected. {% endhint %} {% endstep %} {% step %} ### Authorise the Display * From the CMS, navigate to the **Displays** page * Use the row menu for the newly registered entry and select **Authorise** * Click **Yes** to confirm {% hint style="success" %} The Display is now ready to start showing content from the Xibo CMS {% endhint %} {% endstep %} {% endstepper %} ## Uninstalling You can safely delete the files the Player created in your temporary directory, and if you want to remove the Player from your system, simply run: ``` snap remove xibo-player ``` # Upgrading your Xibo Cloud Hosted CMS The CMS can be upgraded to later versions to take full advantage of all new features and the latest bug fixes. {% hint style="warning" %} We recommend that all users should upgrade when possible to the most current release. Prior releases are supported for a time after the release of a new major version. {% endhint %} Request an upgrade from **My Account**, by clicking the row menu button at the end of the CMS instance row, and then select **Upgrade**. The CMS can be set to automatically upgrade to new minor versions using the row menu and clicking on **Settings**: ![Auto Upgrade](https://2149703612-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOD5P6BGYveuzkbhjZRsq%2Fuploads%2Fgit-blob-dedaf21f67c51b5c9d50be839f1f8ee411e342ba%2Fupgrading_cms_auto_update.png?alt=media) * **Auto update in Series** - tick to automatically upgrade the CMS Instance as new minor versions become available for the CMS. * **Renew** - tick to renew this CMS instance when it expires. # Upgrading Docker Self hosted Install Before starting the upgrade, it’s strongly recommended to take a full backup of your Xibo system. ## Before attempting an upgrade Please be sure that your media and database files are being correctly written to the `shared` directory. This is particularly important if you are running on a Windows computer. To do so, upload for example an image into the CMS, and check that the same image appears in the `shared/cms/library` directory. Another good check is to make sure that `shared/backup/db/latest.sql.gz` was created within the last 24 hours. If either of those checks fail, please **do not proceed** with the upgrade as this will lead to data loss. Seek support to recover the situation. Before starting the upgrade, it’s strongly recommended to take a full backup of your Xibo system. `stop` your CMS by issuing the command: ``` docker-compose stop ``` and then, backup `config.env`, your docker-compose files, and `shared` directory and keep them somewhere safe. On a Linux system, you will need to be the `root` user, or use `sudo` to make a copy of the shared directory. Once you have a suitable backup of your CMS files, you can proceed with the upgrade process. ## Upgrade Process * Download the appropriate version of the [Docker Compose files](https://github.com/xibosignage/xibo-docker/releases) for the version of Xibo you want to upgrade to. * Extract the Docker Compose files over the top of your existing installation, replacing any existing files. If you are running the CMS on Custom Ports, then you will need to repeat the initial steps in the CMS installation process where you copied the template `cms_custom-ports.yml.template` file to `cms_custom-ports.yml` and make the appropriate modifications for the ports you want to use. If you made any other changes to the docker-compose files, you will need to make those modifications again. `config.env` will have been preserved, so you should not need to make any changes there. Specifically, do not change the MySQL password in that file. To perform the upgrade, run ``` docker-compose down docker-compose up -d ``` substituting the second command there for the appropriate `up` command if you’re using custom ports or a remote MySQL server. The CMS containers will be destroyed and rebuilt with the newer Xibo version. A database backup will be automatically run for you as part of this process. {% hint style="warning" %} The upgrade process can take a few minutes to complete. In the interim, the CMS will be unavailable. If the upgrade is fully successful, you should not see the upgrade wizard at all when you go to log in to the CMS. {% endhint %} {% hint style="warning" %} If you do see the upgrade wizard, you can attempt to work through it, however, please be wary of skipping upgrade steps unless you have a detailed knowledge that it is safe to do so. {% endhint %} The upgrade should now be complete for you. ## Rolling back the Version If you need to roll back to the older Xibo version for some reason, you can do so by running; ``` docker-compose down ``` restoring your original copy of `config.env` , the Docker Compose files and the `shared` directory, and finally running; ``` docker-compose up -d ``` The original version of the CMS will be restored for you. # Upgrade and switch to Docker Install Installations prior to 1.8 will be “Manual/Custom Installations" and should be migrated to Docker during the upgrade Follow the steps for your choice of platform, until you get to the step where the CMS is initially bootstrapped. *Do not run the `docker-compose up` command.* When you get to that step, please return here, and pickup. If your server is already running a web server, then you will need to pay specific attention to the instructions on running on custom port numbers. **Once you have Docker installed, and have extracted the Xibo Docker Release Archive, and created your config.env file, you should continue from this point.** In the same directory as you extracted the `docker-compose.yml` file, create the following directory structure; ``` shared | - backup - cms | - library ``` Copy the library files from your existing install in to `shared/cms/library` - so for example, you might have `shared/cms/library/10.jpg`. On your existing Xibo installation, empty your log table by using the CMS Web Portal to go to the `Log` page and clicking on `Truncate`, or by running `TRUNCATE log` from a MySQL prompt with your Xibo database selected. Export your database from your old installation by running the following, e.g. `mysqldump -u user -p database-name > shared/backup/import.sql`where `user` is the Xibo database user. You will be prompted for the password. You can find both those values in the `settings.php` file in your old Xibo installation directory. If you’re not comfortable using the mysqldump command, then see the following section **Exporting with PHPMyAdmin** which covers using PHPMyAdmin if you have that available, however, please note that PHPMyAdmin is known to have issues exporting very large database backups reliably. It is **CRITICAL** that your import.sql file contains only the Xibo database that you wish to upgrade. It must not contain multiple databases. Specifically, it must not contain a `USE db_name` command. Save your database export as `shared/backup/import.sql` We can now bring up the new CMS containers with your old data. Run the following; ``` docker compose up -d ``` or if you’re using a ‘custom ports’ or remote mysql docker-compose file, ``` docker compose -f custom.yml up -d ``` where custom.yml is that custom file you’ve created. That will cause the containers to be created for your database, web server and XMR server. After a period of time (allow up to 10 minutes), you should see the CMS webpage appear at `http://localhost` or `http://localhost:port` if you’re running on a custom port. Since we’re importing a non-Docker based installation, there’s a couple of additional steps to take which require direct modification of the database. If you’re running with an external database, then please run the SQL commands listed below directly on your remote database instead of running these commands from inside the Docker console. First, run `docker ps` to list all running docker containers, and find there the name of the database container. It will be the one with `web` in the name - so for example `Xibo_cms-web_1`. Once you have the database container name, run the following to get to a shell inside the web container; ``` docker exec -ti Xibo_cms-web_1 bash ``` Next, run the following; ``` mysql -h mysql -u cms -p cms ``` You will be prompted for a password. It will be the one that you chose in config.env for MySQL. Assuming the correct password is entered, you’ll be presented with a MySQL command prompt. Run the following commands; ``` UPDATE `setting` SET `value`="/var/www/cms/library/", userSee=0, userChange=0 WHERE `setting`="LIBRARY_LOCATION"; UPDATE `setting` SET `value`="tcp://cms-xmr:50001", userSee=0, userChange=0 WHERE `setting`="XMR_ADDRESS"; UPDATE `setting` SET `value`="Apache" WHERE `setting`="SENDFILE_MODE"; exit ``` Run `exit` again to return to your local machine shell. Finally, delete any files inside `shared/cms/library/cache` directory (you may need to use sudo or be the root user on a Linux system to do so). You should then be able to log on to the upgraded web interface using an administrative user account. The password will be the same as your old installation used. ## Exporting with PHPMyAdmin The example above uses `mysqldump` , however, if your environment does not have `mysqldump` it is possible to use `phpmyadmin` to generate a backup. Care must be taken to ensure that a database is selected in the left-hand pane **before** going to the export tab. Failure to do this will result in the export containing the existing database name, which may not match the new name in Docker. Step 1: ![Truncate Logs](https://2149703612-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOD5P6BGYveuzkbhjZRsq%2Fuploads%2Fgit-blob-1e05d00cb1d58623cc5f1429c6818fb45563a14e%2Fswitch_to_docker_truncate_logs.png?alt=media) Step 2: ![Export Database](https://2149703612-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOD5P6BGYveuzkbhjZRsq%2Fuploads%2Fgit-blob-c7722f98549f70a1b936d1ee9cbdf66844192485%2Fswitch_to_docker_export_database.png?alt=media) # CAS as an Authentication Provider The CMS can be configured to use CAS as its authentication provider > *The **Central Authentication Service** ( **CAS** ) is a single sign-on protocol for the web. Its purpose is to permit a user to access multiple applications while providing their credentials (such as userid and password) only once. It also allows web applications to authenticate users without gaining access to a user’s security credentials, such as a password. Wikipedia* CAS integration is enabled via the `settings.php` file in the CMS installation. If Docker has been used `settings.php` will not be accessible, however, it is possible to create a `settings-custom.php` file in the `/custom` mount point. The below Configuration can be added to that file instead. The purpose of the integration is to configure a CAS enabled IdP (identity provider) for authentication with the Xibo CMS. A User already authenticated with the IdP will automatically be logged into the CMS. If the User does not exist they will optionally be created with a set of default credentials. ## Configuration CAS integration is configured in the `settings.php` file of the CMS installation. This file can be found in your `/web` folder. There are two sections to adjust, the `$authentication` middleware and the `$samlSettings` configuration array. * ### Middleware The authentication middleware should be changed to `CASAuthentication` , shown below: ``` $authentication = new \Xibo\Middleware\CASAuthentication(); ``` * ### CAS Settings The CAS settings array contains all the necessary information for the CMS to connect and use a CAS enabled IdP. The configuration is split into 3 main sections: * `server` : options for the server provider (these are used by the CMS to identify and communicate with the identity provider). * `port` : specify which port to use. * `uri` : the location of the CAS application at the `server` specified above. ### Example Settings ``` $authentication = new \Xibo\Middleware\CASAuthentication(); $casSettings = array( 'config' => array ( 'service_base_url' => 'https://*url of xibo server*', 'server' => 'your.cas.server', 'port' => '443', 'uri' => '/cas', ) ); ``` # SAML as an Authentication Provider The CMS can be configured to use SAML as its authentication provider > *Security Assertion Markup Language (SAML, pronounced sam-el) is an XML-based, open-standard data format for exchanging authentication and authorization data between parties, in particular, between an identity provider and a service provider. Wikipedia* SAML integration is enabled via the `settings.php` file in the CMS installation. If Docker has been used `settings.php` will not be accessible, however, it is possible to create a `settings-custom.php` file in the `/custom` mount point. The below Configuration can be added to that file instead. The purpose of the integration is to configure a SAML enabled IdP (identity provider) for authentication with the Xibo CMS. A User already authenticated with the IdP will automatically be logged into the CMS. If the User does not exist they will optionally be created with a set of default credentials. ## Configuration SAML integration is configured in the `settings.php` file of the CMS installation. This file can be found in your `/web` folder. There are two sections to adjust, the `$authentication` middleware and the `$samlSettings` configuration array. * ### Middleware The authentication middleware should be changed to `SAMLAuthentication` , shown below: ``` $authentication = new \Xibo\Middleware\SAMLAuthentication(); ``` * ### SAML Settings The SAML settings array contains all the necessary information for the CMS to connect and use a SAML enabled IdP. The configuration is split into 4 main sections: * `idp`: options for the identity provider (these are used by the CMS to identify and communicate with the identity provider). The values for these settings can be found in the IdP. * `sp`: options for the service provider (these are sent by the CMS to the identity provider so that the IdP can communicate back to the CMS). The CMS URL for the target installation should be used in these settings. * `security`: options to enable security as required by the IdP. * `workflow`: CMS specific options to determine how to map the data from the IdP to data in Xibo. This section is used to determine the mapping between the IdP and the CMS. If *single logout* is disabled selecting ‘log out’ in the CMS won’t have any effect as the User will be immediately logged in again on the next request. ## Just-in-time provisioning (JIT) Just-in-time provisioning can be enabled in the workflow section. With JIT provisioning, enabled Users that visit the CMS, who do not currently have an account, are automatically created. If the intention is to use JIT then it is required to define what information should be used to create the User in the CMS. If the IdP does not provide any attributes, it is important to exclude the `mapping` property of the `workflow` settings. ## Example settings ``` $samlSettings = array ( 'workflow' => array( // Enable/Disable Just-In-Time provisioning 'jit' => true, // Attribute to identify the user // if set to nameId then the NameID from SAML will be taken and used as the // username in Xibo. 'field_to_identify' => 'UserName', // Alternatives: UserID, UserName, email // Default libraryQuota assigned to the created user by JIT 'libraryQuota' => 1000, // Initial User Group 'group' => 'Users', // Home Page 'homePage' => 'icondashboard.view', // Enable/Disable Single Logout 'slo' => true, // Attribute mapping between XIBO-CMS and the IdP 'mapping' => array ( 'UserID' => '', 'usertypeid' => '', 'UserName' => 'uid', 'email' => 'mail', 'ref1' => '', 'ref2' => '', 'ref3' => '', 'ref4' => '', 'ref5' => '' ) ), // Configure the IdP and SP 'strict' => false, 'debug' => true, 'idp' => array ( 'entityId' => 'https://idp.example.com/simplesaml/saml2/idp/metadata.php', 'singleSignOnService' => array ( 'url' => 'http://idp.example.com/simplesaml/saml2/idp/SSOService.php', ), 'singleLogoutService' => array ( 'url' => 'http://idp.example.com/simplesaml/saml2/idp/SingleLogoutService.php', ), 'x509cert' => 'MIICbDCCAdWgAwIBAgIBADANBgkqhkiG9w0BAQ0FADBTMQswCQYDVQQGEwJ1czETMBEGA1UECAwKQ2FsaWZvcm5pYTEVMBMGA1UECgwMT25lbG9naW4gSW5jMRgwFgYDVQQDDA9pZHAuZXhhbXBsZS5jb20wHhcNMTQwOTIzMTIyNDA4WhcNNDIwMjA4MTIyNDA4WjBTMQswCQYDVQQGEwJ1czETMBEGA1UECAwKQ2FsaWZvcm5pYTEVMBMGA1UECgwMT25lbG9naW4gSW5jMRgwFgYDVQQDDA9pZHAuZXhhbXBsZS5jb20wgZ8wDQYJKoZIhvcNAQEBBQADgY0AMIGJAoGBAOWA+YHU7cvPOrBOfxCscsYTJB+kH3MaA9BFrSHFS+KcR6cw7oPSktIJxUgvDpQbtfNcOkE/tuOPBDoech7AXfvH6d7Bw7xtW8PPJ2mB5Hn/HGW2roYhxmfh3tR5SdwN6i4ERVF8eLkvwCHsNQyK2Ref0DAJvpBNZMHCpS24916/AgMBAAGjUDBOMB0GA1UdDgQWBBQ77/qVeiigfhYDITplCNtJKZTM8DAfBgNVHSMEGDAWgBQ77/qVeiigfhYDITplCNtJKZTM8DAMBgNVHRMEBTADAQH/MA0GCSqGSIb3DQEBDQUAA4GBAJO2j/1uO80E5C2PM6Fk9mzerrbkxl7AZ/mvlbOn+sNZE+VZ1AntYuG8ekbJpJtG1YfRfc7EA9mEtqvv4dhv7zBy4nK49OR+KpIBjItWB5kYvrqMLKBa32sMbgqqUqeF1ENXKjpvLSuPdfGJZA3dNa/+Dyb8GGqWe707zLyc5F8m', ), 'sp' => array ( 'entityId' => 'http://xibo-cms.example.com/saml/metadata', 'assertionConsumerService' => array ( 'url' => 'http://xibo-cms.example.com/saml/acs', ), 'singleLogoutService' => array ( 'url' => 'http://xibo-cms.example.com/saml/sls', ), 'NameIDFormat' => 'urn:oasis:names:tc:SAML:2.0:nameid-format:emailAddress', 'x509cert' => '', 'privateKey' > '', ), 'security' => array ( 'nameIdEncrypted' => false, 'authnRequestsSigned' => false, 'logoutRequestSigned' => false, 'logoutResponseSigned' => false, 'signMetadata' => false, 'wantMessagesSigned' => false, 'wantAssertionsSigned' => false, 'wantAssertionsEncrypted' => false, 'wantNameIdEncrypted' => false, ) ); ``` {% hint style="warning" %} **Please note:** `homePage` => `icondashboard.view` needs to be replaced if you are using a CMS earlier than v3: Earlier than v3 - replace `icondashboard.view` with `icondashboard` Earlier than v2.0.3 - replace `icondashboard.view` with `dashboard` {/tip} {% endhint %} Further explanation of the SAML specific settings can be found at [GitHub - onelogin/php-saml: Simple SAML toolkit for PHP](https://github.com/onelogin/php-saml#settings). # SAML Single Sign on with Active Directory - ADFS Xibo can be setup to authenticate against any SAML 2.0 IdP. Microsoft Active Directory Federation Services can be configured to act as such an IdP * Firstly, install the ADFS role on your server. You will need a valid SSL certificate for the URL you intend to publish your IdP on. In this example, I’m publishing an IdP at `https://fs.test.alexharrington.co.uk`. This IdP won’t exist by the time this article is published. Similarly, your Xibo CMS will need to be hosted on a server protected by a valid SSL certificate. Once the IdP is installed, ensure you can access the IdP webpage at the URL you have configured from both your Xibo CMS Server, and from the Client computers that your users will use to authenticate against. {% hint style="info" %} Visiting, for example, `https://fs.test.alexharrington.co.uk/adfs/ls/` should bring up a webpage served by ADFS with an error. That’s normal. We’re just checking connectivity here. {% endhint %} First we need to export the signing certificate from ADFS. * Open the ADFS console, go to `Service > Certificates` and find the `Token-signing` certificate. ![ADFS Console](https://2149703612-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOD5P6BGYveuzkbhjZRsq%2Fuploads%2Fgit-blob-9aadf27603a07343f5b0335cf0449b598bfd9aa3%2Fsaml_adfs_console.png?alt=media) * Right click on it, and choose `View Certificate`. * Move to the `Details` tab, and click `Copy to File`...: ![Certificate Details](https://2149703612-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOD5P6BGYveuzkbhjZRsq%2Fuploads%2Fgit-blob-fb104166d56ed80c0e0c4be9ba8f43d8802f84e3%2Fsaml_adfs_certificate_details.png?alt=media) * Choose `Base-64 encoded X.509` format, and save the file somewhere convenient: ![Certificate Export](https://2149703612-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOD5P6BGYveuzkbhjZRsq%2Fuploads%2Fgit-blob-66bb9f559b1ef355be29fcbb021bef763280287d%2Fsaml_adfs_certificate_export.png?alt=media) * Now on your Xibo CMS, edit your `settings.php` or `settings-custom.php` file, and add in the example SAML configuration below: ``` $authentication = new \Xibo\Middleware\SAMLAuthentication(); $samlSettings = array ( 'workflow' => array( // Enable/Disable Just-In-Time provisioning 'jit' => true, // Attribute to identify the user 'field_to_identify' => 'email', // Alternatives: UserID, UserName or email // Default libraryQuota assigned to the created user by JIT 'libraryQuota' => 1000, // Initial User Group 'group' => 'Users', // Home Page 'homePage' => 'icondashboard.view', // Enable/Disable Single Logout 'slo' => false, // Attribute mapping between XIBO-CMS and the IdP 'mapping' => array ( 'UserID' => '', 'usertypeid' => '', 'UserName' => 'uid', 'email' => 'mail', ) ), // Settings for the PHP-SAML toolkit. // See documentation: https://github.com/onelogin/php-saml#settings 'strict' => false, 'debug' => true, 'idp' => array ( 'entityId' => 'https:///saml/acs', 'singleSignOnService' => array ( 'url' => 'https:///adfs/ls', ), 'singleLogoutService' => array ( 'url' => 'http://idp.example.com/simplesaml/saml2/idp/SingleLogoutService.php', ), 'x509cert' => '', ), 'sp' => array ( 'entityId' => 'https:///saml/acs', 'assertionConsumerService' => array ( 'url' => 'https:///saml/acs', ), 'singleLogoutService' => array ( 'url' => 'https:///saml/sls', ), 'NameIDFormat' => 'urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress', 'x509cert' => '', 'privateKey' > '', ), 'security' => array ( 'nameIdEncrypted' => false, 'authnRequestsSigned' => false, 'logoutRequestSigned' => false, 'logoutResponseSigned' => false, 'signMetadata' => false, 'wantMessagesSigned' => false, 'wantAssertionsSigned' => false, 'wantAssertionsEncrypted' => false, 'wantNameIdEncrypted' => false, ) ); ``` Be sure to replace: * `` with the URL of your ADFS server * `` with the URL of your Xibo CMS * `` with the text contents of the certificate you exported from ADFS, all on one line, excluding the `-----BEGIN CERTIFICATE-----` and `-----END CERTIFICATE-----` lines {% hint style="warning" %} **Please note:** `homePage` => `icondashboard.view` needs to be replaced if you are using a CMS earlier than v3.x: Earlier than v3.x - replace `icondashboard.view` with `icondashboard` Earlier than v2.0.3 - replace `icondashboard.view` with `dashboard` {% endhint %} **Save** the file, and now your CMS will redirect to your SAML IdP when you go to login. * Back in the ADFS console, go to `Trust Relationships -> Relaying Party Trusts` * Select `Add Relaying Party Trust` to start the Wizard. * At the `Select Data Source` step, enter the SAML metadata URL for your CMS - so for example `https:// add(store = "_OpaqueIdStore", types = ("http://xibo/internal/persistentId"), query = "{0};{1};{2}", param = "ppid", param = c.Value, param = c.OriginalIssuer); ``` * Add a second rule, and choose the type `Transform an Incoming Claim`. Call this rule `Create Persistent Identifier 2`, and configure as follows: ![Edit Rule](https://2149703612-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOD5P6BGYveuzkbhjZRsq%2Fuploads%2Fgit-blob-2b138d34ea45ab1be99f712fcf120af9019e6882%2Fsaml_edit_rule.png?alt=media) * Finally add a third rule, of type `Send LDAP Attributes as Claims`. Name it `User Info`, and set it up as follows: ![User Info](https://2149703612-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOD5P6BGYveuzkbhjZRsq%2Fuploads%2Fgit-blob-cf6ddb16ab7b75cb772c41a66ed7cca997900eb8%2Fsaml_user_info.png?alt=media) You should now be able to log in to your Xibo CMS as any user inside Active Directory. {% hint style="warning" %} Please ensure all users have a valid email address set on their Active Directory User account. Users will be created in Xibo using the Active Directory SAM-Account-Name as the username, and E-Mail address from the E-Mail Addresses field. {% endhint %} # Configure Wake on LAN Wake on LAN is supported if the media player hardware supports it and if the signage Player is addressable by the CMS {% hint style="success" %} In this case, “addressable” means that there is a clear network route between the CMS and the Player hardware. {% endhint %} {% hint style="warning" %} Wake on LAN is not supported with Docker installations as the CMS will be running on a different network to the host machine {% endhint %} Assuming the hardware and network supports Wake on LAN, it is configured in the **CMS** using the **Display Edit Form**. * Click on **Displays** from the main CMS menu. * Use the row menu for the chosen **Display** and select **Edit**. * Use the **Wake on LAN** tab to configure: ![Wake on LAN](https://2149703612-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOD5P6BGYveuzkbhjZRsq%2Fuploads%2Fgit-blob-477371d2495a2c4eb0eae684f38f8412426b550b%2Fwake_on_lan_edit.png?alt=media) {% hint style="success" %} An immediate WOL message can be sent to the **Display** for testing purposes using the Display row menu and selecting **Wake on LAN**. {% endhint %} {% hint style="warning" %} The [maintenance module](/setup-docs/cms-installation/cms-maintenance) must be correctly configured for a timed WOL message to be sent. {% endhint %} {% hint style="success" %} There are a few different options for putting the Player to sleep - such as a **Scheduled Task** or [Shell Command](https://xibo.org.uk/docs/setup/command-functionality) {% endhint %} # Using MongoDB to store Proof of Play and other time series data. From v2.1 the CMS can be configured to use MongoDB to store Proof of Play statistics and other time series data. MongoDB is enabled via the `settings.php` file in the CMS installation. If Docker has been used `settings.php` will not be accessible, however, it is possible to create a `settings-custom.php` file in the `/custom` mount point. The below **Configuration** can be added to that file instead. ## Configuration Please ensure you have Xibo version 2.1.0 or later before enabling MongoDB. You will also need to have a working MongoDB instance with a user and database created. Add a new variable called `$timeSeriesStore` to your settings file. The variable should be a function which returns a `\Xibo\Storage\MongoDbTimeSeriesStore` created with your MongoDB connection details. ```php $timeSeriesStore = function() { return new \Xibo\Storage\MongoDbTimeSeriesStore([ 'host' => 'mongo', 'port' => '1234', 'database' => 'db_name', 'username' => 'user', 'password' => 'password' ]); }; ``` ## Mongo Indexes We recommend adding an index to the `stat` collection in your MongoDB database. To do this from the console, make sure you have your database selected and then: ``` db.stat.ensureIndex({ "start": -1, "end" : -1, "type": 1}, {background: true}) ``` ## Migrating Unless your CMS is a brand new installation you will likely have existing proof of play data which you want to move into MongoDB in a controlled fashion. Xibo provides a migration task to achieve this which can be enabled by clicking on **Tasks** under the **Administration** section of the main CMS menu. We have provided a set of default options for the task which you may want to adjust according to your environment. The default options intend to provide a slow and steady migration of your existing data. #### Available options: * killSwitch (0 or 1 to completely disable processing) * numberOfRecords (how many to process each time) * numberOfLoops (how many loops to do per task run) * pauseBetweenLoops (how long to wait between each loop) * optimiseOnComplete (issue an OPTIMIZE TABLE stat after truncating) * configOverride (an optional path to a JSON file containing overrides for all of the above settings) If you already use the StatsArchiver task it will be disabled during migration to prevent conflicts. Nothing will be deleted from the `stat` table in the MySQL database until the migration has completed. # Power BI Authentication Setup The Xibo Dashboard Service does not support Microsoft Authenticator as a two factor method for the Power BI Xibo Dashboard Service authentication. This guide will take you through the required steps using the Authenticator App to obtain the secret key required for configuration to enable the Power BI Dashboard. First go to `https://mysignins.microsoft.com/security-info` ![Security Info](https://2149703612-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOD5P6BGYveuzkbhjZRsq%2Fuploads%2Fgit-blob-b15528842bf63f276f315eeabb74eec7453105cc%2Fdashboards_security_info.png?alt=media) * Click **Add sign-in method** * Select **Authenticator App** from the **Add a method** form: ![Add a method](https://2149703612-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOD5P6BGYveuzkbhjZRsq%2Fuploads%2Fgit-blob-c5afd3d40e558924d5ef30d51071f6a108895b12%2Fdashboards_authenticator_method.png?alt=media) The **Microsoft Authenticator** box will open. * Select the bottom option **I want to use a different authenticator app**: ![Microsoft Authenticator](https://2149703612-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOD5P6BGYveuzkbhjZRsq%2Fuploads%2Fgit-blob-89163665fec75b222a1e73c1faad2ceec381476d%2Fdashboards_microsoft_authenticator.png?alt=media) * Click on the "**Can't scan image?**" text to reveal the **Secret key**. * Copy this key for later to enter into the **Second Factor secret** field when at the Configuring the Power BI connector stage. * Next scan the QR code using Google Authenticator, Microsoft Authenticator or similar and click Next. * Complete the setup by entering the 6 digit code as shown on your chosen authenticator app. ![QR Code](https://2149703612-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOD5P6BGYveuzkbhjZRsq%2Fuploads%2Fgit-blob-3f8b075c4fc81211319ac91bf09df380a1933a9c%2Fdashboards_qr_code.png?alt=media) {% hint style="info" %} On returning to the Security Info page at `https://mysignins.microsoft.com/security-info`, ensure that no other sign in methods are enabled! {% endhint %} # Canva Integration Designs created in Canva can be published directly into a Xibo Layout without having to leave the Canva dashboard The **Xibo Canva App** allows exporting designs directly into the CMS Library or into a Layout, with additional features available. * Install the **Xibo App** from the Canva's Apps marketplace. * Once installed, click on the app from the left hand navigation menu to open the Xibo App panel. You will be asked to 'Connect' the first time you publish to Xibo or if you haven't published to Xibo in a while. ### Connecting Canva to the Xibo CMS * Click **Connect**, to open the Xibo popup. The URL should be "canva.xibosignage.com" with the padlock icon present, to denote a secure connection. * Enter your full **CMS URL**, including https\:// * Click **Connect** and follow the connection steps for your CMS below.
Cloud Hosted CMS * Clicking **Connect** will take you directly to your CMS and ask you to **login**. * Click **Approve** to grant Canva full access.
Self Hosted CMS You will be prompted to enter a **Client ID** and **Client Secret** into the Connect to Xibo popup. To get these credentials: * Login to your CMS as a **Super Administrator User** and navigate to the **Applications** page to access the **Canva Connector**. * Tick **Authorisation Code**. * Tick **Is Confidential**. * Enter in the **New Redirect URI** field. * From the **Sharing** tab, tick Access to Library, Layouts, Playlists, Widgets and Resolutions for Scopes. * Make a note of the **Client ID** and **Client Secret**. * Click to **Save**. * Enter the Client ID and Client Secret into the **Connect to Xibo** popup. * Click **Register**. {% hint style="success" %} Once you have registered you will be taken back to your CMS to complete the approval to grant Canva access. {% endhint %}
### Xibo Canva App Features Once connected, the Xibo Canva App provides a set of features to help you publish and reuse content from your CMS. These features are organised into two main tabs: {% tabs %} {% tab title="Publish Tab" %} The **Publish** tab is where you send your Canva designs to the Xibo CMS: * Export your design either as a complete Layout or as a Media file to save in the CMS Library, to give flexibility in how the content is later used. * Open the connected Xibo CMS directly from Canva to quickly view and manage the designs you have published. ### Publishing a Design as a Layout or to the Media Library * From the Xibo App panel, go to the **Publish** tab. * From the **Destination** dropdown, select from **Publish as Layout** or **Publish to Library**. * Click **Continue to export**. The Canva export panel will open for the following configuration steps: * Select a File type: JPG or PNG * Adjust the Size and Quality sliders as needed * Use the **Select pages** dropdown to choose which pages to include * Once ready, click **Export** to begin publishing. * After export is complete, a success message will appear with a link to view the design. * Select **Click here to View**, Canva will show a confirmation that you are leaving the site to open the Xibo CMS. * Click **Continue** to view the exported design in the CMS. * If the design was exported as a **Layout**, you will be taken to the Layout Editor. * If the design was exported to the **Library**, you will be taken to the media file’s preview page. {% hint style="info" %} When exporting multiple pages to the Library, the preview page will only display the first image. Each page is saved as a separate media file and can be found in the **Media** grid under the Library section of the main CMS menu. {% endhint %} {% endtab %} {% tab title="Import Tab" %} The **Import** tab is where you can bring media from your Xibo CMS into Canva: * Browse through existing CMS media assets, use the search bar to find what you need and upload selected items into your Canva workspace so they can be added directly to your design. ### Uploading Images from CMS to Canva Once the Xibo App has been successfully connected to your CMS, the **Import** tab will automatically load media from the CMS Media Library and display it in a grid. * Use the search bar at the top to quickly locate specific images. * Add an image to your design by **dragging** the image directly from the grid onto the Canva page. * Or by **clicking** the image to upload to your Canva Library and automatically insert into the current active design page. {% hint style="warning" %} Canva doesn’t allow the Xibo App to delete or overwrite items in your Canva Media Library. If you want to manage or remove files, you’ll need to do it manually from the **Uploads** panel. If you click or drag the same image again in the Xibo App, it will be reuploaded as a new file, even if it already exists in your Canva Library. {% endhint %} {% endtab %} {% endtabs %} ## FAQs
What file formats can be published to Xibo? *Currently JPG and PNG image formats can be published to Xibo.* *We are working with the Canva team to offer more formats in the future!*
What about white labelling? *Unfortunately the Canva app cannot be white labelled*.
I have an error message in Canva “Problem publishing design”? *If a User deletes the standard “1080p HD Landscape / 1080p HD Portrait” resolutions within their CMS, the User publishing from Canva will need to have* [*Feature access/Permission*](https://xibo.org.uk/manual/en/users_features_and_sharing.html) *to create resolutions in order to successfully publish.*
Where can I get support with the Canva app? *If you are a Xibo Cloud hosting customer then please open a* [*Ticket*](https://xibosignage.com/my-account/tickets?open=true) *via My Account. If you are self-hosting/on-prem then please create a topic in the* [*Get Help*](https://community.xibo.org.uk/c/support/6) *section on the Xibo Community.*
Can I connect an on-premise CMS? *Yes you can, but Canva and the Xibo Canva app need access to your CMS over HTTPS to publish your designs. If your CMS is only available via HTTP, or on a private network, it will not be possible to use the app.*
I’m getting the following Canva connection error {"error":"invalid_client","error_description":"Client authentication failed","message":"Client authentication failed"} ? *The error message indicates incorrect client information, manually correct your CMS credentials by visiting this link:* [*Register | Xibo Canva Connector*](https://canva.xibosignage.com/register)
Why can I no longer use the Canva Publish option to send my designs directly into a Layout? *We received notice that the Publish extension would be retired by Canva and we implemented the new Design Publisher App, ahead of the retirement date. This extension is now no longer available from Canva, however, the new Design Publisher intent in the Apps SDK unlocks additional functionality which was previously not possible with the Publish Extension.*
# Xibo Dashboard Service The Xibo Dashboard connector is an add-on service from Xibo Signage which enables simple and secure connection to a variety of 3rd party services. We securely connect to the 3rd party, save your credentials and capture dashboards for display on your signage network. [Supported Services](#dashboard-service-providers) Enable this service with an API key from Xibo Signage {% hint style="info" %} **Please note:** This commercial feature is available from v3.2.0 and is included with both the Business and Enterprise [Plans](https://xibosignage.com/pricing). If you are on the Professional Plan or use a self-hosted CMS the Xibo Dashboard Connector is available for purchase separately. Further information can be found on our [website](https://xibosignage.com/pricing#dashboards) {% endhint %} Once purchased, an API key will be made available in My Account which is used to Configure the Connector for the Xibo Dashboard Service. {% hint style="success" %} If your CMS is hosted in our [Cloud](https://xibosignage.com/hosting) the connector will be available in your CMS on upgrading to v3.2.0. {% endhint %} {% hint style="success" %} If you are a Business or Enterprise customer your API key will be pre-filled for you.Your CMS requires access to `https://api.dashboards.xibosignage.com` and `https://xibo-dashboard.fra1.digitaloceanspaces.com` for the Dashboard Connector to function! Players do not directly contact the Xibo Dashboard Service. {% endhint %} {% hint style="danger" %} The Dashboard Service `api.dashboards.xibosignage.com` also requires access to the 3rd party providers you wish to connect to. 3rd party services behind a firewall will not work unless access can be granted. {% endhint %} Configuration also requires a User to supply dashboard credentials in the CMS for Xibo to authenticate with the 3rd party service. Xibo does not store these credentials in the CMS. They are securely stored and encrypted in our credential manager. We strongly recommend that you use a dedicated account for Xibo to log in to your 3rd party services with. This is sometimes referred to as a service account. This account should only have access to the dashboards that you wish to show with the Xibo Dashboard service, and should not use credentials that can be used for any other service. {% hint style="warning" %} Once credentials have been entered and the form has been accepted they cannot be retrieved from the CMS. {% endhint %} Once the Connector has been successfully configured, Users can add Dashboards to display in Layouts using the Dashboards Widget {% hint style="warning" %} The minimum refresh interval that can be entered per dashboard is 5 minutes as we do not support dashboard service updates more frequently than 5 minutes. {% endhint %} On first entering a URL into the Dashboard Widget it may take a few moments to load as it is dependent on how long it takes to render your dashboard content, and how busy the service currently is. Once you are showing your dashboards on displays, the service will keep your dashboards updated at the interval you specify so it will always be ready to show and appear instantly on Displays. If you stop showing a dashboard on your displays for a time, then the service will stop refreshing it, but will start again automatically the next time that dashboard is shown. ### Operation and Security Showing “dashboard” style content has long been desirable in the digital signage world, however doing so securely has always been problematic. Each vendor has its own authentication system, and those which offer a way to embed content directly involve making that data available at a public URL, which is not very secure in itself. Those embed pages often use large amounts of javascript and require a powerful computer to render properly. The class of devices used for digital signage players is often a lower power Android or SoC device, or lower spec Windows PC, and they are not capable of rendering that content in a reasonable timeframe. Xibo has developed its own Dashboards service, which allows you to input the URL of a report or dashboard you want to show within a [supported service](#dashboard-service-providers), and have that shown on your Players without the Players needing to have credentials to access that service, and with that content rendered quickly and efficiently. To enable this, users Configure Credentials for the service they wish to use inside their CMS. Passwords and TOTP secrets are securely encrypted (using AES 128 bit CBC with a SHA-256 HMAC) and stored inside Xibo’s Dashboard Service. They are not held in the CMS, and once input it’s impossible to retrieve them again from the CMS. Users then configure the dashboards that they want their displays to show, and the dashboard service will log in to that service on your behalf, load the content you’ve asked it to show, and then send a static image capture of that dashboard and store it on encrypted storage within DigitalOcean’s Spaces service. When a display wants to show that dashboard, it requests it from the CMS which will authorise or reject the request, and if authorised it will connect to the **Xibo Dashboard Service** and download the latest image and pass it to the Player, without storing it in the CMS or on the Player storage. Provided the Player connected to your CMS continues to request that dashboard periodically then the Xibo Dashboard Service will continue to keep the stored image updated at the interval you specify. If you stop requesting a specific dashboard, then the service will stop updating that stored image after 10x the interval you’ve specified and will delete it completely after a period of 20x the interval. {% hint style="info" %} For example if you have a dashboard that is set to be updated every 1 hour, then if the last request for it was more than 10 hours ago, the service will stop refreshing the stored image of it, and after 20 hours will delete it completely. It will be automatically re-added the next time that a Player tries to show that image. {% endhint %} Our Dashboards service is run from Hetzner's Falkenstein data centre and DigitalOcean’s Frankfurt data centre, and you will see connections to the services you configure coming from an IP in those locations. This is normal. {% hint style="success" %} Our support team can provide you with a list of the current IP addresses in use, although these do change from time to time. {% endhint %} All users of the CMS for which the Dashboards connector has been enabled can use the connector to show dashboards from that service. You should not install the Dashboards connector on a multi-tenanted CMS since you cannot prevent users from one tenant from accessing services authenticated by another within the same CMS. It’s not possible to store multiple credentials for each service type inside the same CMS instance. ### Dashboard Service Providers ### Power BI
Obtaining a URL You can use the page URL for your Report directly inside Power BI. If you need to pre-configure options within the Report: * Set those options and then bookmark that using the bookmark icon at the top right of the screen. * Select “Add a personal bookmark” and then give the bookmark a name: ![Personal Bookmarks](https://2149703612-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOD5P6BGYveuzkbhjZRsq%2Fuploads%2Fgit-blob-926d34d678f1237aa95f9552897f7d16906b70cf%2Fdashboards_powerbi_personal_bookmarks.png?alt=media) * Go back to the bookmark menu and select your bookmark. * Copy the URL from your browser and use that with the Dashboard service. {% hint style="success" %} You can increase the quality of the image captured by the service by adding `&chromeless=true` to the end of the URL. {% endhint %} **Supported authentication mechanisms** The Xibo Dashboard Service supports the native Power BI authentication mechanism using your Microsoft Account, including a TOTP based second factor authentication code. We do not support the two factor method for Microsoft Authenticator. {% hint style="success" %} To obtain a secret key to configure the Power BI Dashboard, follow the steps provided in this guide [Power BI Authentication Setup](/setup-docs/cms-configuration-and-integration/xibo-dashboards-power-bi-authentication-setup) {% endhint %} This service does not support SAML-based login. Please ensure the user credentials you provide will work at **Limitations** Your report must load within 60 seconds of the report URL being opened in the browser. Some reports that use Direct Query may take longer than this. In that case, the report will be captured at the 60 second mark and the resulting image returned.
### Grafana
Obtaining a URL * Log in to Grafana and open the dashboard you wish to show. * At the top right of the screen change the “Refresh” interval to 5m. This is so if your dashboard takes a long time to load fully, some elements are not trying to refresh before the first elements have fully loaded. * Click the “Cycle View Mode” button once to remove the menus and again if you want to remove the dashboard title. ![Cycle View Mode](https://2149703612-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOD5P6BGYveuzkbhjZRsq%2Fuploads%2Fgit-blob-61824a4afac107540217c20e54a1e31ae3303427%2Fdashboards_grafana_cycle_view_mode.png?alt=media) * Refresh settings. * Copy the page URL and use this with the Dashboard service. Press your Esc key to return to the standard view. **Supported authentication mechanisms** The Xibo Dashboard service supports Grafana Cloud’s native authentication, and locally installed Grafana instances using the built-in authentication mechanism. It does not support logging in with OAuth providers (Microsoft, Google, Github etc). Grafana does not support multi factor authentication, so please leave the **Secret field empty** when configuring this integration. **Limitations** Your dashboard must load within 60 seconds of the dashboard URL being opened in the browser. If your dashboard takes longer than this, the dashboard will be captured at the 60 second mark and the resulting image returned.
### Matomo
Obtaining a URL * Load the Dashboard you wish to show inside your Matomo instance. * Copy the page URL from your browser address bar. By default, the Matomo dashboard shows data for the previous day. If you want to adjust it to show today instead, substitute the word “yesterday” for “today” in the URL in both places, so for example the above URL becomes: **Supported authentication mechanisms** The Xibo Dashboard service supports the built-in Matomo authentication including a TOTP based second factor authentication code. It does not support any external authentication system. **Limitations** Your dashboard must load within 60 seconds of the dashboard URL being opened in the browser. If your dashboard takes longer than this, the dashboard will be captured at the 60 second mark and the resulting image returned.
# Xibo SSP Connector An add-on service from Xibo Signage which enables integration to a variety of supported DooH (Digital out of Home) Supply Side Platforms (SSP's) to monetise an established Xibo network. {% hint style="danger" %} **IMPORTANT:** This service is available from v3.3.0 and is for existing customers who have already got a reliable and functional Xibo network which includes an audience measurement solution. The SSP onboarding process can be a lengthy process and consists of stages that need to be addressed **prior** to the purchase of the Xibo SSP Connector. Customers should only commit to a purchase from Xibo Signage once they get to the 'sandbox testing' stage of their SSP's on-boarding process. Further information about the on-boarding process and a list of **Supported SSP's** can be found on our [website](https://xibosignage.com/advertising) {% endhint %} Once purchased, an API key will be made available in the **Connectors** section of [My Account](https://account.xibosignage.com/login). This key is required to Configure the SSP Connector in the Xibo CMS. ## Reference ID's for Displays During the on-boarding process you will either be asked to provide ID's or given ID's unique to the SSP software. If asked for ID's the `displayId` should be used with no further configuration required for Displays in the CMS. SSP's often use unique ID's in their software so in the event that you are provided with ID's they can be entered by editing Displays using the Reference /Custom ID fields from the **Reference** tab. ## Configure SSP Connector From the CMS: * Click on **Applications** under the **Administration** section of the main menu. * Scroll down to the **Connectors** section of the page. * Click the **Configure** button for the **Xibo SSP Connector**: * Enter the **API Key** available in **My Account** after purchase. * Include your **CMS URL** your Players will use to connect. {% hint style="warning" %} Players require HTTP access to `https://exchange.xibo-adspace.com` in order to receive ad's from SSP's. {% endhint %} * Tick to **Enable** to initiate the Xibo SSP Connector service. Next select the tab for your chosen SSP or opt to use the **Test SSP** tab which can be used to check settings with Xibo related ad's shown on your Displays. * Provide the **API Key** for the **SSP**. If you are asked to run a test by the SSP as part of the approval service, tick the **Test Mode** check box to send requests into the specific SSP's test environment. * Configure a **Share of Voice** in **seconds** or as a **percentage**. * Provide the expected total **Duration** of each ad served by the SSP. * Include a **Minimum Duration** for each ad. * Include a **Maximum Duration** for each ad. * Use the drop down to specify the **Type** of ad to be served, Images and Videos, Images only, Videos only. * Select the **Display Group** to use. Leave this field blank to select all Displays. * Use the drop down menu to select the **ID** to use for the SSP. (Please see the Reference ID's for Display/Display Groups section above) * Click to **Save**. Once all information has been provided and Display/Display Groups have been correctly configured tick the **Enabled?** button at the top of the form to confirm the connection to the SSP for Players to start requesting ads from the enabled SSP's: ### Share of Voice The recommended configuration for the SSP connector is to dedicate a "share of voice" to ads. This share of voice is the estimated duration of ads which your Displays will request and does not represent expected playback which is determined by your SSP partner. The setting you provide is combined with the ad duration to calculate an ad request rate. Setting a realistic share of voice allows the Display to spread ad requests in the most appropriate way and will yield the best results. {% hint style="danger" %} Xibo will not show SSP adverts alongside or in the middle of other content. Ads will only be played between your scheduled Layouts with any Overlay Layouts hidden during playback. For this reason is it important to note that the Xibo SSP Connector is not suitable for Users who have scheduled Layouts with durations longer than 5 minutes. {% endhint %} ### SSP Widget For Users with complex Playlist schedule loops or video wall configurations an SSP Widget is available to add to Layouts. {% hint style="warning" %} The SSP Widget can only be used for SSP providers that support its functionality. {% endhint %} Add the SSP Widget to your Layout and optionally select the Partner to use from the properties panel. If there is an Ad available at time of play it will be converted to an Image/Video Widget. ### Testing The Test SSP tab is a useful tool to see how the information you provide, **Share of Voice** for example, is then calculated to give you X number of plays. Test your existing Displays and see a sample of Xibo Advertisements play on your screens allowing you to make adjustments to the SSP Configuration if required to achieve your desired play time. {% hint style="success" %} We recommend creating a "test" **Display Group** to initially target {% endhint %} The following ad's will be shown on your Displays based on the display orientation when utilising the Test SSP: ## Troubleshooting If you are not receiving the ad revenue you expect, initial troubleshooting should be done with your SSP partner. The Xibo SSP Connector facilitates connection between your Displays and the SSP, but does not track performance of that connection beyond basic reporting which is explained in the activity report section below. In rare cases the SSP may not see any ad requests from your Display, which indicates an issue to be troubleshooted in Xibo using the activity report. ### Activity Report Once enabled and connected to a Partner you will see an additional Activity Report in the **Reports** section of the CMS. There are two tabs available on the report: {% stepper %} {% step %} ### Summary For the filter options selected show a summary of activity listing plays, errors and misses {% endstep %} {% step %} ### Detail For the filter options selected show every ad request and the status of that request {% endstep %} {% endstepper %} Returned results can be printed or exported to a CSV. #### Error codes The **Activity Report** is a great tool for troubleshooting with activity summaries and error codes available to view: | Code | Error | | ---- | -------------------------------------------------- | | 200 | Creative type not supported | | 202 | Creative duration not supported | | 203 | Creative dimensions invalid (wrong aspect ratio) | | 302 | Maximum number of hops exceeded requesting an ad | | 303 | No ad returned from SSP | | 401 | The creative has not been downloaded yet | | 405 | MediaFile display error (faulty creative returned) | | 408 | Outside geofence | #### 303 errors A 303 error is normal and means the SSP did not have any ads to return for the ad spot. If you are seeing a large quantity of 303 errors there may be an issue with the Display's metadata in the SSP. #### Missed ad spots A small percentage of missed ad spots is normal as Xibo will serve slightly more ad spots than the display can consume so that it does not run out. A large quantity of missed ad spots is an indicator of a problem. The most common issue is late changes to the schedule loop on the display, which can be caused by user action or interactivity. If you regularly take those actions you should discuss it with your SSP to ensure they are aware and can sell your display accordingly. ### Xibo version We recommend running the latest version of the Xibo CMS and player app on your Display to ensure maximum compatibility with your chosen SSP. ## Partner Notes ### Vistar Media When entering the API Key for Vistar Media please ensure you use the following format: `network_id||api_key` # My Account Once registered, all products and services are available for purchase from [My Account](https://account.xibosignage.com/login) Manage all purchased **Plans**, **Perpetual Licences**, **Hardware, Connector API keys** and **White Labels** from your My Account dashboard. Keep a track of how your orders are progressing: ![Progress](https://2149703612-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOD5P6BGYveuzkbhjZRsq%2Fuploads%2Fgit-blob-478307df3b3e80ddf5e55b52e386fc149b6af580%2Fmy_account_progress.png?alt=media) Provide and manage **Billing** information: ![Billing](https://2149703612-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOD5P6BGYveuzkbhjZRsq%2Fuploads%2Fgit-blob-a2133b222228914ddb05831b93153b4d45c879b1%2Fmy_account_billing.png?alt=media) ## Teams Invite other Users to your My Account dashboard using the **Team** button: Click to **Invite** and use the drop down menu to set a **Role** for the team member: There are four **Roles** to select which give varying access to **My Account** for users: * **Owner** - has access to everything * **Admin** - has access to everything * **Support** - has access to view Plans, Perpetual Licences, White Label, Hardware and open Tickets, with no access to purchase. * **Billing** - has access to billing information only. Include the users **email address** to send an invite notification {% hint style="success" %} You can change a Users **Role** and **Reset Passwords** using the buttons at the end of a row for users! {% endhint %} ## My email address was rejected when I tried to sign up? When signing up for an account, Xibo Signage may reject signups from email addresses hosted by certain providers. This may be because the email provider hosts “disposable” email accounts, or because there are technical issues with delivering email to those providers. The sections below provide some more details for specific cases. {% hint style="warning" %} If you believe that we’re preventing signup from your email address wrongly, please email us at and we will be happy to investigate. {% endhint %} ### Disposable Email Accounts It’s important that once you’ve signed up for an account, we can contact you regarding the products and services that you’ve ordered. Using a disposable email address prevents us from getting in contact with you. Please use a non-disposable email address - such as those offered for free by Google Mail, [Outlook.com](http://outlook.com/) etc, or the one offered by your internet service provider. Any consents to be kept informed by email can be changed at anytime from the **Profile** section of the **My Account** dashboard once registered. ### Apple iCloud / MobileMe We’ve experienced significant issues with reliable email delivery within the iCloud system. Messages sent from Xibo Signage simply vanish within the iCloud system without a non-delivery report, so we don’t know if you have received our messages or not. We contacted Apple support to discuss this and to try and find a resolution, however Apple were unwilling to investigate, so we’ve been left with no option but to block signups from Apple iCloud users at this time. # Purchasing for your Customers Reselling of Xibo is only available to companies who have entered in to one of our [Channel Partner](https://xibosignage.com/become-a-partner) programmes. ### Distributors Distributors are required to make a child company for each company they wish to sell to and then switch to the child company to purchase products/Plans for that particular account. ### White Label Reseller Each company can only have one Plan so if the requirement is for customers to have different renewal dates or have different types of Plan, you will need to create a child company to facilitate that. ## Creating a Child Company in My Account From **Billing** click on the **Resell Customers** tab: ![Resell customers tab](https://2149703612-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOD5P6BGYveuzkbhjZRsq%2Fuploads%2Fgit-blob-0322ea74717220871dfb014e997ca060133a4bda%2Fbilling_resell_customers.png?alt=media) Click the **Add New Company** button: ![Adding child companies](https://2149703612-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOD5P6BGYveuzkbhjZRsq%2Fuploads%2Fgit-blob-8edfe1711904a2fe4d4a65b3a8cb747b161c0a62%2Fbilling_add_child_company.png?alt=media) Complete the form fields to create the Child Company record for your customer, and click to **Save**. The saved record will show under the Companies section. ![View companies](https://2149703612-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOD5P6BGYveuzkbhjZRsq%2Fuploads%2Fgit-blob-f4be5c32b47ac60eb424e4986dbd2aabc912b9e7%2Fbilling_companies_grid.png?alt=media) Use the buttons at the end of a row for a Company to **Load** or **Edit** the Company record. ## Purchasing products/Plans for your Customer Use the drop down menu at the top of My Account to select the Child Company from the list: ![Select company](https://2149703612-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOD5P6BGYveuzkbhjZRsq%2Fuploads%2Fgit-blob-dff97d6eb6c8cfd2b1da21deff4e533a22bf5b5d%2Fbilling_company_selector.png?alt=media) {% hint style="success" %} You can also **Load** the company using the button at the end of the Company record! {% endhint %} * Once switched to the company account, proceed to select the products according to their needs. * Proceed to purchasing and submit payment. {% hint style="info" %} Billing notifications are always sent to the main Company contacts and not the Child Company! {% endhint %} ## Customer access to My Account If you want your customer to have access to their product details through My Account, please go to [Tickets](https://xibosignage.com/my-account/tickets?open=true) and submit a request, include your customers **Email address** and the **Company Name** they should be added to. # On-Premise Licensing Player Licences must be verified every 30 days. Devices that fail to get a licence will automatically stop downloading new content from the Xibo CMS it is connected to. This module acts as a pass-through to our licensing servers for Players that will not have reliable internet access, or that will run permanently disconnected from the internet. ## First steps 1. From My Account navigate to **Perpetual Licences**. 2. Click the end button for the **Licence Pool** to **Purchase On-Premise Module**. ![purchase\_on\_prem](https://2149703612-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOD5P6BGYveuzkbhjZRsq%2Fuploads%2Fgit-blob-5e03b4e3567a27c169ec329e068fbd2e6f645ae9%2Fplayer_licensing_purchase_on_prem.png?alt=media) Once purchased follow the steps below: ## Download and Install to your CMS From My Account, navigate to the Licence Pool which now has the **On-Premise Module** now enabled. ![Row Menu](https://2149703612-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOD5P6BGYveuzkbhjZRsq%2Fuploads%2Fgit-blob-2a180e527884d758805316f2723fe992e917b4ec%2Fonprem_module_row_menu.png?alt=media) Use the row menu and download by clicking on **Download Module** and select the correct folder for the version/Player required from the downloaded zip. Install on your server as per the instructions for your Player as detailed below:
Android ### CMS Docker Install Open the correct folder from the downloaded zip file, and then copy the contents of the folder into your `shared/cms/custom` folder. Edit `shared/cms/custom/settings-custom.php` file, and add the following lines to the end of the file, before the closing `?>` tag, so that it looks like this: ```auto $androidOnPremise = new \Xibo\Custom\XiboForAndroidOnPremise(); $androidOnPremise->setConfig('licences@example.org'); $middleware = [$androidOnPremise]; ?> ``` Be sure to replace `licences@example.org` with your correct Licence Pool email address. If you already have other middleware enabled, please see the comments at the top of the `XiboForAndroidOnPremise.php` file which explains how to handle that. Finally, run a manual licence check from the Player. It won’t licence the Player initially but a file - request.txt should be created on in the `shared/cms/library/android` folder. ### CMS Custom Install Open the correct folder from the downloaded zip file, and then copy the contents of the folder into your `shared/cms/custom` folder. Edit `/web/settings.php` file, and add the following lines to the end of the file, before the closing `?>` tag, so that it looks like this: ```auto $androidOnPremise = new \Xibo\Custom\XiboForAndroidOnPremise(); $androidOnPremise->setConfig('licences@example.org'); $middleware = [$androidOnPremise]; ?> ``` Be sure to replace `licences@example.org` with your correct licence pool email address. If you already have other middleware enabled, please see the comments at the top of the `XiboForAndroidOnPremise.php` file which explains how to handle that. Finally, run a manual licence check from the Player. It won’t licence the Player initially but a file - request.txt should be created on in the `/library/android` folder.
webOS ### CMS Docker Install Open the correct folder from the downloaded zip file, and then copy the contents of the folder into your `shared/cms/custom` folder. Edit `shared/cms/custom/settings-custom.php` file, and add the following lines to the end of the file, before the closing `?>` tag, so that it looks like this: ```auto $webOSOnPremise = new \Xibo\Custom\XiboForWebosOnPremise(); $webOSOnPremise->setConfig('licences@example.org'); $middleware = [$webOSOnPremise]; ?> ``` Be sure to replace `licences@example.org` with your correct Licence Pool email address. If you already have other middleware enabled, please see the comments at the top of the `XiboForWebosOnPremise.php` file which explains how to handle that. Finally, run a manual licence check from the Player. It won’t licence the Player initially but a file - request.txt should be created on in the `shared/cms/library/webos` folder. ### CMS Custom Install Open the correct folder from the downloaded zip file, and then copy the contents of the folder into your `/custom` folder. Edit `/web/settings.php` file, and add the following lines to the end of the file, before the closing `?>` tag, so that it looks like this: ```auto $webOSOnPremise = new \Xibo\Custom\XiboForWebosOnPremise(); $webOSOnPremise->setConfig('licences@example.org'); $middleware = [$webOSOnPremise]; ?> ``` Be sure to replace `licences@example.org` with your correct Licence Pool email address. If you already have other middleware enabled, please see the comments at the top of the `XiboForWebosOnPremise.php` file which explains how to handle that. Finally, run a manual licence check from the Player. It won’t licence the Player initially but a file - request.txt should be created in the `/library/webos` folder.
Tizen ### CMS Docker Install Open the correct folder from the downloaded zip file, and then copy the contents of the folder into your `shared/cms/custom` folder.. Edit `shared/cms/custom/settings-custom.php` file, and add the following lines to the end of the file, before the closing `?>` tag, so that it looks like this: ```auto $TizenOnPremise = new \Xibo\Custom\XiboForTizenOnPremise(); $TizenOnPremise->setConfig('licences@example.org'); $middleware = [$TizenOnPremise]; ?> ``` Be sure to replace `licences@example.org` with your correct Licence Pool email address. If you already have other middleware enabled, please see the comments at the top of the `XiboForTizenOnPremise.php` file which explains how to handle that. Finally, run a manual licence check from the Player. It won’t licence the Player initially but a file - request.txt should be created on in the `shared/cms/library/tizen` folder. ### CMS Custom Install Open the correct folder from the downloaded zip file, and then copy the contents of the folder into your `/custom` folder. Edit `/web/settings.php` file, and add the following lines to the end of the file, before the closing `?>` tag, so that it looks like this: ```auto $TizenOnPremise = new \Xibo\Custom\XiboForTizenOnPremise(); $TizenOnPremise->setConfig('licences@example.org'); $middleware = [$TizenOnPremise]; ?> ``` Be sure to replace `licences@example.org` with your correct Licence Pool email address. If you already have other middleware enabled, please see the comments at the top of the `XiboForTizenOnPremise.php` file which explains how to handle that. Finally, run a manual licence check from the Player. It won’t licence the Player initially but a file - request.txt should be created in the `/library/tizen` folder.
## Install your Players Download and install the Player application onto your devices and set the appropriate Licence Pool code in the Player settings. ***Please Note:** During this configuration, if the Player has access and connects to our licence servers it will automatically licence directly from us, so you need to ensure your Players don’t have any access to the internet unless you are using the “shortcut” method outlined below. To do this, you can simply forget any defined wireless networks in the Player’s wifi device manager, or remove the ethernet cable or mobile SIM card. Please do ensure that the wifi adapter in your device is enabled.* ## Upload and Download Licence files Once you have all the Players you want to licence in the request.txt file, you need to upload that file into My Account for your Licence Pool, using the row menu and selecting **Upload Licence**: ![Upload Licence](https://2149703612-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOD5P6BGYveuzkbhjZRsq%2Fuploads%2Fgit-blob-47960365eeefb45316c731903f8edd5d32908802%2Fonprem_upload_licence.png?alt=media) Once uploaded you need to download the `android.txt` / `webos.txt` / `tizen.txt` file by clicking **Download Licence**: ![Download Licence](https://2149703612-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOD5P6BGYveuzkbhjZRsq%2Fuploads%2Fgit-blob-de22391d10f73afbc37b5cf12bf8f695c60719b9%2Fonprem_download_licence.png?alt=media) ### Copy to your CMS When you have your `android.txt` / `webos.txt` / `tizen.txt` file you’ll need to copy it to your CMS.
Android Place the `android.txt file` in the CMS library directory, in the `android` folder. By default on a Docker install, that would be `shared/cms/library/android`, and for a custom install, `/library/android`.
webOS Place the `webos.txt file` in the CMS library directory, in the `webos` folder. By default on a Docker install, that would be `shared/cms/library/webos`, and for a custom install, `/library/webos`.
Tizen Place the `tizen.txt file` in the CMS library directory, in the `tizen` folder. By default on a Docker install, that would be `shared/cms/library/tizen`, and for a custom install, `/library/tizen`.
### Shortcut Method If you are able to setup Players somewhere where they have internet access before taking them to their final location then follow this shortcut method. This process will initially licence directly with the licence service and then with the CMS after they are physically moved to their final site, without the need for a request.txt file. Licence your device online as normal to get it registered with My Account, then click on your Licence Pool with On-Premise enabled. Use the row menu and then select **Licence Download** to download the `android.txt` / `webos.txt` / `tizen.txt` file for you. Then at your destination site (where there’s no internet access), copy your downloaded file. Next, you will need to copy it to your CMS as previously mentioned above. # Player Licence Management Perpetual Player Licences can be added and managed from My Account
From here you can add new Pools and easily see all the important information, like the Version and how many upgrades you have, for your existing Licence Pools. {% hint style="info" %} Use the buttons at the end of Pool rows to purchase additional **Licences**, purchase the **On-Premise Licensing Module** and purchase **Upgrades** when they become available. {% endhint %} Licenses can be moved between **Licensed Devices** to give flexibility if a device fails or is no longer required to be in use. You may see entries in your Licensed Devices that have a **Last Check** date older than 30 days. Players must check in with your Licence Pool within a 30 day period to retain their licence. If they fail to check in within this period, the entry will still show but the Player will no longer be licensed and therefore no further updates will be made with regards to changes to Layouts and Player Schedules. Manage your devices by removing any entries that have a **Last Check** date over 30 days, which are not using the On-Premise Module, by clicking the bin icon at the end of the row. {% hint style="info" %} There is no need to remove devices which are expected to be turned off. {% endhint %} # Purchased Player Upgrades Once purchased you need to Upgrade your Players so that they will automatically migrate between Licence Pool versions and consume upgrade licences as necessary Licences are available for purchase at the ‘latest version’ and are automatically downgraded 1 previous major version if required. This results in an upgrade licence being issued which can be used for upgrading in the future. {% hint style="info" %} **Example Scenario:** A customer has a v3 CMS and some v3 Players and needs an additional licence. The customer purchases an additional licence, which currently means a v4 licence is issued. On using this licence to connect another v3 Player to the existing licence pool, it will automatically downgrade the purchased v4 licence to a v3 licence so that their player can be licensed. This situation will also issue a v3 to v4 upgrade so that the customer can upgrade in the future and use the licence on a v4 player with no additional charges. {% endhint %} {% hint style="warning" %} If you need to downgrade to earlier version, please open a [Ticket](https://account.xibosignage.com/my-account/tickets?open=true) with our help desk {% endhint %} It is technically possible to run a mismatched series of CMS and Player, providing that the CMS is of a higher or equal version than the Player. So for example, a v3 Player can run in compatibility mode against a v4 CMS, using a v3 Player licence. {% hint style="success" %} For the best results, we would always recommend running a **Player** and **CMS** from the **same major version**. {% endhint %} ### **If you have upgrades but no available licences:** * **Existing connected players**: upgrade your existing players. * **New players**: un-licence one of your existing players, and install the new version onto the new player. If you have a number of upgrades greater than the number of connected players, install the new version onto your new player, the licence upgrade will happen automatically. ### **If you have available licences:** Firstly, ensure you know what version you want to use and what version you currently have. * If you want to use the new major version, you can purchase an upgrade then install the new version onto your player. * If you want to use the earlier version you can install the older version onto your player and it will find your available licence. * If you have an available licence for the new major version, you should install the new version onto your player and it will find your available licence. {% hint style="warning" %} The version of your licence must match the version of the installation file that you want to install onto your player. {% endhint %} # CMS Error logs The CMS has a central “error log” which collects messages from all components in the platform which is a valuable resource when investigating issues. ## How to collect CMS error logs 1. Click the **Settings** section of the main CMS menu 2. Click the **Troubleshooting** tab 3. Use the drop down menu and set **Log Level** to **Debug** 4. Set a date and time in the **Elevate Log Until** field {% hint style="warning" %} Ensure that this is set far enough into the future that the system can collect the logs required. {% endhint %} #### Export CMS error log file 1. Click the **Advanced** section of the main CMS menu 2. Click Log and use the **Filters** button to set a **from** date and time 3. Set additional filters to capture the required information 4. Click **Apply Filter** 5. Click the CSV button to export the log file ## Contacting support Open a new ticket via **My Account** ensuring you provide the following: * [ ] The **version** of the software that you are using (both CMS and Player) * [ ] Description of the **issue** you are experiencing * [ ] Detailed **steps** so that the issue can be recreated by our team * [ ] Attach the downloaded **log file** to the ticket * [ ] Provide a **screenshot** of the Player Status page # Display Error/Audit logs Xibo Displays can collect logs during routine operations so Display alerts can be monitored, error conditions can be identified and troubleshooting can occur An administrator can enable additional **Audit** logging as necessary, usually this is during a troubleshooting session. {% hint style="info" %} The default configuration for a Display is to keep logging to a minimum as this prevents unnecessary processor and memory usage. When running with the default **Error** logging status an administrator can expect to see **Display Alerts** and **Error logs** only. {% endhint %} ## How to collect Display logs There are to logging channels available: * **XMDS Logging** happens in the CMS and logs messages from XMDS each time a Display connects which gives information about what the Display is sending and receiving from the CMS (to determine why a file has not been downloading or the Display is not updating properly for example) * **Display Logging** happens locally on the Display and is recorded in a local database for sending to the CMS at the next regular interval gives information as to what a Display is doing internally (not playing content at a scheduled time or a specific video not playing for example) {% hint style="info" %} Both types of logging have either **Error** or **Audit** log levels; Error being the default and Audit being an elevated log level which collects more information, especially helpful when opening a support ticket. {% endhint %}
XMDS Logging Configure in the CMS: 1. Click on **Displays** from the main CMS menu 2. Use the **row menu** for the Display you wish to collect logs for and click **Edit** 3. From the **Advanced** tab, enter a date/time in the **Auditing until** field {% hint style="warning" %} This should not be set for too long a period which goes beyond the troubleshooting window {% endhint %}
Display Logging Configure from the **Display Settings Profile** (logging will be recorded for all Displays which share the same profile) or from the Override in **Display Settings** (for a singular Display) **Display Settings Profile**: 1. Click on **Display Settings** from the main CMS menu 2. Use the row menu for the Display profile type and click **Edit** 3. From the **Troubleshooting** tab, set a date/time in the **Elevate Logging** until 4. Click to **Save** **Override Display Settings**: 1. Click on **Displays** from the main CMS menu 2. Use the row menu for the Display and click **Edit** 3. From the **Settings** tab, scroll to find **Elevate Logging until** 4. Click **Override** and provide date/time 5. Click **Apply** 6. Click **Save**
#### Export Display log file 1. Click the **Advanced** section of the main CMS menu 2. Click Log and use the **Filters** button to set a **from** date and time 3. Set filters to capture the required information 4. Click **Apply Filter** 5. Click the CSV button to export the log file # Request Player Status Player status information is likely to be requested by our support team when investigating issues. There are two ways to request the status, which is dependent on whether your Displays are showing as connected are not: {% tabs %} {% tab title="Connected and Logged in" %} 1. Click on **Displays** from the main CMS menu 2. Use the row menu for the Display and click **Request Screenshot** 3. Use the **Columns** drop down and ensure that **Screenshot** is ticked 4. Click the thumbnail shown in the grid 5. Click on the `i` icon in the top right corner of the thumbnail 6. Scroll down to **Player Status** 7. Capture the status to attach to your support ticket {% endtab %} {% tab title="Not Connected" %} 1. Connect a mouse to your device 2. Click on the screen whilst Xibo is running 1. For webOS click the yellow button whilst Xibo is running 2. for Tizen click OK on the remote whilst Xibo is running 3. Click **Status** from the Action bar at the top of the screen 4. Capture the status to attach to your ticket {% endtab %} {% endtabs %} # Audit Trail The CMS provides audit logs which records all User and System Task activity within certain parts of the CMS. From the **Advanced** section of the main CMS, click on **Audit Trail:** | Field | Description | | ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | |

ID

| This column shows the generated identification number for the record | | **DATE** | Gives the date and timestamp to show when the action occurred | | **USER** | This column shows who initiated the action. When the action has occurred as a result of a System Task, the username will show as blank | | **ENTITY** | Name of the type of object affected by the action | | **ENTITY ID** | The identification number of the affected object | | **IP ADDRESS** | IP Address associated with the action | | **MESSAGE** | Shows what action has occurred | | **OBJECT** | Click the icon to see a breakdown to give further details as to what has been actioned | {% hint style="warning" %} Audit Log information for Xibo Cloud customers is limited to 30 days. {% endhint %} # Log The CMS has a central repository for all log information, including the Players which send back information with each collection from the CMS. Click on the **Advanced** section of the main CMS menu and select **Log.** The Log is split into **Channels**, **Functions** and **Pages** for easy searching. Each unique request has a *`runNo`* to group messages together. ## Fields | Field | Description | | ------------ | ------------------------------------------------------------------------------------------ | | **ID** | A sequential ID of log messages | | **Run** | The *run* identifier used to group messages generated by a single request | | **Date** | The CMS date of the message | | **Channel** | The Channel that the message relates to | | **Function** | The HTTP verb used in the request the generated the message, GET, POST, PUT, DELETE, HEAD. | | **Level** | The severity of log message | | **Display** | The display name, if the log message came from a Player | | **Page** | The page requested - usually the route | | **Message** | The log message | ## Channels | Channel | Description | | ----------- | ------------------------------------------ | | **WEB** | The CMS Web Portal | | **API** | The CMS API | | **XMDS** | The CMS/Player API (Media Distribution) | | **AUTH** | The oauth authorization server for the API | | **CONSOLE** | XTR task running | ## Finding your message Understanding the log can be complicated in a busy system and it can often be hard to find messages related to your interest. The log can be filtered for this purpose, it is usually best to start with the **Channel**, then the **Function** and finally (if necessary) the **Page**. {% hint style="info" %} For example, if an API call to the statistics search function is not working as expected the log can be searched for API, GET and `/stats`. {% endhint %} # Introduction The Xibo Platform offers various opportunities for a developer or designer to be involved in the Digital Signage creative process, and often adding a technical element to your network really makes it > This documentation is written for a technical audience. If you are looking for a [user manual](https://account.xibosignage.com/manual/en/), or [documentation for running Xibo](https://docs.xibosignage.com/), please use the links provided. These documents are ordered such that more common activities are discussed first, however which parts you need will depend on what you want to achieve; refer to the below overview.
SectionDescriptionExample
WidgetsLearn how to create Embedded or Package HTML Widgets using the Layout Editor, or dive into creating your own Module.Creating a new visualisation for use on a Layout. This may involve pulling data from a 3rd party.
Player ControlDiscover what can be done player side including what information from the Player is available to a Widget, displaying real time data, how to control duration and how to send/receive webhooks.Interactivity on a player, for example triggering content via a light sensor.
IntegrateConnect a 3rd party system by calling the Xibo API. Learn how to authenticate via oAuth and what API calls are available.A 3rd party will push content into Xibo. The Xibo Canva app is a good example of this.
{% hint style="danger" %} ### Deprecation notice - Theme and custom code changes in v4.5 4.5 CMS has a new React/Tailwind CSS front end which means we need to retire the old "PHP templating" available from inside the `web/theme/` folder. Themes purchased from Xibo will be automatically updated for the new approach and available to download in My Account. Instructions for applying them can be found in our knowledge base: [Applying a White label to a CMS in a docker environment](/kb/white-label-application/applying-a-white-label-to-a-cms-in-a-docker-environment). Future versions of the CMS will include a branding feature from inside the CMS itself, making these changes easier to manage. Custom code (deployed in the `custom/` folder will continue to function, except where it relies on PHP templating (twig). The following things are no longer supported: * Custom connectors * Custom reports (pending refactor) * Custom twig views * Custom display profiles {% endhint %} {% hint style="warning" %} ### Deprecation notice - extending the PHP code will no longer be available after 4.5 Xibo has for a long time let advanced users extend the CMS by dropping custom PHP into the codebase. A stop-gap between running a standard release and maintaining your own fork. **We're removing it.** In practice, that mechanism is a fork[^1] in disguise. Code dropped into the codebase runs with full application privileges, sits outside the release's review and integrity checks, and gets overwritten on upgrade. It should carry the maintenance burden and security exposure of maintaining your own fork, but oftentimes doesn't, and it comes without an upgrade path. We don't think this capability belongs in the product, and is one we can't support or diagnose against a standard release. Everything it was used for now has a first-class, supported home. Xibo ships a fully-covered API, a Widget and Data ingest toolset for custom content and data sources, and comprehensive Display-side tooling. There is enough to build what you need without touching core code, and without inheriting the upgrade and security costs that came with the old approach. If you need something we don't have, we welcome the feedback (hit the button in the CMS), and of course you are always welcome to fork the code on GitHub. {% endhint %} [^1]: a developer term for creating your own version of the code # Contributing to Xibo How can a user of the open source software contribute back to the community? The heart of the Xibo platform is open source software and always will be. If you benefit from Xibo and want to contribute to our project, you’re very welcome to do so. There are lots of different ways to be helpful no matter what your technical knowledge. ## Be active in the community It sounds like a simple thing, but one of the most helpful things an experienced user of Xibo can do is be active in the community. Xibo is lucky enough to attract a huge variety of different users with different abilities, and the community is always busy with questions and requests for advice. ## Report bugs If you’re sure something doesn’t work the way it should, or the way it's documented to work, then opening a topic in the [Get Help](https://community.xibo.org.uk/c/support/6) section of the Community forum with step by step instructions for reproducing the issue is super helpful. One of our support team can pick that up and pass it directly to the development team to be fixed in the next release. ## Suggest a feature or improvement Xibo thrives on suggestions - much of the software does what it does because of our users describing how they want Xibo to work. If you have an idea for a new feature, or an improvement to something existing, open a topic in the [Feature Requests](https://community.xibo.org.uk/c/features/8) category of the Community forum. A member of the support team will likely want to discuss that with you and find out a bit more (there is nothing worse than adding a feature which turns out to be not quite what you meant!), but once it's all understood they will pass it to the development team to be introduced in an appropriate release. ## Write some code Xibo does not currently accept code contributions due in part to the recent wave of AI authored pull requests, but also to maintain the integrity and security of the product. There are lots of ways you can integrate and extend Xibo without contributing to the core code, and these are discussed here. ## CLA So that we can be confident in the future of the project, any contribution requires a CLA (contributor licence agreement) to be reviewed and signed [here](https://github.com/xibosignage/xibo/blob/master/CONTRIBUTING.md). All development is on GitHub in the [xibosignage](https://github.com/xibosignage) organization. Xibo contains multiple components which are organised into their own repositories, we also have a central repository for collecting issues. This can be found [here](https://github.com/xibosignage/xibo). ## Release Cycle Xibo actively works on two releases at any one time - the stable release and the development release. The stable release is in the `master` branch, and the development release is in the `develop` branch. It is always best to ask the best place to put your code before you start, as sometimes there can be framework changes between major releases.
You’ve refused my contribution! We are always very sorry when your idea or contribution doesn’t fit with the project. There are lots of things we have to take into consideration before including something. Xibo has a lot of existing users we need to consider. We don’t want to be strict gatekeepers, but if we weren’t then you might find yourself a “victim” of a change that didn’t fit well. Don’t worry though, you can still have your feature in your Xibo! We have built Xibo with an extensive set of tools to extend with custom additions and modifications. Xibo also has a comprehensive API. Find out more in our [developer documentation](https://xibo.org.uk/docs/developer/).
# Integrating with Xibo Integrating applications opens the door to many exciting possibilities, and we’ve designed the Xibo CMS from first principles with maximum support for integration. The heart of the CMS is an API which is used by Xibo’s own user interface, and can also be accessed via a 3rd party! The CMS API is used to pull data from the Xibo CMS into another system, or push data from another system into the CMS. Our API makes exciting opportunities to integrate Xibo with other systems possible! For example, imagine an integration with a point of sale system which pushed complimentary products to the signage when a customer purchased something. The CMS API is a RESTful API protected by oAuth. It can be consumed at `//yoururl/api` and exposes routes for all CMS operations. The API is [OpenAPI Compliant](http://swagger.io/) and the documentation is presented using Swagger-UI. Every Xibo CMS install has a `/swagger.json` end point which can be used to provide an API document specific to the version of Xibo running. > The API document in this manual is always for the latest release. [View the API documentation](https://xibo.org.uk/manual/api/). **Older versions** The explore bar at the top of the Swagger documentation can be used to load the API docs from older releases. * 3.3: * 2.3: * 1.8: **Postman** You can copy/paste the `swagger.json` from the above links into Postman’s import function.
Can’t find an API route you need? Xibo has a comprehensive system for customisation and the API is no exception. You can use custom Middleware, Routes and Controllers to implement your own API endpoints to do whatever you need to! The most common use is to group up existing Xibo operations into something easier to call by the 3rd party! These are documented in our [section on extending Xibo](broken://pages/7039b32911961170b41a0d6a70f1be66912a2c3c).
# Authentication The Xibo CMS API is protected by OAuth 2.0. Every request must carry a valid `access_token` in an Authorization header: {% code title="HTTP Header" %} ```http Authorization: Bearer <> ``` {% endcode %} This page covers how to register an application, obtain a token, refresh it, and scope it. {% hint style="info" %} Throughout this page, replace `https://cms.example.org` with the URL of your CMS. If your CMS is installed in a sub-directory, include it — for example `https://example.org/xibo/api/authorize/access_token`. {% endhint %} ### Quick start If you're building a server-side integration and just want a token, this is the whole flow: ```bash curl -X POST https://cms.example.org/api/authorize/access_token \ -d "grant_type=client_credentials" \ -d "client_id=YOUR_CLIENT_ID" \ -d "client_secret=YOUR_CLIENT_SECRET" ``` Response: ```json { "token_type": "Bearer", "expires_in": 3600, "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9..." } ``` Use it: ```bash curl https://cms.example.org/api/display \ -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9..." ``` The rest of this page explains where the credentials come from and what to do when the token expires. ### Step 1: Register an Application Before you can request a token, an Application must exist in the CMS. 1. Sign in to the CMS and go to **Administration** → **Applications**. 2. Select **Add Application** and give it a name. This name is shown to users on the authorisation screen, so make it recognisable. 3. Save, then edit the new Application to configure it. The Application edit form controls everything about how your integration authenticates:
SettingWhat it does
Client IDPublic identifier for your application. Safe to include in configuration files.
Client SecretPassword for your application. Treat it like a password — see Keeping credentials safe.
ConfidentialWhether the application can keep a secret. Leave enabled for server-side integrations.
Authorisation Code / Client CredentialsWhich grant types this application may use. Enable only what you need.
Redirect URIsRequired for the authorisation code grant. The CMS will only redirect to a URI listed here.
ScopesWhich parts of the API this application may reach. Defaults to all.
{% hint style="warning" %} The Client Secret is generated when the Application is created and cannot be retrieved later in plain text. If you lose it, reset it from the Application edit form — this immediately invalidates any integration using the old value. {% endhint %} ### Step 2: Choose a grant type Two grant types are supported. Pick based on *whose* data you're acting on. | | Client Credentials | Authorisation Code | | ------------------------ | --------------------------------------------------------- | ------------------------------------------------------------------------------------ | | **`grant_type` value** | `client_credentials` | `authorization_code` | | **Acts as** | The user who owns the Application | The user who signs in and approves | | **Use for** | Server-to-server integrations, scheduled jobs, middleware | Applications used by multiple CMS users, or where you must not hold user credentials | | **User interaction** | None | Sign-in and consent in a browser | | **Refresh tokens** | Not issued | Issued | | **Needs a redirect URI** | No | Yes | {% hint style="danger" %} The Applications page labels the authorisation code grant **Authorisation Code**, and older documentation referred to it as `access_code`. Neither is the value you send. The `grant_type` parameter must be exactly `authorization_code`, per the OAuth 2.0 specification. {% endhint %} ### Step 3: Obtain an access token All token requests are `POST` to `/api/authorize/access_token`, with parameters in a form-encoded request body (`application/x-www-form-urlencoded`). They are **not** query string parameters. #### Client credentials grant A single request. There is no user to redirect and no consent screen. {% tabs %} {% tab title="cURL" %} ```bash curl -X POST https://cms.example.org/api/authorize/access_token \ -H "Content-Type: application/x-www-form-urlencoded" \ -d "grant_type=client_credentials" \ -d "client_id=YOUR_CLIENT_ID" \ -d "client_secret=YOUR_CLIENT_SECRET" ``` {% endtab %} {% tab title="PHP" %} ```php $client = new \GuzzleHttp\Client(); $response = $client->post('https://cms.example.org/api/authorize/access_token', [ 'form_params' => [ 'grant_type' => 'client_credentials', 'client_id' => getenv('XIBO_CLIENT_ID'), 'client_secret' => getenv('XIBO_CLIENT_SECRET'), ], ]); $token = json_decode($response->getBody(), true)['access_token']; ``` {% endtab %} {% tab title="Python" %} ```python import os, requests response = requests.post( "https://cms.example.org/api/authorize/access_token", data={ "grant_type": "client_credentials", "client_id": os.environ["XIBO_CLIENT_ID"], "client_secret": os.environ["XIBO_CLIENT_SECRET"], }, timeout=30, ) response.raise_for_status() token = response.json()["access_token"] ``` {% endtab %} {% tab title="JavaScript" %} ```javascript const body = new URLSearchParams({ grant_type: 'client_credentials', client_id: process.env.XIBO_CLIENT_ID, client_secret: process.env.XIBO_CLIENT_SECRET, }); const response = await fetch('https://cms.example.org/api/authorize/access_token', { method: 'POST', body, }); const { access_token: token } = await response.json(); ``` {% endtab %} {% endtabs %} The token acts as the CMS user who owns the Application. It can do everything that user can do, and nothing they cannot — API permissions are still subject to normal CMS user permissions and features. #### Authorisation code grant Three steps: send the user to the CMS, receive a code, exchange the code for a token. **1. Redirect the user to the authorisation endpoint** ``` https://cms.example.org/api/authorize/?client_id=YOUR_CLIENT_ID &response_type=code &redirect_uri=https://yourapp.example.com/callback &scope=all &state=RANDOM_UNGUESSABLE_STRING ```
ParameterRequiredNotes
client_idYesFrom the Application page.
response_typeYesAlways code.
redirect_uriYesMust exactly match one of the URIs registered against the Application.
scopeNoSpace-delimited. Omit to receive all scopes configured for the Application.
stateStrongly recommendedRandom per-request value. Verify it on return to protect against CSRF.
The user signs in if they aren't already, then sees an authorisation screen naming your application. If they approve, the CMS redirects to your `redirect_uri`. **2. Receive the authorisation code** ``` https://yourapp.example.com/callback?code=AUTH_CODE&state=RANDOM_UNGUESSABLE_STRING ``` Check that `state` matches the value you sent before going any further. If the user declines, you receive an `error` parameter instead of `code`. **3. Exchange the code for a token** Authorisation codes are valid for **10 minutes** and may be used once. ```bash curl -X POST https://cms.example.org/api/authorize/access_token \ -d "grant_type=authorization_code" \ -d "client_id=YOUR_CLIENT_ID" \ -d "client_secret=YOUR_CLIENT_SECRET" \ -d "redirect_uri=https://yourapp.example.com/callback" \ -d "code=AUTH_CODE" ``` Response: ```json { "token_type": "Bearer", "expires_in": 3600, "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9...", "refresh_token": "def50200a1b2c3..." } ``` Store the `refresh_token` securely alongside the user's record. #### Refreshing a token Access tokens last one hour. Rather than sending the user through the authorisation screen again, exchange the refresh token: ```bash curl -X POST https://cms.example.org/api/authorize/access_token \ -d "grant_type=refresh_token" \ -d "client_id=YOUR_CLIENT_ID" \ -d "client_secret=YOUR_CLIENT_SECRET" \ -d "refresh_token=YOUR_REFRESH_TOKEN" ``` The response contains a new access token **and a new refresh token**. Replace the stored refresh token each time — the previous one is invalidated. Client credentials integrations do not receive refresh tokens. Simply request a new token when the old one expires. ### Step 4: Call the API The API is served from `/api` on your CMS. Send the token as a Bearer credential on every request: ```bash curl "https://cms.example.org/api/display?start=0&length=10" \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" ``` See OpenAPI for the full route reference, or Getting Started with Postman to explore interactively. ### Token lifetimes
TokenLifetimeRenewal
Access token1 hourRequest a new one, or use a refresh token
Authorisation code10 minutes, single useRestart the authorisation flow
Refresh token1 monthRotated on every use
Cache your access token for its lifetime rather than requesting a new one per API call. Requesting a token on every call is wasteful and will trip rate limiting on busy systems. {% hint style="info" %} Treat `expires_in` as advisory rather than a guarantee. Tokens can be invalidated early — for example if the Application's secret is reset or its scopes are changed. Handle a `401` at any time by re-authenticating and retrying once. {% endhint %} ### Scopes Scopes limit which API routes a token can reach. Each scope defines a set of route and method combinations; a request is allowed if any scope on the token permits that route and method. * The `all` scope grants access to every route and is the default. * Request specific scopes with a space-delimited `scope` parameter on the token request. * If you request no scopes, the token receives every scope configured against the Application. * A token that reaches a route none of its scopes permit receives `403 Access to this route is denied for this scope`. Scopes are configured per Application under **Administration** → **Applications**. Grant the narrowest set your integration needs — a data-feed integration that only writes to a DataSet has no reason to be able to delete Displays. {% hint style="info" %} Scopes constrain a token; they do not expand it. The effective permission is the intersection of the token's scopes and the CMS permissions of the user the token acts as. {% endhint %} ### Error responses Token endpoint errors follow the OAuth 2.0 error format: ```json { "error": "invalid_client", "error_description": "Client authentication failed", "message": "Client authentication failed" } ```
StatusErrorUsual cause
400unsupported_grant_typegrant_type missing, misspelled, or sent as a query parameter instead of a form field
400invalid_requestA required parameter is missing
400invalid_grantAuthorisation code expired, already used, or redirect_uri doesn't match the one used to obtain it
400invalid_scopeA requested scope isn't configured against the Application
401invalid_clientWrong client_id/client_secret, or the grant type isn't enabled for this Application
401access_deniedAccess token expired or malformed
403—Token is valid but its scopes don't permit this route
### Keeping credentials safe * **Always use HTTPS.** A Bearer token in a request over plain HTTP is a credential in the clear. The CMS should not be exposed over HTTP in production. * **Never embed a client secret in a browser or mobile application.** Anything shipped to a device is public. Client credentials belong on a server you control. * **A client credentials token inherits the Application owner's permissions.** Create a dedicated CMS user for each integration, with only the permissions and features that integration needs, and own the Application from that user. Don't run integrations as a Super Admin out of convenience. * **Store secrets outside your codebase** — environment variables or a secrets manager, never source control. * **Reset the secret if it may have leaked.** Resetting takes effect immediately. * **Review Applications periodically** and delete ones no longer in use. ### Troubleshooting
I get unsupported_grant_type even though I sent a grant type The parameters must be in the POST body as `application/x-www-form-urlencoded`, not in the query string and not as JSON. In cURL, use `-d`; in most HTTP libraries, this is the "form" or "form\_params" option rather than the "json" option. Also check the value itself: the authorisation code grant is `authorization_code`, not `access_code` or `auth_code`.
I get invalid_client with credentials I'm sure are correct Check that the grant type you're requesting is enabled against that Application. An Application with only Client Credentials enabled will reject an `authorization_code` request with `invalid_client` rather than a more specific error. Also confirm you're using the Client ID and Secret, not a CMS username and password.
The authorisation redirect fails or returns to the wrong place The `redirect_uri` must match a URI registered against the Application exactly, including scheme, host, port, path, and trailing slash. The same value must then be sent again when exchanging the code.
Everything worked, then started returning 401 after an hour Working as intended — access tokens last one hour. Cache the token with its expiry and renew before or on expiry, rather than assuming a token is permanent.
API configuration problem, consult your administrator The CMS could not load its API signing keys. On a self-hosted install, check that the private key path and encryption key are configured and readable by the web server. Contact your CMS administrator, or Xibo Support if you are Cloud hosted.
# OpenAPI This section deals with general information related to making requests. ## Enveloping All requests can be enveloped by adding `envelope=1` as a query parameter. ## Errors API errors are reported via the 4xx and 5xx HTTP response codes, the most common of which are: * 404 Not Found (the resource could not be found) * 409 Conflict (the request conflicts with an existing entity) * 422 Unprocessable Entity (the entity provided is invalid) Extra information is available in the response body and is JSON formatted. A human readable error message is presented, the HTTP status code and a data block indicating further information. An example 422 response: ```json { "error": { "message": "Layout Name must be between 1 and 50 characters", "code": 422, "data": { "property": "name" } } } ``` 5xx errors indicate an issue with the CMS environment and extra information will be available in the CMS logs. ## Grid Data — lists of records Lists of records, henceforth referred to as grids, are paged by default, with a default page size of 10 records. They also have a default sort order applied to them, which is appropriate for that record type. ### Paging Paging is controlled by 2 parameters, `start` and `length`. The `start` parameter denotes at which record in the set the results should start from, and `length` denotes the number of records to return. The default `length` is 10 records which means to get page 2, `start=20` would be provided. The headers of the response contain extra information related to paging, these are: * `X-Total-Count`: The total count of records (all pages) * `Link`: Links pointing to the first, prev, next and last pages (as appropriate) The Link header is RFC formatted: and consists of a url and `;` and a `rel=` (relationship) attribute. For example, the headers returned with page 1 are: ``` Link: ; rel="next", ; rel="first" X-Total-Count: 26 ``` ### Sorting Sorting happens in two steps using a columns array and an order array. The columns array describes the fields that should be ordered, and the order array describes how they should be ordered and in what order. Taking the layout grid as an example, if you want to order by the `duration` of the layout, descending, specify a columns array: ``` columns[1][data]:duration ``` And an order array: ``` order[1][column]:1 order[1][dir]:desc ``` # Misc Miscellaneous ## The current CMS time > The Time ```json {"openapi":"3.0.0","info":{"title":"Xibo API","version":"4.5"},"tags":[{"name":"misc","description":"Miscellaneous"}],"servers":[{"url":"/api"}],"paths":{"/clock":{"get":{"tags":["misc"],"summary":"The current CMS time","description":"The Time","operationId":"clock","responses":{"200":{"description":"successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":{"type":"string"}}}}}}}}}} ``` ## Help page links > Get the help landing page and any page specific help links ```json {"openapi":"3.0.0","info":{"title":"Xibo API","version":"4.5"},"tags":[{"name":"misc","description":"Miscellaneous"}],"servers":[{"url":"/api"}],"paths":{"/help/page-links":{"get":{"tags":["misc"],"summary":"Help page links","description":"Get the help landing page and any page specific help links","operationId":"helpPageLinks","parameters":[{"name":"page","in":"query","description":"The page name (route name) to return help links for","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"successful response"}}}}}} ``` --- [Next Page](https://docs.xibosignage.com/llms-full.txt/1)