File Name breakdown

Details

<datestamp>-<locationId>-accesscontrol.csv

<datestamp>-accesscontrol.csv

File Name Part

Additional Details

<datestamp>

Required

unique date stamp without separators

<locationid>

Optional

Unique identifier representing the physical location of your store.

Column Name

Required

Data Type

Examples

Purpose

dataType

✱ Required

Constant

'access-control'

Must always be "access-control". Row is rejected if any other value is provided.

eventUniqueId

✱ Required

String

'AC-001-20241201-120000'

'ACC_123456789'

Unique event identifier. Must be unique within the dataset.

startTime

✱ Required

Date/Time

YYYY-MM-DDTHH:MM:SS.sss±HH:MM

"2024-06-15T06:15:00.000-06:00"

YYYY-MM-DDTHH:MM:SS.sssZ

"2024-06-15T06:15:00.000Z"

Date/Time the event started. ISO-8601 datetime string. T is required between date and time. ±HH:MM = timezone offset; Z = UTC.

endTime

Optional

Date/Time

Same format as startTime

Date/Time the event ended. If omitted, defaults to startTime.

locationId

✱ Required

String

'111'

'SITE_001'

Site/location identifier where the event occurred. Maps to siteId internally.

locationName

Optional

String

'Main Building Entrance'

'Server Room'

Site/location name. Maps to siteName internally. Defaults to device name if omitted.

terminalId

✱ Required

String

'TERM001'

'TERMINAL_789'

Terminal identifier that processed the event. Also used as dataSourceId.

terminalName

Optional

String

'Main Entrance Reader'

'Server Room Reader'

Terminal name.

doorId

✱ Required

String

'DOOR001'

'DEVICE_456'

Door/device identifier (e.g., card reader, lock). Maps to deviceId internally.

doorName

Optional

String

'Main Entrance'

'Front Door Reader'

Door/device name. Maps to deviceName internally.

actorId

✱ Required

String

'ACT001'

'ACTOR_101'

ID of the person attempting access.

actorName

Optional

String

'John Smith'

'Jane Doe'

Name of the person attempting access.

actionName

✱ Required

String

'Card Swipe'

'PIN Entry'

'Biometric Scan'

'Door Alarm'

Descriptive name of the action performed. Becomes the event title displayed in the system.

action

Optional

Picklist

'Access Granted'

'Access Denied'

'Exception Event'

'Informational Event'

Categorized event type. Classifies the actionName into a standard category.

actionId

Optional

String

'ACN001'

'ACT001'

Action identifier code.

vendorName

✱ Required

String

'HID Global'

'Brivo'

'Schlage'

Name of the access control vendor/system.

vendorId

Optional

String

'V001'

'VENDOR_123'

Vendor identifier code.

result

✱ Required

Picklist

'success'

'failure'

'unprocessable'

Result of the access attempt. Must be one of the listed values exactly (case-sensitive). Row is REJECTED if an invalid value is provided.

state

✱ Required

Picklist

'open'

'close'

'unknown'

Access control state (e.g., door opened or closed). Must be one of the listed values exactly (case-sensitive). Row is REJECTED if an invalid value is provided.

accessMethod

Optional

String

'Swipe'

'RFID'

'Pin'

'Biometric'

'Mobile'

'Cloud'

'QR'

'Other'

Method used for access. Defaults to "Other" if omitted.

buildingId

Optional

String

'BUILDING_001'

Building identifier.

buildingName

Optional

String

'Corporate Headquarters'

Building name.

authorizerId

Optional

String

'AUTH_202'

ID of the person who authorized access.

authorizerName

Optional

String

'Security Guard'

Name of the person who authorized access.

notes

Optional

String

'Emergency access granted'

'Access denied - biometric mismatch'

Additional free-text notes associated with the event.

Value

Description

Success

The access attempt or operation completed successfully (e.g. access granted, door opened, or command executed without error).

Failure

The access attempt or operation did not succeed (e.g. access denied due to invalid credentials or policy, or a command failed). An attempt was made and evaluated, but the outcome was negative.

Unprocessable

The request or data could not be meaningfully processed (e.g. malformed data, missing required fields, or unsupported operation). The system could not properly evaluate success or failure.

Value

Description

Open

The access point (door, gate, turnstile, etc.) is unlocked, accessible, or in an active state where entry or exit is allowed; or an access session/event is in progress.

Close

The access point is locked, secured, or otherwise not allowing passage; or the access session/event has ended.

Unknown

The current state cannot be determined or was not reported (e.g. device offline, sensor/communication error, or uninitialized state).

Value

Description

Access Granted

The access request was authorized and entry/exit was permitted (e.g. valid credential presented, door unlocked). Represents a successful, allowed access decision.

Access Denied

The access request was evaluated and rejected (e.g. invalid or expired credential, insufficient permissions, wrong schedule/zone). An attempt was made but entry/exit was not permitted.

Exception Event

An abnormal or security-relevant condition at the access point that isn't a normal grant/deny decision (e.g. door forced open, door held/propped open too long, tamper, or duress). Typically warrants attention or alarm review.

Informational Event

A non-access, status/diagnostic occurrence that carries no allow/deny outcome (e.g. device online/offline, reader heartbeat, configuration change, or a routine state report). Provided for context and auditing.

Value

Description

SwipeCard

Swiped through a magnetic stripe reader

RFID

Card/fob tapped near a proximity reader

Pin

Numeric code entered on a keypad

Biometric

Fingerprint, face or other biometric scan

Mobile

Smartphone app or digital credential used

Cloud

Access granted via cloud-based authentication

QR

QR code scanned for entry

Other

Access method not covered by standard categories