fiberguardian/FiberGuardian_Summary.md

# FiberGuardian – Summary Document

This document summarizes the **ServiceNow event export**, **Netcool rules logic**, and **MIB-based OID/trap mappings** for the FiberGuardian (ADVA FSP3000 fiber monitoring) integration.

---

## 1. Summary of Events in ServiceNow

### Source and scope

- **File:** `test_events_servicenow.xml`
- **Export date:** 2026-02-23 13:38:14
- **Total event records:** 83 (`em_event` rows)

### Event classification

- **Event class:** All events are `Trap From Enterprise 2544` (ADVA enterprise OID 1.3.6.1.4.1.2544).
- **Source:** `Trap From Enterprise 2544`
- **Node:** Events are reported from node `10.82.8.55` (trap receiver / mid-server).

### Processing and state

- **Processing notes:** All 83 events have `No event rule applied` — no ServiceNow event rule matched these traps.
- **Resolution state:** All `New`.
- **State:** All events are in **Error** state.
- **Error message:** `severity: Invalid value` — the trap’s severity could not be mapped or validated, which likely contributes to “No event rule applied” and Error state.

So in this export: every event is an ADVA Enterprise 2544 trap, unclassified by event rules, and in Error due to invalid/missing severity.

### Event types (by `snmpTrapOID`)

Traps use the **ALM** trap OID branch: `iso.org.dod.internet.private.enterprises.2544.1.14.0.*` (numeric: **.1.3.6.1.4.1.2544.1.14.0.X**).

| Count | Trap OID (last digit) | Trap name (from MIB) |
|------|------------------------|----------------------|
| 47   | .14.0.62               | authenticationNotification |
| 8    | .14.0.9                | alarmFaRunning |
| 8    | .14.0.19               | objectChangedTrap |
| 4    | .14.0.63               | authenticationNotificationSummary |
| 4    | .14.0.44               | transientFaSaved |
| 4    | .14.0.42               | transientFaCompleted |
| 4    | .14.0.41               | transientFaStarted |
| 4    | .14.0.14               | alarmLinkBudgetExceeded |

**Total:** 83 events across 8 trap types. Most frequent: **authenticationNotification** (62), then **alarmFaRunning** and **objectChangedTrap** (8 each).

### Typical payload (from `additional_info` / description)

- **Common OIDs in varbinds:**  
  `2544.1.14.1.4.1.2.X` (event type name), `2544.1.14.4.2.1.2/4.X` (timestamp, entity ID), `2544.1.14.2.2.1.4/5.1` (duct/port name, unit name), `2544.1.14.5.8.*` (auth: user, IP, protocol, etc.), `sysUpTime`.
- **Example resources:** MCH-1-1, SHMON-1, “Duct 1-miniduct 2 Grijs”.

---

## 2. Summary of Logic in the Netcool File

### File and purpose

- **File:** `FiberGuardianSNMPRules-netcool.txt`
- **Role:** Netcool (OMNIbus) rules for normalizing and enriching FiberGuardian SNMP traps (enterprise 2544) before forwarding or display.

### High-level flow

1. **Match:** Traps whose `@AlertKey` matches `.1.3.6.1.4.1.2544` (enterprise 2544).
2. **Normalize node:** Hostname is taken from `@Node`, then trimmed to the part before `.nl.eu.abnamro.com` and stored back in `@Node`.
3. **Fixed enrichment:**
   - `@ApplId = "FiberGuardian"`
   - Log line: `AAB Specific : Fiber Guardian trap from <hostname>`
4. **Branch by OID:** Depending on the full trap OID (`.1.3.6.1.4.1.2544.1.14.6.X` for ALM or `.1.3.6.1.4.1.2544.1.15.6.X` for SCALM), the rule sets:
   - **Severity** (`@Severity`)
   - **Reason code** (`$Event_Reasoncode`)
   - **Summary** (`@Summary`) using trap-specific varbinds (e.g. portAidString, portName, alarmSeverity, neEventLogIdentityTranslation).
5. **Unknown traps:** If the OID does not match any known branch, the trap is **discarded** and a log line is written with enterprise and specific-trap number.

### Severity and reason codes

- **@Severity 5** → `MON.I.FIB.00001` (link/fiber-related: threshold, link budget, root link fault).
- **@Severity 4** → `MON.I.FIB.00002` (system/equipment: internal error, reboot, bad sys stat, monitoring process, auth, hardware, temperature, voltage, fan, etc.).

### Trap branches implemented (by OID suffix)

**ALM branch (2544.1.14.6.X) – monitor-unit style (portAidString, portName, alarmSeverity):**

- 11 → alarmThresCrossedFast  
- 12 → alarmThresCrossedMedium  
- 13 → alarmThresCrossedSlow  
- 14 → alarmLinkBudgetExceeded  
- 15 → alarmLinkBudgetNearlyExceeded  
- 45 → transientInternalError  
- 46 → alarmRebootRunning  
- 48 → alarmBadSysStat  
- 50 → alarmMonProcNotRunning  
- 60 → alarmEmailNotifyLinkBudgetExceeded (many varbinds in summary)  
- 63 → authenticationNotificationSummary  
- 68 → alarmRootLinkFault  

**SCALM branch (2544.1.15.6.X) – neEventLogIdentityTranslation, alarmSeverity where applicable:**

- 11, 12, 13 → alarmThresCrossedFast/Medium/Slow  
- 14, 15 → alarmLinkBudgetExceeded / NearlyExceeded  
- 50 → alarmMonProcNotRunning  
- 102 → alarmAinsState  
- 103 → alarmRemoved  
- 104, 111 → alarmHwFailure  
- 107 → alarmDatabaseFailure  
- 110 → alarmHwDegrade  
- 112 → alarmLinkDown  
- 121 → transientSwResetReload  
- 122 → alarmTemperatureTooHigh  
- 123 → transientBootUpFailed  
- 124 → transientBootUpCompleted  
- 125 → transientBootUpStarted  
- 128 → alarmVoltageOutOfRange  
- 129 → alarmMultipleFanFailure  
- 130 → alarmCurrentTooHigh  
- 131 → alarmInputVoltageFailure  
- 303 → authenticationNotificationSummary  

### Gaps vs ServiceNow events

- **authenticationNotification** (62) and **authenticationNotificationSummary** (63) are only partially handled: Netcool implements **.14.6.63** and **.15.6.303**, but not **.14.6.62** (single auth notification). So trap 62 can fall through to “unknown” and be discarded if the probe sends 2544.1.14.6.62.
- **alarmFaRunning** (9), **objectChangedTrap** (19), **transientFaStarted** (41), **transientFaCompleted** (42), **transientFaSaved** (44), **alarmLinkBudgetExceeded** (14) are implemented for the branches and OID style used in the Netcool file (e.g. .14.6.X / .15.6.X). If ServiceNow receives the same traps under **.14.0.X** (standard trap OID), the Netcool logic still applies to the probe’s AlertKey format (which may use .6.X).
- ServiceNow’s “severity: Invalid value” suggests the trap varbinds (e.g. `alarmSeverity`) are not being mapped to a valid ServiceNow severity in event rules — alignment with Netcool’s severity and reason codes may help when defining or adjusting those rules.

---

## 3. Summary of OID and Value Mapping (from MIBs)

### MIB files

- **ADVA-FSP3000ALM-MIB.txt** – FSP3000 ALM (standalone monitor), Version V3.2.1 (2019), `::= { products 14 }`.
- **ADVA-FSP3000SCALM-MIB.txt** – FSP3000 SCALM (controller-based), Version V2.1.1 (2017), `::= { products 15 }`.

**Enterprise:** `advaMIB = 1.3.6.1.4.1.2544` (enterprises.2544).

### OID tree (relevant branches)

| Branch | OID (numeric) | Description |
|--------|----------------|-------------|
| advaMIB | 1.3.6.1.4.1.2544 | ADVA enterprise |
| products | 2544.1 | |
| fsp3000alm | 2544.1.14 | ALM product |
| fsp3000scalm | 2544.1.15 | SCALM product |
| ALM trap | 2544.1.14.0 | trap subtree (ALM) |
| SCALM almTrap | 2544.1.15.0 | almTrap subtree (SCALM) |

Trap OIDs in SNMP are typically **2544.1.14.0.X** (ALM) or **2544.1.15.0.X** (SCALM), where **X** is the trap number below.

### ALM trap definitions (ADVA-FSP3000ALM-MIB) – selected

| # | Name | Description (short) |
|---|------|--------------------|
| 1–6 | alarmTempCPU, alarmTempBoard1/2Low/2High, alarmTempLaserLow/High | Temperature thresholds |
| 7 | alarmMonNotRunning | Monitoring function enabled/disabled |
| 8 | alarmFpRunning | Fingerprint calculation in progress |
| 9 | alarmFaRunning | Fault analysis in progress |
| 10 | alarmFpMissing | Fingerprint not calculated for port |
| 11–13 | alarmThresCrossedFast/Medium/Slow | Loss deviation vs fast/medium/slow threshold |
| 14 | alarmLinkBudgetExceeded | Link loss vs budget threshold |
| 15 | alarmLinkBudgetNearlyExceeded | Link loss vs “close to budget” threshold |
| 16–17 | alarmManagementState, alarmDisabledState | portAdminState changes (mgt / dsbld) |
| 18 | stateChangedTrap | Entity state change (OperState/AdminState) |
| 19 | objectChangedTrap | Object change (e.g. severity, threshold) |
| 24–26 | transientFpStarted/Completed/Failed | Fingerprint lifecycle |
| 30–32 | transientDbMgmtActionStarted/Completed/Failed | Database management |
| 41–44 | transientFaStarted/Completed/Failed/Saved | Fault analysis lifecycle |
| 45 | transientInternalError | Critical error affecting monitoring |
| 46–50 | alarmRebootRunning, alarmWarmupRunning, alarmBadSysStat, alarmWrongFWVersion, alarmMonProcNotRunning | Reboot, warmup, system/process alarms |
| 62 | authenticationNotification | Single authentication event |
| 63 | authenticationNotificationSummary | Auth events (e.g. &gt;5 in 10 s) |

(Additional ALM traps 20–23, 27–29, 33–40, 51–61, 64–83 exist in the MIB; above list focuses on those seen in ServiceNow or Netcool.)

### SCALM trap definitions (ADVA-FSP3000SCALM-MIB) – selected

Same trap **names** as ALM for overlapping numbers; OBJECTS often use **neEventLogIdentityTranslation** and **neEventLogTimeStamp** instead of portAidString/portName. Examples:

- 1–19, 24–26, 30–32, 34, 37–44, 50–56: same semantic as ALM where defined.
- 100–131: creation/deletion, Ains, maintenance, removed, DB/hardware/link/temperature/boot/voltage/fan/current, etc.
- 302 → authenticationNotification  
- 303 → authenticationNotificationSummary  

### Alarm list type (integer enumeration)

Both MIBs define an alarm/trap list type with the same numeric identifiers for trap types (e.g. 9 = alarmFaRunning, 14 = alarmLinkBudgetExceeded, 41–44 = transientFa*, 62–63 = authentication*). These appear in tables and varbinds (e.g. **2544.1.14.1.4.1.2.X** in ServiceNow `additional_info`).

### Severity and state (from MIBs)

- **alarmSeverity** in traps is typed **TrapAlarmSeverity** (imported from **ADVA-MIB**; not in the provided MIB files). Typical conventions: integer severity (e.g. 2 = minor, 5/6 = clear/warning, etc.); exact values are defined in ADVA-MIB.
- **Fsp3000scalmAdminState:** is(2), mgt(4), dsbld(6).
- **Fsp3000scalmOperState:** undefined(0), nr(1), anr(2), out(3), un(4).

### Mapping table: trap number → name (for ALM .14.0.X and SCALM .15.0.X)

| OID suffix | ALM / SCALM name |
|------------|-------------------|
| 9 | alarmFaRunning |
| 14 | alarmLinkBudgetExceeded |
| 19 | objectChangedTrap |
| 41 | transientFaStarted |
| 42 | transientFaCompleted |
| 44 | transientFaSaved |
| 62 | authenticationNotification |
| 63 | authenticationNotificationSummary |

This matches the 8 trap types observed in the ServiceNow export and aligns with the trap numbers in the ALM MIB.

---

## 4. Message key: what uniquely identifies an event

**Purpose of the message key:** In ServiceNow (and similar event managers), the **message_key** is used to **uniquely identify an event** so that:

- **Deduplication:** The same trap received more than once (e.g. multiple listeners, retries) updates one event record instead of creating many.
- **Correlation:** Raise and clear for the same alarm can be tied to the same logical event.
- **Uniqueness:** Two different events (different device, trap type, or occurrence) get different keys.

In your export, **message_key is empty** for all events (`<message_key/>`), so every trap creates a new event and duplicates are not collapsed.

### What makes an event unique (from the trap payload)

From the MIB and the ServiceNow payload:

1. **Trap type** — `snmpTrapOID` (e.g. `.1.3.6.1.4.1.2544.1.14.0.62`). Identifies *what* happened (e.g. authenticationNotification, alarmFaRunning).
2. **Source entity (unit name)** — The device/unit that generated the event. In the trap it appears as the **value** of the varbind whose OID is **2544.1.14.4.2.1.4.X** (event log table, entity name). In `additional_info` the key is the long form `iso.org.dod.internet.private.enterprises.2544.1.14.4.2.1.4.XXX`; the **XXX** is the event log row index. The **value** is the entity name (e.g. `MCH-1-1`, `SHMON-1`).
3. **Event log index** — The **index X** in the event log OIDs (2544.1.14.4.2.1.2.X and 2544.1.14.4.2.1.4.X). The device uses this to identify a specific event record. Different occurrences have different indices (e.g. 188, 189, 190, 191, 192, 193, 194). Duplicate receptions of the *same* trap carry the **same** index and entity, so they can be deduplicated.

Analysis of your XML shows that duplicate receptions (e.g. events 1 & 2, 3 & 4, 5 & 7) share the same **entity + trap OID + event log index**, while distinct events have different indices or entities.

### Recommended message_key construction

Use a composite key built from trap varbinds (and optionally the trap source IP if available):

| Component | Source in payload | Example |
|-----------|-------------------|--------|
| **Entity name** | Value of `2544.1.14.4.2.1.4.X` (any X present) | `MCH-1-1`, `SHMON-1` |
| **Trap OID** | `snmpTrapOID` (full or normalized, e.g. last part) | `2544.1.14.0.62` or `62` |
| **Event log index** | The index **X** from the OID `2544.1.14.4.2.1.4.X` (extract from the varbind key) | `194`, `192`, `191` |

**Recommended formula:**

```text
message_key = {entityName}|{snmpTrapOID}|{eventLogIndex}
```

- **entityName** — value of the varbind 2544.1.14.4.2.1.4.* (e.g. MCH-1-1). If multiple, use the first or the one that matches the event (same index as the timestamp varbind).
- **snmpTrapOID** — full OID (e.g. `1.3.6.1.4.1.2544.1.14.0.62`) or a normalized form (e.g. `2544.1.14.0.62`) so that ALM vs SCALM and trap number are unambiguous.
- **eventLogIndex** — the numeric suffix from 2544.1.14.4.2.1.4.X (e.g. `194`).

**Examples:**

- `SHMON-1|2544.1.14.0.62|194` → one unique event (e.g. one auth notification on SHMON-1, log entry 194). Duplicate receptions get the same key.
- `MCH-1-1|2544.1.14.0.42|192` → one unique event (transientFaCompleted on MCH-1-1, log entry 192).
- `MCH-1-1|2544.1.14.0.9|191` vs `MCH-1-1|2544.1.14.0.9|189` → two different alarmFaRunning events (different log entries).

### Fallback when event log varbinds are missing

Some traps (e.g. **objectChangedTrap**) may not include the event log table varbinds (2544.1.14.4.2.1.4.X / 1.2.X). In that case:

- Use **event log timestamp** if present: value of `2544.1.14.4.2.1.2.X` (device timestamp).
- Or use **time_of_event** (ServiceNow ingestion time) as a last resort:  
  `message_key = {entityName}|{snmpTrapOID}|{eventLogTimestamp}` or `...|{time_of_event}`.

That way you still get a stable key for deduplication, with slightly less precision than the event log index.

### Optional: include resource (port/monitor point)

For **alarm** correlation (raise/clear), the same logical alarm is often identified by **entity + trap type + resource** (port/monitor point). The MIB uses **portAidString** / **portName** or **neEventLogIdentityTranslation**. If you want the message_key to represent “this alarm on this port” rather than “this trap occurrence,” you can extend the key with the resource when present:

```text
message_key = {entityName}|{snmpTrapOID}|{eventLogIndex}|{resource}
```

**resource** = value of portAidString, portName, or neEventLogIdentityTranslation (from varbinds 2544.1.14.2.2.1.4.1 / 2544.1.14.2.2.1.5.1 or equivalent). Omit or leave empty when the trap has no port/resource.

### Summary

- **Uniquely identify an event:** Use **entity name + snmpTrapOID + event log index** from the trap varbinds.
- **Deduplicate duplicate receptions:** Same key → update existing event instead of creating a new one.
- **Implement in event rules:** In ServiceNow (or the probe), compute this string from `additional_info` / varbinds and set **message_key** so that event management can deduplicate and correlate correctly.

---

## 5. Cross-reference: ServiceNow vs Netcool vs MIB

- **ServiceNow** receives traps with OID **.1.3.6.1.4.1.2544.1.14.0.X** (ALM trap number X). No event rule is applied; severity is invalid, state is Error.
- **Netcool** matches **.1.3.6.1.4.1.2544.1.14.6.X** and **.1.3.6.1.4.1.2544.1.15.6.X** and sets Severity, Reason code, and Summary; unknown OIDs are discarded (e.g. .14.6.62 not implemented).
- **MIBs** define trap **names** and **numbers** under **.14.0** (ALM) and **.15.0** (SCALM); the **.6** in Netcool likely corresponds to a different subtree (e.g. event log) used by the probe.

To improve ServiceNow handling:

1. Map **snmpTrapOID** (e.g. .14.0.62, .14.0.9, .14.0.14) to event type and severity using the same semantics as Netcool (and MIB names).
2. Define or extend event rules so that Enterprise 2544 traps get a valid **severity** (and optionally reason code / summary) from trap OID and varbinds (e.g. alarmSeverity, port/entity identifiers).
3. Optionally normalize **node** (e.g. strip `.nl.eu.abnamro.com`) and set a fixed **application** (e.g. FiberGuardian) for consistency with Netcool.

---

*Generated from: test_events_servicenow.xml, FiberGuardianSNMPRules-netcool.txt, ADVA-FSP3000ALM-MIB.txt, ADVA-FSP3000SCALM-MIB.txt.*