Primer TMF642 Example

TMF642 – Alarm Management API

Intermediate Level 12 min read Real Telecom Examples BSS Bridge Included

Learning Objective: Understand TMF642 – the TM Forum Open API for alarm and fault management. Learn the key fields, severity handling, state transitions, and how it is used in OSS-BSS integration.

What is TMF642?

TMF642 is the TM Forum Open API specification for Alarm Management. It defines a standard REST API for exposing and managing alarms in OSS systems. It is used for:

Exposing normalized alarms from NMS/EMS
Querying active and historical alarms
Correlating alarms across domains
Integrating with BSS for customer impact analysis
Exposing alarm data to NOC dashboards and ticketing systems
Maintaining alarm history for analytics, audit, SLA, and compliance purposes

TMF642 Is a Northbound API

TMF642 is typically used between OSS applications, BSS systems, customer portals, and assurance platforms. Network devices themselves usually communicate via southbound protocols like SNMP, Netconf, gNMI, or streaming telemetry.

Event vs Alarm Reminder

TMF642 focuses on actionable alarms, not all network events. Many raw telemetry events never become alarms unless they require operational attention. Normalization transforms vendor-specific alarms into standardized TMF642 structures before cross-domain consumption.

Key TMF642 Alarm Fields

Field	Type	Description	Example
id	String	Unique alarm identifier	"alm-67890"
alarmRaisedTime	DateTime	Time when alarm was raised (UTC)	"2025-05-09T10:23:00Z"
alarmChangedTime	DateTime	Last update time	"2025-05-09T10:25:00Z"
alarmClearedTime	DateTime	Time when alarm was cleared	"2025-05-09T11:00:00Z"
severity (v4+)	String	Critical, major, minor, warning, indeterminate, cleared	"major"
perceivedSeverity (legacy)	String	Legacy severity field (capitalized)	"Major"
alarmType	String	Category of alarm	"CommunicationsAlarm"
probableCause	String	Standardized probable root cause category	"loss-of-signal"
specificProblem	String	Detailed problem description	"Radio Link Failure"
affectedResource	ResourceRef	Resource that caused the alarm	{"id":"res-1001","name":"Mumbai_05"}
state	String	raised, updated, cleared	"raised"
ackedBy	String	User who acknowledged the alarm	"noc_user_01"

Severity Handling – Important Note

Modern TMF642 implementations (v4+) use lowercase severity values: critical, major, minor, warning, indeterminate, cleared. Many deployed OSS systems still use legacy perceivedSeverity with capitalized values. Real-world integrations often support both formats for backward compatibility.

Complete TMF642 Alarm Object Example

// TMF642 v4+ compliant alarm object

{
  "id": "alm-67890",
  "alarmRaisedTime": "2025-05-09T10:23:00Z",
  "alarmChangedTime": "2025-05-09T10:25:00Z",
  "severity": "major",
  "alarmType": "CommunicationsAlarm",
  "probableCause": "loss-of-signal",
  "specificProblem": "Radio Link Failure",
  "affectedResource": {
    "id": "res-1001",
    "href": "/resource/res-1001",
    "name": "Mumbai_05",
    "@referredType": "LogicalResource"
  },
  "state": "raised",
  "ackedBy": null,
  "alarmDetails": {
    "vendorNokia": {
      "rlfCause": "outOfSync"
    }
  }
}

Legacy OSS Format (Still Common)

Many deployed OSS platforms still expose the legacy perceivedSeverity field with capitalized values:

{
  "id": "alm-67890",
  "alarmRaisedTime": "2025-05-09T10:23:00Z",
  "perceivedSeverity": "Major",
  "alarmType": "CommunicationsAlarm",
  "affectedResource": {
    "id": "res-1001",
    "name": "Mumbai_05"
  },
  "state": "raised"
}

Real-World Example: From SNMP Trap to TMF642

A Cisco router reports an interface down via SNMP trap:

// Raw SNMP Trap

%LINK-3-UPDOWN: Interface GigabitEthernet0/1, changed state to down

// NMS Correlation & Enrichment

Router: RTR-MUM-01
Interface: Gig0/1
Site: Mumbai
Customer: Enterprise VPN Customer

// Normalization → TMF642 Alarm (OSS Output)

{
  "id": "alm-001",
  "alarmRaisedTime": "2025-05-09T14:30:00Z",
  "severity": "critical",
  "alarmType": "CommunicationsAlarm",
  "specificProblem": "Interface down",
  "affectedResource": {
    "id": "res-1001",
    "name": "RTR-MUM-01-Gig0/1",
    "href": "/resource/rtr-mum-01/port/gig0/1"
  },
  "impactedServices": ["VPN-CUST-001", "VPN-CUST-002"]
}

TMF642 Alarm State Management

Alarm Lifecycle States

Raised Updated Cleared

Alarm lifecycle commonly includes raised, updated, and cleared states. Acknowledgement is often tracked as operator metadata rather than a separate lifecycle state.

TMF642 API Operations

HTTP Method	Endpoint	Description
GET	/alarm	Retrieve all alarms (filterable)
GET	/alarm/{id}	Retrieve a specific alarm by ID
POST	/alarm	Ingest or expose alarm generated by EMS/NMS
PATCH	/alarm/{id}	Update alarm (acknowledge, update severity, clear)
DELETE	/alarm/{id}	DELETE is uncommon in telecom OSS. Most systems retain alarms for audit, SLA, compliance, and analytics purposes.

Alarm Correlation Using TMF642

TMF642 supports correlation via the correlatedAlarms field (array of alarm IDs). This allows OSS to group related alarms under a single root cause, reducing noise in NOC dashboards.

{
  "id": "alm-root",
  "correlatedAlarms": ["alm-001", "alm-002", "alm-003"],
  "specificProblem": "Fibre cut affecting multiple interfaces"
}

Connection to BSS

Customer impact analysis: OSS enriches TMF642 alarms with impacted customers before sending to BSS
SLA notifications: Critical alarms trigger automatic customer notifications via BSS CRM
SLA credits: Alarm duration and severity feed SLA breach calculation in BSS
Customer portal: Northbound TMF642 API exposes service-impacting alarms to customer dashboards

Common Interview Questions

Q1. What is TMF642 used for?

TMF642 is the TM Forum Open API for Alarm Management. It defines standard REST APIs for exposing and managing alarms in OSS systems.

Q2. What is the difference between severity and perceivedSeverity in TMF642?

severity (v4+) uses lowercase values (critical, major, minor). perceivedSeverity is a legacy field with capitalized values (Critical, Major, Minor). Many OSS systems support both for backward compatibility.

Q3. How does TMF642 support alarm correlation?

Via the correlatedAlarms field – an array of alarm IDs linked to a root cause alarm. This reduces alarm noise in NOC dashboards.

Q4. What are the key fields in a TMF642 alarm object?

id, alarmRaisedTime, severity, alarmType, specificProblem, affectedResource, state.

Q5. How does TMF642 integrate with BSS?

Alarms are enriched with impacted customer information, then used for customer notifications, SLA tracking, and automatic credit generation.

Key Terms

TMF642 Alarm Management Severity PerceivedSeverity CommunicationsAlarm EquipmentAlarm ProcessingErrorAlarm EnvironmentalAlarm QualityOfServiceAlarm AffectedResource CorrelatedAlarms Alarm State (Raised, Updated, Cleared) Normalization

Takeaways for You

TMF642 is the standard REST API for alarm management in OSS systems – a northbound API used between OSS, BSS, and customer portals.
Key fields: id, alarmRaisedTime, severity, alarmType, specificProblem, affectedResource, state.
Severity handling: modern (v4+) uses lowercase; legacy uses perceivedSeverity with capitals. Both coexist in real deployments.
Alarm correlation uses the correlatedAlarms field to reduce alarm noise.
Alarm states: Raised → Updated → Cleared. Acknowledgement is operator metadata, not a lifecycle state.
REST operations: GET (list/retrieve), POST (ingest/expose), PATCH (update), DELETE (rare – alarms retained for audit/compliance).
Normalization transforms vendor-specific alarms into standardized TMF642 structures.
BSS integration: Enriched alarms drive customer notifications, SLA tracking, and automatic credits.
TMF642 focuses on actionable alarms, not raw network events.

Recommended Next Learning Path

📖 Glossary 🔧 TMF Field Mapper Tool

📚 Jump to another topic:

Previous: End-to-End Flow

Next: Glossary