Access alarms from a script

🟢 Beginner

script alarm

osp-scripts osp-alarms

This example will show how to access the alarms from a script.

  • Create a detached script that runs on a fixed interval using detached.scripts.

  • Check for the existence of an alarm using alarms.exists before acting.

  • Create a new alarm from script if it does not exist.

  • Retrieve live alarms with alarms.getLive and escalate severity when needed.

git checkout origin/osp-scripts-configuration .
git checkout origin/osp-alarms-configuration .
git checkout origin/example-scripts-access-alarms .

Steps

1. Create the detached script that is executed every 10 seconds

root/examples/scripts/access-alarms/detached.scripts

{
  "moduleId": "modules.scripts.scripts-1",
  "sourceFile": "root/examples/access-alarms/script.js",
  "scheduledExecutions": [
    "0/10 * * ? * * *"
  ]
}

root/examples/scripts/access-alarms/script.js

1main();
2
3function main() {
4  log.info("Running examples access-alarms.");
5}

You should see the log message appears every 10 seconds on the scripts log.

2026-04-09 09:27:50.008 [script-executor] INFO  s.logger.root.examples.access-alarms - Running examples access-alarms.
2026-04-09 09:28:00.003 [script-executor] INFO  s.logger.root.examples.access-alarms - Running examples access-alarms.

2. Check if the wanted alarm exists

We will use the function alarms.exists() to check if the wanted alarm exists.

root/examples/scripts/access-alarms/script.js

 1const SERIAL = "example-alarm";
 2
 3main();
 4
 5function main() {
 6  log.info("Running examples access-alarms.");
 7
 8  const existResult = alarms.exists(SERIAL);
 9  if (existResult.success) {
10    log.info("Alarm [{}] exists. Checking its severity.", [SERIAL]);
11  } else {
12    log.info("Alarm [{}] doesn't exist. Creating it.", [SERIAL]);
13  }
14}

The script log should contain the new log entry.

2026-04-09 09:28:00.007 [script-executor] INFO  s.logger.root.examples.access-alarms - Alarm [example-alarm] doesn't exist. Creating it.

3. Create the alarms

The next step is to add the creation of the alarms. We will not detail the alarm creation process. For more information, you can check the example Create an alarm from a script.

root/examples/scripts/access-alarms/script.js

 1const SERIAL = "example-alarm";
 2const INSERT_SEVERITY = 400;
 3
 4main();
 5
 6function main() {
 7  log.info("Running examples access-alarms.");
 8
 9  const existResult = alarms.exists(SERIAL);
10  if (existResult.success) {
11    log.info("Alarm [{}] exists. Checking its severity.", [SERIAL]);
12  } else {
13    log.info("Alarm [{}] doesn't exist. Creating it.", [SERIAL]);
14    createAlarm();
15  }
16}
17
18function createAlarm() {
19  const insertResult = alarms.insert(
20    alarms
21      .newAlarmBuilder(SERIAL, INSERT_SEVERITY)
22      .addTag("Example")
23      .setSource("root.examples.access-alarms"),
24  );
25
26  if (!insertResult.success) {
27    log.warn("Insertion of alarm [{}] failed with message [{}].", [
28      SERIAL,
29      insertResult.message,
30    ]);
31  } else {
32    log.info("Insertion of alarm [{}] successful.", [SERIAL]);
33  }
34}

The script log should contain the new log entry.

2026-04-09 09:32:40.343 [script-executor] INFO  s.logger.root.examples.access-alarms - Insertion of alarm [example-alarm] successful.

4. Update the alarm if the severity is not correct

The last step is to escalate the alarm if necessary. We will use the function alarms.getLive() with a filter to get the alarm.

When we have the alarms list, we iter on each alarm and check the severity.

Note

In this case, we only have one alarm.

root/examples/scripts/access-alarms/script.js

 1const SERIAL = "example-alarm";
 2const INSERT_SEVERITY = 400;
 3const EXPECTED_SEVERITY = 500;
 4
 5main();
 6
 7function main() {
 8  log.info("Running examples access-alarms.");
 9
10  const existResult = alarms.exists(SERIAL);
11  if (existResult.success) {
12    log.info("Alarm [{}] exists. Checking its severity.", [SERIAL]);
13    checkSeverity();
14  } else {
15    log.info("Alarm [{}] doesn't exist. Creating it.", [SERIAL]);
16    createAlarm();
17  }
18}
19
20function createAlarm() {
21  const insertResult = alarms.insert(
22    alarms
23      .newAlarmBuilder(SERIAL, INSERT_SEVERITY)
24      .addTag("Example")
25      .setSource("root.examples.access-alarms"),
26  );
27
28  if (!insertResult.success) {
29    log.warn("Insertion of alarm [{}] failed with message [{}].", [
30      SERIAL,
31      insertResult.message,
32    ]);
33  } else {
34    log.info("Insertion of alarm [{}] successful.", [SERIAL]);
35  }
36}
37
38function checkSeverity() {
39  const getLiveResult = alarms.getLive(
40    "root.alarms.filters.all",
41    "root.alarms.views.default",
42    [{ field: "serial", operation: "EQUAL", content: SERIAL }],
43  );
44
45  if (!getLiveResult.success) {
46    log.warn("Retrieving of alarm [{}] failed with message [{}].", [
47      SERIAL,
48      getLiveResult.message,
49    ]);
50  } else {
51    for (const alarm of getLiveResult.content.value) {
52      if (alarm?.severity !== EXPECTED_SEVERITY) {
53        log.info("Alarm severity is [{}]. Escalating to [{}].", [
54          alarm?.severity,
55          EXPECTED_SEVERITY,
56        ]);
57        alarms.escalate(alarm.serial, EXPECTED_SEVERITY);
58      } else {
59        log.info("Alarm [{}] has the correct state", [JSON.stringify(alarm)]);
60      }
61    }
62  }
63}

The script log should contain the new log entry.

2026-04-09 09:40:40.082 [script-executor] INFO  s.logger.root.examples.access-alarms - Alarm severity is [400]. Escalating to [500].
2026-04-09 09:40:50.063 [script-executor] INFO  s.logger.root.examples.access-alarms - Alarm [{"id":"example-alarm","serial":"example-alarm","firstTimestamp":{"epochMillis":1775727630346},"lastTimestamp":{"epochMillis":1775727630346},"severity":500,"summary":"","location":"","source":"root.examples.access-alarms","tags":["Example"],"additionalData":null,"acknowledged":false,"hideUntil":null,"forceHide":null,"journal":[],"count":1,"origSeverity":500,"isSeverityLocked":false,"highestSeverity":null,"lowestSeverity":null,"parent":null,"children":null}] has the correct state

5. Log of a full cycle

The complete example took 30 seconds to create the original alarm, escalate it and display the final state.

2026-04-09 09:46:10.009 [script-executor] INFO  s.logger.root.examples.access-alarms - Running examples access-alarms.
2026-04-09 09:46:10.014 [script-executor] INFO  s.logger.root.examples.access-alarms - Alarm [example-alarm] doesn't exist. Creating it.
2026-04-09 09:46:10.028 [script-executor] INFO  s.logger.root.examples.access-alarms - Insertion of alarm [example-alarm] successful.

2026-04-09 09:46:20.004 [script-executor] INFO  s.logger.root.examples.access-alarms - Running examples access-alarms.
2026-04-09 09:46:20.009 [script-executor] INFO  s.logger.root.examples.access-alarms - Alarm [example-alarm] exists. Checking its severity.
2026-04-09 09:46:20.024 [script-executor] INFO  s.logger.root.examples.access-alarms - Alarm severity is [400]. Escalating to [500].

2026-04-09 09:46:30.009 [script-executor] INFO  s.logger.root.examples.access-alarms - Running examples access-alarms.
2026-04-09 09:46:30.016 [script-executor] INFO  s.logger.root.examples.access-alarms - Alarm [example-alarm] exists. Checking its severity.
2026-04-09 09:46:30.031 [script-executor] INFO  s.logger.root.examples.access-alarms - Alarm [{"id":"example-alarm","serial":"example-alarm","firstTimestamp":{"epochMillis":1775727970016},"lastTimestamp":{"epochMillis":1775727970016},"severity":500,"summary":"","location":"","source":"root.examples.access-alarms","tags":["Example"],"additionalData":null,"acknowledged":false,"hideUntil":null,"forceHide":null,"journal":[],"count":1,"origSeverity":500,"isSeverityLocked":false,"highestSeverity":null,"lowestSeverity":null,"parent":null,"children":null}] has the correct state