system.user

system.user tells a script who it runs as and lets it check roles before acting. All three functions are gateway calls, so they work in screen, cron, console and module scripts, and not in an expression tag. See Users and roles for the roles and The system API for how calls run.

Types

type ScadexRole = "viewer" | "operator" | "engineer" | "admin";

interface ScadexUser {
  id: string;
  name: string;
  email: string;
  role: ScadexRole;
}

current

current(): ScadexUser

Who runs the script, with the role the script runs under. Any role.

Context	What it returns
Screen script	The signed-in user, with their role as it is at that moment
Script console	The administrator who pressed Run (or the identity of the API key that called the route)
Cron job, scheduled	The gateway's own account for the job: id and name are cron:<job name>, email is empty, role is engineer
Cron job, run by hand	The user who started it, with the role engineer
Module script	The principal the module named, role engineer

var me = system.user.current();
console.log(me.name + ' (' + me.role + ')');

hasRole

hasRole(role: ScadexRole): boolean

Parameter	Type	Meaning
role	"viewer", "operator", "engineer" or "admin"	The role to test. Required

Whether whoever runs the script has at least this role, in the order viewer, operator, engineer, admin. Any role. Error for anything else: role must be viewer, operator, engineer or admin.

Use it to avoid a refused call in a screen script, which would fail the script and drop its writes:

if (system.user.hasRole('operator')) {
  system.alarm.acknowledge(system.alarm.active({ tagPath: event.params.Motor }).map(function (a) { return a.id; }));
} else {
  return { toast: { message: 'Operators acknowledge alarms', variant: 'warning' } };
}

list

list(): ScadexUser[]

Everyone who can sign in, ordered by name, with each user's own role. Needs the admin role; an engineer's cron script fails with Listing users needs the admin role, and this script runs as engineer.