Scripts de calcul

Un script de calcul (affiché sous le nom Transform dans les paramètres de la carte) est une petite fonction JavaScript qui déduit ce que dessine une carte à partir des données qu’elle a chargées. Utilisez-le lorsqu’aucune source ne fournit exactement la forme dont vous avez besoin : convertir des unités, associer deux séries en un itinéraire, compter des lignes, retenir le pire statut. Un script ne fait que calculer. Il ne peut pas définir un paramètre, exécuter une commande, ouvrir une page ni accéder au réseau.

Ajouter un script

Personnalisez le tableau de bord et ouvrez les paramètres de la carte.
Dans l’onglet Données, ouvrez Avancé : calculer les valeurs avec un script.
Cochez Exécuter ce script et rédigez le Script.
Sélectionnez Exécuter maintenant pour exécuter votre brouillon sur les données actuelles de la carte. Le Résultat liste ce qui est revenu par emplacement, par exemple « series: table, 12 row(s) » et « ran in 3 ms ».
Définissez le Délai d’exécution (ms) et En cas d’échec d’une exécution.
Sélectionnez Enregistrer.

Supprimer le script le supprime. Le script est copié avec la carte, voyage dans les fichiers de tableau de bord et reste sur la carte lorsque vous l’enregistrez comme widget.

Le contrat

Le script est un module ES dont l’export par défaut est une fonction synchrone :

export default function transform({ slots, params, window, now }) {
  // slots:  the bound data by slot key, as the source returned it (shape table | scalar | series | record)
  // params: the effective board parameters of the card's page (read-only)
  // window: { from, to, interval? } (ms since the epoch) when the card's data ran with a window
  // now:    ms since the epoch, the host's clock (a script never reads Date)
  return { slots: { /* the slots you replace */ } };
}

Il renvoie { slots }. Chaque emplacement renvoyé remplace celui chargé ; les emplacements que vous ne renvoyez pas restent tels que chargés. Un résultat vide affiche les données telles que chargées.

Forme	Forme
Scalaire	`{ shape: 'scalar', value: 21.5, meta: { unit: '°C', decimals: 1 } }`
Série	`{ shape: 'series', series: [{ name: 'temperature', points: [{ t: '2026-11-09T10:00:00Z', v: 21.5 }] }] }`
Tableau	`{ shape: 'table', columns: [{ key: 'id' }, { key: 'value', type: 'number' }], rows: [{ id: 'p1', value: 3 }] }`
Enregistrement	`{ shape: 'record', record: { level: 2.4, flow: 18 } }`

Une carte de schéma de procédé ou de modèle 3D peut aussi renvoyer scene : des objets, des surcharges par objet, des connexions et zones supplémentaires, la vue et les problèmes. Cela modifie uniquement le dessin.

Lieu d’exécution

Le script s’exécute dans votre navigateur, dans un cadre masqué sans accès à Hermetry, au réseau ou à votre session, dans son propre worker. Il se relance à chaque changement des données de la carte (mise à jour en direct incluse) ou d’un paramètre. Une seule exécution par carte est en cours à la fois ; la dernière entrée l’emporte, à raison de 20 exécutions par seconde au maximum. Une carte qui n’est pas affichée ne s’exécute pas. Les écrans d’affichage exécutent les scripts de la même manière.

Limites

Limite	Valeur
Longueur du script	65 536 caractères
Délai d’exécution	De 10 à 500 ms par exécution, 50 par défaut. Au-delà, l’exécution est arrêtée.
Emplacements renvoyés	16
Lignes par tableau	5,000
Colonnes	64
Une valeur textuelle	10 Kio
Résultat complet	2 Mio
Objets dans une scène	500 sur un schéma de procédé, 2 000 sur un modèle 3D

En cas d’échec d’une exécution

En cas d’échec d’une exécution	La carte
Conserver le résultat précédent	Conserve la dernière sortie valide et affiche un badge Transform failed
Afficher la carte vide	Affiche l’erreur à la place des données

Messages : « The script ran past its time budget: … », « The script could not be loaded: … », « Transform failed: … ».

Exemples

Celsius vers Fahrenheit sur une carte de statistique (emplacement value) :

export default function transform({ slots }) {
  const c = slots.value && typeof slots.value.value === 'number' ? slots.value.value : null;
  if (c === null) return {};
  return { slots: { value: { shape: 'scalar', value: c * 9 / 5 + 32, meta: { unit: '°F', decimals: 1 } } } };
}

Compter les alarmes ouvertes des appareils d’un paramètre (une carte de statistique dont l’emplacement value est lié à Alarms (live), un tableau) :

export default function transform({ slots }) {
  const rows = slots.value && Array.isArray(slots.value.rows) ? slots.value.rows : [];
  return { slots: { value: { shape: 'scalar', value: rows.length, meta: { decimals: 0 } } } };
}

Un itinéraire à partir de séries de latitude et de longitude (une carte dont l’emplacement routes est lié à Device readings over time avec les clés lat,lng) :

export default function transform({ slots }) {
  const series = slots.routes && Array.isArray(slots.routes.series) ? slots.routes.series : [];
  const named = (k) => series.find((s) => s && s.name === k) || { points: [] };
  const lng = new Map(named('lng').points.map((p) => [p.t, p.v]));
  const track = named('lat').points
    .filter((p) => lng.has(p.t))
    .map((p) => [p.v, lng.get(p.t), Date.parse(p.t)])
    .sort((a, b) => a[2] - b[2]);
  return { slots: { routes: { shape: 'table',
    columns: [{ key: 'name' }, { key: 'positions' }],
    rows: track.length >= 2 ? [{ id: 'route', name: 'Route', positions: track.slice(-256) }] : [] } } };
}

Une liste dans une cellule contient au plus 256 éléments ; limitez donc un itinéraire à 256 points. Voir Cartes de carte.

Bonnes pratiques

Ne renvoyez que les emplacements que vous modifiez.
Prévoyez l’absence de données : un emplacement peut être vide lorsque l’appareil est silencieux.
Gardez les scripts petits et rapides ; une longue boucle sur une année de relevés bruts dépassera le délai d’exécution. Privilégiez une source avec un agrégat.
Utilisez now, jamais Date.now(), pour toute logique liée au temps.