Datasource mappers

A Datasource mapper runs a small JavaScript function over a Datasource's data before that data reaches the Widgets, and writes the result somewhere you can bind to. The original Datasource is never changed — a mapper only produces an extra, calculated copy of what you asked for.

Reach for one when the Datasource gives you more than the screen should show, or gives it in the wrong shape: a calendar feed that lists every event when you only want today's, two feeds that have to be merged into one list, or a value that needs counting, filtering or reformatting before a Widget can use it.

A mapper never creates data — it reshapes what a Datasource already returns, so the Datasource comes first. If the feed you want to work with is not connected yet, set that up before writing the rule: Wallboard pulls from spreadsheets, databases, APIs, feeds and calendars, and each type brings its own settings and its own data shape.

Learn more: External Datasources

The same feature has two names

The button in the Properties panel says Edit datasource mappers. The modal it opens is titled Edit datasource custom field calculator rules. They are the same thing, and a rule inside it is one mapper.

How a mapper works

Every mapper is three decisions, and the modal asks them in this order:

1. What goes in — the Content's own bound data, one Datasource, or several at once.
2. What is calculated — a JavaScript function. You either write it, or pick a preset that writes it for you.
3. Where the result goes — onto the Datasource as an extra property, into a Mock Datasource, or into an internal Datasource.

The result is data like any other, so a Widget reads it through a normal data binding.

Opening the mapper editor

Mappers belong to the Content or Slide that uses them, and both editors keep them in the same place: the Properties panel, under Data binding, in a button labeled Edit datasource mappers sitting next to Mock datasources.

Editor	How to get there
Content Designer	Open the Content, then Properties > Data binding > Edit datasource mappers. Learn more: Content Properties
Slide Editor	Open the Slide, then Properties > Data binding > Edit datasource mappers. Learn more: Slide Properties

The rules are stored on the Content or Slide you opened them from, not on the Datasource. Two Contents can therefore map the same Datasource in completely different ways, and copying a Content takes its mappers with it.

Click Add rule, then choose an entry from Select calculator. That choice only decides what the rule starts out as — everything it fills in stays editable afterwards.

What each calculator does

The calendar and CAP entries are presets: picking one writes a finished script for you and sets a matching Output property path. Custom starts from an empty function that returns nothing. A preset is not a black box — open its script and you can read or change exactly what it does.

Calculator	Output property path	What it returns
Custom	customFields.custom	Whatever you write. The rule starts as an empty function.
Calendar full	customFields.calendar	One object holding all five lists below at once, under the names currentEvents, upcomingEvents, todayEvents, todayUpcomingEvents and tomorrowEvents.
Calendar current events	customFields.currentEvents	Events in progress right now — started at or before this moment and ending at or after it.
Calendar upcoming events	customFields.upcomingEvents	Every event starting after this moment, with no limit on how far ahead.
Calendar today events	customFields.todayEvents	Events whose start time falls inside today, including ones that have already finished.
Calendar today upcoming events	customFields.todayUpcomingEvents	Events starting later today — today's list minus everything already started.
Calendar tomorrow events	customFields.tomorrowEvents	Events whose start time falls inside tomorrow.
Dynamic CAP filter	customFields.filteredAlerts	CAP alerts that match the Device's own Tags and have not expired.

What the calendar presets assume

Three things decide whether a calendar preset gives you what you expect:

• They read a calendar Datasource. Each one filters the events list and reads each event's start and end timestamps, so pointing one at a Datasource without that shape returns nothing useful.
• "Now", "today" and "tomorrow" come from the Device's own clock, not from the server and not from the calendar's own time zone.
• Today and Tomorrow filter on the START time. An event that began yesterday and runs into today is not in Calendar today events, because it did not start today. Use Calendar current events for what is actually on now.

Calendar full is the one to pick when a Content needs more than one of these lists — it calculates all five in a single rule, and each list is then read from under customFields.calendar.

What Dynamic CAP filter does

It keeps an alert when the Device carries the Tags the alert targets and the alert has not expired. Which Tags count as a match follows the CAP Datasource's own device identification rule: with the OR operator the Device needs any one of the alert's Tags, otherwise it needs all of them. Expired alerts are dropped either way.

A player that cannot report its Tags does no filtering

Tag matching needs the player to tell the script which Tags the Device carries. Where that is unavailable, no Tag filtering happens at all and every alert passes through. If a screen is showing alerts meant for other sites, check this before the rule itself.

Choosing the input

Source type decides what the script receives:

Source type	What it feeds in
Base data path	The Content's own bound data.
Single Datasource	One Datasource you pick in Source.
Multiple Datasources	Several at once. Custom calculator only.

With Multiple Datasources, select at least two — the rule shows Select at least 2 datasources until you do, and with fewer than two it quietly falls back to behaving like a single-Datasource rule. Inside the script each one is reachable by position: datasource1, datasource2, and so on, in the order listed. The editor prints that reference next to each Datasource name, so you never have to count.

Choosing where the result goes

Output mode offers three destinations, and appears on the Custom calculator only — every preset writes to an output property path.

• Output property path — adds the result as an extra property on the Datasource. This is the original behavior, and what every preset uses.
• Output to mock datasource — writes the result into a Mock Datasource you choose. Useful when several Contents should read the same calculated result.
• Overwrite internal datasource — writes the result into an internal Datasource, either replacing it or merging into it.

The fields on a rule

Field	What it does
Name	Free text, for your own reference. A preset fills in its own name.
Source type	Base data path, Single Datasource or Multiple Datasources.
Source	The base data path or the Datasource itself, depending on the source type.
Output mode	Where the result is written. Custom calculator only.
Output property path	A dot-separated path (property.property2) holding the result. This is what you bind a Widget to.
Target datasource	Which of the selected Datasources carries the output property. Appears only with Multiple Datasources.
Target mock datasource	The Mock Datasource the result is written into, with Output to mock datasource.
Target internal datasource	The internal Datasource the result is written into, with Overwrite internal datasource.
Write mode	With Overwrite internal datasource: SET (Replace all) replaces the Datasource's contents, MERGE (Merge with existing) merges the result into what is already there.
Open calculator editor	Opens the script itself, so a preset can be adjusted or a Custom rule written.

Reading the result

A mapper's result is reachable at the path it wrote to, so a Widget bound to customFields.todayEvents shows what Calendar today events produced. The presets' paths are in the table above; for a Custom rule it is whatever you typed into Output property path.

Recalculate periodically

Without it, a mapper recalculates whenever the Content loads or refreshes its Datasource data. Switch Recalculate periodically on to re-run every mapper on the Content on a fixed interval as well, and enter that interval in seconds.

Please note

If the original datasource's refresh time is greater than the value you wrote into the box, then the custom datasource may not refresh as often as you expect.

Example:

The datasource operates on a cron expression, setting the refresh interval to every 1 hour. If your datasource mapper has a refresh time value of 60 seconds, it won't be able to receive new information from the source until the cron-defined refresh cycle completes.

A worked example

An example that merges two calendar feeds with mappers and an action batch: Combine and filter calendar events.