LenelS2 NetBox / S2 Global

Drives doors and auxiliary outputs on a LenelS2 NetBox, NetBox Extreme or S2 Global appliance using the controller's local NBAPI — an XML-over-HTTP interface served by the appliance itself. No cloud account and no LenelS2 middleware are involved.

Each NetBox portal (a door with its reader, strike and contacts) becomes a GEM zone that can be locked, unlocked and buzzed open. Auxiliary outputs become on/off zones. A background poll of the access log surfaces who badged where and flags invalid attempts so the alarm engine can act on them.

• Driver name: lenels2_netbox
• Transport: HTTP POST of an XML packet to /goforms/nbapi
• Default port: 80
• Category: access control

Prerequisites

1. The API must be enabled on the appliance. In the NetBox UI go to Configuration : Site Settings : Network Controller, open the Data Integration tab, and tick Enabled. Until that is done every call returns APIERROR 2 and the device will not connect.

2. A user account with API privilege. The built-in roles differ:

   Role	NBAPI access
   Full system setup	Read/write, all partitions
   Partition setup	Read/write, that partition
   Partition administrator	None
   Partition monitor	None

   A custom role works too — set API Privilege to Read/Write under Configuration : Site Settings : User Roles. A Read-Only role can run get_portals, get_outputs and get_access_history but every lock/unlock will be refused by the appliance.

3. Network reachability. NetBox appliances usually sit on a dedicated security VLAN. Either route port 80 (or 443) from the GEM server to the appliance, or place GEM on that VLAN.

4. Commissioned portals. This driver reads and drives existing NetBox configuration. It does not create portals, readers, people or credentials.

warning

Enabling the NBAPI exposes lock and unlock control to anything that can reach the appliance's web port with valid credentials. Treat the API account like a door key: give it its own account, not a shared installer login, and keep the appliance off any routable/untrusted segment.

Setup steps

1. Enable the API and create the API user on the NetBox (see above).

2. In GEM go to /admin/devices, add a device, and choose driver LenelS2 NetBox / S2 Global.

3. Fill in the appliance IP address, username and password, then save. The driver logs in, reads the API version, and marks the device connected.

4. Run the get_portals command from the device's command list. It walks the portal groups and returns every portal with its PORTALKEY and name:

   {
     "portals": [
       {"address": "7",  "name": "Lobby Door",        "groups": ["Bldg 10 Portal Group"]},
       {"address": "12", "name": "Server Room",       "groups": ["Restricted"]}
     ],
     "count": 2
   }

5. Create one GEM zone per door. Set zone.address to the PORTALKEY — 7 in the example above. Put the zones in a door, access-control or security subsystem.

6. For auxiliary outputs (a gate operator relay, a strike wired to a spare output, an arming output to a burglar panel), run get_outputs and create zones with addresses of the form output:36.

7. On a partitioned system, run get_partitions and set the device's partition_key attribute so each session switches to the right partition after login.

8. Set the device's Elevated flag. It is off by default, which lets any signed-in account send the device commands. This is an access-control panel, so turn it on — see Devices and Elevated devices and macros.

Who can drive this panel

The Elevated flag on the device row is the control that decides who can operate these doors. Two backstops sit beneath it, which apply to any caller the transport marked non-elevated — a wall panel or guest account, not a macro, schedule or the status poller:

• Addressed commands are confined to published zones. Any command carrying an address is refused with not authorized: address is not mapped to a zone on this device unless it matches a GEM zone on this device — enforced centrally at the command dispatch layer, so it covers every verb rather than an enumerated list. A PORTALKEY that is commissioned on the appliance but was deliberately never exposed as a zone — a server room, a tenant suite, an exterior perimeter door — cannot be reached by naming it directly.
• raw_command and switch_partition are refused outright. raw_command reaches the whole NBAPI, including person and credential administration, so it is admin-only regardless of address.

Neither backstop replaces the device flag. Set Elevated on the device as well.

Attribute reference

Device attributes

Attribute	Required	Default	What it does
ip	yes	—	LAN IP or hostname of the NetBox / S2 Global appliance.
username	yes	—	NetBox user with API privilege on the partition being controlled.
password	yes	—	That user's password. Stored encrypted.
port	no	80	Web port on the appliance.
protocol	no	http	http or https. Self-signed certificates are accepted.
api_path	no	/goforms/nbapi	Endpoint path. Use /global/goforms/nbapi for an S2 Global head end.
partition_key	no	—	PARTITIONKEY to switch to after login. Empty stays in the login partition (Master by default).
momentary_seconds	no	10	How long a zone displays released after a momentary unlock. Display only — see limitations.
status_interval	no	15000	Access-history poll interval in ms. Also the connection-health probe.
max_events	no	100	Ceiling on access records pulled per poll.

Zone attributes written by the driver

Attribute	Written when	Values
state	On a successful command, and on a valid badge read	locked, unlocked, released (portals); on, off (outputs)
last_access_person	A badge is presented at that portal	The person's ID # from the NetBox person record
last_access_reader	"	Reader name, e.g. Lobby Door In
last_access_time	"	Appliance timestamp, YYYY-MM-DD HH:MM:SS with timezone offset
last_access_result	"	valid, invalid, elevator_valid, elevator_invalid, not_completed
last_access_reason	An invalid attempt	Plain-text reason — card expired, wrong time, anti-passback violation, …

The device row also carries api_version, read once at connect.

Zone address format

Form	Meaning
7	Portal (door) with PORTALKEY 7
portal:7	The same portal, written explicitly
output:36	Auxiliary output with OUTPUTKEY 36

Portal and output keys live in separate namespaces — output 7 and portal 7 are different pieces of hardware. A bare number is always read as a portal.

Commands

Command	Args	Notes
get_portals	—	Lists commissioned doors by walking the portal groups.
get_outputs	—	Lists auxiliary outputs.
get_readers	—	Lists card readers, for mapping access events to doors.
get_partitions	—	Lists partitions and their keys.
get_api_version	—	Reads the NBAPI version; also a session check.
unlock	address	Extended unlock — stays unlocked until lock.
lock / close	address	Returns the portal to the Ready (locked) state.
momentary_unlock / open	address	Buzzes the door for the unlock time configured on the NetBox.
on / off	address	Activate / deactivate an output: zone.
get_access_history	limit, after_log_id	Reads the access log tail. Newest-first by default; ascending when after_log_id is given.
switch_partition	partition_key	Switches the current session to another partition.
refresh	—	Forces an immediate access-history poll.
raw_command	command, params	Escape hatch to any NBAPI command, e.g. GetPerson with {PERSONID: "1234"}.

note

unlock and momentary_unlock are genuinely different actions. unlock is the NBAPI UnlockPortal, which puts the door into Extended Unlock and leaves it there indefinitely. momentary_unlock is MomentaryUnlockPortal, the buzz-open, whose duration comes from the portal definition on the appliance. Scheduling an unlock without a matching lock leaves the door open.

Known limitations

• There is no portal state read. The NBAPI has no GetPortalStatus command. GEM's zone state is therefore what GEM last commanded, plus a released pulse whenever a valid badge appears in the access log for that portal. A door unlocked from the NetBox UI, a keypad, a REX button or a schedule on the appliance will not move the zone state until it produces an access record. If accurate door position matters, wire the door contact to a monitored input and bring that in as its own zone.
• momentary_seconds is cosmetic. The real strike time lives in the portal definition and is never reported back. Set this attribute to match the portal so the UI stops showing released at roughly the moment the door actually re-locks.
• Portals outside a portal group are invisible to get_portals. Enumeration goes through GetPortalGroups, so an ungrouped portal will not be listed. Its PORTALKEY still works as a zone address — read it off the NetBox UI and type it in.
• People, credentials and access levels are read-only here. The NBAPI can add and modify person records, cards and access levels; this driver does not expose those as first-class commands. raw_command reaches them if you need to, but cardholder administration belongs in the NetBox.
• Elevator floor control is not implemented. GetElevators and GetFloors exist in the API; they are not wired to GEM zones.
• The activity log is finite. The appliance keeps 100,000 activity records by default. If GEM is offline longer than it takes the site to generate that many events, the gap is lost — the driver resumes from the newest record rather than trying to backfill.
• The first poll after connect does not replay history. On connect the driver records the newest log id as a baseline. This is deliberate: replaying a day of badge reads would fire every attribute trigger attached to those zones at once.

Troubleshooting

Device never connects, log shows apierror 2 The NBAPI is not enabled. Tick Enabled on Network Controller : Data Integration.

apierror 5 on every call Authentication failure. Check the username and password, then check the account's role — a Partition administrator or Partition monitor authenticates successfully at the UI but has no API privilege at all.

Commands return Portal state not changed Not a fault. The appliance reports "already in that state" as a failure. Sending lock to a portal that is already locked produces this.

Commands return Portal not online or reachable The portal's node (blade/controller) is offline on the NetBox side. Check the node status in the NetBox UI — GEM is only relaying what the appliance said.

Lock and unlock are refused but get_portals works The API role is Read-Only. Change API Privilege to Read/Write.

get_portals returns fewer doors than the site has Those portals are not in any portal group. Add them to a group on the NetBox, or address them directly by PORTALKEY.

Nothing appears in last_access_* even though people are badging Confirm the zone address matches the PORTALKEY the reader is attached to — the access record's portal key is what the driver matches on. get_access_history shows the raw records including portal_key, which is the fastest way to check.

Connection flaps after the appliance is rebooted or updated Sessions do not survive a restart. The driver detects APIERROR 5, re-logs in and replays the call, so a single flap is expected and self-healing. Repeated flapping usually means two GEM devices (or another integration) are sharing one API account and expiring each other's sessions — give each its own account.

Related

• Access Control — GEM's access-control model and how door zones are surfaced.
• Devices — adding and configuring device rows.