PUT /edgeDevices/{linkId}/database

This resource is used to selectively push an access control database change to a specified linked edge device. The payload is the JSON object db as defined in the ENGAGE - JSON Data Structures document.

Gateway

The Gateway sends anything that is in the body to the linked edge device. That means the Gateway does not error check the contents of the database. Error checking is done by the edge device, so audit trails should be checked to validate database updates. A successful response indicates that the edge device has accepted a single test message and the Gateway will begin sending the content to the target edge device. It does not indicate that the message has been completely received by the target edge device. Overall transfer status can be monitored with the resource /edgeDevice/{{linkId}}/dbDownloadStatus.

Depending on the size of the database, this operation can take considerable time as the maximum transfer rate of the Gateway to a device over BLE is 768 bytes/sec. As such, it is suggested that db data be ‘minified’ by removing all whitespace from the JSON. As an example, a 5000 user database having a size of 984K would have a best case transfer time of ~22 minutes; performing this test in an office environment where there are many 2.4GHz devices and access points competing for bandwidth, the transfer time has been measured to typically be ~50 minutes.

Notes

1. An edgeDevice stores the database information into non-volatile memory. It is therefore not advised that database transfers be performed on a highly frequent periodic basis; rather, it is ideal to only send a new database when a change has occurred. Up to 500 “delta” add/mod/delete db operations can be sent as well before a complete database should be sent again with all credential entries. This avoids dominating available bandwidth continuously and reduces transfer times.

2. If the edge device is not connected when this resource is requested the Gateway will not store the message (see Note 3).

3. For Gateway firmware version 1.49.24 and later, NDE firmware version 2.8.16 and later, and LE firmware version 2.09.05 and later, this resource supports a database “resume” functionality. If the edge device is disconnected either when this resource is requested, or at any time during the database download, the Gateway attempts to restart the database transfer from the last packet that was successfully sent, once the respective edge device is re-connected.

This process is serialized, therefore for a Gateway which has multiple linked edge devices, the device-0 database download will progress until it either completes or disconnects, at which time the device-1 database download will begin and progress until it either completes or disconnects. This round-robin process continues until all the databases have been sent to their respective edge devices. If a database change must be made immediately to a linked edge device and the Gateway is currently transferring a database to another linked edge device, the resource PUT /edgeDevices/{linkId}/config can be utilized to “jump the line” and send the request immediately to that edge device.

Details of how to implement the config endpoint are shown below, with the notable exception that the JSON body message would contain the “db” JSON tag instead of the “config” JSON tag if used for this purpose.

4. While this is allowed, it is NOT a recommended method to be implemented programmatically. In addition, the JSON body size limit for the config endpoint still holds true when sending a database through the config endpoint. For this reason, it is not recommended that the config endpoint be utilized for modifying databases with more than one user addition, modification, or deletion at a time. Consideration should be given to canceling a database download currently in que, in the event that the config endpoint must be utilized to modify the database door file.

While the “status” tag has been added to the /dbDownloadStatus endpoint to indicate the status of the database resume functionality, edge device audits should still be checked at the completion of the database download to ensure that the database has been properly received and processed by the edge device. For firmware versions 1.51.22 and later, the Gateway has implemented a 36 hour timeout on database messages that are not able to be transmitted successfully to the edge device. Please check the edge device audits for successful processing of the JSON body.

Reader-Controller

A successful response indicates that the reader-controller has received the message, but not that the reader-controller has activated the database. Overall transfer status can be monitored with the resource /edgeDevice/dev00000/dbDownloadStatus.

Authentication

Basic: Unique credentials defined and accepted during setup.

Request

URI parameters:  <missing or is this 'None'?>

Type: path parameter

• linkId = linked edge device identifier, as defined in the ENGAGE - JSON Data Structures document, section titled “Gateway Edge Device Link List”
• For reader-controllers this is a constant dev00000.

Body:  <missing or is this 'None'?>

Type: application/json

• db = parent tag + children, as defined in the ENGAGE - JSON Data Structures document, section titled “Lock JSON Messages” in sections defining the related components of the “db” tag.

Example:

{"db":{"usrRcrd":{"deleteAll":1,"delete":[],"update":[],"add":[{"usrID":"17856","adaEn":0,"actDtTm":"20150303000000",
"expDtTm":"21350101000000","fnctn":"norm","crSch":[1],"primeCr":"bc477b6b51700a797fda79646cafb160","prCrTyp":"card",
"scndCr":null,"scndCrTyp":null}]},"schedules":[{"days":["Su","Mo","Tu","We","Th","Fr","Sa"],"strtHr":0,"strtMn":0,"lngth":1439}],
"holidays":[],"autoUnlock":[]},"nxtDbVerTS":"0x8d22651fb4300a2"}

Success Response(s)

HTTP status code: 202

• This message indicates the request was accepted by Gateway or reader-controller and transfer will begin. 
• A 202 does not indicate that it has been delivered to the target edge device.

Error Response(s)

HTTP status code: 503

Response parameters:  <missing or is this 'None'?>

Type: application/json

• statusMessage = “Currently processing another database”, indicates Gateway, edge device, or reader-controller is processing another database.

Last Modified: October 15, 2019