Overview

Maptician integrates with the LenelS2 NetBox access control system to automatically update user presence based on badge swipe activity. When a user badges into an office location, Maptician detects the event and sets that user's presence status to the corresponding location - no manual input required. 

This article covers how the integration works, what data is synced and how it is handled, and what your network team must configure to allow Maptician to reach your NetBox API endpoint. 

How the Integration Works

Maptician connects to the NetBox web-based API to retrieve badge access activity and user records. This data is used to populate the Presence feature in Maptician, giving authorized users a current view of who is in the office and where. 

Maptician runs two parallel synchronization processes against the NetBox API: 

• User sync: Maps users between the S2 system and Maptician so that badge swipes can be attributed to the correct occupant.
• Badge access history sync: Retrieves badge swipe events and converts them into Presence entries in Maptician.

Sync Behavior

Maptician pulls badge access history from the NetBox server every 5 minutes. Each sync retrieves the previous 30 minutes of badge access data. 

User Mapping

Before badge swipe data can be attributed to an occupant in Maptician, the system must establish a mapping between the user in S2 and the corresponding occupant in Maptician. The mapping process works as follows: 

• Maptician first attempts to match users by email address, which is the most reliable identifier.
• If email is unavailable or insufficient, Maptician falls back to first name, last name, and any relevant custom fields, depending on your configuration settings.
• Once a match is confirmed, the user's unique PERSONID from the S2 system is recorded in the corresponding occupant record in Maptician. This ID is used to accurately attribute all future badge swipe events.

Data Handling

When Maptician converts a badge swipe into a Presence entry, it extracts three pieces of information: 

• Occupant identifier: Links the badge swipe to the correct individual.
• Time of entry: Records when the badge swipe occurred.
• Location: Since a NetBox instance is typically associated with a single office location, Maptician automatically assigns all badge swipes from that instance to the configured location.

Required Network Access

Maptician initiates all connections outbound to your NetBox API endpoint. From your network's perspective, this requires allowing inbound TCP traffic from the Maptician source IP to the NetBox API endpoint. The table below lists the values your network team will need. 

API Endpoint Access

The NetBox API endpoint must be reachable from Maptician at the URL provided during implementation. The endpoint may be served directly by NetBox or through a client-managed network layer such as a reverse proxy, firewall, VPN, or load balancer. 

Example endpoint formats:

• https://<netbox-host-or-ip>/nbws/goforms/nbapi
• http://<netbox-host-or-ip>/nbws/goforms/nbapi

Firewall Allowlisting

The Maptician source IP must be allowlisted on any firewall, VPN, reverse proxy, load balancer, or other network security appliance positioned in front of NetBox. Use the rule below as a reference for your allowlist configuration. 

Communication Behavior

For each sync run, Maptician follows this sequence to communicate with the NetBox API. The same pattern applies to both user synchronization and badge access history synchronization. Requests use the Connection: keep-alive HTTP header. 

1. Sends an HTTP POST request with an XML Login command to authenticate with the configured NetBox API username and password. 
2. Receives a NetBox session ID in the response.
3. Issues the required API command or commands for the operation, reusing the session ID.
4. Sends a Logout command to terminate the session.

Enabling API Access in NetBox

To enable Maptician's access to your NetBox API, you will need to configure API access and set up username and password authentication in NetBox. The exact steps depend on your specific NetBox configuration. Contact your S2 service provider for assistance with this setup. 

For detailed instructions, refer to the following sections in the NetBox Web-Based API documentation: 

• Creating User Roles for API (page 17)
• User Login Authentication (page 18)