Mantieni aggiornate le schede da un indirizzo esterno

Come funziona un’origine

• Un’origine, una scheda. Un’origine indica la scheda che alimenta. Una scheda ha al massimo un’origine, e un’organizzazione ne ha fino a 200 in tutti i suoi progetti.
• Viene eseguita a intervalli. Un’origine calendario si sincronizza ogni 5 minuti, e ogni origine può essere impostata tra 1 minuto e 24 ore. Un’origine viene eseguita pochi secondi dopo la creazione o la modifica, e source refresh la sincronizza subito.
• Una sincronizzazione non riuscita non modifica mai la scheda. La scheda conserva l’ultimo documento valido e lo stato dell’origine dice cosa è andato storto. I tentativi falliti si ripetono da soli, con un’attesa più lunga dopo ciascuno.
• Vengono scritte solo le modifiche. Quando una sincronizzazione trova ciò che la scheda contiene già, non viene scritto nulla e gli schermi non vengono svegliati.
• Le sincronizzazioni sono gratuite. I documenti contano nello spazio per i dati delle schede come qualsiasi altra scrittura.
• Le credenziali sono cifrate. Un indirizzo che concede l’accesso viene memorizzato cifrato, restituito solo con schema e host, e non compare mai in un log, in un errore o nel registro eventi del progetto.
• Conserva gli ultimi dati validi per un periodo a vostra scelta. Quando una fonte non riesce ad aggiornarsi, la sua scheda conserva gli ultimi dati validi per il periodo di scadenza della fonte (--stale-after, da 1 minuto a 7 giorni; una fonte di prenotazioni di una sede li conserva per 30 minuti); poi i dati scadono su ogni schermo, anche offline, e le pagine che ne dipendono passano alle pagine successive. Senza periodo, gli ultimi dati validi restano finché la fonte non si aggiorna di nuovo. Vedi Quando una fonte non riesce ad aggiornarsi.

Partire da un preset

Un preset è un’origine già pronta per un servizio che spesso si mette su uno schermo. Scegline uno, compila alcuni campi, aggiungi la credenziale che il servizio emette, e screenRIG costruisce l’origine e mappa la risposta sulla scheda. I preset sono origini json, che ogni piano include.

La dashboard, il tuo agente e l’API elencano i preset, con la riga di aiuto e l’esempio di ogni campo e i passaggi per ottenere ogni credenziale: GET /api/source-presets li restituisce tutti e GET /api/source-presets/NAME uno solo (il gruppo Origini dati del riferimento API). Crea un’origine da un preset con preset, settings e secrets al posto di kind e config. Tieni la credenziale nel file della richiesta, non nella riga di comando, e sostituisci BOT_TOKEN con il 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 stampa il documento che la scheda mostrerebbe, se la scheda lo accetta e cosa ha notato, e non scrive nulla. POST /api/sources salva lo stesso file, e PATCH /api/sources/ID con nuovi settings ricostruisce l’origine dal preset.

• Il tuo account, le tue condizioni. Un preset legge il tuo account con una credenziale che crei tu, secondo le condizioni del servizio, e la scheda mostra ciò che quelle condizioni richiedono: le recensioni Google compaiono con il marchio Google e il nome di ogni recensore.
• Pianificazione e scadenza. Ogni preset stabilisce il proprio intervallo e il proprio periodo di scadenza, come un minuto e 15 minuti per Slack, o 6 ore e 24 ore per le recensioni Google. Un’origine può scegliere un altro intervallo, mai più breve del minimo del suo preset. Quando una sincronizzazione fallisce, la scheda conserva i suoi ultimi dati finché non passa il periodo di scadenza, poi resta vuota.
• Fatturazione presso il servizio. Ogni aggiornamento delle recensioni Google è una richiesta Place Details sul tuo progetto Google Cloud, e ogni aggiornamento dei tempi di percorrenza Google è un elemento di percorso per ogni destinazione: quattro destinazioni ogni 15 minuti fanno circa 11.500 elementi al mese.
• Slack richiede un’app interna. Non distribuirla: Slack limita a una richiesta al minuto un’app distribuita fuori dal suo Marketplace. L’app legge solo i canali a cui è stata aggiunta, e la scheda mostra i messaggi propri delle persone, non gli ingressi, i post dei bot né gli avvisi del canale.

Creare un’origine

Crea prima la scheda, poi guarda l’anteprima e infine salva.

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 recupera l’indirizzo, lo adatta alla scheda e verifica il risultato con la scheda, senza salvare né scrivere nulla. Mostra il documento, se la scheda lo accetta e ciò che ha notato lungo il percorso. Indica l’indirizzo in un file (@FILE) o dallo standard input (-) perché resti fuori dalla cronologia della shell.

--settings accetta l’intera configurazione della fonte come JSON, @FILE o -. L’opzione --config della CLI indica il suo file di credenziali e non ha nulla a che fare con le fonti.

Quando una fonte non riesce ad aggiornarsi

Una fonte scrive ogni documento con una scadenza: il suo periodo di scadenza dopo la scrittura, rinnovato finché la fonte continua ad aggiornarsi. Finché la fonte funziona, la scadenza continua a spostarsi. Quando fallisce, la scheda continua a mostrare gli ultimi dati validi fino alla scadenza, poi i dati scadono su ogni schermo, anche offline.

• Impostate il periodo con --stale-after 30m su source create o source update, da 1 minuto a 7 giorni e almeno il doppio dell'intervallo di aggiornamento. --stale-after none conserva gli ultimi dati validi fino al prossimo aggiornamento. Una fonte di prenotazioni di una sede (momentus) li conserva per 30 minuti, salvo diversa indicazione; gli altri tipi li conservano fino al prossimo aggiornamento.
• Passare ai vostri contenuti. Una pagina la cui condizione visibility.data indica il documento (per una sala, momentus-room-{screen.field.room}) viene mostrata finché i dati ci sono e lascia il posto alla pagina successiva quando scadono. Tenete dopo di essa una pagina normale, con il vostro marchio, come riserva.
• Leggerlo. source show mostra stale_after, data_expires_at e, quando i dati sono scaduti mentre la fonte continua a fallire, stale: true. La pagina Fonti di dati della dashboard mostra lo stesso: una fonte in errore è In errore, e una con dati scaduti è Scaduta.
• Essere avvisati. Una notifica sulle condizioni source_failed (un aggiornamento è fallito) e source_stale (i dati sono scaduti) invia e-mail o pubblica su Slack, Teams, PagerDuty o Telegram, come per uno schermo: screenrig notifications create --email owner --conditions source_failed,source_stale --hold 5. Un avviso nomina la fonte e collega la sua pagina, si chiude quando un aggiornamento riesce, e --tag non corrisponde mai a una fonte.

Stato ed errori

Ogni origine mostra il proprio stato: quando è stata eseguita l’ultima volta, quando ha avuto successo l’ultima volta e ha modificato la scheda l’ultima volta, quando verrà eseguita di nuovo, quante sincronizzazioni consecutive sono fallite e l’ultimo errore.

ok non valuta se i dati di origine sono corretti o aggiornati, né se uno schermo mostra la scheda.

La creazione o la modifica di un’origine può rispondere source_target_taken (la scheda ha già un’origine), source_target_unsupported (il tipo non può alimentare quella scheda; la risposta elenca le schede possibili), source_secret_required (manca un segreto, oppure è stato inserito per un altro indirizzo e va inserito di nuovo), source_limit_reached e source_busy (una sincronizzazione è in corso; riprova dopo l’intervallo). source test risponde source_test_failed con il motivo quando l’indirizzo non può essere letto.

Calendari

Un’origine calendario legge indirizzi iCalendar (ICS): l’indirizzo segreto che Google Calendar, Outlook, iCloud e Nextcloud forniscono per un calendario, e qualsiasi link webcal://. Alimenta una scheda events con un’agenda di tutti i calendari, oppure una scheda study-rooms con una sala per calendario.

Ogni calendario ha un segreto, calendar_url.KEY, che contiene il suo indirizzo.

• Gli eventi ricorrenti (regole giornaliere, settimanali, mensili e annuali, eccezioni, occorrenze spostate e annullate) e i fusi orari vengono espansi sul server, così un evento mantiene l’ora anche con il cambio dell’ora legale e una scheda non ripete mai le regole del calendario. I nomi dei fusi orari di Windows usati da Outlook sono riconosciuti.
• Gli eventi privati (CLASS:PRIVATE o CONFIDENTIAL) mostrano solo gli orari, con il titolo privato e senza organizzatore né luogo. La regola copre quelli contrassegnati come privati e non valuta ciò che rivelano gli altri eventi.
• Il tempo libero (eventi contrassegnati come trasparenti o liberi) resta in un’agenda ed è escluso da una tabella delle sale, dove conta solo il tempo occupato. Gli eventi annullati vengono scartati e quelli provvisori contano come occupati.
• Gli eventi di un’intera giornata appaiono come date; un evento senza fine non mostra una fine.
• Avvisi. Quando un feed non indica alcun fuso orario, ne usa uno che screenRIG non riconosce, o contiene più di 500 occorrenze di un evento o più di 5.000 eventi, la sincronizzazione riesce e lo stato mostra un avviso.
• Più calendari si sincronizzano insieme: se uno fallisce, fallisce l’intera sincronizzazione e l’errore indica il calendario, così una tabella non mostra mai un insieme parziale.

Mantenere o nascondere gli eventi per parola chiave

Le origini ics, microsoft365, google_calendar e momentus accettano due impostazioni facoltative, include e exclude, ciascuna un elenco di 1-20 parole chiave di 1-100 caratteri. Un evento resta quando il suo titolo contiene almeno una parola chiave di include (se include è impostato) e nessuna di exclude. Una parola chiave corrisponde all’interno di un titolo senza distinguere maiuscole e accenti, quindi café e CAFE corrispondono tra loro.

• Solo il titolo. Il luogo, l’organizzatore e la descrizione non vengono mai confrontati. Un evento senza titolo viene confrontato come Untitled event.
• Gli eventi privati vengono confrontati sul proprio titolo e continuano a mostrare il titolo privato. Il titolo privato in sé non viene mai confrontato, quindi exclude: ["private"] non rimuove nulla.
• Tutto ciò che l’origine scrive legge i calendari filtrati: la scheda e ogni documento di sala per chiave. Un filtro rimuove solo eventi, mai un calendario o una sala, e gli eventi liberi contano come gli altri.
• Lo stato conta ciò che è stato escluso come filtered, anche 0. Quando la finestra contiene eventi e le parole chiave non ne lasciano nessuno, la sincronizzazione riesce con un avviso che invita a controllarle, e la scheda mostra un elenco vuoto. source test mostra lo stesso.

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

Fogli, CSV e JSON

Un’origine sheets, csv o json legge una tabella o un documento JSON e ne ricava i dati di una scheda con una mappatura, così riempie qualsiasi scheda: un menu da un listino prezzi, un tabellone di indicatori da un foglio di metriche, una tabella da un foglio di classifiche. La mappatura è un modello JSON nelle impostazioni dell’origine. Le regole proprie della scheda decidono se ciò che la mappatura costruisce è accettato, e source test stampa il documento e dice se la scheda lo accetta, così modifichi la mappatura finché lo fa. Queste origini si sincronizzano ogni 5 minuti, e ogni minuto al minimo.

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

Condividere un foglio Google

Un’origine sheets legge il foglio tramite l’esportazione CSV di Google. Non richiede accesso né l’accesso al tuo account Google, e il foglio deve poter essere letto da chiunque abbia il suo link.

1. In Fogli Google scegli Condividi, imposta Accesso generale su Chiunque abbia il link e il ruolo su Visualizzatore. Per pubblicare invece, scegli File, Condividi, Pubblica sul web.
2. Copia il link dalla barra degli indirizzi del browser in url. Un link a una scheda del foglio mantiene quella scheda. Per leggere un’altra scheda per nome, imposta sheet; un link pubblicato non accetta sheet.
3. Guarda l’anteprima con source test. La riga di intestazione del foglio diventa le chiavi di colonna lette dalla mappatura.

Un foglio che non è condiviso risponde con una pagina di accesso, un 401 o un 403. Lo stato è allora not_shared, e il messaggio indica l’impostazione da cambiare: Condividi, Accesso generale, Chiunque abbia il link, Visualizzatore, oppure File, Condividi, Pubblica sul web. Chiedi al proprietario del foglio di condividerlo. not_shared giudica solo queste tre risposte. Non confronta le colonne con la tua mappatura.

Indirizzi con token

Un file CSV o un documento JSON a un indirizzo pubblico non richiede alcun token. Per uno protetto, imposta auth su bearer (screenRIG invia Authorization: Bearer TOKEN) o su header con header_name (invia HEADER_NAME: TOKEN), e fornisci il token come segreto token:

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

Il token viene memorizzato cifrato e restituito solo come indizio: i suoi ultimi quattro caratteri se ne ha 12 o più, altrimenti …. Viene inviato solo all’origine dell’indirizzo stesso: schema, host e porta. Un reindirizzamento a un altro sito non viene seguito con il token, e puntare l’origine a un’altra origine senza reinserire il token viene rifiutato con source_secret_required. Cambiare solo il percorso o la query mantiene il token. Per basic, OAuth 2 e le richieste di token, e per una richiesta con corpo, intestazioni o pagine, vedi Richieste, accesso e pagine. header_name non può essere Host, Cookie, Content-Length, Connection, Transfer-Encoding, Upgrade né un’intestazione Proxy-, né un’intestazione che screenRIG imposta da sé.

Richieste, accesso e pagine

Un’origine csv o json invia una GET al proprio url. Queste impostazioni inviano un corpo o intestazioni aggiuntive, accedono, leggono più di una pagina e inseriscono la data di oggi in una richiesta. Ogni richiesta ha 20 secondi e un’esecuzione intera ne ha 60.

Un segreto chiamato header.NAME viene inviato come intestazione NAME, quindi un’API con due intestazioni di credenziali usa header.X-Client-Id e header.X-Api-Key. Un segreto chiamato query.NAME viene aggiunto all’indirizzo come NAME=value. Ogni tipo ne accetta fino a 8, entrambi sono memorizzati sigillati e non vengono mai mostrati, e l’anteprima mostra un segreto di query come NAME=***.

screenRIG tiene un token in memoria, mai nell’archiviazione, e lo rinnova un minuto prima della scadenza. Quando l’indirizzo rifiuta un token con un 401, ne chiede uno nuovo una volta. Un rifiuto all’indirizzo del token (HTTP 400, 401 o 403) è auth_failed, e nulla di ciò che dice l’indirizzo del token viene citato.

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

I segnaposto di data riempiono l’indirizzo, il corpo e headers: {{now}} (2026-11-01T17:30:00Z), {{today}} (2026-11-01) e {{unix}} (secondi), ciascuno con uno scostamento facoltativo come {{now-90m}}, {{now+7d}} o {{today-1d}} (unità m, h e d; {{today}} accetta solo giorni). Vengono letti in time_zone, o in UTC. Ogni esecuzione li riempie dall’orologio, quindi l’esecuzione di domani chiede la data di domani.

Pagine. pagination è {type, max_pages}, con max_pages da 1 a 20 (5 per impostazione predefinita). Un’origine json imposta rows_path perché le righe delle pagine si uniscano in un solo array, e un’origine csv unisce le righe della tabella.

L’indirizzo successivo deve restare sull’origin dell’origine stessa, così un segreto non la lascia mai. Una pagina ripetuta, o più pagine di max_pages, termina la lettura con un avviso, e tutte le pagine insieme pesano al massimo 5 MB.

XML e RSS. Una risposta che inizia con <, o format xml, viene letta come XML. body contiene l’elemento radice: gli attributi sono @name, il testo di un elemento che ha figli è #text, gli elementi ripetuti sono elenchi e i nomi mantengono il prefisso (item["media:thumbnail"]["@url"]). Un feed RSS o Atom riceve anche body.items, ogni voce con title, link, published, summary (testo semplice, fino a 1.000 caratteri) e image, quando la voce li ha. Un DOCTYPE non viene mai seguito e nulla viene recuperato da esso.

source test mostra in request la prima richiesta così come è partita: i segnaposto compilati, i segreti di query come NAME=***, i nomi delle intestazioni oltre a Accept e Content-Type senza i loro valori, il primo KiB del corpo e il numero di pagine lette.

Che cosa legge un’origine

• CSV e fogli. CSV ordinario: vengono letti un byte order mark, i campi tra virgolette, le virgolette raddoppiate, gli a capo dentro le virgolette e i fine riga CRLF. Le celle vengono ripulite dagli spazi e le righe senza contenuto vengono scartate. Un’intestazione diventa una chiave in minuscolo, senza accenti, con ogni sequenza di altri caratteri trasformata in un solo _, così Sold out diventa sold_out; un’intestazione vuota diventa column_3 (la sua posizione) e una ripetizione _2, _3. Un file che non è testo UTF-8, come un file di foglio di calcolo, è parse_failed: salvalo come CSV in UTF-8.
• JSON. I numeri mantengono le loro cifre. Con rows_path l’origine cerca lì l’array delle righe; un percorso che non trova alcun array è mapping_failed in rows_path, e un array vuoto è una tabella senza righe.
• Limiti. Una tabella viene letta fino a 10.000 righe e 200 colonne. Oltre, la sincronizzazione riesce e lo stato elenca un avviso che conta le righe o le colonne lasciate fuori.
• Una pagina web all’indirizzo, al posto dei dati, è parse_failed.

La mappatura

La mappatura è un modello JSON. Una stringa con segnaposto come {{item.price}} è testo, e una stringa che è esattamente un solo segnaposto mantiene il tipo del valore. Un percorso che non contiene nulla è vuoto in un testo e lascia fuori un valore isolato, così la scheda indica poi che cosa le manca. Da dove può partire un percorso dipende dal tipo:

Preferisci by_key a una posizione come rows[2]: una riga trovata tramite la sua chiave continua a essere trovata quando qualcuno ordina il foglio o inserisce una riga sopra di essa. Scrivi una chiave con spazi come by_key["Net sales"].value. Se due righe condividono una chiave, vince la prima e lo stato elenca un avviso che conta le ripetizioni. Nessun avviso cita una cella.

Le celle sono testo, quindi convertile: {"$number": "{{item.price}}"} legge 1,234.50, $4.50, 3,50 € e 12% (aggiungi "$decimal": "," per la virgola decimale), e {"$bool": "{{item.sold_out}}"} legge true, yes, y, 1 e x. $each scorre un elenco con item e index nell’ambito, $group con $by raggruppa le righe in ordine di prima comparsa con group.key e group.items nell’ambito, e $text con $max tronca il testo. Il modello viene verificato quando l’origine viene salvata.

Un menu da un foglio con le colonne Section, Item, Price e Sold out raggruppa le righe per sezione:

{
  "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 tabellone di indicatori da un foglio con le colonne Metric, Value, Unit e Change cerca ogni metrica per nome, quindi ordinare il foglio non sposta nulla:

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

Una scheda tabella elenca ogni riga:

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

Per vedere che cosa legge un’origine, prova con la mappatura {"columns": "{{columns}}", "rows": "{{rows}}"}. La scheda rifiuta quel documento, e l’anteprima lo stampa comunque, con ogni chiave e ogni riga.

ok su una di queste origini significa che l’indirizzo ha risposto e la scheda ha accettato il documento prodotto dalla mappatura. Non dice che il foglio o la risposta contengano le righe che la mappatura si aspetta: una colonna che scompare lascia fuori il suo membro, e la scheda rifiuta un documento a cui manca un membro obbligatorio.

Valori calcolati

Una mappatura può anche calcolare vero o falso e numeri sul server, così una condizione di pagina che verifica solo l’uguaglianza, come visibility.data con equals: true, può seguire un numero. Le mappature dei webhook delle schede e dei trigger di sovrapposizione hanno le stesse funzioni.

• Un confronto che non si può fare è falso, con un avviso che indica il punto e mai il valore, quindi un valore mancante, vuoto o non numerico non attiva mai una pagina. $bool è l’unico lettore che considera falso un valore mancante.
• Elenchi. $of legge un segnaposto da ogni elemento, con item e index disponibili, e $where mantiene gli elementi per cui una condizione è vera. Un elemento vuoto o che non è un numero viene saltato, e un avviso li conta. Senza nulla da sommare, $sum e $count valgono 0, e $avg, $min e $max omettono il proprio membro.
• Numeri. Una virgola decimale (3,50, 1.234,50) richiede "$decimal": ",". $avg arrotonda a 2 decimali, e "$round" imposta da 0 a 6. $sum, $min e $max sono esatti.

Un indicatore di scorte basse da una risposta JSON. Una pagina il cui visibility.data indica il documento con path /low_stock e equals true compare solo finché le scorte sono basse:

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

Da un foglio, ogni prodotto sotto il proprio livello di riordino:

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

Documenti per chiave

Le sorgenti JSON, CSV e Sheets accettano key_template, ad esempio room-{screen.field.room}. Trasforma il feed in un array documents di oggetti {"fields":{"room":"A101"},"document":{"body":"Room A101"}}. Un webhook di scheda usa --key-template con lo stesso output, oppure riceve direttamente l’oggetto contenitore senza trasformazione.

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

Posiziona l’istanza crd_ corrispondente con data: "room-{screen.field.room}"; ogni schermo legge solo la chiave ricavata dal proprio campo room. Tutti gli output usano lo schema di scheda dell’istanza. Usa istanze, trasformazioni e prefissi separati per diversi tipi di scheda che leggono lo stesso feed.

Visualizza l’anteprima con source test. Documenti non validi, campi mancanti e chiavi duplicate causano il rifiuto del lotto prima della scrittura. Un errore di archiviazione può lasciare una parte già scritta: ritenta lo stesso corpo del webhook con la stessa Idempotency-Key, oppure aggiorna la sorgente. Le chiavi omesse conservano i dati e la scadenza precedenti; i webhook non impostano scadenze. Cancella il modello di un webhook con --clear-key-template.

Suggerimenti per file e fogli

• OneDrive e SharePoint. Un link di condivisione apre una pagina di anteprima, che un’origine legge come pagina web (parse_failed). Aggiungi ?download=1 al link di un file CSV, oppure &download=1 se ha già un ?, perché il link restituisca il file stesso. Il link deve funzionare senza accesso.
• Cercare le righe per nome. Imposta key_column sulla colonna che dà il nome a ogni riga, tramite la sua intestazione in qualsiasi maiuscola o minuscola, e leggi una riga come by_key.NAME.column: ordinare il foglio o inserire una riga non cambia nulla. Un nome che non corrisponde a nessuna colonna dà mapping_failed in key_column, e una chiave ripetuta mantiene la prima riga con un avviso che conta le ripetizioni.

Sale riunioni

Un’origine di sale legge i calendari delle sale riunioni e alimenta una scheda room, la targa sulla porta di una sala, oppure una scheda room-board, tutte le sale di un edificio. Può anche alimentare un’agenda events o una scheda study-rooms, e un indirizzo di calendario (ICS) alimenta le stesse schede.

Le schede calcolano sullo schermo, ogni secondo, se una sala è libera, occupata o cosa viene dopo, a partire dalle prenotazioni che conservano: una targa resta corretta anche con lo schermo offline. Un’origine di sale si limita a leggere: una scheda mostra prenotazioni e non accetta input, quindi da uno schermo non si prenota, non si termina e non si registra nulla.

Cassette postali delle sale Microsoft 365

Il tipo microsoft365 legge le cassette postali delle sale di Exchange Online con la tua app Microsoft Entra, così l’app, il suo segreto e ciò che può leggere restano tuoi. Altre due impostazioni: tenant, l’ID della directory o un dominio verificato come contoso.com (common, organizations e consumers vengono rifiutati), e client_id, l’ID applicazione (client) dell’app. Il segreto client_secret è il valore del segreto client dell’app.

1. Nell’interfaccia di amministrazione di Microsoft Entra registra un’app a tenant singolo senza URI di reindirizzamento, aggiungi un segreto client (copia il suo valore, non l’ID del segreto), aggiungi l’autorizzazione dell’applicazione Microsoft Graph Calendars.Read e concedi il consenso dell’amministratore.
2. Limita l’app alle cassette postali delle sale. Calendars.Read raggiunge ogni cassetta postale dell’organizzazione finché un criterio di accesso alle applicazioni non la limita. Inserisci le sale in un gruppo di sicurezza abilitato alla posta e esegui i primi due comandi qui sotto in Exchange Online PowerShell; Test-ApplicationAccessPolicy risponde Granted per una sala del gruppo. L’RBAC di Exchange per le applicazioni limita un’app allo stesso modo.
3. Le cassette postali delle sale sostituiscono l’oggetto di una riunione con il nome dell’organizzatore, salvo diversa impostazione. Per mostrare i titoli delle riunioni, esegui il terzo comando per ogni sala.
4. Visualizza l’anteprima, poi salva. source test effettua l’accesso, legge ogni sala e riporta le sale e le prenotazioni lette, un conteggio per sala e, se l’app possiede anche Place.Read.All, quante sale elenca l’organizzazione.

# 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

• Corrispondenza. Le riunioni private e riservate mostrano il titolo privato e nessun organizzatore. Le riunioni contrassegnate come libere o in lavoro altrove, e quelle che la sala ha rifiutato, sono tempo libero; le riunioni provvisorie contano come occupate; quelle annullate vengono scartate. Gli eventi di un’intera giornata sono date nel fuso orario della sala.
• Frequenza. Un’origine di sale si sincronizza ogni 2 minuti. L’accesso dura circa un’ora e viene riutilizzato.
• Errori. Il codice e il testo di errore di Microsoft vengono citati, ad esempio AADSTS7000215 per un segreto client errato, e una sala che l’app non riesce a leggere fa fallire la sincronizzazione e viene nominata.
• Una connessione al suo posto. Imposta connection_id su una connessione Microsoft del progetto, in entrambe le modalità, al posto di tenant, client_id e client_secret. L’origine allora non conserva alcun segreto e accede come fa la connessione.

Calendari delle risorse di Google Workspace

Il tipo google_calendar legge i calendari delle risorse e delle sale con il tuo account di servizio Google. Il segreto service_account_key è il file di chiave come lo rilascia Google, e il suo suggerimento è l’indirizzo dell’account. L’impostazione facoltativa subject indica l’utente per conto del quale l’account agisce con la delega a livello di dominio.

1. In Google Cloud abilita l’API di Google Calendar, crea un account di servizio e scarica una chiave JSON per esso.
2. Dai all’account l’accesso alle sale. Oppure condividi ogni calendario di sala con l’indirizzo dell’account e l’autorizzazione Visualizza tutti i dettagli degli eventi, oppure attiva la delega a livello di dominio per l’account nella console di amministrazione con l’ambito https://www.googleapis.com/auth/calendar.events.readonly e imposta subject su un utente che può vedere le sale.
3. Il calendar_id di una sala è l’ID calendario della risorsa nella console di amministrazione, in Edifici e risorse; termina con @resource.calendar.google.com. Visualizza l’anteprima con source test, poi salva.

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

• Corrispondenza. Gli eventi privati e riservati mostrano il titolo privato e nessun organizzatore. Gli eventi contrassegnati come trasparenti, e quelli che la sala ha rifiutato, sono tempo libero; quelli annullati vengono scartati. Gli eventi di un’intera giornata mantengono le loro date.
• Errori. Il testo di errore di Google viene citato. Un calendario che l’account non vede viene nominato nell’errore, con le istruzioni per condividerlo.
• Una connessione al suo posto. Imposta connection_id su una connessione Google del progetto al posto di service_account_key. Con l’app di screenRIG l’origine legge i calendari che l’account che l’ha approvata può vedere, quindi quell’account deve vedere ogni calendario di sala che l’origine elenca, e subject non è consentito.

Limiti e privacy

• Una scheda room conserva le 200 prenotazioni più vicine e una scheda room-board ne conserva 60 per sala. Se ce ne sono di più, lo stato mostra un avviso con quante sono state lasciate fuori.
• Il documento della scheda contiene solo ciò che la scheda disegna, perché ogni schermo che mostra una scheda ne conserva il documento. Una scheda room riceve gli organizzatori solo con showOrganizer attivo. Una scheda room-board non riceve mai gli organizzatori e riceve il titolo privato al posto di ogni titolo di riunione, a meno che showTitles sia attivo. Una modifica a una delle due impostazioni raggiunge la scheda alla sincronizzazione successiva. Una riunione privata porta il titolo privato in entrambi i casi.
• I messaggi di questi tipi citano il testo di errore risposto da Microsoft o Google, e mai un segreto.

Il sistema di prenotazione di una sede

Il tipo momentus legge le funzioni (ogni utilizzo di una sala, con date e orari) e gli spazi di un'installazione Momentus Enterprise, il sistema venduto in precedenza come Ungerboeck ed EBMS, con un utente API che il vostro amministratore crea in Momentus (Main Menu, Api Users). Riempie una scheda events per un elenco di eventi, una scheda room-board per una hall o un corridoio, o una scheda room per una sala, e con un documento per sala, ogni schermo mostra le prenotazioni della propria sala. Una sala che cambia poco prima di un evento compare entro l'intervallo di aggiornamento, un minuto per impostazione predefinita.

Due segreti: api_key, uno dei GUID chiave dell'utente API, e api_secret, il suo GUID segreto. Entrambi sono archiviati sigillati, non vengono più mostrati e vanno inseriti di nuovo se la fonte punta a un altro server, un'altra organizzazione o un altro utente 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 legge Momentus, dà forma al documento e lo verifica con la scheda, e mostra le sale e gli eventi letti (functions, functions_other_spaces, events_KEY). Non viene salvato né scritto nulla.

• Che cosa diventa una funzione. Il Space della funzione sceglie la sala, il suo Description è il titolo (title_field può indicare una delle sue descrizioni alternative) e il nome della sala è il luogo. Una funzione senza ora di inizio è un evento di un giorno intero. Una funzione su più date con orari mostra quegli orari in ogni data; quella che finisce prima di iniziare prosegue nella notte.
• Titoli privati. Un room-board mostra il titolo privato a meno che show_titles sia attivo, come per gli altri tipi di sala.
• Errori. Il testo proprio di Momentus non viene mai citato, perché il server è vostro: auth_failed significa che l'utente API, la chiave o il segreto è sbagliato o non può leggere funzioni e spazi, config_invalid che un filtro non è una ricerca Momentus valida, e parse_failed che base_url ha raggiunto una pagina web e non l'API.

Un'insegna per ogni sala

Impostate room_key_prefix (ad esempio momentus-room-) e la fonte scrive anche un documento room per ogni sala con quel prefisso seguito dalla chiave della sala. Date a ogni schermo di sala la sua sala e collocate una scheda room la cui chiave data è il prefisso seguito dal campo proprio dello schermo:

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

Usa il tipo di catalogo inline room in questa primitiva della playlist:

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

Le primitive crd_ usano params e major dell’istanza; ometti questi campi. Il campo facoltativo data seleziona una chiave di documento o un modello di chiave per schermo. --card crd_ID della sorgente continua a indicare la destinazione della sincronizzazione. Per la pagina, imposta visibility.data.key su momentus-room-{screen.field.room} e aggiungi dopo una pagina alternativa senza condizioni.

Il backend riempie il campo nel manifest di ogni schermo, quindi una sola playlist mostra a ogni schermo la propria sala, e uno schermo senza campo sala non mostra nulla per quella scheda. area_key_prefix fa lo stesso per un display di corridoio: l'area di ogni sala la raggruppa, e un room-board delle sale di quell'area viene scritto con il prefisso seguito dalla chiave dell'area (area_card può essere events). screen_field e area_field indicano i campi dello schermo che il controllo qui sotto legge (room e area per impostazione predefinita).

Controllare la mappatura

screenrig source rooms src_ID (e la sezione Mappatura delle sale nella pagina della fonte nella dashboard) elenca le sale che la fonte offre e che nessuno schermo mostra, e gli schermi la cui sala manca o indica una sala che Momentus non ha:

screenrig source rooms src_VENUE

Uno schermo compare nel rapporto quando ha un valore per il campo, o quando la sua playlist colloca una scheda che legge la chiave. Ciascuno è mapped, missing (la playlist legge il campo e lo schermo non ne ha) o unknown (il valore non indica alcuna sala; il rapporto indica la sala che probabilmente si intendeva, ad esempio le stesse lettere in un'altra maiuscola/minuscola). Correggete uno schermo con screenrig screen update scr_ID --field room=ROOM_KEY. Il rapporto legge le sale dell'ultimo aggiornamento riuscito della fonte e non recupera nulla; una fonte che elenca le sue rooms le conosce prima del primo aggiornamento.

Menu dalla tua cassa

Un’origine Square, Shopify o Toast riempie una scheda menu (sezioni di righe con un prezzo su ciascuna) o una scheda price-matrix (articoli sul lato, formati in alto) dal catalogo che già tieni. Una variazione di prezzo, un articolo nuovo o un contrassegno di esaurito arriva sugli schermi alla sincronizzazione successiva, ogni 5 minuti, o subito con 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 prima sincronizzazione sostituisce le sezioni della scheda con quelle del catalogo. source test stampa il documento che la scheda mostrerebbe, se la scheda lo accetta e cosa ha notato.

Cosa arriva sulla scheda

• Sezione. Square: la categoria dell’articolo. Shopify: la collezione che indichi, altrimenti il tipo di prodotto.
• Articolo e formati. Square: l’articolo e le sue variazioni. Shopify: il prodotto e le sue varianti (Default Title non è un formato).
• Prezzo. Square: il prezzo della variazione, oppure il prezzo specifico della sede. Shopify: il prezzo della variante nella valuta del negozio.
• Descrizione. Square: la descrizione dell’articolo in testo semplice. Shopify: la descrizione del prodotto, i primi 400 caratteri.
• Tag. Square: preferenze alimentari vegano, vegetariano e senza glutine. Shopify: tag di prodotto vegan, vegetarian, gluten-free, spicy, new e popular.
• Esaurito. Square: il contrassegno di esaurito della cassa nella sede, fino alla scadenza. Shopify: nessuna variante è disponibile per la vendita. Nessuno dei due valuta le giacenze.

Un articolo con più formati mostra una riga per formato (Latte (Small), Latte (Large)) su una scheda menu e una colonna per formato su una scheda price-matrix. Gli articoli archiviati ed eliminati, le bozze e i prodotti archiviati sono esclusi. Le immagini non vengono trasferite: una scheda che mostra foto usa i media del progetto. I prezzi arrivano nella valuta del catalogo, e l’impostazione currency della scheda disegna il simbolo, quindi impostala sulla scheda (€ per gli euro); lo stato avvisa finché una scheda mostra ancora $ sopra prezzi in un’altra valuta.

Square

1. Nel Square Developer Dashboard crea un’applicazione. È gratuito e non cambia nulla nel tuo negozio.
2. Passa la dashboard a Production, apri Credentials, copia il token di accesso di Production e salvalo in un file. Per la Sandbox usa il suo token e imposta environment su sandbox.
3. Crea l’origine con --secret access_token=@FILE. Un account con una sola sede attiva la usa. Con più sedi, imposta location_id; source test elenca le sedi dell’account quando ne serve una.

Un token di accesso Square porta tutte le autorizzazioni dell’account e non può essere ristretto. screenRIG lo usa per due letture, le sedi e la libreria degli articoli, e lo invia solo ai server di Square. Viene conservato cifrato, mostrato solo con gli ultimi quattro caratteri, e puoi sostituirlo o revocarlo in qualsiasi momento nel Developer Dashboard.

Shopify

L’app richiede l’autorizzazione read_products e nient’altro. Collegati con uno dei due tipi di app:

• Un’app personalizzata. Nell’admin di Shopify apri Impostazioni, App e canali di vendita, Sviluppa app. Assegna all’app read_products, installala, mostra il token di accesso dell’API Admin e salvalo in un file. Crea l’origine con --secret access_token=@FILE.
• Un’app del Dev Dashboard. Su dev.shopify.com crea un’app con read_products e installala nel negozio. Imposta client_id e crea l’origine con --secret client_secret=@FILE. screenRIG scambia i due valori con un token di accesso che dura un giorno e si rinnova da solo.

Toast

Un’origine Toast legge i menu e le scorte di un ristorante con l’accesso API standard che il ristorante crea da sé: in sola lettura e per una sola sede.

1. In Toast Web apri Integrations, Toast API access, Manage credentials e crea credenziali con gli ambiti menus:read e stock:read. Toast richiede Restaurant Management Suite Essentials o superiore e l’autorizzazione Manage Integrations.
2. Copia l’ID client e il segreto client. Toast invia per email il GUID del ristorante quando crea le credenziali.
3. Crea l’origine con restaurant (il GUID), client_id e --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

• Sezioni e righe. Un gruppo di menu con articoli è una sezione, e un sottogruppo è una sezione a sé. Un articolo in più gruppi è un solo articolo, sotto il primo di essi. Un articolo con prezzo per formato è una riga per ogni formato.
• Prezzi. I prezzi base e di menu come li dà Toast, e un prezzo a fascia oraria finché la sua pianificazione copre il momento attuale. Un prezzo aperto non ne ha. La risposta di Toast non contiene valuta, quindi imposta currency sulla scheda.
• Esaurito. Un articolo che Toast contrassegna come esaurito, o con quantità pari a zero o meno. Una scorta bassa non viene mai letta come esaurito.
• Fasce della giornata. Quando nessun menu è disponibile in quell’ora, la sincronizzazione fallisce con config_invalid e la scheda mantiene l’ultimo menu. Un tabellone che segue le fasce della giornata usa un’origine per ciascuna, oppure indica il suo menu.
• Credenziali. Il segreto è legato all’ambiente e al ristorante, quindi cambiare l’uno o l’altro lo richiede di nuovo (source_secret_required). screenRIG accede una volta per esecuzione e condivide l’accesso tra le origini che usano le stesse credenziali, come chiede Toast. Modificatori, combo, allergeni, porzioni e immagini non vengono letti.

Cosa aspettarsi

• Formati. Una scheda price-matrix ha fino a 6 colonne di formati, nell’ordine in cui compaiono per la prima volta. Non accetta variations.
• Limiti. Una scheda menu contiene 8 sezioni da 24 righe e una scheda price-matrix 12 sezioni da 40 articoli. Il resto viene escluso e lo stato mostra un avviso con il numero; scegli cosa mostrare con include_sections.
• Un catalogo troppo grande (oltre 30 pagine di articoli e categorie Square, o 500 prodotti Shopify) fa fallire la sincronizzazione con too_large invece di mostrare una parte del menu. Indica collezioni o sezioni per mostrarne meno.
• Niente da mostrare. Se le impostazioni non lasciano alcun articolo, la sincronizzazione fallisce con config_invalid e la scheda mantiene l’ultimo menu.
• Limiti di frequenza. La sincronizzazione attende fino a 10 secondi che il budget di Shopify si ricarichi, e una sincronizzazione limitata riprova all’intervallo successivo.
• Clover e Lightspeed danno accesso alla loro API solo ai partner approvati, quindi non sono origini.

Una credenziale conservata è vincolata all’ambiente Square o al negozio Shopify per cui è stata inserita. Puntare l’origine a un altro ambiente o negozio richiede di nuovo la credenziale (source_secret_required), così un’origine non può inviarla altrove. Le richieste vanno solo ai server di Square e a NAME.myshopify.com, e sono solo di lettura.

Sicurezza

Un indirizzo che concede l’accesso è una credenziale. screenRIG lo memorizza cifrato, restituisce solo schema e host, e lo usa soltanto per eseguire la sincronizzazione. Le origini leggono indirizzi http(s) pubblici sulla porta 80 o 443 e seguono al massimo tre reindirizzamenti; un indirizzo che non si risolve in un host pubblico, una connessione rifiutata e un handshake fallito appaiono tutti allo stesso modo, quindi un’origine non può servire a esplorare una rete. Nessun messaggio cita un indirizzo o la risposta ricevuta. Le origini si limitano a leggere: non scrivono mai in un calendario.

Correlato

• Schede: tipi di scheda, proprietà e dati in tempo reale.
• CLI per segnaletica: ogni comando screenrig.
• Connessioni: un accesso salvato a Microsoft o a Google per le origini delle sale, Power BI e la sincronizzazione dei media.
• Riferimento API: le route /api/sources e i relativi problemi.