> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.kodelabs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# OnGuard

> Connect Lenel OnGuard to KODE OS for access control, alarm, and credential data

> Connect Lenel OnGuard to KODE OS for access control data integration

## Overview

Use this integration to connect your Lenel OnGuard (8.3+) system to KODE OS. You receive real-time access, credential, and alarm activity over SignalR (WebSocket) while REST covers historical polling and inventory-style data such as badges and alarm definitions.

| Property            | Value                      |
| ------------------- | -------------------------- |
| **System Type**     | Access Control             |
| **Communication**   | REST + SignalR (WebSocket) |
| **Collection**      | Hybrid (Pull + Push)       |
| **Collection Mode** | SNAPSHOT                   |

## Supported Capabilities

* Collect Non-Sensor Data (Access Events, Alarms, Credentials)
* Receive Real-Time Events via SignalR (WebSocket)
* Collect Historical Data via REST

## Prerequisites

* OnGuard 8.3 system with OpenAccess API enabled
* Valid username and password credentials for the OnGuard system
* A `LENEL_API_KEY` (Application ID) configured as an environment variable in the KODE OS API Integration Service -- this key is shared across all Lenel datasources
* Network connectivity from KODE OS to the OnGuard server (both REST and WebSocket endpoints)
* KODE OS environment with access to Data Sources

## Configure Connector in KODE OS

1. Navigate to **Data Sources** in your building
2. Click **API Catalog** and search for **OnGuard**
3. Click **+ Add Datasource**
4. Fill in the fields below and complete the three-page setup flow

| Field              | Required | Type     | Description                                   |
| ------------------ | -------- | -------- | --------------------------------------------- |
| **Connector Name** | Yes      | text     | Display name for this connector               |
| **URL**            | Yes      | text     | Base URL of the OnGuard OpenAccess API server |
| **Username**       | Yes      | text     | OnGuard login username                        |
| **Password**       | Yes      | password | OnGuard login password (encrypted)            |

## How Authentication Works

OnGuard uses a session-based authentication flow:

1. KODE OS sends credentials to `POST /api/access/onguard/openaccess/authentication` with the `Application-Id` header
2. OnGuard returns a `session_token` and API `version`
3. All subsequent requests include `Session-Token` and `Application-Id` headers

<Note>
  If authentication fails due to invalid credentials, expired password, or invalid application ID, the connector automatically deactivates to prevent account lockout. Check the connector status page if data stops flowing.
</Note>

## Data Collection Methods

OnGuard data is collected through two channels:

| Data Type                            | KODE Entity | Protocol                 | Frequency    |
| ------------------------------------ | ----------- | ------------------------ | ------------ |
| Hardware Events (door access)        | Access Log  | SignalR (real-time push) | Instant      |
| Software Events (credential changes) | Access Log  | SignalR (real-time push) | Instant      |
| Alarm Acknowledgments                | Event Log   | SignalR (real-time push) | Instant      |
| Badge/Credential Inventory           | Access Card | REST (poll)              | Daily backup |
| Alarm Definitions                    | Alarm       | REST (poll)              | Every hour   |

## What Data You Get

### Access Logs

Real-time access events from card readers, doors, and entry points, delivered via SignalR WebSocket.

| #  | Source Field            | KODE Field      | Notes                                         |
| -- | ----------------------- | --------------- | --------------------------------------------- |
| 1  | `serial_number`         | `id`            | Unique event identifier                       |
| 2  | `cardholder_key`        | `person_id`     | Cardholder reference                          |
| 3  | `event_type`            | `type`          | 0 = Access Granted, 1 = Access Denied         |
| 4  | `alarm_name`            | `description`   | Event description text                        |
| 5  | `timestamp`             | `created_at`    | Local timezone (building TZ per OnGuard cert) |
| 6  | `badge_id_str`          | `credential_id` | Badge/card identifier                         |
| 7  | `device_id`             | `point_id`      | Reader/device reference                       |
| 8  | `cardholder_first_name` | `person_name`   | Cardholder name                               |
| 9  | `event_subtype`         | custom field    | Retrieved from `Lnl_EventSubtype` lookup      |
| 10 | `event_source_name`     | custom field    | Source reader/panel name                      |
| 11 | `controller_id`         | custom field    | Controller panel ID                           |
| 12 | `controller_name`       | custom field    | Controller panel name                         |
| 13 | `segment_id`            | custom field    | Segment identifier                            |

### Alarms

Alarm definitions collected via REST polling, providing the alarm inventory for the site.

| # | Source Field          | KODE Field    | Notes                               |
| - | --------------------- | ------------- | ----------------------------------- |
| 1 | `ID`                  | `id`          | Alarm definition ID                 |
| 2 | `Priority`            | `priority`    | Numeric priority level              |
| 3 | `Description`         | `description` | Alarm description                   |
| 4 | `TextInstructionName` | `name`        | Instruction name                    |
| 5 | `TextInstructionData` | `alarm_cause` | Root cause instruction text         |
| 6 | `Active`              | `status`      | true = "Active", false = "Inactive" |

### Access Cards

Badge and credential inventory collected daily via REST as a backup to real-time SignalR software events.

| # | Source Field     | KODE Field         | Notes                                  |
| - | ---------------- | ------------------ | -------------------------------------- |
| 1 | `BADGEKEY`       | `id`               | Unique badge key                       |
| 2 | `ID_Str`         | `access_card_id`   | Display badge ID string                |
| 3 | `ACTIVATE`       | `active_date_time` | Activation date                        |
| 4 | `DEACTIVATE`     | `expiry_date_time` | Expiry/deactivation date               |
| 5 | `STATUS`         | `is_active`        | 1 = active, other = inactive           |
| 6 | `PERSONID`       | `user_id`          | Associated cardholder                  |
| 7 | `BadgeType.NAME` | `cardType`         | Badge type name (from `Lnl_BadgeType`) |
| 8 | `ID`             | `card_id`          | Numeric card ID                        |

### Event Logs

Alarm acknowledgment events collected via SignalR in real time.

| # | Source Field            | KODE Field    | Notes                         |
| - | ----------------------- | ------------- | ----------------------------- |
| 1 | (generated)             | `id`          | UUID generated per event      |
| 2 | `eventType`             | `name`        | Event type from lookup map    |
| 3 | `deviceId`              | `deviceId`    | Associated device             |
| 4 | (derived)               | `status`      | Acknowledgment status         |
| 5 | `acknowledgeNotes`      | `description` | Ack notes from operator       |
| 6 | `ALARM_ACKNOWLEDGEMENT` | `category`    | Fixed category                |
| 7 | `timestamp`             | `created_at`  | Event timestamp (building TZ) |

### Polling Schedule

* **Access Log** -- Real-time via SignalR; REST backup every 1 hour (min: 1 hour, max: 24 hours)
* **Access Card** -- Daily REST poll (badge inventory backup)
* **Alarm** -- REST poll every 1 hour (alarm definitions)
* **Event Log** -- Real-time via SignalR

For more details on collection modes, see the [Data Collection guide](/products/integrations/capabilities/data-collection).

## Use Cases

Once connected, this integration enables you to:

* Receive real-time door access events (granted/denied) across all entry points for live security monitoring
* Track credential lifecycle: activations, deactivations, and badge type classifications
* Centralize alarm management with priority levels, instruction text, and acknowledgment audit trails
* Correlate access patterns with occupancy and energy data for building optimization
* Generate compliance reports with detailed audit trails for every access event

## Troubleshooting

<AccordionGroup>
  <Accordion title="WebSocket/SignalR connection failed">
    Verify the URL and credentials are correct. Ensure the OnGuard OpenAccess API is enabled and the `LENEL_API_KEY` environment variable is set correctly. Check that network firewalls allow WebSocket connections from the KODE OS server to the OnGuard host.
  </Accordion>

  <Accordion title="Connector auto-deactivated">
    The connector automatically deactivates on authentication failures to prevent account lockout. Common causes: expired password, invalid Application ID, or locked account. Fix the credentials and re-enable the connector from the Data Sources page.
  </Accordion>

  <Accordion title="Data collection stops or gaps appear">
    Check the connector status on the Data Sources page. For SignalR data, verify the WebSocket connection is active. For REST data (badges, alarms), check that the OnGuard server is reachable and responding. Review error logs on the connector detail page.
  </Accordion>
</AccordionGroup>