Documentation

Keep cards live from an outside address

A data source is an address screenRIG reads on a schedule. It writes what it finds into one card's data, so the card stays current without anyone republishing, and every screen showing the card refetches it when it changes. A Google, Outlook, iCloud or Nextcloud calendar becomes an agenda or a room board, a sheet or an API becomes a menu or a KPI board, and a preset turns a Slack channel, Google reviews or a job board into a card.

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. --refresh sets 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, and source refresh syncs 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.

PresetCardWhat it needs
slack-channelworkplace-posts, message-wallThe 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
bonuslykudosA Bonusly access token with recognition:read, which a Global or Tech admin creates under Company, Integrations, API & Tokens
facebook-pagesocial-wallThe 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-businesssocial-wallThe 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-reviewsreviewsThe place ID, and a Google Cloud API key with the Places API (New) enabled
google-travel-timestravel-timesA starting address, one to eight destinations, drive or transit, and a Google Cloud API key with the Routes API enabled
greenhouse-jobsnow-hiringThe board token from boards.greenhouse.io/TOKEN. No credential: the board is public
lever-jobsnow-hiringThe site name from jobs.lever.co/NAME and the region. No credential
ashby-jobsnow-hiringThe board name from jobs.ashbyhq.com/NAME. No credential
github-actionsbuild-boardThe 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-scoresscoresThe 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-standingsstandingsThe league ID and the season, and the same API-Sports key
api-sports-scoresscoresThe 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-standingsstandingsThe 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.token

Over 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.json

POST /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_SOURCE

source 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.

CommandWhat it does
source list, source show IDThe project's sources, with status, settings and masked secrets
source createSaves a source and runs it within seconds. --preset NAME replaces --kind, and --disabled saves it stopped
source update IDChanges the name, card, settings (--set KEY=VALUE, or --settings JSON), secrets (--secret, --unset-secret), schedule (--refresh 10m) or --enable and --disable
source testPreviews a source, saved or not, without writing
source refresh IDSyncs 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 IDThe room mapping of a venue booking source: see Check the mapping
source delete IDRemoves 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 30m on source create or source update, from 1 minute to 7 days and at least twice the refresh interval. --stale-after none keeps 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.data condition 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 show lists stale_after, data_expires_at and, 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) and source_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 --tag never 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.

StateMeaning
pendingThe source has not run yet
okThe last fetch succeeded and the card accepted the document
errorThe last sync failed; the card keeps its last good document
disabledThe schedule is stopped

ok does not judge whether the data upstream is right or current, or whether a screen shows the card.

Error codeWhat happened
unreachablescreenRIG could not reach the address. Use a public http(s) address on port 80 or 443
timeoutThe address did not answer within 20 seconds
too_largeThe answer is larger than 5 MB
http_statusThe address answered with an HTTP error. A 404 means the address is no longer right
auth_failedThe address refused the credentials; the next try waits an hour
not_sharedA 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_failedThe answer is not a calendar. A sign-in page reads as a web page, not a calendar: use the calendar's ICS address
rate_limitedThe service is limiting requests; the next sync waits
mapping_failedThe mapping could not read the answer at the place the message names, such as a rows_path that finds no array
card_data_invalidThe card refused the document at the path the message names
target_missingThe card was deleted. Point the source at another card
payment_requiredThe project's storage is full, so the document was not written
config_invalidA setting or stored secret can no longer be used. Enter it again
internalThe 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.

SettingMeaning
calendars1 to 60 calendars, each {key, name, floor, capacity}. The key is lower-case letters, digits, - and _; name, floor and capacity label a room
daysHow many days from today to show, 1 to 31 (default 7)
time_zoneAn IANA zone such as America/Vancouver, used for the day boundary and for times a feed leaves unzoned
private_titleThe title shown for private events (default Private)
include, excludeKeywords 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:PRIVATE or CONFIDENTIAL) 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 test shows 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.url

Sheets, 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
SettingKindsMeaning
urlallThe sheet's link, or the address of the CSV file or JSON document: a public http(s) address on port 80 or 443
mappingallThe template that builds the card's data. Required
key_templateallOptional key with {screen.field.NAME} tokens; the mapping returns a documents array of {fields,document}
sheetsheetsA tab's name, to read a tab other than the one the link names
header_rowsheets, csvtrue (default) when the first row holds the column names; false when every row is data, named Column 1, Column 2
key_columnsheets, csvThe column whose cells name the rows, so the mapping can look a row up by name
delimitercsv,, ; or tab. By default the one the first line uses most
authcsv, jsonnone (default), bearer, header, basic, oauth2 or token_request: see Requests, sign-in and pages
header_namecsv, jsonWith auth header, the header that carries the token, such as X-API-Key
rows_pathjsonWhere the array of rows sits in the answer, such as data.items
key_fieldjsonThe 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.

  1. 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.
  2. 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, set sheet; a published link takes no sheet.
  3. 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.token

The 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.

SettingMeaning
methodGET (default) or POST. A body or graphql makes it a POST
bodyA JSON object or array, or text sent as written. At most 16 KiB once its placeholders are filled in
body_formatjson (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
headersUp 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_zoneAn IANA zone for the date placeholders. Without one they read UTC and the status lists a warning
paginationReads more than one page, as described below
formatjson 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=***.

AuthenticationSettings and secrets
noneThe default
bearerThe secret token, sent as Authorization: Bearer
headerheader_name and the secret token
basicusername (no colon) and the secret password, sent as Authorization: Basic
oauth2Client 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_requestA 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.secret

Date 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.

TypeHow the next page is found
link_headerThe rel="next" address in the Link header
next_urlpath, the place in the answer that holds the next address (json only)
cursorparam 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)
pageparam, 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 _, so Sold out is sold_out; an empty header becomes column_3 (its position) and a repeat _2, _3. A file that is not UTF-8 text, such as a spreadsheet file, is parse_failed: save it as CSV in UTF-8.
  • JSON. Numbers keep their digits. With rows_path the source finds the array of rows there; a path that finds no array is mapping_failed at rows_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:

KindStarts fromHolds
sheets, csvrowsEvery data row, an object by column key
sheets, csvcolumns[{key, name}] in the order of the sheet
sheets, csvby_keyWith key_column: the rows by the trimmed text of that column's cell
jsonbodyThe whole answer
jsonby_keyWith 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.

HelperGivesWritten
$gt, $gte, $lt, $lteTrue or false, reading both values as numbers{"$lt": ["{{body.stock}}", 5]}
$betweenTrue when the value is within both bounds, inclusive{"$between": ["{{body.temp}}", 18, 24]}
$eq, $neNumbers by value (5, "5" and "5.00" match), anything else as exact text, case included{"$eq": ["{{body.status}}", "open"]}
$containsText holds text, ignoring case, or a list holds a value{"$contains": ["{{body.title}}", "closed"]}
$inThe value is one of a list{"$in": ["{{body.tier}}", ["gold", "silver"]]}
$and, $or, $notCombine conditions{"$and": [{"$gt": ["{{body.a}}", 1]}, {"$not": {"$eq": ["{{body.s}}", "x"]}}]}
$sum, $avg, $min, $maxOne number from a list{"$sum": "{{rows}}", "$of": "{{item.amount}}"}
$countHow 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. $bool is the one reader that takes a missing value as false.
  • Lists. $of reads one placeholder from each element, with item and index in scope, and $where keeps 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, $sum and $count are 0 and $avg, $min and $max leave their member out.
  • Numbers. A comma mark (3,50, 1.234,50) needs "$decimal": ",". $avg rounds to 2 places, and "$round" sets 0 to 6. $sum, $min and $max are 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.

HelperGivesWritten
$where and $limit on $each or $groupThe elements a condition holds for, then the first $limit of those{"$each": "{{body.messages}}", "$where": {"$exists": "{{item.text}}"}, "$limit": 20, "$template": T}
$findT 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}
$existsTrue when the value is there: not null, not blank text, not an empty list or object (0 and false are values){"$exists": "{{item.subtype}}"}
$firstThe first value that exists{"$first": ["{{item.thumbnail_url}}", "{{item.media_url}}"]}
$joinThe 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}
$timeAn 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 $roundThe 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=1 to the link of a CSV file, or &download=1 when 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_column to the column that names each row, by its header in any case, and read a row as by_key.NAME.column: sorting the sheet or inserting a row moves nothing. A name that matches no column is mapping_failed at key_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.

SettingMeaning
rooms1 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
daysHow many days from today to show, 1 to 31 (default 7)
time_zoneAn 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_titleThe 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.

  1. 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.Read and grant admin consent.
  2. Scope the app to the room mailboxes. Calendars.Read reaches 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-ApplicationAccessPolicy answers Granted for a room in the group. Exchange RBAC for Applications scopes an app the same way.
  3. 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.
  4. Preview, then save. source test signs in, reads each room and reports the rooms and bookings it read, a count per room and, when the app also holds Place.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 AADSTS7000215 for 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 of tenant, client_id and client_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.

  1. In Google Cloud enable the Google Calendar API, create a service account and download a JSON key for it.
  2. 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.readonly and set subject to a user who can see the rooms.
  3. A room's calendar_id is the resource's calendar ID in the Admin console under Buildings and resources; it ends in @resource.calendar.google.com. Preview with source 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 of service_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, and subject is not allowed.

Limits and privacy

  • A room card holds the 200 earliest bookings and a room-board card 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 room card gets organizers only with showOrganizer on. A room-board card never gets organizers, and gets the private title in place of each meeting title unless showTitles is 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.

SettingMeaning
base_urlThe https address of your Momentus web server, such as https://momentus.example.com/prod; the API is read from {base_url}/api/v1/...
organizationThe Momentus organization code the data is read from
api_userThe API user's id
time_zoneThe 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
daysHow many days from today to read, 1 to 31 (default 7)
roomsOptional 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_filterOptional Momentus search expressions that narrow the spaces or the functions read
exclude_status_codesFunction status codes to leave out, such as cancelled ones. Status codes are your venue's own, so there is no default
include, excludeKeywords that keep or hide functions by the title the source shows, as for calendars
title_fieldThe function field that gives an event its title: Description (default) or AlternateDescription to AlternateDescription5
multidaydaily (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_titlestrue (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.guid

source 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 Space picks the room, its Description is the title (title_field can 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-board card that --card names shows the private title unless its showTitles is on, as for the other room kinds.
  • Errors. Momentus's own text is never quoted, because the server is yours: auth_failed means the API user, key or secret is wrong or may not read functions and spaces, config_invalid that a filter is not a valid Momentus search, and parse_failed that base_url reached 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-a

Use 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_VENUE

A 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 put and add --ttl sized to the schedule, so the card goes blank on every screen if the writer stops. A notification on card_data_stale says 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.