pulse-signage/docs/user/guide-data-sources.md

Data Sources Guide

Data sources let slides show information that changes without requiring someone to edit the slide each time. Configure a source once, allow it to refresh on its schedule, and use the current values in the appropriate slide region.

The source page is where you configure and test the connection or data. The template and slide editors are where you decide how that data appears on screen.

Choosing a Source

Use the source type that matches the data you need:

• RSS feeds: headlines and other syndicated feed content.
• API sources: JSON data returned by a configured web service.
• Timetables: schedules made from named groups and entries.
• Weather locations: current or forecast weather for a saved location.

Create separate sources when the refresh cadence, authentication, location, or presentation needs are different. Give each source a clear name that identifies its purpose rather than only its URL.

RSS Feeds

An RSS feed needs a name, a feed URL, an update interval, and the number of items to pull. The latest pulled items are shown on the feed page so you can verify the title, link, publication date, description, author, identifier, and comments fields before using them in a slide.

Use the item limit to keep the stored feed focused on the number of recent items your slides need. If the feed contains more items than the limit, older or excess items are not useful for the source's slide regions.

When an RSS feed fails, open the latest-items preview and check the reported pull error. Confirm the URL returns an RSS or compatible feed, then use Refresh now after correcting the source.

API Sources

An API source connects to a JSON endpoint and can use either GET or POST:

• GET: retrieve data directly from the API URL.
• POST: send a JSON request body with the request.

Use Items path when the records needed by a slide are nested inside the response. Enter a dot-separated path such as items or results.data to identify the array that should be treated as the source items.

API authentication supports:

• No authentication.
• Basic username and password authentication.
• A bearer token.
• An API key sent in a named header.
• A login-then-token flow for services that issue a token from a login request.

For a login-then-token source, configure the login URL, JSON login body, token response path, and token header. If the service supports token refresh, configure the refresh URL, refresh-token response path, refresh body, and token prefix as required by that service. Keep credentials and tokens out of slide content and request examples that will be shared with other users.

After a pull, review the latest response details, including the last-pulled time, HTTP status, content type, and stored JSON response. Use the response structure to choose the item number, items path, and fields used by an API region.

Timetables

A timetable group contains the events that a timetable region displays. Configure:

• A group name and optional short description.
• The IANA time zone used by the group, such as Europe/Berlin.
• One or more entries with a title, optional description, start time, and optional end time.

Use the group timezone consistently with the people and screens that will read the schedule. An entry without an end time can represent an item with an open-ended or display-only start time. Remove old entries rather than leaving expired events mixed with current ones.

Weather Locations

A weather location is a saved place that weather regions can use. Search for a town, city, or postcode and choose a result so the application fills the coordinates and timezone. Coordinates can be edited manually when the lookup result needs adjustment.

Configure the provider and display units for each location:

• Temperature: Celsius or Fahrenheit.
• Wind: km/h, mph, or m/s.
• Precipitation: millimetres or inches.
• Update interval: minutes or hours, within the available limits.

The weather page provides a current preview and forecast preview. Use them to confirm the location, units, and provider before adding the location to a slide. A provider that is unavailable because its service credentials are not configured cannot be selected until the deployment is set up for it.

Using Sources in Slides

Configure the source before selecting it in a template or slide region. The available region types include RSS, API, Timetable, and Weather, as well as Time / Date for values based on a timezone.

When designing a data-backed region:

• Leave enough width and height for the longest expected value.
• Decide which item, field, or forecast mode the region should show.
• Use the preview to check missing values, long titles, dates, and line wrapping.
• Keep the playlist stable when the changing information belongs in a source rather than in slide text.

Changing a source can affect every slide and screen that uses it. Check the source's existing usage before changing its field structure or meaning.

Refreshing Data

Each source has an update interval and unit. Available intervals depend on the source type; RSS and API sources support seconds, minutes, or hours, while weather locations use minutes or hours. A source can also be refreshed manually when you need the latest values immediately.

Use Disable when a source should stop updating temporarily without deleting its configuration. Re-enable it when the source is ready to be used again. Deleting a source is a larger change because regions that depend on it may no longer have current values.

Troubleshooting

When a data-backed slide is stale or empty, check in this order:

1. Open the source page and check whether it is enabled.
2. Check the last refresh time, latest response, or preview data.
3. Use Refresh now and read any returned error.
4. Confirm the source URL, authentication, response format, or location coordinates.
5. Check the region's selected source, item, field, path, or forecast mode.
6. Confirm the player is connected and has received the refreshed state.

An online source with a successful response can still produce an empty region when the selected item or field no longer exists. An online source can also appear stale on a player that has not yet reconnected or refreshed.