> ## Documentation Index
> Fetch the complete documentation index at: https://learn.nexudus.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Avigilon Access Control
> Connect Nexudus with Avigilon's on-premises access control system to automate door access based on plans, passes, bookings, and desk assignments
# Avigilon Access Control Integration
## Overview
Avigilon is an enterprise-grade access control platform that provides physical security management through on-premises hardware and software. The Nexudus integration with Avigilon automates credential provisioning and role assignments based on customer contracts, passes, bookings, and desk assignments.
### Key Features
* **On-premises management**: Dedicated hardware appliance installed at your location
* **LDAP-based architecture**: Enterprise-grade directory services for identity management
* **Automatic provisioning**: Access is granted and revoked automatically based on plan changes, bookings, and pass assignments
* **RFID card support**: Multiple RFID cards per customer with PIN code support
* **Role-based permissions**: Map your inventory (passes, resources, desks) to Avigilon roles
* **Booking-based temporary access**: Automatic access during reservation windows
### Integration Type
**On-premises** — Avigilon requires a dedicated access control appliance installed at your location. The system is accessed via its local network IP address.
### Capabilities
| Feature | Supported | Notes |
| -------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------ |
| **Pass-based access** | ✅ Yes | Customers receive access based on their active passes |
| **Plan-based access** | ✅ Indirect | Plans grant access through the passes they include |
| **Resource-based access** | ✅ Yes | Grants temporary access during reservations |
| **Desk/unit-based access** | ✅ Yes | Includes support for team billing contracts |
| **Visitor access** | ❌ No | Not supported by this integration |
| **Booking guest access** | ❌ No | Customers added as booking guests cannot access spaces during booking windows. Only main booking holder can. |
| **Check-in tracking** | ❌ No | Door events are not processed for automatic check-ins |
| **Mobile app access** | ❌ No | No mobile app integration available |
| **Remote door unlock** | ❌ No | Physical cards/PIN codes required for access |
## How It Works
### Access Control Model
Avigilon uses a **role-based** model to manage access permissions:
* **Identities** represent individuals in the system (mapped to Nexudus customers)
* **Roles** define collections of doors that identities can access
* **Tokens** are physical RFID cards assigned to identities
* **Doors** are individual access points managed by door controllers
When a customer's access needs change in Nexudus (e.g., they purchase a pass, book a resource, or their contract renews), the integration automatically updates their identity record in Avigilon with the appropriate role memberships.
### Multi-Door Support
Avigilon uses **roles** to grant permissions to multiple doors. Instead of mapping each door individually:
1. In Avigilon, create a role (e.g., "Coworking Space Access")
2. Add the relevant doors to that role in Avigilon
3. In Nexudus, select that role from the dropdown when mapping your pass/resource/desk
4. Customers with that pass automatically get access to all doors in the role
You must configure which doors belong to each role in the Avigilon system. Nexudus assigns customers to roles by selecting from the available roles retrieved from your Avigilon system. The door-to-role mapping is managed in Avigilon.
## Prerequisites
Before connecting Nexudus to Avigilon, ensure you have:
1. **Avigilon access control system** installed and operational at your location
2. **Network access** to the Avigilon appliance from Nexudus servers (see connectivity options below)
3. **API credentials** with administrative permissions
4. **IP address** of the Avigilon appliance
5. **Avigilon system configured** with door controllers installed and online
6. **Roles created** in Avigilon for different access levels (e.g., 24/7 access, business hours only)
7. **Nexudus location configured** with plans, passes, and resources
### Network Connectivity Options
Since Avigilon is an on-premises system, you have two options for network connectivity:
**Option 1: Direct Connection (Firewall Configuration)**
* Configure your firewall to allow incoming HTTPS connections from Nexudus IP addresses
* Set up a static IP or internal DNS for your Avigilon appliance
* Ensure valid SSL certificates (self-signed certificates are accepted but not recommended for production)
**Option 2: Nexudus Network Bridge (Recommended for restricted networks)**
If you cannot open firewall ports to allow Nexudus servers to reach your local network, use the **Nexudus Network Bridge**:
* A lightweight application runs on your local network
* Creates an outbound connection to Nexudus (no inbound ports required)
* Securely proxies API requests between Nexudus and your Avigilon appliance
* See [Network Bridge documentation](/integrations/network-bridge) for setup instructions
The Network Bridge is the recommended approach for organizations with strict firewall policies or those who prefer not to expose on-premises systems directly to the internet.
## Configuration
### Step 1: Enable and Connect to Avigilon
1. In the Nexudus dashboard, go to **Settings > Integrations**
2. Find **Avigilon** in the list and expand the settings
3. Enable the **Enable Avigilon integration** toggle
4. Enter your connection details (fields appear when toggle is enabled):
* **IP Address**: The IP address or hostname of your Avigilon appliance
* Direct connection: `192.168.1.100` or `avigilon.yourcompany.local`
* Network Bridge: Use the bridge hostname (see [Network Bridge setup](/integrations/network-bridge))
* **Username**: Your Avigilon administrator username
* **Password**: Your Avigilon administrator password
5. Click **Save** to establish the connection
6. Once connected successfully, the configuration panels for passes, resources, and desks will load below
If using the Network Bridge, ensure the bridge application is running and connected before saving your Avigilon settings in Nexudus.
### Step 2: Map Passes to Roles
Passes are the primary way customers receive access in Nexudus. Each pass can be mapped to an Avigilon role.
1. In the **Passes** section, you'll see all passes configured for this location
2. For each pass, select an **Avigilon access group** from the dropdown menu
* The dropdown shows all roles available in your connected Avigilon system
* Roles are automatically retrieved when you save the connection settings
3. Leave blank if a pass should not grant physical access
**How it works:**
* When a customer has an active contract on a plan that includes passes, they automatically receive those passes
* If the pass is mapped to an Avigilon role, the customer is added to that role
* When the pass expires or is consumed, access is revoked
* Time-limited passes (e.g., day passes with validity windows) automatically grant and revoke access at the appropriate times
**Example mapping:**
| Pass Name | Avigilon Role | Purpose |
| ------------------- | ------------- | ---------------------------------- |
| 24/7 Access Pass | 247Members | Round-the-clock building access |
| Business Hours Pass | BusinessHours | Access only during operating hours |
| Meeting Room Pass | MeetingRooms | Access to meeting room zones |
Roles are automatically retrieved from your Avigilon system. If you don't see a role in the dropdown, verify it exists in Avigilon and re-save your connection settings to refresh the list.
Plans are **not** directly mapped to roles. Instead:
1. Plans include passes via the plan configuration
2. Passes are what get mapped to roles (selected from dropdown)
3. When a customer starts a contract on a plan, they receive the passes included in that plan
4. Those passes then grant the associated Avigilon access
### Step 3: Map Resources to Roles
Resources (meeting rooms, event spaces, etc.) can require specific access permissions for bookings.
1. In the **Resources** section, you'll see all resources configured for this location
2. For each resource, select an **Avigilon access group** from the dropdown menu
3. Leave blank if resource bookings should not grant physical access
**How it works:**
* When a customer books a resource, Nexudus grants them access 15 minutes before the booking starts
* Access is automatically revoked when the booking ends
* If the booking is cancelled, access is removed immediately
**Example mapping:**
| Resource Name | Avigilon Role | Purpose |
| ----------------- | -------------- | ---------------------------------- |
| Conference Room A | ConfRoomA | Access to specific meeting room |
| Event Space | EventHall | Access to event space for bookings |
| Private Office | PrivateOffices | Access to private office area |
Resource-based access is temporary and booking-specific. A customer only receives access during their booking window, even if they don't hold a general access pass.
### Step 4: Map Desks/Units to Roles
Floor plan desks and units can grant access to specific areas when included in a customer's contract.
1. In the **Desks/Units** section, you'll see all desks from your floor plans
2. For each desk, select an **Avigilon access group** from the dropdown menu
3. Leave blank if desk assignments should not grant physical access
**How it works:**
* When a desk is added to a customer's contract, they receive access to the mapped role
* Access is granted when the contract starts and revoked when it ends
* **Team billing support**: If a customer uses team billing (merged billing), they also receive access to desks included in the paying member's contracts
**Example mapping:**
| Desk/Unit Name | Avigilon Role | Purpose |
| --------------------- | ------------- | ----------------------------------------- |
| Private Office #101 | PrivateFloor1 | Access to first-floor private office area |
| Dedicated Desk Zone A | DeskZoneA | Access to dedicated desk zone A |
| Studio #5 | StudioAccess | Access to individual studio unit |
Desk access is based on **contract assignments**, not direct desk bookings. Customers must have the desk included in an active contract to receive access. Ad-hoc desk bookings (if using desk booking) do not automatically grant Avigilon access.
### Step 5: Save Configuration
1. Review all mappings to ensure they're correct
2. Verify role names match exactly with your Avigilon system (case-sensitive)
3. Click **Save** to apply the configuration
4. Nexudus will immediately start provisioning access for customers based on the new mappings
## How Access is Managed
### When Access is Granted
Nexudus automatically grants Avigilon access when:
1. **Contract starts**: Customer begins a contract on a plan → receives passes included in that plan → assigned to corresponding Avigilon roles
2. **Pass activated**: Customer receives a pass directly (not via a contract) → assigned to the mapped Avigilon role
3. **Booking created**: Customer books a resource → granted access to resource's role 15 minutes before booking start time
4. **Desk added to contract**: Desk is added to an active contract → customer receives access to the desk's mapped role
5. **Booking guest added**: Non-customer is added as a guest on a booking → granted access to resource's role for the booking duration
### When Access is Revoked
Nexudus automatically revokes Avigilon access when:
1. **Contract ends or cancelled**: Customer loses passes from that contract → removed from corresponding Avigilon roles
2. **Pass expires**: Pass validity ends or usage is consumed → removed from mapped Avigilon role
3. **Booking ends or cancelled**: Booking time expires or is cancelled → access to resource's role is removed
4. **Desk removed from contract**: Desk is removed from contract → access to desk's role is revoked
5. **Customer deactivated**: Customer account is deactivated → all Avigilon access removed
### Access Update Timing
* **Immediate updates**: Contract changes, pass assignments, and customer deactivations trigger access updates within seconds
* **Booking lead time**: Booking access is granted 15 minutes before the booking start time
* **Background processing**: Access updates are queued in background jobs to handle high volumes efficiently
* **Distributed locking**: Prevents concurrent updates to the same customer across multiple servers
If a customer should have access but doesn't, the system automatically retries access provisioning. Check the Business Checkup page for any integration errors.
## RFID Card Management
Avigilon supports traditional RFID access cards with optional PIN code support. To assign cards to customers:
1. Go to **Operations > Customers**
2. Select the customer
3. In their profile, enter card IDs in the **Access Card ID** field
4. Separate multiple cards with commas: `123456,789012,345678`
5. Optionally, set a PIN code in the **Access PIN Code** field
6. Save the customer profile
**Card behavior:**
* **No card**: Identity exists in Avigilon but cannot unlock doors (no physical credentials)
* **Card assigned**: Customer can use physical RFID card to unlock doors
* **PIN code set**: Customer can use card + PIN for enhanced security
* **Card removed**: Physical access is revoked (identity remains in system)
**Card numbering:**
* Cards use both **internal number** and **embossed number** fields (Nexudus sets both to the same value)
* Card IDs should match the format expected by your Avigilon system
* Cards are assigned validity dates: Active from 2000-01-01 to 2500-01-01 (effectively permanent)
Unlike cloud-based systems, Avigilon does **not** support mobile access. Customers must use physical RFID cards or PIN codes to unlock doors.
## Troubleshooting
**Possible causes:**
1. **Pass not mapped**: The passes included in the customer's plan are not mapped to any Avigilon roles
* **Solution**: Go to Settings > Integrations > Avigilon and select a role for the relevant passes
2. **Role no longer exists**: The selected role was deleted from Avigilon
* **Solution**: Select a different role or recreate the role in Avigilon, then refresh the integration
3. **Pass expired or inactive**: The customer's pass has expired or hasn't started yet
* **Solution**: Check the customer's passes under their profile to verify validity windows
4. **Identity not created**: The customer wasn't created in Avigilon
* **Solution**: Check the Business Checkup page for integration errors, or manually trigger an update by editing and saving the customer's profile
5. **Role permissions**: The Avigilon role exists but isn't assigned to any doors
* **Solution**: In Avigilon, verify the role includes the correct door controllers
6. **No card assigned**: Customer exists in Avigilon but has no physical credentials
* **Solution**: Assign an RFID card in the customer's Access Card ID field
7. **Network connectivity**: Nexudus cannot reach your Avigilon appliance
* **Solution**: Check firewall rules and verify the IP address is correct
**Possible causes:**
1. **Resource not mapped**: The booked resource is not mapped to an Avigilon role
* **Solution**: Select a role for the resource in Settings > Integrations > Avigilon
2. **Booking too far in future**: Access is only granted 15 minutes before booking start time
* **Solution**: Wait until booking is within 15 minutes of start time
3. **Booking not confirmed**: Some resources require booking confirmation
* **Solution**: Confirm the booking if it's in pending state
4. **No card assigned**: Customer has no physical card to use
* **Solution**: Assign an RFID card to the customer's profile
**Possible causes:**
1. **Card format**: Card IDs don't match the format expected by your Avigilon system
* **Solution**: Check your Avigilon system documentation for the correct card ID format
2. **Card not synced**: Recent card changes haven't been synced to Avigilon
* **Solution**: Wait a few minutes for sync, or manually trigger by editing and saving the customer profile
3. **Identity inactive**: Customer's identity is marked as inactive in Avigilon
* **Solution**: Verify customer has active passes/contracts that grant access
4. **Card reader issue**: Physical hardware problem
* **Solution**: Test cards on different readers to isolate hardware issues
**Possible causes:**
1. **Incorrect IP address**: The Avigilon appliance IP has changed or is incorrect
* **Solution**: Verify the correct IP address and update in Settings > Integrations > Avigilon
2. **Network connectivity**: Firewall blocking HTTPS connections
* **Solution**: Configure firewall to allow HTTPS from Nexudus servers to your Avigilon appliance, or use the [Network Bridge](/integrations/network-bridge) instead
3. **Network Bridge not running**: If using the bridge, it may not be running or connected
* **Solution**: Verify the Network Bridge application is running and connected (check bridge status dashboard)
4. **Invalid credentials**: Username or password is incorrect
* **Solution**: Verify credentials have administrative access in Avigilon
5. **SSL certificate issues**: Certificate validation failing
* **Solution**: Ensure Avigilon has a valid SSL certificate, or contact support if using self-signed certificates
6. **Appliance offline**: Avigilon system is powered off or unreachable
* **Solution**: Verify Avigilon appliance is online and accessible on your network
**Possible causes:**
1. **Role deleted**: Role was selected but has since been deleted from Avigilon
* **Solution**: Recreate the role in Avigilon or select a different role in Nexudus
2. **Stale role list**: Available roles not refreshed after changes in Avigilon
* **Solution**: Re-save your connection settings to refresh the role list from Avigilon
3. **API permissions**: Avigilon user doesn't have permission to modify roles
* **Solution**: Ensure the API user has administrative permissions in Avigilon
4. **Background job delay**: Updates are queued but not yet processed
* **Solution**: Wait a few minutes for background jobs to process
## Monitoring Integration Errors
Nexudus monitors your access control integration and alerts you to any issues that need attention.
### Business Checkup Dashboard
Access control integration errors are displayed on the **Business Checkup** page:
1. Go to **Home > Important Items** in the dashboard, or
2. Navigate directly to [dashboard.nexudus.com/dashboards/checkup](https://dashboard.nexudus.com/dashboards/checkup)
3. Look for the **Access Control Integration** tile
4. If there are errors, the tile will be displayed in red
### What Gets Flagged
* **Authentication failures**: Invalid credentials or connection errors
* **Provisioning errors**: Failed attempts to create or update customer access
* **Configuration issues**: Missing or invalid role mappings
* **Network connectivity**: Connection timeouts or unreachable appliance
Each error includes:
* The customer affected
* The nature of the problem
* When the error occurred
* Suggested actions to resolve it
Nexudus automatically retries failed operations. If errors persist, check the Business Checkup page for detailed information and follow the suggested resolution steps.
## Security Considerations
### Data Shared with Avigilon
When provisioning access, Nexudus shares the following information with Avigilon:
* **Customer data**: First name, last name
* **External ID**: Nexudus customer ID (used to link records between systems)
* **RFID cards**: Card IDs from the Access Card ID field
* **PIN codes**: Optional PIN codes from the Access PIN Code field
Nexudus **does not** share:
* Email addresses
* Phone numbers
* Billing information
* Payment details
* Contract specifics (only role assignments)
* Personal notes or custom fields
### Network Security
* **HTTPS encryption**: All communication uses HTTPS (SSL/TLS)
* **Basic authentication**: Username and password sent with each request (over HTTPS)
* **On-premises control**: Your Avigilon system remains on your local network
* **Firewall protection**: Configure firewall rules to restrict access to authorized IP addresses only
Because Avigilon is an on-premises system, you must configure your firewall to allow incoming HTTPS connections from Nexudus servers. Ensure you restrict access to Nexudus IP addresses only to maintain security.
### Credential Management
* **Physical cards**: Managed in both Nexudus and Avigilon; always assign through Nexudus
* \*Network Bridge Setup]\(/integrations/network-bridge) - For on-premises connectivity without opening firewall ports
* \[*PIN codes*\*: Stored in Nexudus and synced to Avigilon
* **User passwords**: Never shared with Nexudus; authentication is handled by Avigilon
## Related Documentation
* [Access Control Overview](/platform/access-control/overview)
* [Passes Configuration](/platform/billing/time-passes)
* [Plans & Contracts](/platform/billing/plans)
* [Resource Bookings](/platform/operations/bookings)
* [Check-ins](/platform/operations/check-ins)
## Best Practices
### Role Organization
Create roles in Avigilon based on access levels, not products or plans:
* ✅ **Good**: "247Access", "BusinessHours", "MeetingRooms", "PrivateOffices"
* ❌ **Avoid**: "HotDeskPlan", "DedicatedDeskPlan" (these are billing products, not access types)
This approach lets you grant the same physical access through multiple plans.
### Naming Conventions
* Create descriptive role names in Avigilon that make them easy to identify in the dropdown
* Avoid overly long role names that are difficult to read in the admin panel
* Document role-to-door mappings in Avigilon for future reference
### Card Management
* Assign unique card IDs to each customer
* Keep spare cards for emergencies
* Use PIN codes for enhanced security on sensitive areas
* Regularly audit card assignments and deactivate unused cards
**Direct Connection:**
* Place Avigilon appliance on a secure network segment
* Use firewall rules to restrict access to Nexudus IP addresses only
* Maintain separate admin credentials for Nexudus integration vs. manual administration
**Network Bridge (Recommended):**
* Install Network Bridge on a server within your local network
* No inbound firewall ports required (bridge initiates outbound connection)
* Bridge encrypts all communication between Nexudus and your Avigilon appliance
* See [Network Bridge documentation](/integrations/network-bridge) for security details
* Use firewall rules to restrict access to Nexudus IP addresses only
* Consider VPN for additional security if Avigilon is on internal network
* Maintain separate admin credentials for Nexudus integration vs. manual administration
## Technical Details
### API Architecture
* **Protocol**: HTTPS with XML-based API
* **Authentication**: HTTP Basic Authentication (username/password)
* **API Format**: XML (using ServiceStack XmlServiceClient)
* **Base URL**: `https://{ip_address}/`
* **Certificate validation**: Accepts self-signed certificates (ServerCertificateValidationCallback returns true)
### LDAP Structure
Avigilon uses LDAP (Lightweight Directory Access Protocol) for identity management:
* **Distinguished Names (DN)**: Format `cn={id},ou=identities,dc=plasec`
* **Roles**: Format `cn={id},ou=roles,dc=plasec`
* **External IDs**: Custom LDAP attribute `plasecId` stores Nexudus customer ID
### Key Endpoints
* **Identities (Users)**:
* GET `/identities.xml?adv_search_exec_search=true&adv_search_field_0=plasecId&adv_search_val_0={id}&adv_search_and_or=%26&adv_search_cnt=0` - Find identity by external ID
* POST `/identities.xml` - Create new identity
* PUT `/identities/{id}.xml` - Update identity
* PUT `/identities/{id}/update_roles.xml` - Update role assignments
* **Roles (Access Groups)**:
* GET `/roles.xml` - List all roles
* POST `/roles.xml` - Create new role
* **Doors**:
* GET `/doors.xml` - List all doors
* **Tokens (Cards)**:
* GET `/identities/{id}/tokens.xml` - List tokens for identity
* POST `/identities/{id}/tokens.xml` - Create new token
* DELETE `/identities/{id}/tokens/{tokenId}.xml` - Delete token
### Identity Model
```xml theme={null}
12345
cn=user123,ou=identities,dc=plasec
John Doe
John
Doe
1
```
**Status values:**
* `1`: Active - identity can access doors
* `2`: Inactive - identity exists but cannot access doors
### Token (Card) Model
```xml theme={null}
cn=token123,ou=tokens,dc=plasec
123456
123456
1234
1
TRUE
20000101000000+0100
25000101000000+0100
```
**Token properties:**
* **InternalNumber**: Primary card identifier
* **EmbossedNumber**: Printed number on card (Nexudus sets same as internal)
* **PIN**: Optional PIN code
* **Status**: `1` = active, `2` = inactive
* **Download**: `TRUE` enables card for use
* **Dates**: Format `YYYYMMDDhhmmss+timezone` (default: 2000-2500 for permanent cards)
### Role Assignment Model
```xml theme={null}
cn=Role1,ou=roles,dc=plasec
cn=Role2,ou=roles,dc=plasec
```
### Business Settings Reference
| Setting | Purpose |
| ---------------------------------------- | ------------------------------------------------------------------------------------ |
| `Avigilon.Enabled` | Integration enabled flag ("true"/"false") |
| `Avigilon.IpAddress` | IP address or hostname of Avigilon appliance |
| `Avigilon.Username` | Administrator username for API authentication |
| `Avigilon.Password` | Administrator password for API authentication |
| `Avigilon.Controller.Id_{doorId}.Action` | Check-in action per door (Nothing/CheckIn/CheckOut/Toggle) - currently not processed |
### Access Update Logic
1. **Passes**: Active passes from contracts + shared passes from paying member
2. **Check-ins**: Passes from open check-ins (maintains access during session)
3. **Bookings**: Resources with bookings starting within 15 minutes
4. **Booking guests**: Resources from bookings where customer is a visitor
5. **Desks**: Desks from active contracts (own + team billing)
6. **Roles**: Aggregated list of unique role names
7. **Identity provisioning**: Create/update identity with aggregated roles
8. **Card management**: Create/update/delete tokens based on AccessCardID field
9. **Status**: Active (status=1) if customer has any roles, Inactive (status=2) if no roles
### External IDs
* **Customers**: `plasecId` set to Nexudus coworker ID (integer as string)
* **Lookup**: Identities retrieved via advanced search on `plasecId` field
* **Uniqueness**: ExternalSystemId ensures no duplicate identities
### Error Handling
* **Nil-classes error**: Returned when no results found, handled as empty list
* **Authentication failures**: Logged to business log entries
* **Provisioning errors**: Automatic retry with distributed locking
* **Business Checkup**: Integration errors displayed on dashboard
* **Event system**: OnExceptionHandler raises AccessControlEventData for error tracking
### Card Management Logic
* **Multiple cards**: Comma-separated list in AccessCardID field
* **Card sync**: Existing tokens compared with current AccessCardID, unused tokens deleted
* **No cards**: If AccessCardID is empty, all tokens are removed
* **Token creation**: Each card gets separate token with same internal/embossed number
* **PIN code**: Synced from AccessPincode field to token.Pin
### Performance Optimization
* **Debouncing**: 5-second debounce prevents rapid repeated updates for same customer
**Direct Connection:**
* **Firewall rules**: Allow HTTPS (443) from Nexudus servers to Avigilon appliance
* **SSL/TLS**: HTTPS required (self-signed certificates accepted)
* **IP addressing**: Static IP or DNS hostname recommended
* **Latency**: Low latency recommended for responsive access updates
**Network Bridge:**
* **Outbound connection**: Bridge initiates HTTPS connection to Nexudus (no inbound ports)
* **Local network access**: Bridge requires access to Avigilon appliance on local network
* **Bridge requirements**: See [Network Bridge documentation](/integrations/network-bridge) for full requirement
### Network Requirements
* **Firewall rules**: Allow HTTPS (443) from Nexudus servers to Avigilon appliance
* **SSL/TLS**: HTTPS required (self-signed certificates accepted)
* **IP addressing**: Static IP or DNS hostname recommended
* **Latency**: Low latency recommended for responsive access updates