Gardez des cartes à jour à partir d’une adresse externe

Comment fonctionne une source

• Une source, une carte. Une source désigne la carte qu’elle alimente. Une carte a au plus une source, et une organisation en compte jusqu’à 200, tous projets confondus.
• Elle s’exécute selon un calendrier. Une source de calendrier se synchronise toutes les 5 minutes, et chaque source peut être réglée entre 1 minute et 24 heures. Une source s’exécute dans les secondes qui suivent sa création ou sa modification, et source refresh la synchronise tout de suite.
• Une synchronisation en échec ne modifie jamais la carte. La carte garde son dernier bon document, et le statut de la source indique ce qui a échoué. Les échecs sont repris automatiquement, avec une attente plus longue après chacun.
• Seuls les changements sont écrits. Lorsqu’une synchronisation trouve ce que la carte contient déjà, rien n’est écrit et les écrans ne sont pas réveillés.
• Les synchronisations sont gratuites. Les documents comptent dans le stockage des données de cartes comme toute autre écriture.
• Les identifiants sont chiffrés. Une adresse qui donne accès est stockée chiffrée, n’est renvoyée que sous la forme de son schéma et de son hôte, et n’apparaît jamais dans un journal, une erreur ou le journal d’événements du projet.
• Elle garde les dernières bonnes données pendant la durée de votre choix. Quand une source ne peut pas s'actualiser, sa carte garde les dernières bonnes données pendant la période d'expiration de la source (--stale-after, de 1 minute à 7 jours ; une source de réservations de lieu les garde 30 minutes), puis les données expirent sur chaque écran, y compris hors ligne, et les pages qui en dépendent basculent sur les pages suivantes. Sans période, les dernières bonnes données restent jusqu'à la prochaine actualisation. Voir Quand une source ne peut pas s'actualiser.

Partir d’un préréglage

Un préréglage est une source toute faite pour un service que l’on affiche souvent sur un écran. Choisissez-en un, remplissez quelques champs, ajoutez l’identifiant que le service délivre, et screenRIG construit la source et fait correspondre la réponse à la carte. Les préréglages sont des sources json, que tous les forfaits incluent.

Le tableau de bord, votre agent et l’API listent les préréglages, avec l’aide et l’exemple de chaque champ et les étapes pour obtenir chaque identifiant : GET /api/source-presets les renvoie tous et GET /api/source-presets/NAME un seul (le groupe Sources de données de la référence de l’API). Créez une source à partir d’un préréglage avec preset, settings et secrets à la place de kind et config. Gardez l’identifiant dans le fichier de requête, pas sur la ligne de commande, et remplacez BOT_TOKEN par le jeton :

{
  "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 affiche le document que la carte montrerait, indique si la carte l’accepte et ce qu’il a remarqué, et n’écrit rien. POST /api/sources enregistre le même fichier, et PATCH /api/sources/ID avec de nouveaux settings reconstruit la source à partir du préréglage.

• Votre compte, vos conditions. Un préréglage lit votre propre compte avec un identifiant que vous créez, selon les conditions du service, et la carte affiche ce que ces conditions demandent : les avis Google apparaissent avec la marque Google et le nom de chaque auteur.
• Horaire et expiration. Chaque préréglage fixe son propre intervalle et sa propre période d’expiration, par exemple une minute et 15 minutes pour Slack, ou 6 heures et 24 heures pour les avis Google. Une source peut choisir un autre intervalle, jamais plus court que le minimum de son préréglage. Quand une synchronisation échoue, la carte garde ses dernières données jusqu’à la fin de la période d’expiration, puis devient vide.
• Facturation chez le service. Chaque actualisation des avis Google est une requête Place Details sur votre projet Google Cloud, et chaque actualisation des temps de trajet Google est un élément d’itinéraire pour chaque destination : quatre destinations toutes les 15 minutes font environ 11 500 éléments par mois.
• Slack exige une application interne. Ne la distribuez pas : Slack limite à une requête par minute une application distribuée hors de son Marketplace. L’application ne lit que les canaux auxquels elle a été ajoutée, et la carte affiche les messages propres des personnes, pas les arrivées, les publications de bots ni les avis de canal.

Créer une source

Créez d’abord la carte, puis faites un aperçu, puis enregistrez.

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 récupère l’adresse, la met en forme pour la carte et vérifie le résultat auprès de la carte, sans rien enregistrer ni écrire. Il affiche le document, indique si la carte l’accepte et signale ce qu’il a remarqué en chemin. Donnez l’adresse dans un fichier (@FILE) ou sur l’entrée standard (-) pour qu’elle reste hors de l’historique de votre shell.

--settings prend toute la configuration de la source en JSON, @FILE ou -. L’option --config de la CLI désigne son fichier d’identifiants et n’a rien à voir avec les sources.

Quand une source ne peut pas s'actualiser

Une source écrit chaque document avec une échéance : sa période d'expiration après l'écriture, renouvelée tant que la source continue de s'actualiser. Tant que la source fonctionne, l'échéance recule sans cesse. Quand elle échoue, la carte continue d'afficher les dernières bonnes données jusqu'à l'échéance, puis les données expirent sur chaque écran, y compris hors ligne.

• Définissez la période avec --stale-after 30m sur source create ou source update, de 1 minute à 7 jours et au moins le double de l'intervalle d'actualisation. --stale-after none garde les dernières bonnes données jusqu'à la prochaine actualisation. Une source de réservations de lieu (momentus) les garde 30 minutes sauf indication contraire ; les autres types les gardent jusqu'à la prochaine actualisation.
• Basculer sur votre propre contenu. Une page dont la condition visibility.data désigne le document (pour une salle, momentus-room-{screen.field.room}) s'affiche tant que les données sont là et cède la place à la page suivante à leur expiration. Gardez après elle une page ordinaire, à votre image, comme repli.
• Le lire. source show indique stale_after, data_expires_at et, une fois les données expirées alors que la source continue d'échouer, stale: true. La page Sources de données du tableau de bord montre la même chose : une source en échec est En échec, et celle dont les données ont expiré est Périmée.
• Être prévenu. Une notification sur les conditions source_failed (une actualisation a échoué) et source_stale (les données ont expiré) envoie un courriel ou publie dans Slack, Teams, PagerDuty ou Telegram, comme pour un écran : screenrig notifications create --email owner --conditions source_failed,source_stale --hold 5. Un avis nomme la source et renvoie à sa page, disparaît quand une actualisation réussit, et --tag ne correspond jamais à une source.

Statut et erreurs

Chaque source affiche son statut : quand elle a tourné pour la dernière fois, réussi pour la dernière fois et modifié la carte pour la dernière fois, quand elle tournera de nouveau, combien de synchronisations de suite ont échoué, et la dernière erreur.

ok ne juge pas si les données en amont sont exactes ou à jour, ni si un écran affiche la carte.

La création ou la modification d’une source peut répondre source_target_taken (la carte a déjà une source), source_target_unsupported (ce type ne peut pas alimenter cette carte; la réponse liste les cartes possibles), source_secret_required (un secret manque, ou a été saisi pour une autre adresse et doit l’être de nouveau), source_limit_reached et source_busy (une synchronisation est en cours; réessayez après l’intervalle). source test répond source_test_failed avec la raison lorsque l’adresse ne peut pas être lue.

Calendriers

Une source de calendrier lit des adresses iCalendar (ICS) : l’adresse secrète que Google Agenda, Outlook, iCloud et Nextcloud donnent pour un calendrier, et tout lien webcal://. Elle alimente une carte events avec un agenda de tous les calendriers, ou une carte study-rooms avec une salle par calendrier.

Chaque calendrier a un secret, calendar_url.KEY, qui contient son adresse.

• Les événements récurrents (règles quotidiennes, hebdomadaires, mensuelles et annuelles, exceptions, occurrences déplacées et annulées) et les fuseaux horaires sont développés sur le serveur : un événement garde son heure malgré le changement d’heure, et une carte ne répète jamais les règles du calendrier. Les noms de fuseaux horaires de Windows utilisés par Outlook sont reconnus.
• Les événements privés (CLASS:PRIVATE ou CONFIDENTIAL) n’affichent que leurs horaires, avec le titre privé et sans organisateur ni lieu. La règle couvre ceux qui sont marqués privés et ne juge pas ce que révèlent les autres événements.
• Temps libre (événements marqués comme transparents ou libres) : conservé dans un agenda et exclu d’un tableau de salles, où seul le temps occupé compte. Les événements annulés sont retirés, et les événements provisoires comptent comme occupés.
• Les événements sur toute la journée s’affichent comme des dates; un événement sans fin n’affiche pas de fin.
• Avertissements. Lorsqu’un flux n’indique aucun fuseau horaire, en utilise un que screenRIG ne reconnaît pas, ou contient plus de 500 occurrences d’un événement ou plus de 5 000 événements, la synchronisation réussit et le statut affiche un avertissement.
• Plusieurs calendriers se synchronisent ensemble : si l’un échoue, toute la synchronisation échoue et l’erreur nomme le calendrier, de sorte qu’un tableau n’affiche jamais un ensemble partiel.

Garder ou masquer des événements par mot-clé

Les sources ics, microsoft365, google_calendar et momentus acceptent deux paramètres facultatifs, include et exclude, chacun une liste de 1 à 20 mots-clés de 1 à 100 caractères. Un événement est conservé quand son titre contient au moins un mot-clé include (si include est défini) et aucun des mots-clés exclude. Un mot-clé correspond à l’intérieur d’un titre sans égard à la casse ni aux accents : café et CAFE se correspondent donc.

• Titre seulement. Le lieu, l’organisateur et la description ne sont jamais comparés. Un événement sans titre est comparé comme Untitled event.
• Les événements privés sont comparés sur leur propre titre et affichent toujours le titre privé. Le titre privé lui-même n’est jamais comparé, de sorte que exclude: ["private"] ne retire rien.
• Tout ce que la source écrit lit les calendriers filtrés : la carte et chaque document de salle par clé. Un filtre retire seulement des événements, jamais un calendrier ni une salle, et les événements libres comptent comme les autres.
• Le statut compte ce qui a été écarté sous filtered, 0 compris. Quand la fenêtre contient des événements et que les mots-clés n’en laissent aucun, la synchronisation réussit avec un avertissement qui demande de les vérifier, et la carte affiche une liste vide. source test montre la même chose.

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

Feuilles, CSV et JSON

Une source sheets, csv ou json lit un tableau ou un document JSON et en tire les données d’une carte grâce à un mappage, de sorte qu’elle alimente n’importe quelle carte : un menu à partir d’une liste de prix, un tableau d’indicateurs à partir d’une feuille de mesures, un tableau à partir d’une feuille de classement. Le mappage est un modèle JSON dans les paramètres de la source. Les règles propres à la carte décident si ce que produit le mappage est accepté, et source test affiche le document et indique si la carte l’accepte; vous modifiez donc le mappage jusqu’à ce qu’elle l’accepte. Ces sources se synchronisent toutes les 5 minutes, et toutes les minutes au plus court.

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

Partager une feuille Google

Une source sheets lit la feuille par l’exportation CSV de Google. Elle n’exige aucune connexion ni aucun accès à votre compte Google, et la feuille doit être lisible par toute personne qui en a le lien.

1. Dans Google Sheets, choisissez Partager, réglez Accès général sur Tous les utilisateurs disposant du lien et le rôle sur Lecteur. Pour publier plutôt, choisissez Fichier, Partager, Publier sur le web.
2. Copiez le lien de la barre d’adresse du navigateur dans url. Un lien vers un onglet garde cet onglet. Pour lire un autre onglet par son nom, définissez sheet; un lien publié n’accepte pas sheet.
3. Faites un aperçu avec source test. La ligne d’en-tête de la feuille devient les clés de colonne que lit le mappage.

Une feuille qui n’est pas partagée répond par une page de connexion, un 401 ou un 403. Le statut est alors not_shared, et le message nomme le réglage à changer : Partager, Accès général, Tous les utilisateurs disposant du lien, Lecteur, ou Fichier, Partager, Publier sur le web. Demandez au propriétaire de la feuille de la partager. not_shared ne juge que ces trois réponses. Il ne compare pas les colonnes avec votre mappage.

Adresses avec jeton

Un fichier CSV ou un document JSON à une adresse publique n’exige aucun jeton. Pour une adresse protégée, réglez auth sur bearer (screenRIG envoie Authorization: Bearer TOKEN) ou sur header avec header_name (il envoie HEADER_NAME: TOKEN), et fournissez le jeton comme secret token :

screenrig source create --kind csv --card crd_TABLE --name "Standings" \
  --settings @standings.json --secret token=@api.token

Le jeton est stocké chiffré et n’est renvoyé que sous forme d’indice : ses quatre derniers caractères s’il en compte 12 ou plus, sinon …. Il n’est envoyé qu’à l’origine de l’adresse elle-même : le schéma, l’hôte et le port. Une redirection vers un autre site n’est pas suivie avec le jeton, et pointer la source vers une autre origine sans saisir de nouveau le jeton est refusé avec source_secret_required. Ne changer que le chemin ou la requête garde le jeton. Pour basic, OAuth 2 et les demandes de jeton, et pour une requête avec un corps, des en-têtes ou des pages, voir Requêtes, connexion et pages. header_name ne peut pas être Host, Cookie, Content-Length, Connection, Transfer-Encoding, Upgrade ni un en-tête Proxy-, ni un en-tête que screenRIG définit lui-même.

Requêtes, connexion et pages

Une source csv ou json envoie un GET à son url. Ces paramètres envoient un corps ou des en-têtes supplémentaires, ouvrent une session, lisent plus d’une page et placent la date du jour dans une requête. Chaque requête dispose de 20 secondes et une exécution complète de 60.

Un secret nommé header.NAME est envoyé comme l’en-tête NAME : une API à deux en-têtes d’identification prend donc header.X-Client-Id et header.X-Api-Key. Un secret nommé query.NAME est ajouté à l’adresse sous la forme NAME=value. Chaque sorte en accepte jusqu’à 8, les deux sont stockées chiffrées et jamais affichées, et l’aperçu affiche un secret de requête sous la forme NAME=***.

screenRIG garde un jeton en mémoire, jamais en stockage, et le renouvelle une minute avant son expiration. Quand l’adresse refuse un jeton avec un 401, il en demande un nouveau une fois. Un refus à l’adresse du jeton (HTTP 400, 401 ou 403) donne auth_failed, et rien de ce que dit l’adresse du jeton n’est cité.

{
  "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

Les marqueurs de date remplissent l’adresse, le corps et headers : {{now}} (2026-11-01T17:30:00Z), {{today}} (2026-11-01) et {{unix}} (secondes), chacun avec un décalage facultatif comme {{now-90m}}, {{now+7d}} ou {{today-1d}} (unités m, h et d ; {{today}} n’accepte que les jours). Ils sont lus dans time_zone, ou en UTC. Chaque exécution les remplit d’après l’horloge : l’exécution de demain demande donc la date de demain.

Pages. pagination est {type, max_pages}, avec max_pages de 1 à 20 (5 par défaut). Une source json définit rows_path pour que les lignes des pages se joignent en un seul tableau, et une source csv joint les lignes du tableau.

L’adresse suivante doit rester sur l’origine de la source, de sorte qu’un secret ne la quitte jamais. Une page répétée, ou plus de pages que max_pages, met fin à la lecture avec un avertissement, et l’ensemble des pages fait au plus 5 Mo.

XML et RSS. Une réponse qui commence par <, ou format xml, est lue comme du XML. body contient l’élément racine : les attributs sont @name, le texte d’un élément qui a des enfants est #text, les éléments répétés sont des listes, et les noms gardent leur préfixe (item["media:thumbnail"]["@url"]). Un flux RSS ou Atom reçoit aussi body.items, chaque entrée avec title, link, published, summary (texte brut, jusqu’à 1 000 caractères) et image, quand l’entrée les a. Un DOCTYPE n’est jamais suivi et rien n’en est récupéré.

source test montre dans request la première requête telle qu’elle est partie : les marqueurs remplis, les secrets de requête sous la forme NAME=***, les noms des en-têtes autres que Accept et Content-Type sans leurs valeurs, le premier Kio du corps et le nombre de pages lues.

Ce que lit une source

• CSV et feuilles. CSV ordinaire : une marque d’ordre des octets, des champs entre guillemets, des guillemets doublés, des sauts de ligne entre guillemets et des fins de ligne CRLF sont tous lus. Les cellules sont rognées et les lignes sans contenu sont ignorées. Un en-tête devient une clé en minuscules, sans accents, chaque suite d’autres caractères devenant un seul _, de sorte que Sold out devient sold_out; un en-tête vide devient column_3 (sa position) et un doublon _2, _3. Un fichier qui n’est pas du texte UTF-8, comme un fichier de tableur, donne parse_failed : enregistrez-le en CSV UTF-8.
• JSON. Les nombres gardent leurs chiffres. Avec rows_path, la source y cherche le tableau de lignes; un chemin qui ne mène à aucun tableau donne mapping_failed à rows_path, et un tableau vide est un tableau sans lignes.
• Limites. Un tableau est lu jusqu’à 10 000 lignes et 200 colonnes. Au-delà, la synchronisation réussit et le statut affiche un avertissement qui compte les lignes ou les colonnes omises.
• Une page web à l’adresse, au lieu des données, donne parse_failed.

Le mappage

Le mappage est un modèle JSON. Une chaîne contenant des marqueurs comme {{item.price}} est du texte, et une chaîne qui est exactement un seul marqueur garde le type de la valeur. Un chemin qui ne contient rien est vide dans un texte et fait disparaître une valeur seule, de sorte que la carte nomme alors ce qui lui manque. Ce que peut viser le début d’un chemin dépend du type :

Préférez by_key à une position comme rows[2] : une ligne trouvée par sa clé reste trouvée quand quelqu’un trie la feuille ou insère une ligne au-dessus. Écrivez une clé contenant des espaces ainsi : by_key["Net sales"].value. Si deux lignes partagent une clé, la première l’emporte et le statut affiche un avertissement qui compte les doublons. Aucun avertissement ne cite une cellule.

Les cellules sont du texte; convertissez-les : {"$number": "{{item.price}}"} lit 1,234.50, $4.50, 3,50 € et 12% (ajoutez "$decimal": "," pour une virgule décimale), et {"$bool": "{{item.sold_out}}"} lit true, yes, y, 1 et x. $each parcourt une liste avec item et index dans la portée, $group avec $by regroupe les lignes dans l’ordre de première apparition avec group.key et group.items dans la portée, et $text avec $max coupe le texte. Le modèle est vérifié à l’enregistrement de la source.

Un menu tiré d’une feuille aux colonnes Section, Item, Price et Sold out regroupe les lignes par 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}}" }
          }
        }
      }
    }
  }
}

Un tableau d’indicateurs tiré d’une feuille aux colonnes Metric, Value, Unit et Change cherche chaque indicateur par son nom; trier la feuille ne déplace donc rien :

{
  "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}}" } }
    ]
  }
}

Une carte de tableau liste chaque ligne :

{
  "mapping": {
    "rows": {
      "$each": "{{rows}}", "$limit": 50,
      "$template": {
        "team": "{{item.team}}",
        "points": { "$number": "{{item.points}}" },
        "played": { "$number": "{{item.played}}" }
      }
    }
  }
}

Pour voir ce qu’une source lit, faites un test avec le mappage {"columns": "{{columns}}", "rows": "{{rows}}"}. La carte refuse ce document, et l’aperçu l’affiche quand même, avec chaque clé et chaque ligne.

ok sur l’une de ces sources signifie que l’adresse a répondu et que la carte a accepté le document produit par le mappage. Cela ne dit pas que la feuille ou la réponse contient les lignes que votre mappage attend : une colonne qui disparaît fait tomber son membre, et la carte refuse un document auquel il manque un membre obligatoire.

Valeurs calculées

Un mappage peut aussi calculer vrai ou faux et des nombres sur le serveur : une condition de page qui ne teste que l’égalité, comme visibility.data avec equals: true, peut donc suivre un nombre. Les mappages des webhooks de carte et des déclencheurs de superposition disposent des mêmes fonctions.

• Une comparaison qui ne peut pas être faite est fausse, avec un avertissement qui nomme l’endroit et jamais la valeur : une valeur absente, vide ou non numérique n’active donc jamais une page. $bool est le seul lecteur qui prend une valeur absente pour faux.
• Listes. $of lit un marqueur dans chaque élément, avec item et index disponibles, et $where garde les éléments pour lesquels une condition est vraie. Un élément vide ou non numérique est ignoré, et un avertissement les compte. Sans rien à additionner, $sum et $count valent 0, et $avg, $min et $max omettent leur membre.
• Nombres. Une virgule décimale (3,50, 1.234,50) exige "$decimal": ",". $avg arrondit à 2 décimales, et "$round" fixe de 0 à 6. $sum, $min et $max sont exacts.

Un indicateur de stock bas à partir d’une réponse JSON. Une page dont visibility.data désigne le document avec path /low_stock et equals true ne s’affiche que lorsque le stock est bas :

{
  "sku": "{{body.sku}}",
  "stock": {"$number": "{{body.stock}}"},
  "low_stock": {"$lt": ["{{body.stock}}", 5]}
}

À partir d’une feuille, tout produit sous son propre seuil de réapprovisionnement :

{"low_stock": {"$gt": [{"$count": "{{rows}}", "$where": {"$lt": ["{{item.stock}}", "{{item.reorder_at}}"]}}, 0]}}

Documents par clé

Les sources JSON, CSV et Sheets acceptent key_template, par exemple room-{screen.field.room}. Transformez le flux en un tableau documents d’objets {"fields":{"room":"A101"},"document":{"body":"Room A101"}}. Un webhook de carte utilise --key-template avec la même sortie, ou reçoit directement l’objet englobant sans transformation.

{
  "key_template": "room-{screen.field.room}",
  "mapping": {
    "documents": {
      "$each": "{{rows}}",
      "$template": {
        "fields": {"room": "{{item.room}}"},
        "document": {"body": "{{item.title}}"}
      }
    }
  }
}

Placez l’instance crd_ correspondante avec data: "room-{screen.field.room}"; chaque écran lit uniquement la clé formée à partir de son propre champ room. Toutes les sorties utilisent le schéma de carte de l’instance. Utilisez des instances, des transformations et des préfixes distincts pour les différents types de cartes qui lisent le même flux.

Prévisualisez avec source test. Les documents invalides, les champs manquants et les clés en double font refuser le lot avant l’écriture. Une défaillance du stockage peut laisser une partie écrite : renvoyez le même corps du webhook avec le même Idempotency-Key, ou actualisez la source. Les clés omises conservent leurs données et leur expiration précédentes; les webhooks ne définissent aucune expiration. Effacez le modèle d’un webhook avec --clear-key-template.

Conseils pour les fichiers et les feuilles

• OneDrive et SharePoint. Un lien de partage ouvre une page d’aperçu, qu’une source lit comme une page web (parse_failed). Ajoutez ?download=1 au lien d’un fichier CSV, ou &download=1 s’il contient déjà un ?, pour que le lien renvoie le fichier lui-même. Le lien doit fonctionner sans connexion.
• Retrouver des lignes par leur nom. Réglez key_column sur la colonne qui nomme chaque ligne, par son en-tête sans égard à la casse, et lisez une ligne sous la forme by_key.NAME.column : trier la feuille ou insérer une ligne ne change rien. Un nom qui ne correspond à aucune colonne donne mapping_failed à key_column, et une clé répétée garde la première ligne avec un avertissement qui compte les répétitions.

Salles de réunion

Une source de salles lit des calendriers de salles de réunion et alimente une carte room, le panneau de porte d’une salle, ou une carte room-board, toutes les salles d’un bâtiment. Elle peut aussi alimenter un agenda events ou une carte study-rooms, et une adresse de calendrier (ICS) alimente les mêmes cartes.

Les cartes déterminent à l’écran, chaque seconde, si une salle est libre, occupée ou ce qui vient ensuite, à partir des réservations qu’elles détiennent : un panneau reste exact même quand son écran est hors ligne. Une source de salles ne fait que lire : une carte affiche des réservations et n’accepte aucune saisie, donc rien n’est réservé, terminé ou enregistré depuis un écran.

Boîtes aux lettres de salle Microsoft 365

Le type microsoft365 lit les boîtes aux lettres de salle d’Exchange Online avec votre propre application Microsoft Entra : l’application, son secret et ce qu’elle peut lire restent à vous. Deux paramètres de plus : tenant, l’ID du répertoire ou un domaine vérifié comme contoso.com (common, organizations et consumers sont refusés), et client_id, l’ID d’application (client) de l’application. Le secret client_secret est la valeur du secret client de l’application.

1. Dans le centre d’administration Microsoft Entra, enregistrez une application à locataire unique sans URI de redirection, ajoutez un secret client (copiez sa valeur, pas son ID de secret), ajoutez l’autorisation d’application Microsoft Graph Calendars.Read et accordez le consentement de l’administrateur.
2. Limitez l’application aux boîtes aux lettres de salle. Calendars.Read atteint toutes les boîtes aux lettres de l’organisation tant qu’une stratégie d’accès aux applications ne la restreint pas. Placez les salles dans un groupe de sécurité à extension messagerie et exécutez les deux premières commandes ci-dessous dans Exchange Online PowerShell; Test-ApplicationAccessPolicy répond Granted pour une salle du groupe. Le RBAC Exchange pour les applications limite une application de la même façon.
3. Les boîtes aux lettres de salle remplacent l’objet d’une réunion par le nom de l’organisateur, sauf indication contraire. Pour afficher les titres des réunions, exécutez la troisième commande pour chaque salle.
4. Faites un aperçu, puis enregistrez. source test ouvre une session, lit chaque salle et indique les salles et les réservations lues, un compte par salle et, si l’application détient aussi Place.Read.All, combien de salles l’organisation répertorie.

# 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

• Correspondance. Les réunions privées et confidentielles affichent le titre privé et aucun organisateur. Les réunions marquées comme libres ou en télétravail, et celles que la salle a refusées, sont du temps libre; les réunions provisoires comptent comme occupées; les réunions annulées sont écartées. Les événements d’une journée entière sont des dates dans le fuseau de la salle.
• Cadence. Une source de salles se synchronise toutes les 2 minutes. L’ouverture de session dure environ une heure et est réutilisée.
• Erreurs. Le code et le texte d’erreur de Microsoft sont cités, par exemple AADSTS7000215 pour un secret client erroné, et une salle que l’application ne peut pas lire fait échouer la synchronisation et est nommée.
• Une connexion à la place. Réglez connection_id sur une connexion Microsoft du projet, dans l’un ou l’autre mode, à la place de tenant, client_id et client_secret. La source ne détient alors aucun secret et se connecte comme la connexion.

Calendriers de ressources Google Workspace

Le type google_calendar lit les calendriers de ressources et de salles avec votre propre compte de service Google. Le secret service_account_key est le fichier de clé tel que Google le délivre, et son indice est l’adresse du compte. Le paramètre facultatif subject nomme l’utilisateur au nom duquel le compte agit avec la délégation à l’échelle du domaine.

1. Dans Google Cloud, activez l’API Google Agenda, créez un compte de service et téléchargez-en une clé JSON.
2. Donnez au compte l’accès aux salles. Soit partagez chaque calendrier de salle avec l’adresse du compte et l’autorisation Voir tous les détails de l’événement, soit activez la délégation à l’échelle du domaine pour le compte dans la console d’administration avec la portée https://www.googleapis.com/auth/calendar.events.readonly et réglez subject sur un utilisateur qui voit les salles.
3. Le calendar_id d’une salle est l’ID de calendrier de la ressource dans la console d’administration, sous Bâtiments et ressources; il se termine par @resource.calendar.google.com. Faites un aperçu avec source test, puis enregistrez.

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

• Correspondance. Les événements privés et confidentiels affichent le titre privé et aucun organisateur. Les événements marqués comme transparents, et ceux que la salle a refusés, sont du temps libre; les événements annulés sont écartés. Les événements d’une journée entière gardent leurs dates.
• Erreurs. Le texte d’erreur de Google est cité tel quel. Un calendrier que le compte ne voit pas est nommé dans l’erreur, avec la marche à suivre pour le partager.
• Une connexion à la place. Réglez connection_id sur une connexion Google du projet à la place de service_account_key. Avec l’application de screenRIG, la source lit les calendriers que peut voir le compte qui l’a approuvée : ce compte doit donc voir chaque calendrier de salle que la source liste, et subject n’est pas permis.

Limites et confidentialité

• Une carte room garde les 200 premières réservations et une carte room-board en garde 60 par salle. S’il y en a davantage, l’état affiche un avertissement indiquant combien ont été laissées de côté.
• Le document de la carte ne contient que ce que la carte affiche, parce que chaque écran qui montre une carte en garde le document. Une carte room reçoit les organisateurs seulement si showOrganizer est activé. Une carte room-board ne reçoit jamais d’organisateurs et reçoit le titre privé à la place de chaque titre de réunion, sauf si showTitles est activé. Un changement de l’un ou l’autre réglage atteint la carte à la prochaine synchronisation. Une réunion privée porte le titre privé dans les deux cas.
• Les messages de ces types citent le texte d’erreur que Microsoft ou Google a renvoyé, et jamais un secret.

Le système de réservation d'un lieu

Le type momentus lit les fonctions (chaque utilisation d'une salle, avec ses dates et heures) et les espaces d'une installation Momentus Enterprise, le système vendu auparavant sous les noms Ungerboeck et EBMS, avec un utilisateur d'API que votre administrateur crée dans Momentus (Menu principal, Api Users). Il alimente une carte events pour un répertoire d'événements, une carte room-board pour un hall ou un couloir, ou une carte room pour une salle, et avec un document par salle, chaque écran affiche les réservations de sa propre salle. Une salle qui change peu avant un événement s'affiche dans l'intervalle d'actualisation, une minute par défaut.

Deux secrets : api_key, l'un des GUID de clé de l'utilisateur d'API, et api_secret, son GUID secret. Les deux sont stockés scellés, ne sont jamais réaffichés et sont à saisir de nouveau si la source pointe vers un autre serveur, une autre organisation ou un autre utilisateur d'API.

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 lit Momentus, met le document en forme et le vérifie auprès de la carte, puis montre les salles et les événements lus (functions, functions_other_spaces, events_KEY). Rien n'est enregistré ni écrit.

• Ce que devient une fonction. Le Space de la fonction choisit la salle, son Description est le titre (title_field peut désigner l'une de ses descriptions alternatives) et le nom de la salle est le lieu. Une fonction sans heure de début est un événement d'une journée. Une fonction sur plusieurs dates avec des heures affiche ces heures à chaque date ; celle qui finit avant de commencer se prolonge sur la nuit.
• Titres privés. Un room-board affiche le titre privé sauf si show_titles est activé, comme pour les autres types de salles.
• Erreurs. Le texte propre à Momentus n'est jamais cité, car le serveur est le vôtre : auth_failed signifie que l'utilisateur d'API, la clé ou le secret est incorrect ou ne peut pas lire les fonctions et les espaces, config_invalid qu'un filtre n'est pas une recherche Momentus valide, et parse_failed que base_url a atteint une page Web et non l'API.

Une affiche pour chaque salle

Définissez room_key_prefix (par exemple momentus-room-) et la source écrit aussi un document room pour chaque salle sous ce préfixe suivi de la clé de la salle. Donnez à l'écran de chaque salle sa salle, et placez une carte room dont la clé data est le préfixe suivi du champ propre à l'écran :

screenrig screen update scr_BALLROOM --field room=ballroom-a

Utilisez le type de catalogue intégré room dans cette primitive de la liste de lecture :

{"id":"door","primitive":"card","card":"room","layout":"full","content_fit":"fill","params":{"room":"{screen.field.room}"},"data":"momentus-room-{screen.field.room}"}

Les primitives crd_ utilisent params et major de l’instance; omettez ces champs. Leur data facultatif sélectionne une clé de document ou un modèle de clé par écran. Le --card crd_ID de la source désigne toujours sa cible de synchronisation. Pour la page, définissez visibility.data.key à momentus-room-{screen.field.room} et ajoutez ensuite une page de repli sans condition.

Le backend remplit le champ dans le manifeste de chaque écran : une seule liste de lecture montre donc à chaque écran sa propre salle, et un écran sans champ de salle n'affiche rien pour cette carte. area_key_prefix fait de même pour un affichage de couloir : le area de chaque salle la regroupe, et une room-board des salles de cette zone est écrite sous le préfixe suivi de la clé de la zone (area_card peut valoir events). screen_field et area_field nomment les champs d'écran que la vérification ci-dessous lit (room et area par défaut).

Vérifier le mappage

screenrig source rooms src_ID (et la section Mappage des salles de la page de la source dans le tableau de bord) liste les salles que la source offre et qu'aucun écran n'affiche, ainsi que les écrans dont la salle est absente ou désigne une salle que Momentus n'a pas :

screenrig source rooms src_VENUE

Un écran figure dans le rapport lorsqu'il a une valeur pour le champ, ou lorsque sa propre liste de lecture place une carte qui lit la clé. Chacun est mapped, missing (la liste de lecture lit le champ et l'écran n'en a pas) ou unknown (la valeur ne désigne aucune salle ; le rapport indique la salle probablement visée, par exemple les mêmes lettres dans une autre casse). Corrigez un écran avec screenrig screen update scr_ID --field room=ROOM_KEY. Le rapport lit les salles de la dernière bonne actualisation de la source et ne récupère rien ; une source qui liste ses rooms les connaît avant sa première actualisation.

Des menus à partir de votre caisse

Une source Square, Shopify ou Toast alimente une carte menu (des sections de lignes avec un prix sur chacune) ou une carte price-matrix (les articles sur le côté, les formats en haut) à partir du catalogue que vous tenez déjà. Un changement de prix, un nouvel article ou une marque de rupture de stock arrive sur les écrans à la synchronisation suivante, toutes les 5 minutes, ou aussitôt avec source refresh.

echo '{"title":"Counter","sections":[{"name":"Menu","items":[{"name":"Coffee"}]}]}' > menu.json
screenrig card create --type menu --file menu.json
screenrig source test --kind square --card crd_CARD --secret access_token=@square.token
screenrig source create --kind square --card crd_CARD --name "Counter menu" \
  --secret access_token=@square.token

La première synchronisation remplace les sections propres à la carte par celles du catalogue. source test affiche le document que la carte présenterait, indique si la carte l’accepte et signale ce qu’il a remarqué.

Ce qui arrive sur la carte

• Section. Square : la catégorie de l’article. Shopify : la collection que vous indiquez, sinon le type de produit.
• Article et formats. Square : l’article et ses variantes. Shopify : le produit et ses variantes (Default Title n’est pas un format).
• Prix. Square : le prix de la variante, ou le prix propre à l’emplacement. Shopify : le prix de la variante dans la devise de la boutique.
• Description. Square : la description de l’article en texte brut. Shopify : la description du produit, ses 400 premiers caractères.
• Étiquettes. Square : préférences alimentaires végétalien, végétarien et sans gluten. Shopify : étiquettes de produit vegan, vegetarian, gluten-free, spicy, new et popular.
• Épuisé. Square : la marque « épuisé » de la caisse à l’emplacement, jusqu’à son expiration. Shopify : aucune variante n’est disponible à la vente. Aucun des deux ne juge les quantités en stock.

Un article en plusieurs formats occupe une ligne par format (Latte (Small), Latte (Large)) sur une carte menu et une colonne par format sur une carte price-matrix. Les articles archivés et supprimés, les brouillons et les produits archivés sont laissés de côté. Les images ne sont pas transmises : une carte qui affiche des photos utilise les médias du projet. Les prix arrivent dans la devise du catalogue, et c’est le paramètre currency de la carte qui dessine le symbole; réglez-le sur la carte (€ pour les euros); l’état avertit tant qu’une carte affiche encore $ sur des prix dans une autre devise.

Square

1. Dans le Square Developer Dashboard, créez une application. C’est gratuit et cela ne change rien dans votre commerce.
2. Faites passer le tableau de bord en Production, ouvrez Credentials, copiez le jeton d’accès de Production et enregistrez-le dans un fichier. Pour le Sandbox, utilisez son jeton et définissez environment à sandbox.
3. Créez la source avec --secret access_token=@FILE. Un compte ayant un seul emplacement actif l’utilise. Avec plusieurs, définissez location_id; source test énumère les emplacements du compte quand il en faut un.

Un jeton d’accès Square porte toutes les autorisations du compte et ne peut pas être restreint. screenRIG l’utilise pour deux lectures, les emplacements et la bibliothèque d’articles, et ne l’envoie qu’aux serveurs de Square. Il est stocké chiffré, n’est affiché que par ses quatre derniers caractères, et vous pouvez le remplacer ou le révoquer à tout moment dans le Developer Dashboard.

Shopify

L’application a besoin de l’autorisation read_products et de rien d’autre. Connectez-vous avec l’un de ces deux types d’application :

• Une application personnalisée. Dans l’admin Shopify, ouvrez Paramètres, Applications et canaux de vente, Développer des applications. Donnez à l’application read_products, installez-la, affichez le jeton d’accès de l’API Admin et enregistrez-le dans un fichier. Créez la source avec --secret access_token=@FILE.
• Une application du Dev Dashboard. Sur dev.shopify.com, créez une application avec read_products et installez-la sur la boutique. Définissez client_id et créez la source avec --secret client_secret=@FILE. screenRIG échange les deux contre un jeton d’accès valable un jour, qui se renouvelle de lui-même.

Toast

Une source Toast lit les menus et les stocks d’un restaurant avec l’accès API standard que le restaurant crée lui-même : en lecture seule, et pour un seul établissement.

1. Dans Toast Web, ouvrez Integrations, Toast API access, Manage credentials et créez des identifiants avec les portées menus:read et stock:read. Toast exige Restaurant Management Suite Essentials ou supérieur et l’autorisation Manage Integrations.
2. Copiez l’ID client et le secret client. Toast envoie par courriel le GUID du restaurant quand il crée les identifiants.
3. Créez la source avec restaurant (le GUID), client_id et --secret client_secret=@FILE.

screenrig source test --kind toast --card crd_MENU \
  --set restaurant=RESTAURANT_GUID --set client_id=CLIENT_ID --secret client_secret=@toast.secret

• Sections et lignes. Un groupe de menu qui contient des articles est une section, et un sous-groupe est une section à part. Un article présent dans plusieurs groupes est un seul article, sous le premier d’entre eux. Un article tarifé par format donne une ligne par format.
• Prix. Les prix de base et de menu tels que Toast les donne, et un prix selon l’horaire tant que son horaire couvre le moment présent. Un prix libre n’en a pas. La réponse de Toast ne contient aucune devise : réglez donc currency sur la carte.
• Rupture de stock. Un article que Toast marque en rupture de stock, ou dont la quantité est de zéro ou moins. Un stock bas n’est jamais lu comme une rupture.
• Périodes de la journée. Quand aucun menu n’est disponible à l’heure, la synchronisation échoue avec config_invalid et la carte garde son dernier menu. Un tableau qui suit les périodes de la journée prend une source pour chacune, ou nomme son menu.
• Identifiants. Le secret est lié à l’environnement et au restaurant : en changer l’un ou l’autre le redemande (source_secret_required). screenRIG se connecte une fois par exécution et partage la connexion entre les sources qui utilisent les mêmes identifiants, comme Toast le demande. Les modificateurs, combos, allergènes, portions et images ne sont pas lus.

À quoi s’attendre

• Formats. Une carte price-matrix compte jusqu’à 6 colonnes de formats, dans l’ordre où ils apparaissent d’abord. Elle n’accepte pas variations.
• Limites. Une carte menu contient 8 sections de 24 lignes et une carte price-matrix, 12 sections de 40 articles. Le surplus est laissé de côté et l’état affiche un avertissement avec le nombre; choisissez ce qui s’affiche avec include_sections.
• Un catalogue trop volumineux (plus de 30 pages d’articles et de catégories Square, ou 500 produits Shopify) fait échouer la synchronisation avec too_large plutôt que d’afficher une partie d’un menu. Nommez des collections ou des sections pour en afficher moins.
• Rien à afficher. Quand les paramètres ne laissent aucun article, la synchronisation échoue avec config_invalid et la carte garde son dernier menu.
• Limites de débit. La synchronisation attend jusqu’à 10 secondes que le budget de Shopify se reconstitue, et une synchronisation limitée recommence à l’intervalle suivant.
• Clover et Lightspeed ne donnent accès à leur API qu’aux partenaires approuvés : ce ne sont donc pas des sources.

Un identifiant stocké est lié à l’environnement Square ou à la boutique Shopify pour lesquels il a été saisi. Pointer la source vers un autre environnement ou une autre boutique redemande l’identifiant (source_secret_required), de sorte qu’une source ne peut pas l’envoyer ailleurs. Les requêtes vont uniquement aux serveurs de Square et à NAME.myshopify.com, et ne font que lire.

Sécurité

Une adresse qui donne accès est un identifiant. screenRIG la stocke chiffrée, ne renvoie que son schéma et son hôte, et ne l’utilise que pour effectuer la synchronisation. Les sources lisent des adresses http(s) publiques sur le port 80 ou 443 et suivent au plus trois redirections; une adresse qui ne se résout pas vers un hôte public, une connexion refusée et un échec de négociation se lisent tous de la même façon, ce qui empêche d’utiliser une source pour explorer un réseau. Aucun message ne cite une adresse ni la réponse reçue. Les sources ne font que lire : elles n’écrivent jamais dans un calendrier.

Lié

• Cartes : types de cartes, propriétés et données en direct.
• CLI d’affichage : chaque commande screenrig.
• Connexions : une connexion enregistrée à Microsoft ou à Google pour les sources de salles, Power BI et la synchronisation des médias.
• Référence de l’API : les routes /api/sources et leurs problèmes.