How a source works
- One source, one card. A source names the card it fills. A card has at most one source, and an organization has up to 200 across its projects.
- It runs on a schedule. A calendar source syncs every 5 minutes.
--refreshsets any interval from the kind's shortest up to 24 hours: 1 minute for calendars, sheets, CSV, JSON and room sources, 2 minutes for point-of-sale sources, 30 seconds for a venue booking source and a preset's own minimum for a preset. A source runs within seconds of being created or changed, andsource refreshsyncs it now. - A failed sync never changes the card. The card keeps its last good document, and the source's status says what went wrong. Failures retry by themselves, waiting longer after each one.
- Only changes are written. When a sync finds what the card already holds, nothing is written and screens are not woken. A source with a stale period rewrites an unchanged document now and then to renew its deadline.
- Syncs are free. Documents count toward card data storage like any other write.
- Plans. Calendars, sheets, CSV, JSON and every preset are in every plan. Square, Shopify, Toast, Microsoft 365 and Google Workspace sources are connected sources, and the venue booking source is a Momentus source: Pricing lists the plans that include them. Without the plan, creating one answers
feature_not_in_plan, and a source already saved keeps running. - Credentials are sealed. An address that grants access is stored sealed, shown back only as its scheme and host, and never appears in a log, an error or the project's event log.
- It keeps the last good data for a period you choose. When a source cannot refresh, its card keeps the last good data for the source's stale period (
--stale-after, 1 minute to 7 days; a venue booking source keeps it for 30 minutes), then the data expires on every screen, offline ones included, and pages that depend on it fall back to the pages after them. Without a period the last good data stays until the source refreshes again. See When a source cannot refresh.
Start from a preset
A preset is a ready-made source for a service people often put on a screen. Pick one, fill in a few fields, add the credential the service issues, and screenRIG builds the source and maps the answer to the card. Presets are json sources, which every plan includes.
| Preset | Card | What it needs |
|---|---|---|
slack-channel | workplace-posts, message-wall | The channel ID, and the bot token (xoxb-…) of an internal Slack app in your workspace: at api.slack.com/apps add the scopes channels:history and groups:history, install the app, then add it to the channel |
bonusly | kudos | A Bonusly access token with recognition:read, which a Global or Tech admin creates under Company, Integrations, API & Tokens |
facebook-page | social-wall | The Page ID, the name to show, and a Page access token with pages_read_engagement and pages_show_list from the Graph API Explorer |
instagram-business | social-wall | The Instagram account ID, the name to show, and the access token of the linked Facebook Page with instagram_basic, pages_show_list and pages_read_engagement |
google-reviews | reviews | The place ID, and a Google Cloud API key with the Places API (New) enabled |
google-travel-times | travel-times | A starting address, one to eight destinations, drive or transit, and a Google Cloud API key with the Routes API enabled |
greenhouse-jobs | now-hiring | The board token from boards.greenhouse.io/TOKEN. No credential: the board is public |
lever-jobs | now-hiring | The site name from jobs.lever.co/NAME and the region. No credential |
ashby-jobs | now-hiring | The board name from jobs.ashbyhq.com/NAME. No credential |
github-actions | build-board | The owner, repository and branch, and a fine-grained personal access token with read-only Actions access to that repository, from github.com/settings/personal-access-tokens |
api-football-scores | scores | The league ID, the season, the screen's time zone, whether to show the day's games or only the games in play, and an API-Sports key from dashboard.api-football.com |
api-football-standings | standings | The league ID and the season, and the same API-Sports key |
api-sports-scores | scores | The sport (basketball, hockey, baseball or american-football), the league ID, the season, the screen's time zone, and the same API-Sports key |
api-sports-standings | standings | The sport, the league ID and the season, and the same API-Sports key |
The dashboard, the CLI and the API list the presets, with each field's help line and example and the steps to get each credential: screenrig source presets lists them and screenrig source presets NAME shows one, and GET /api/source-presets and GET /api/source-presets/NAME do the same (the Data sources group of the API reference). Make a source from a preset with --preset NAME in place of --kind, the preset's fields as --set FIELD=VALUE and its credential from a file:
screenrig source presets slack-channel
screenrig source test --preset slack-channel --card crd_CARD \
--set channel=C0123456789 --secret token=@slack.token
screenrig source create --preset slack-channel --card crd_CARD --name "Announcements" \
--set channel=C0123456789 --secret token=@slack.tokenOver the API, a preset source takes preset, settings and secrets in place of kind and config. Keep the credential in the request file, not on the command line, and replace BOT_TOKEN with the token:
{
"name": "Announcements",
"preset": "slack-channel",
"target": {"card_id": "crd_CARD"},
"settings": {"channel": "C0123456789", "channel_label": "#announcements"},
"secrets": {"token": "BOT_TOKEN"}
}curl -sS https://api.screenrig.ai/api/sources/test \
-H "Authorization: Bearer $SCREENRIG_TOKEN" -H "Content-Type: application/json" -d @source.jsonPOST /api/sources/test prints the document the card would show, whether the card accepts it and what it noticed, and writes nothing. POST /api/sources saves the same file, and PATCH /api/sources/ID with new settings builds the source again from the preset.
- Your account, your terms. A preset reads your own account with a credential you create, under the service's terms, and the card shows what those terms ask: Google reviews appear with the Google mark and each reviewer's name.
- Schedule and expiry. Each preset sets its own interval and stale period, such as a minute and 15 minutes for Slack, or 6 hours and 24 hours for Google reviews. A source may choose another interval, never one shorter than its preset's minimum. When a sync fails the card keeps its last data until the stale period passes, then goes blank.
- Billing at the service. Each Google reviews refresh is one Place Details request on your Google Cloud project, and each Google travel times refresh is one route element for every destination: four destinations every 15 minutes are about 11,500 elements a month.
- Slack needs an internal app. Do not distribute it: Slack limits a distributed app outside its Marketplace to one request a minute. The app reads only the channels it was added to, and the card shows people's own messages, not joins, bot posts or channel notices.
- API-Sports. The sports presets use your own API-Sports key, one key for football, basketball, hockey, baseball and American football, under API-Sports' terms: the data is for your own screens. Each refresh is one request counted against your API-Sports account, and a free account allows 100 a day for each sport. Scores refresh every 20 minutes and standings every 6 hours, which together use 76 of a sport's 100 requests a day, and every source that reads one key shares the allowance. A spent quota, a season the account's plan lacks or a refused key fails the sync, and the card keeps its data.
Create a source
Create the card first, then preview, then save.
screenrig card create --type events --file events.json
screenrig source test --kind ics --card crd_CARD \
--set 'calendars=[{"key":"lobby"}]' --set time_zone=America/Vancouver \
--secret calendar_url.lobby=@lobby.url
screenrig source create --kind ics --card crd_CARD --name "Lobby calendar" \
--set 'calendars=[{"key":"lobby"}]' --set time_zone=America/Vancouver \
--secret calendar_url.lobby=@lobby.url
screenrig source show src_SOURCEsource test fetches the address, shapes it for the card and checks the result against the card, and saves and writes nothing. It prints the document, whether the card accepts it, and what it noticed along the way. Give the address in a file (@FILE) or on stdin (-) so it stays out of your shell history.
| Command | What it does |
|---|---|
source list, source show ID | The project's sources, with status, settings and masked secrets |
source create | Saves a source and runs it within seconds. --preset NAME replaces --kind, and --disabled saves it stopped |
source update ID | Changes the name, card, settings (--set KEY=VALUE, or --settings JSON), secrets (--secret, --unset-secret), schedule (--refresh 10m) or --enable and --disable |
source test | Previews a source, saved or not, without writing |
source refresh ID | Syncs now and shows the result |
source presets [NAME] | Lists the presets, or shows one preset's fields, credentials and where to get them |
source rooms ID | The room mapping of a venue booking source: see Check the mapping |
source delete ID | Removes the source; the card keeps its last document |
--settings takes the source's whole config as JSON, @FILE or -. The --config option of the CLI names its credential file and has nothing to do with sources. Previews are limited to 30 a minute for an organization, and source refresh to 6 a minute for a source.
In the dashboard, New data source on the Data sources page opens a picker of kinds and presets and a form in three steps, Connect, Data and Card, with a Test button that previews the source without saving it.
When a source cannot refresh
A source writes each document with a deadline: its stale period after the write, renewed as the source keeps refreshing. While the source works, the deadline keeps moving. When it fails, the card keeps showing the last good data until the deadline, and then the data expires on every screen, offline ones included.
- Set the period with
--stale-after 30monsource createorsource update, from 1 minute to 7 days and at least twice the refresh interval.--stale-after nonekeeps the last good data until the next refresh. A venue booking source (momentus) keeps it for 30 minutes and a preset for its own period unless you say otherwise; the other kinds keep it until the next refresh. - Fall back to your own content. A page whose
visibility.datacondition names the document (for a room,momentus-room-{screen.field.room}) shows while the data is there and gives way to the next page when it expires. Keep an ordinary page after it, with your own branding, as the fallback. - Read it.
source showlistsstale_after,data_expires_atand, once the data has expired while the source keeps failing,stale: true. The dashboard's Data sources page shows the same: a failing source is Failing, and one whose data has expired is Stale. - Be told. A notification on the conditions
source_failed(a refresh failed) andsource_stale(the data expired) emails people or posts to Slack, Teams, PagerDuty or Telegram, as for a screen:screenrig notifications create --email owner --conditions source_failed,source_stale --hold 5. A notice names the source and links its page, clears when a refresh works, and--tagnever matches a source.
Status and errors
Every source shows its status: when it last ran, last succeeded and last changed the card, when it runs next, how many syncs in a row have failed, and the last error.
| State | Meaning |
|---|---|
pending | The source has not run yet |
ok | The last fetch succeeded and the card accepted the document |
error | The last sync failed; the card keeps its last good document |
disabled | The schedule is stopped |
ok does not judge whether the data upstream is right or current, or whether a screen shows the card.
| Error code | What happened |
|---|---|
unreachable | screenRIG could not reach the address. Use a public http(s) address on port 80 or 443 |
timeout | The address did not answer within 20 seconds |
too_large | The answer is larger than 5 MB |
http_status | The address answered with an HTTP error. A 404 means the address is no longer right |
auth_failed | The address refused the credentials; the next try waits an hour |
not_shared | A Google Sheet is not shared: Google answered with a sign-in page, a 401 or a 403. Share it with Anyone with the link, or publish it to the web |
parse_failed | The answer is not a calendar. A sign-in page reads as a web page, not a calendar: use the calendar's ICS address |
rate_limited | The service is limiting requests; the next sync waits |
mapping_failed | The mapping could not read the answer at the place the message names, such as a rows_path that finds no array |
card_data_invalid | The card refused the document at the path the message names |
target_missing | The card was deleted. Point the source at another card |
payment_required | The project's storage is full, so the document was not written |
config_invalid | A setting or stored secret can no longer be used. Enter it again |
internal | The sync failed inside screenRIG and retries |
Creating or changing a source can answer source_target_taken (the card already has a source), source_target_unsupported (the kind cannot fill that card; the answer lists the cards it can), source_secret_required (a secret is missing, or was entered for a different address and must be entered again), source_limit_reached and source_busy (a sync is running; retry after the interval). source test answers source_test_failed with the reason when the address cannot be read.
Calendars
A calendar source reads iCalendar (ICS) addresses: the secret address Google Calendar, Outlook, iCloud and Nextcloud give for a calendar, and any webcal:// link. It fills an events card with one agenda of every calendar, or a study-rooms card with one room per calendar, and fills a room or room-board card as described in Meeting rooms.
| Setting | Meaning |
|---|---|
calendars | 1 to 60 calendars, each {key, name, floor, capacity}. The key is lower-case letters, digits, - and _; name, floor and capacity label a room |
days | How many days from today to show, 1 to 31 (default 7) |
time_zone | An IANA zone such as America/Vancouver, used for the day boundary and for times a feed leaves unzoned |
private_title | The title shown for private events (default Private) |
include, exclude | Keywords that keep or hide events by title: see Keep or hide events by keyword |
Each calendar has one secret, calendar_url.KEY, holding its address.
- Recurring events (daily, weekly, monthly and yearly rules, exceptions, moved and cancelled occurrences) and time zones are expanded on the server, so an event keeps its hour across daylight saving time and a card never repeats the calendar's own rules. Windows time zone names from Outlook are understood.
- Private events (
CLASS:PRIVATEorCONFIDENTIAL) show their times only, with the private title and no organiser or location. The rule covers those marked private and does not judge what other events reveal. - Free time (events marked transparent or free) is kept on an agenda and left out of a room board, where only busy time counts. Cancelled events are dropped, and tentative ones count as busy.
- All-day events show as dates; an event with no end shows no end.
- Warnings. When a feed names no time zone, uses one screenRIG cannot place, or holds more than 500 occurrences of one event or 5,000 events, the sync succeeds and the status lists a warning.
- Several calendars sync together: if one fails, the sync fails whole and the error names the calendar, so a board never shows a partial set.
Keep or hide events by keyword
ics, microsoft365, google_calendar and momentus sources take two optional settings, include and exclude, each a list of 1 to 20 keywords of 1 to 100 characters. An event stays when its title holds at least one include keyword (when include is set) and none of the exclude keywords. A keyword matches inside a title without regard to case or accents, so café and CAFE match each other.
- Title only. The location, organizer and description are never matched. An event with no title is matched as
Untitled event. - Private events are matched on their own title and still show the private title. The private title itself is never matched, so
exclude: ["private"]removes nothing. - Everything the source writes reads the filtered calendars: the card and each keyed room document. A filter removes events only, never a calendar or a room, and free events count like the rest.
- The status counts what was left out as
filtered, 0 included. When the window holds events and the keywords leave none, the sync succeeds with a warning that says to check them, and the card shows an empty list.source testshows the same.
screenrig source create --kind ics --card crd_EVENTS --name "Public events" \
--set 'calendars=[{"key":"main"}]' --set 'include=["open house","tour"]' --set 'exclude=["cancelled"]' \
--secret calendar_url.main=@calendar.urlSheets, CSV and JSON
A sheets, csv or json source reads a table or a JSON document and builds a card's data from it with a mapping, so it fills any card: a menu from a price list, a KPI board from a metrics sheet, a table from a standings sheet. The mapping is a JSON template in the source's settings. The card's own rules decide whether what the mapping builds is accepted, and source test prints the document and whether the card accepts it, so you edit the mapping until it does. These sources sync every 5 minutes, and every minute at the shortest.
screenrig source test --kind sheets --card crd_MENU --settings @menu-sheet.json
screenrig source create --kind sheets --card crd_MENU --name "Cafe menu" --settings @menu-sheet.json
screenrig source create --kind json --card crd_KPI --name "Daily numbers" \
--settings @kpi-api.json --secret token=@api.token| Setting | Kinds | Meaning |
|---|---|---|
url | all | The sheet's link, or the address of the CSV file or JSON document: a public http(s) address on port 80 or 443 |
mapping | all | The template that builds the card's data. Required |
key_template | all | Optional key with {screen.field.NAME} tokens; the mapping returns a documents array of {fields,document} |
sheet | sheets | A tab's name, to read a tab other than the one the link names |
header_row | sheets, csv | true (default) when the first row holds the column names; false when every row is data, named Column 1, Column 2 |
key_column | sheets, csv | The column whose cells name the rows, so the mapping can look a row up by name |
delimiter | csv | ,, ; or tab. By default the one the first line uses most |
auth | csv, json | none (default), bearer, header, basic, oauth2 or token_request: see Requests, sign-in and pages |
header_name | csv, json | With auth header, the header that carries the token, such as X-API-Key |
rows_path | json | Where the array of rows sits in the answer, such as data.items |
key_field | json | The member of each row that names it. Set it together with rows_path |
Share a Google Sheet
A sheets source reads the sheet through Google's CSV export. It needs no sign-in and no access to your Google account, and the sheet has to be readable by anyone who has its link.
- In Google Sheets choose Share, set General access to Anyone with the link and the role to Viewer. To publish instead, choose File, Share, Publish to web.
- Copy the link from the browser's address bar into
url. A link to a tab keeps that tab. To read another tab by name, setsheet; a published link takes nosheet. - Preview with
source test. The sheet's header row becomes the column keys the mapping reads.
A sheet that is not shared answers with a sign-in page, a 401 or a 403. The status is then not_shared, and the message names the setting to change: Share, General access, Anyone with the link, Viewer, or File, Share, Publish to web. Ask the sheet's owner to share it. not_shared judges only those three answers. It does not compare the columns with your mapping.
Addresses with a token
A CSV file or JSON document at a public address needs no token. For a protected one, set auth to bearer (screenRIG sends Authorization: Bearer TOKEN) or to header with header_name (it sends HEADER_NAME: TOKEN), and give the token as the secret token:
screenrig source create --kind csv --card crd_TABLE --name "Standings" \
--settings @standings.json --secret token=@api.tokenThe token is stored sealed and shown back only as a hint: its last four characters when it has 12 or more, otherwise …. It is sent only to the address's own origin, the scheme, host and port. A redirect to another site is not followed with the token, and pointing the source at another origin without entering the token again is refused with source_secret_required. Changing only the path or the query keeps the token. For basic, OAuth 2 and token requests, and for a request with a body, headers or pages, see Requests, sign-in and pages. header_name cannot be Host, Cookie, Content-Length, Connection, Transfer-Encoding, Upgrade or a Proxy- header, or a header screenRIG sets itself.
Requests, sign-in and pages
A csv or json source sends a GET to its url. These settings send a body or extra headers, sign in, read more than one page and put today's date in a request. Each request has 20 seconds and a whole run has 60.
| Setting | Meaning |
|---|---|
method | GET (default) or POST. A body or graphql makes it a POST |
body | A JSON object or array, or text sent as written. At most 16 KiB once its placeholders are filled in |
body_format | json (default) or form. A form body is an object of text, number and boolean fields, or text such as a=1&b={{today}}; the values are URL-encoded |
graphql | {query, variables}, sent as a JSON POST. An answer with errors and no data is parse_failed; errors beside data are a warning |
headers | Up to 8 more headers whose values are not secrets. Authorization is refused, and so is any header header_name refuses: use auth or a header secret |
time_zone | An IANA zone for the date placeholders. Without one they read UTC and the status lists a warning |
pagination | Reads more than one page, as described below |
format | json kind only: auto (default), json, csv or xml |
A secret named header.NAME is sent as the header NAME, so an API with two credential headers takes header.X-Client-Id and header.X-Api-Key. A secret named query.NAME is added to the address as NAME=value. Each kind takes up to 8, both are stored sealed and never shown, and the preview prints a query secret as NAME=***.
| Authentication | Settings and secrets |
|---|---|
none | The default |
bearer | The secret token, sent as Authorization: Bearer |
header | header_name and the secret token |
basic | username (no colon) and the secret password, sent as Authorization: Basic |
oauth2 | Client credentials: token_url, client_id, optional scope and audience, token_auth (body, the default, or basic) and the secret client_secret. screenRIG asks token_url for a token and sends it as Authorization: Bearer |
token_request | A login that returns a token: token_url, token_body (an object whose strings may read stored secrets as {{secrets.NAME}}), token_body_format (json or form), token_path (where the token sits in the answer, such as token.accessToken) and optionally token_expires_path, token_ttl (60 to 86,400 seconds, 3,600 by default) and header_name (the header that carries the token as it is; without it Authorization: Bearer) |
screenRIG keeps a token in memory, never in storage, and renews it a minute before it expires. When the address refuses a token with a 401 it asks for a new one once. A refusal at the token address (HTTP 400, 401 or 403) is auth_failed, and nothing the token address says is quoted.
{
"url": "https://api.example.com/v2/orders/summary",
"method": "POST",
"body": {"from": "{{today-7d}}", "to": "{{today}}"},
"time_zone": "America/Vancouver",
"auth": "oauth2",
"token_url": "https://login.example.com/oauth/token",
"client_id": "screen-signs",
"scope": "orders.read",
"mapping": {"body": "{{body.total}} orders this week"}
}screenrig source create --kind json --card crd_BOARD --name "Orders" \
--settings @orders.json --secret client_secret=@client.secretDate placeholders fill the address, the body and headers: {{now}} (2026-11-01T17:30:00Z), {{today}} (2026-11-01) and {{unix}} (seconds), each with an optional offset such as {{now-90m}}, {{now+7d}} or {{today-1d}} (units m, h and d; {{today}} takes days only). They read in time_zone, or UTC. Every run fills them from the clock, so tomorrow's run asks for tomorrow's date.
Pages. pagination is {type, max_pages}, with max_pages from 1 to 20 (5 by default). A json source sets rows_path so the rows of the pages join at one array, and a csv source joins the table's rows.
| Type | How the next page is found |
|---|---|
link_header | The rel="next" address in the Link header |
next_url | path, the place in the answer that holds the next address (json only) |
cursor | param and path: the cursor goes in the address as param, or in the body with "in": "body", and the read ends when the cursor is missing or empty (json only) |
page | param, start (1 by default) and size_param with size: the page number goes in the address or, with "in": "body", the body, and the read ends on a page with no rows or fewer than size |
The next address must stay on the source's own origin, so a secret never leaves it. A repeated page, or more pages than max_pages, ends the read with a warning, and all the pages together are at most 5 MB.
XML and RSS. An answer that starts with <, or format xml, is read as XML. body holds the root element: attributes are @name, the text of an element that has children is #text, repeated elements are lists, and names keep their prefix (item["media:thumbnail"]["@url"]). An RSS or Atom feed also gets body.items, each entry with title, link, published, summary (plain text, up to 1,000 characters) and image, when the entry has them. A DOCTYPE is never followed and nothing is fetched from it.
source test shows the first request as it went out in request: the placeholders filled in, query secrets as NAME=***, the names of the headers beyond Accept and Content-Type without their values, the first 1 KiB of the body and the number of pages read.
What a source reads
- CSV and sheets. Ordinary CSV: a byte-order mark, quoted fields, doubled quotes, line breaks inside quotes and CRLF line ends are all read. Cells are trimmed and rows with no content are dropped. A header becomes a key in lower case, with accents folded and every run of other characters turned into one
_, soSold outissold_out; an empty header becomescolumn_3(its position) and a repeat_2,_3. A file that is not UTF-8 text, such as a spreadsheet file, isparse_failed: save it as CSV in UTF-8. - JSON. Numbers keep their digits. With
rows_paththe source finds the array of rows there; a path that finds no array ismapping_failedatrows_path, and an empty array is a table of no rows. - Limits. A table is read up to 10,000 rows and 200 columns. Past that the sync succeeds and the status lists a warning that counts the rows or columns left out.
- A web page at the address, rather than the data, is
parse_failed.
The mapping
The mapping is a JSON template. A string with placeholders such as {{item.price}} is text, and a string that is exactly one placeholder keeps the value's type. A path that holds nothing is empty in text and leaves a lone value out, so the card then names what it lacks. What a path can start from depends on the kind:
| Kind | Starts from | Holds |
|---|---|---|
sheets, csv | rows | Every data row, an object by column key |
sheets, csv | columns | [{key, name}] in the order of the sheet |
sheets, csv | by_key | With key_column: the rows by the trimmed text of that column's cell |
json | body | The whole answer |
json | by_key | With rows_path and key_field: the rows by the trimmed text, number or boolean of that member |
Prefer by_key to a position such as rows[2]: a row found by its key stays found when someone sorts the sheet or inserts a row above it. Write a key with spaces as by_key["Net sales"].value. If two rows share a key, the first wins and the status lists a warning that counts the repeats. No warning quotes a cell.
Cells are text, so convert them: {"$number": "{{item.price}}"} reads 1,234.50, $4.50, 3,50 € and 12% (add "$decimal": "," for a comma mark), and {"$bool": "{{item.sold_out}}"} reads true, yes, y, 1 and x. $each maps a list with item and index in scope, $group with $by groups rows in first-seen order with group.key and group.items in scope, and $text with $max cuts text. The template is checked when the source is saved.
A menu from a sheet with the columns Section, Item, Price and Sold out groups the rows by section:
{
"url": "https://docs.google.com/spreadsheets/d/SHEET_ID/edit#gid=0",
"mapping": {
"sections": {
"$group": "{{rows}}", "$by": "{{item.section}}",
"$template": {
"name": "{{group.key}}",
"items": {
"$each": "{{group.items}}",
"$template": {
"name": "{{item.item}}",
"price": { "$number": "{{item.price}}" },
"soldOut": { "$bool": "{{item.sold_out}}" }
}
}
}
}
}
}A KPI board from a sheet with the columns Metric, Value, Unit and Change looks each metric up by name, so sorting the sheet moves nothing:
{
"url": "https://docs.google.com/spreadsheets/d/SHEET_ID/edit#gid=0",
"key_column": "Metric",
"mapping": {
"tiles": [
{ "label": "Revenue", "value": { "$number": "{{by_key.Revenue.value}}" },
"unit": "{{by_key.Revenue.unit}}", "delta": { "$number": "{{by_key.Revenue.change}}" } },
{ "label": "Orders", "value": { "$number": "{{by_key.Orders.value}}" },
"delta": { "$number": "{{by_key.Orders.change}}" } }
]
}
}A table card lists every row:
{
"mapping": {
"rows": {
"$each": "{{rows}}", "$limit": 50,
"$template": {
"team": "{{item.team}}",
"points": { "$number": "{{item.points}}" },
"played": { "$number": "{{item.played}}" }
}
}
}
}To see what a source reads, test with the mapping {"columns": "{{columns}}", "rows": "{{rows}}"}. The card refuses that document, and the preview still prints it, with every key and row.
ok on one of these sources means the address answered and the card accepted the mapped document. It does not say the sheet or the answer holds the rows your mapping expects: a column that disappears leaves its member out, and the card refuses a document that lacks a required one.
Computed values
A mapping can also compute true or false and numbers on the server, so a page condition that only tests equality, such as visibility.data with equals: true, can follow a number. Card webhook and overlay trigger mappings have the same helpers.
| Helper | Gives | Written |
|---|---|---|
$gt, $gte, $lt, $lte | True or false, reading both values as numbers | {"$lt": ["{{body.stock}}", 5]} |
$between | True when the value is within both bounds, inclusive | {"$between": ["{{body.temp}}", 18, 24]} |
$eq, $ne | Numbers by value (5, "5" and "5.00" match), anything else as exact text, case included | {"$eq": ["{{body.status}}", "open"]} |
$contains | Text holds text, ignoring case, or a list holds a value | {"$contains": ["{{body.title}}", "closed"]} |
$in | The value is one of a list | {"$in": ["{{body.tier}}", ["gold", "silver"]]} |
$and, $or, $not | Combine conditions | {"$and": [{"$gt": ["{{body.a}}", 1]}, {"$not": {"$eq": ["{{body.s}}", "x"]}}]} |
$sum, $avg, $min, $max | One number from a list | {"$sum": "{{rows}}", "$of": "{{item.amount}}"} |
$count | How many elements, or how many pass $where | {"$count": "{{body.queue}}", "$where": {"$gt": ["{{item.wait}}", 5]}} |
- A comparison that cannot be made is false, with a warning that names the place and never the value, so a missing, empty or non-numeric value never switches a page on.
$boolis the one reader that takes a missing value as false. - Lists.
$ofreads one placeholder from each element, withitemandindexin scope, and$wherekeeps the elements a condition holds for. An element that is empty or not a number is skipped, and one warning counts them. With nothing to add up,$sumand$countare 0 and$avg,$minand$maxleave their member out. - Numbers. A comma mark (
3,50,1.234,50) needs"$decimal": ",".$avgrounds to 2 places, and"$round"sets 0 to 6.$sum,$minand$maxare exact.
A low-stock flag from a JSON answer. A page whose visibility.data names the document with path /low_stock and equals true shows only while stock is low:
{
"sku": "{{body.sku}}",
"stock": {"$number": "{{body.stock}}"},
"low_stock": {"$lt": ["{{body.stock}}", 5]}
}From a sheet, any product below its own reorder level:
{"low_stock": {"$gt": [{"$count": "{{rows}}", "$where": {"$lt": ["{{item.stock}}", "{{item.reorder_at}}"]}}, 0]}}Shaping helpers
A vendor's answer often needs tidying before a card reads it: a chat channel holds joins and bot posts, a feed writes times as epoch seconds, a route matrix answers in seconds and metres. These helpers only look values up. One that cannot work leaves its member out with a warning that names the place and never quotes the data.
| Helper | Gives | Written |
|---|---|---|
$where and $limit on $each or $group | The elements a condition holds for, then the first $limit of those | {"$each": "{{body.messages}}", "$where": {"$exists": "{{item.text}}"}, "$limit": 20, "$template": T} |
$find | T for the first element a condition holds for, with item and index in scope; none leaves the member out | {"$find": "{{body}}", "$where": {"$eq": ["{{item.destinationIndex}}", 2]}, "$template": T} |
$exists | True when the value is there: not null, not blank text, not an empty list or object (0 and false are values) | {"$exists": "{{item.subtype}}"} |
$first | The first value that exists | {"$first": ["{{item.thumbnail_url}}", "{{item.media_url}}"]} |
$join | The texts of a list in one line, $sep between them (", " by default), at most $limit of them and $max characters | {"$join": "{{item.receivers}}", "$of": "{{item.display_name}}", "$max": 60} |
$time | An instant as 2026-11-01T17:30:00Z, from RFC 3339 text or from epoch seconds ("$unit": "ms" for milliseconds) | {"$time": "{{item.ts}}"} |
$number with $mul, $div and $round | The number scaled, then rounded half away from zero to $round places | {"$number": "{{item.duration}}", "$div": 60, "$round": 0} |
$find over the whole answer ({{body}}) reads one row by an index or an id, whatever order the rows arrive in.
Keyed documents
JSON, CSV and Sheets sources accept key_template, for example room-{screen.field.room}. Map the feed to a documents array of {"fields":{"room":"A101"},"document":{"body":"Room A101"}} objects. A card webhook uses --key-template with the same output, or receives the envelope directly without a mapping.
{
"key_template": "room-{screen.field.room}",
"mapping": {
"documents": {
"$each": "{{rows}}",
"$template": {
"fields": {"room": "{{item.room}}"},
"document": {"body": "{{item.title}}"}
}
}
}
}Place the owning crd_ instance with data: "room-{screen.field.room}"; each screen reads only the key filled from its own room field. All outputs use the instance's card schema. Use separate instances, mappings and prefixes for different card types reading the same feed.
Preview with source test. Invalid documents, missing fields and duplicate keys refuse the batch before writing. A storage failure can leave part written: retry the identical webhook body with the same Idempotency-Key, or refresh the source. Omitted keys keep their previous data and expiry; webhooks set no expiry. Clear a webhook's template with --clear-key-template.
Tips for files and sheets
- OneDrive and SharePoint. A share link opens a preview page, which a source reads as a web page (
parse_failed). Add?download=1to the link of a CSV file, or&download=1when it already has a?, so the link returns the file itself. The link has to work without a sign-in. - Look rows up by name. Set
key_columnto the column that names each row, by its header in any case, and read a row asby_key.NAME.column: sorting the sheet or inserting a row moves nothing. A name that matches no column ismapping_failedatkey_column, and a repeated key keeps the first row with a warning that counts the repeats.
Meeting rooms
A room source reads meeting-room calendars and fills a room card, the door sign of one room, or a room-board card, every room of a building. It can also fill an events agenda or a study-rooms card, and a calendar address (ICS) fills the same cards.
The cards work out free, in use and next on the screen every second from the bookings they hold, so a sign stays right while its screen is offline. A room source only reads: a card shows bookings and takes no input, so nothing is booked, ended or checked in from a screen.
| Setting | Meaning |
|---|---|
rooms | 1 to 60 rooms, each with a key (lower-case letters, digits, - and _), the room's address (email for Microsoft 365, calendar_id for Google) and optional name, floor and capacity. A room card takes exactly one room |
days | How many days from today to show, 1 to 31 (default 7) |
time_zone | An IANA zone such as America/Los_Angeles, used for the day boundary and for all-day events. Without one the day starts at midnight UTC and the status lists a warning |
private_title | The title shown for private events (default Private) |
Microsoft 365 room mailboxes
Kind microsoft365 reads Exchange Online room mailboxes through Microsoft Graph with your own Microsoft Entra app, so the app, its secret and what it can read stay yours. Two more settings: tenant, the directory id or a verified domain such as contoso.com (common, organizations and consumers are refused), and client_id, the app's application (client) id. The secret client_secret is the app's client secret value.
- In the Microsoft Entra admin center register a single-tenant app with no redirect URI, add a client secret (copy its Value, not its Secret ID), add the Microsoft Graph application permission
Calendars.Readand grant admin consent. - Scope the app to the room mailboxes.
Calendars.Readreaches every mailbox in the organization until an application access policy restricts it. Put the rooms in a mail-enabled security group and run the first two commands below in Exchange Online PowerShell;Test-ApplicationAccessPolicyanswersGrantedfor a room in the group. Exchange RBAC for Applications scopes an app the same way. - Room mailboxes replace a meeting's subject with the organizer's name unless told otherwise. To show meeting titles, run the third command for each room.
- Preview, then save.
source testsigns in, reads each room and reports the rooms and bookings it read, a count per room and, when the app also holdsPlace.Read.All, how many rooms the organization lists.
# Exchange Online PowerShell
New-ApplicationAccessPolicy -AppId CLIENT_ID -PolicyScopeGroupId rooms@example.com -AccessRight RestrictAccess -Description "screenRIG room signs"
Test-ApplicationAccessPolicy -AppId CLIENT_ID -Identity boardroom@example.com
Set-CalendarProcessing -Identity boardroom@example.com -DeleteSubject $false -AddOrganizerToSubject $false
# screenRIG (source create takes the same options, plus --name)
screenrig source test --kind microsoft365 --card crd_ROOM \
--set tenant=contoso.com --set client_id=CLIENT_ID --set time_zone=America/Los_Angeles \
--set 'rooms=[{"key":"boardroom","email":"boardroom@example.com","name":"Boardroom","floor":"Level 4","capacity":12}]' \
--secret client_secret=@secret.txt- Mapping. Private and confidential meetings show the private title and no organizer. Meetings marked free or working elsewhere, and meetings the room declined, are free time; tentative meetings count as busy; cancelled ones are dropped. All-day events are dates in the room's zone.
- Schedule. A room source syncs every 2 minutes. The sign-in lasts about an hour and is reused.
- Errors. Microsoft's own error code and text are quoted, for example
AADSTS7000215for a wrong client secret, and one room the app cannot read fails the sync and names the room. - A connection instead. Set
connection_id(or pass--connection-id) to a Microsoft connection of the project, in either mode, in place oftenant,client_idandclient_secret. The source then holds no secret and signs in as the connection does.
Google Workspace resource calendars
Kind google_calendar reads resource and room calendars as your own Google service account. The secret service_account_key is the key file as Google issues it, and its hint is the account's address. The optional setting subject names the user the account acts as under domain-wide delegation.
- In Google Cloud enable the Google Calendar API, create a service account and download a JSON key for it.
- Give the account access to the rooms. Either share each room calendar with the account's address and the permission See all event details, or turn on domain-wide delegation for the account in the Admin console with the scope
https://www.googleapis.com/auth/calendar.events.readonlyand setsubjectto a user who can see the rooms. - A room's
calendar_idis the resource's calendar ID in the Admin console under Buildings and resources; it ends in@resource.calendar.google.com. Preview withsource test, then save.
screenrig source test --kind google_calendar --card crd_ROOM \
--set time_zone=America/Los_Angeles \
--set 'rooms=[{"key":"boardroom","calendar_id":"CALENDAR_ID","name":"Boardroom"}]' \
--secret service_account_key=@key.json- Mapping. Private and confidential events show the private title and no organizer. Events marked transparent, and events the room declined, are free time; cancelled ones are dropped. All-day events keep their dates.
- Errors. Google's own error text is quoted. A calendar the account cannot see is named in the error, with how to share it.
- A connection instead. Set
connection_id(or pass--connection-id) to a Google connection of the project in place ofservice_account_key. With screenRIG's app the source reads the calendars the account that approved it can see, so that account must see every room calendar the source lists, andsubjectis not allowed.
Limits and privacy
- A
roomcard holds the 200 earliest bookings and aroom-boardcard 60 per room. When more exist the status lists a warning with how many were left out. - The card's document carries only what the card draws, because every screen that shows a card keeps its document. A
roomcard gets organizers only withshowOrganizeron. Aroom-boardcard never gets organizers, and gets the private title in place of each meeting title unlessshowTitlesis on. A change to either setting reaches the card at the next sync. A private meeting carries the private title either way. - Messages for these kinds quote the error text Microsoft or Google answered, and never a secret.
A venue's booking system
Kind momentus reads the functions (each use of a room, with its dates and times) and the spaces of a Momentus Enterprise installation, the system formerly sold as Ungerboeck and EBMS, with an API user your administrator creates in Momentus (Main Menu, Api Users). It fills an events card for an event directory, a room-board card for a lobby or a hallway, or a room card for one room, and with a document for each room, every screen shows its own room's bookings. A room that changes shortly before an event shows within the refresh interval, a minute by default.
| Setting | Meaning |
|---|---|
base_url | The https address of your Momentus web server, such as https://momentus.example.com/prod; the API is read from {base_url}/api/v1/... |
organization | The Momentus organization code the data is read from |
api_user | The API user's id |
time_zone | The venue's IANA zone. Momentus keeps local dates and times, so set it; without it times are read as UTC and the status lists a warning |
days | How many days from today to read, 1 to 31 (default 7) |
rooms | Optional list of 1 to 400 rooms, each {key, space, name?, floor?, capacity?, area?}; space is the Momentus space code. Without it every space Momentus lists is a room (key: the code in lower case) |
space_filter, function_filter | Optional Momentus search expressions that narrow the spaces or the functions read |
exclude_status_codes | Function status codes to leave out, such as cancelled ones. Status codes are your venue's own, so there is no default |
include, exclude | Keywords that keep or hide functions by the title the source shows, as for calendars |
title_field | The function field that gives an event its title: Description (default) or AlternateDescription to AlternateDescription5 |
multiday | daily (default) shows a function over several dates with times at those times on each date, up to 31; continuous shows one event from the first start to the last end |
show_titles | true (default) shows meeting titles on the room-board documents written for areas; false shows the private title in place of each |
Two secrets: api_key, one of the API user's Key GUIDs, and api_secret, its Secret GUID. Both are stored sealed, never shown again and entered again if the source points at another server, organization or API user.
screenrig source test --kind momentus --card crd_EVENTS \
--set base_url=https://momentus.example.com/prod --set organization=10 \
--set api_user=venue-api --set time_zone=America/Los_Angeles \
--set 'exclude_status_codes=["XX"]' \
--secret api_key=@key.guid --secret api_secret=@secret.guid
screenrig source create --kind momentus --card crd_EVENTS --name "Venue events" \
--settings @momentus.json --secret api_key=@key.guid --secret api_secret=@secret.guidsource test reads Momentus, shapes the document and checks it against the card, and shows the rooms and events it read (functions, functions_other_spaces, events_KEY). Nothing is saved or written.
- What a function becomes. The function's
Spacepicks the room, itsDescriptionis the title (title_fieldcan name one of its alternate descriptions) and the room's name is the location. A function with no start time is an all-day event. A function over several dates with times shows those times on each date; one that ends before it starts runs overnight. - Private titles. A
room-boardcard that--cardnames shows the private title unless itsshowTitlesis on, as for the other room kinds. - Errors. Momentus's own text is never quoted, because the server is yours:
auth_failedmeans the API user, key or secret is wrong or may not read functions and spaces,config_invalidthat a filter is not a valid Momentus search, andparse_failedthatbase_urlreached a web page and not the API.
One sign for each room
Set room_key_prefix (for example momentus-room-) and the source also writes a room document for each room under that prefix followed by the room's key. Give each room's screen its room, and place a room card whose data key is the prefix followed by the screen's own field:
screenrig screen update scr_BALLROOM --field room=ballroom-aUse the inline catalogue type room in this playlist primitive:
{"id":"door","primitive":"card","card":"room","layout":"full","content_fit":"fill","params":{"room":"{screen.field.room}"},"data":"momentus-room-{screen.field.room}"}crd_ primitives use the instance's own params and major; omit those fields. Their optional data selects a document key or a per-screen key template. The source's --card crd_ID still names its sync target. For the page, set visibility.data.key to momentus-room-{screen.field.room} and add an unconditional fallback page after it.
The backend fills the field in each screen's manifest, so one playlist shows every screen its own room, and a screen without a room field shows nothing for that card. area_key_prefix does the same for a hallway display: each room's area groups it, and a room-board of that area's rooms is written under the prefix and the area's key (area_card can be events). screen_field and area_field name the screen fields the check below reads (room and area by default).
Check the mapping
screenrig source rooms src_ID (and the Room mapping section of the source's page in the dashboard) lists the rooms the source offers that no screen shows, and the screens whose room is missing or names a room Momentus does not have:
screenrig source rooms src_VENUEA screen is in the report when it has a value for the field, or when its own playlist places a card that reads the key. Each is mapped, missing (the playlist reads the field and the screen has none) or unknown (the value names no room; the report says the room it probably meant, such as the same letters in another case). Fix a screen with screenrig screen update scr_ID --field room=ROOM_KEY. The report reads the rooms of the source's last good refresh and fetches nothing; a source that lists its rooms knows them before its first refresh. A source of any other kind answers source_has_no_rooms.
Other ways to keep a card current
A source suits data that lives at an address and should stay current with nobody running anything. Two other paths fill a card, and some cards need none.
- Your own schedule. Write the card's document with
card data putand add--ttlsized to the schedule, so the card goes blank on every screen if the writer stops. A notification oncard_data_stalesays when it does: Write live values. - A system that pushes. A card webhook is a URL an outside system posts to, and it accepts the signature of GitHub, Stripe, Shopify, Slack and other senders: Card webhooks.
- A feed. Weather, air quality, alerts, tides and the other cards that read a feed are filled by screenRIG with no source: Feeds.
Security
An address that grants access is a credential. screenRIG stores it sealed, shows back only its scheme and host, and uses it only to run the sync. Sources read public http(s) addresses on port 80 or 443 and follow at most three redirects; an address that does not resolve to a public host, a refused connection and a failed handshake all read the same, so a source cannot be used to explore a network. No message quotes an address or the answer it returned. Sources only read: they never write to a calendar.