Programma gli schermi da un foglio di calcolo

Dal foglio agli schermi

1. Parti dal modello. Salva il modello come CSV o XLSX, oppure usa un tuo foglio con le stesse colonne.
2. Compila una riga per ogni voce di programmazione. Indica lo schermo (o una cartella o un tag), il file, l’inizio e la fine.
3. Importalo. Trascina il file nella finestra Importa della scheda Programmazione della dashboard, oppure esegui screenrig schedule import FILE.
4. Correggi le righe con errori. Ogni errore indica la riga, la colonna e un codice. Modifica la cella nella finestra di dialogo, oppure modifica il foglio e importalo di nuovo.
5. Controlla l’anteprima. Elenca i livelli creati dal foglio, quelli che modifica o rimuove e il calendario degli schermi che tocca.
6. Pubblica. Tutte le righe vengono applicate insieme, oppure nessuna.

I passaggi da 1 a 5 non scrivono nulla. Uno schermo richiede un fuso orario (screen set-timezone) e una playlist predefinita (screen assign) prima che una riga possa programmarlo, e un file deve essere un’immagine o un video approvato.

Il foglio

La prima riga indica i nomi delle colonne. Ogni riga successiva è una voce di programmazione. Le righe vuote vengono saltate. Un foglio è un file CSV (UTF-8, separato da virgole o punti e virgola) o una cartella di lavoro XLSX, e una cartella di lavoro XLSX viene letta dal suo primo foglio.

Le intestazioni corrispondono senza distinguere maiuscole, spazi e punteggiatura. Una colonna che nulla legge viene ignorata e l’anteprima la elenca. Una riga richiede target, content e almeno uno tra start, end, days o una finestra giornaliera.

Screen,File,Start,End,Timezone,Days,Daily start,Daily end,Priority,Name
LOBBY-01,welcome-spring.jpg,2026-11-05 18:00,2026-11-08 02:00,America/Los_Angeles,,,,0,
folder:Casino Floor,happy-hour.mp4,2026-11-05,2026-11-30,,Mon-Fri,16:00,19:00,5,Happy hour
tag:elevators,playlist:Holiday loop,2026-12-01 09:00,2026-12-26,,,,,0,

• La riga 2 riproduce welcome-spring.jpg sullo schermo con il codice LOBBY-01 dalle 6 PM del 5 novembre alle 2 AM dell’8 novembre, ora del Pacifico.
• La riga 3 riproduce happy-hour.mp4 su ogni schermo della cartella Casino Floor e delle cartelle al suo interno, dalle 4 PM alle 7 PM nei giorni feriali, dal 5 novembre alla fine del 30 novembre.
• La riga 4 riproduce la playlist Holiday loop su ogni schermo con il tag elevators, dalle 9 AM del 1 dicembre alla fine del 25 dicembre.

Destinazioni

Una destinazione è una di queste:

• Uno schermo. Un id schermo, il valore di un qualsiasi campo dello schermo (un codice stanza, un numero di negozio) o il nome dello schermo. --code-field o code_field limita la corrispondenza a un solo campo, come code o room_id.
• Una cartella. folder:NAME o folder:Parent/Child. Raggiunge la cartella e tutte le cartelle al suo interno.
• Un tag. tag:NAME raggiunge ogni schermo con il tag.

Più destinazioni in una cella si separano con ; o |, come in LOBBY-01;LOBBY-02|tag:elevators.

Contenuto

• Un file. Il nome di un file multimediale del progetto, o il nome originale di un upload convertito. Il file viene riprodotto a schermo intero. Il primo commit che usa un file crea la playlist di un solo file Scheduled: FILE; le importazioni successive la riutilizzano.
• Una playlist. playlist:NAME o un id di playlist. La playlist ha una versione approvata e non è un modello.

Orari

• Date e orari. Vengono letti 2026-11-05 18:00, 2026-11-05T18:00, 11/5/2026 6:00 PM e le celle data del foglio di calcolo. Un orario con offset, come Z o +02:00, viene rifiutato.
• L’orologio di ogni schermo. Gli orari sono letti sull’orologio degli schermi che la riga raggiunge, quindi 18:00 sono le 6 PM ovunque si trovi lo schermo.
• Un altro fuso orario. Una cella timezone (o il parametro timezone della richiesta) indica che la riga è scritta in quel fuso. Gli orari vengono convertiti nel fuso degli schermi quando tutti gli schermi della riga condividono lo stesso fuso. Una riga che raggiunge schermi in più fusi lascia timezone vuoto e legge l’orologio di ciascuno schermo.
• Una sola data come fine chiude quel giorno: 2026-11-30 termina alla fine del 30 novembre. Una sola data come inizio comincia a mezzanotte.
• Nessuna fine mantiene la riga in riproduzione finché un’importazione successiva non la rimuove. L’anteprima segnala l’avviso open_end.
• Giorni. Mon-Fri, Mon,Wed,Fri, Sat,Sun, weekdays, weekends o daily. Una riga con days e senza finestra giornaliera riproduce tutto il giorno in quei giorni.
• Una finestra giornaliera. daily start e daily end indicano le ore di ogni giorno, per esempio 16:00 e 19:00 oppure 4:00 PM e 7:00 PM. Indicali entrambi. Una fine uguale o precedente all’inizio attraversa la mezzanotte e appartiene al giorno in cui inizia. Senza days, la finestra vale ogni giorno.

Anteprima ed errori

L’anteprima controlla ogni riga e ogni cella prima di scrivere qualsiasi cosa. Una riga con un errore viene mostrata con le sue celle e ogni errore indica la colonna, un codice e cosa cambiare.

Due avvisi non fermano un’importazione. open_end segnala una riga senza fine. outranked segnala una riga che un livello condiviso (una riga per più schermi, una cartella o un tag) sovrascrive in riproduzione su uno schermo.

Un foglio senza righe, un file che non è UTF-8, più di 5.000 righe, un file oltre 8 MiB, o un commit che scriverebbe le programmazioni proprie di più di 400 schermi viene rifiutato con il motivo.

Livelli

Le righe che coincidono per contenuto, orari, priorità, nome e display diventano un solo livello. La destinazione non fa parte del confronto, quindi dieci righe che riproducono lo stesso file agli stessi orari su dieci schermi creano un solo livello.

• Uno schermo crea una voce nella programmazione propria di quello schermo.
• Più schermi, una cartella o un tag creano un solo livello condiviso, una campagna su quel pubblico. Un livello condiviso prevale sui livelli propri di uno schermo.

Raggruppare trasforma i 200 schermi di un locale in una sola campagna e non in 200 voci, e una correzione nel foglio modifica un solo livello. La colonna name nomina un livello condiviso. Senza di essa, il livello prende il nome dall’importazione, dal contenuto e dalla destinazione, come in Spring promos: happy-hour.mp4 on Casino Floor.

Importa di nuovo

Il valore name di un’importazione la identifica e il predefinito è import. Importando di nuovo con lo stesso nome:

• aggiorna i livelli che ha creato, anche quando le date di una riga sono cambiate;
• aggiunge i livelli delle nuove righe;
• rimuove i livelli le cui righe non sono più nel foglio;
• non cambia nulla quando il foglio è lo stesso.

I livelli creati da un’importazione la portano nel proprio id (le voci di uno schermo iniziano con imp_) e le campagne portano un contrassegno import. I livelli creati a mano non vengono mai toccati. Usa un nome per un foglio e un nome diverso per un altro.

Esegui un’importazione

Dashboard

Apri la scheda Programmazione di un progetto e scegli Importa. Trascina un file CSV o XLSX. La finestra di dialogo mostra una tabella delle righe con ogni errore accanto alla sua cella e modifichi la cella direttamente lì. Mostra poi il calendario composto degli schermi che l’importazione modifica. Pubblica ne esegue il commit.

Riga di comando

screenrig schedule template --output schedule.csv
screenrig schedule import schedule.csv --name "Spring promos" --timezone America/Los_Angeles
screenrig schedule import schedule.csv --name "Spring promos" --timezone America/Los_Angeles --commit

schedule import mostra l’anteprima e non scrive nulla. --commit applica il foglio quando ogni riga è valida.

Il comando termina con 0 per un foglio valido, 8 quando le righe hanno errori (non viene scritto nulla) e 5 quando il progetto è cambiato dopo l’anteprima (eseguilo di nuovo). FILE è un file .csv, .xlsx o .json, oppure - per lo standard input. Un file JSON contiene un array di oggetti riga, oppure {"rows": [...]}, con chiavi pari ai nomi delle colonne.

API

Invia il foglio come righe JSON, oppure come corpo CSV o XLSX con le impostazioni come parametri di query. L’anteprima richiede accesso in lettura. Il commit richiede una credenziale con accesso in scrittura, che concede una persona che può approvare nella dashboard.

curl -s https://api.screenrig.ai/api/schedule/imports/preview \
  --header "Authorization: Bearer $SCREENRIG_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "Spring promos",
    "timezone": "America/Los_Angeles",
    "rows": [
      {"target": "LOBBY-01", "content": "welcome-spring.jpg", "start": "2026-11-05 18:00", "end": "2026-11-08 02:00"},
      {"target": "folder:Casino Floor", "content": "happy-hour.mp4", "start": "2026-11-05", "end": "2026-11-30",
       "days": "Mon-Fri", "daily_start": "16:00", "daily_end": "19:00", "priority": 5, "name": "Happy hour"}
    ]
  }'

Lo stesso foglio come file:

curl -s "https://api.screenrig.ai/api/schedule/imports/preview?name=Spring%20promos&timezone=America/Los_Angeles" \
  --header "Authorization: Bearer $SCREENRIG_TOKEN" \
  --header "Content-Type: text/csv" \
  --data-binary @schedule.csv

La risposta, abbreviata:

{
  "name": "Spring promos",
  "valid": false,
  "fingerprint": "FINGERPRINT",
  "columns": ["target", "content", "start", "end", "days", "daily_start", "daily_end", "priority", "name"],
  "summary": {"rows": 2, "rows_with_errors": 1, "levels": 1, "creates": 1, "updates": 0,
              "unchanged": 0, "removes": 0, "screens": 1, "playlists": 1},
  "rows": [
    {"row": 2, "status": "ok", "level": "LEVEL_KEY"},
    {"row": 3, "status": "error",
     "errors": [{"column": "content", "code": "unknown_file",
                 "message": "No file or playlist is named \"happy-hour.mp4\"."}]}
  ],
  "levels": [{"key": "LEVEL_KEY", "action": "create", "home": "screen", "screen_id": "scr_LOBBY",
              "content": {"kind": "file", "id": "med_WELCOME", "name": "welcome-spring.jpg"},
              "screens": 1, "priority": 0, "from": "2026-11-05T18:00", "until": "2026-11-08T02:00", "rows": [2]}],
  "removals": []
}

rows[].cells restituisce le celle di ogni riga così come le ha fornite il foglio, così un client le corregge e invia di nuovo le righe. valid è true quando nessuna riga ha errori. calendar ha la forma di GET /api/schedule/calendar e mostra gli schermi che l’importazione modifica come sarebbero dopo un commit.

Il commit invia lo stesso foglio e il valore fingerprint della sua anteprima, come membro del corpo JSON o come parametro di query con un file. Invia un Idempotency-Key per riprovare in sicurezza.

curl -s https://api.screenrig.ai/api/schedule/imports \
  --header "Authorization: Bearer $SCREENRIG_TOKEN" \
  --header "Idempotency-Key: spring-promos-1" \
  --header "Content-Type: application/json" \
  --data @commit.json

La risposta contiene preview e applied, i conteggi di ciò che è stato creato, aggiornato, lasciato invariato e rimosso, con gli schermi scritti e le playlist create. Un commit viene rifiutato, senza scrivere nulla, come:

GET /api/schedule/imports/template?format=csv e format=xlsx rispondono con il modello.

Limiti

• 5.000 righe e 8 MiB per foglio.
• 32 livelli propri per schermo. Un’organizzazione può avere fino a 100 campagne in tutti i suoi progetti, e ogni livello condiviso ne è una.
• Per ogni commit vengono scritte le programmazioni proprie di 400 schermi. Una riga con cartella o tag raggiunge un numero qualsiasi di schermi.
• Il nome di un’importazione ha da 1 a 80 caratteri.

Correlato

• CLI di signage: programmazioni, takeover e campagne per uno schermo o una flotta.
• Riferimento API: le route /api/schedule/imports e i relativi problemi.
• Autenticazione: accesso Solo lettura, Proponi e Gestisci.