REST API in U‑PROX: examples of relay control and online integration

U-PROX software (also known as U-PROX IP or U-PROX Web) has two user interfaces: a classic Windows interface and a web interface. It uses the MSSQL database and operates on the Windows OS family.

API usage is available after installing the Web Server component alongside the main U-PROX Server component.

See the description below and the color-highlighted elements.

In the API documentation (see Section B below), use the following items to configure custom responses:

• Authenticate.html – example of authentication and connecting to the server
• EventGetList.html – example of retrieving events and displaying them in soft real-time
• DoorControl.html – example of door control

The U-PROX system does not support arbitrary reaction mechanisms.
Reactions are implemented only through predefined presets, associated with:

• Free access mode (relays controlling door locks)
• Door sensor operation (activation of an alarm relay)

All other behavior scenarios can only be implemented via API integration using the appropriate tools.

There is also a separate feature for controlling relays by schedule, but this is a different functional mechanism and is not considered part of arbitrary reactions.

To work with the API, it is recommended to use U-PROX IP version no lower than v3.057.7988.iso (the download link is available in the API documentation), and to refer to the implementation examples provided below.

Use one of the following approaches:

EITHER configure control of the relevant relays by schedule, setting them to “Programmed” mode with the action type set to “Start-Stop”, “Impulse”, or “Trigger”;

OR implement control of these relays via the API.

For example, when a “free access” event occurs on a specific controller or via an external command, the API-based control mechanism can be triggered.
As a result, a relay on the IP400 controller, previously configured as “programmed”, is activated and performs the opening of a technical passage.

For detailed implementation examples, see the descriptions below: Block A and Block B.

Block A

Additional relays must have the usage type set to “Programmed” in order to be used via API for external control.

In the API documentation (see Block B below), use the following item:

Documentation\html\DoorControl.html – an example of door control

This includes the relevant function “DeviceOutputCommand”.

function DeviceOutputCommand(command, output) {          if (!output) {
         return
       }          // command:
       //   DeviceOutputActivate – увімкнути релейний чи транзисторний вихід контролера
       //   DeviceOutputDeactivate – вимкнути релейний чи транзисторний вихід контролера
       var url = ‘http://localhost:40001/json/’ + command
       var payload = {
         UserSID: $scope.UserSID,
         DeviceToken: output.DeviceToken,
         OutputIndex: output.DeviceIndex
       }
       $http.post(url, payload).then(
         LogResponse,
         LogError
       )
     }
 
// options for using controller outputs
 const DOU_UNUSED = 0 // output not used
const DOU_LOCK = 1 // output used to control a lock
const DOU_BELL = 2 // output used to control a hidden alarm indicator
const DOU_ALARM = 3 // output used to control a siren
const DOU_TURNSTILE = 4 // output used to cut power to certain turnstile types and automatically lower the arm in free pass mode
const DOU_SOFTWARE_CONTROLLED = 5 // output controlled by application software via API calls DeviceOutputActivate/DeviceOutputDeactivate
const DOU_CARD_COLLECTOR_PASS = 6 // output used to send “Pass the card” signal to RFID card collector
const DOU_CARD_COLLECTOR_GET_CARD = 7 // output used to send “Take the card” signal to RFID card collector
const DOU_CARD_COLLECTOR_RETURN_CARD = 8 // output used to send “Return the card” signal to RFID card collector
const DOU_TURNSTILE_EMERGENCY_EXIT = 9 // output used to set a pulse-controlled turnstile to free pass mode
const DOU_TURNSTILE_BLOCKING = 10 // output used to set a pulse-controlled turnstile to blocking mode

 
 
<div ng-app=”exampleApp” ng-controller=”exampleController”>
<form novalidate class=”simple-form”>
 <label>Login:    <input type=”text” ng-model=”login”    /></label><br />
 <label>Password: <input type=”text” ng-model=”password” /></label><br />
 <div ng-if=”UserSID == ””>
   <hr>
   <label>Disconnected</label><br />
   <hr>
   <input type=”button” ng-click=”Authenticate(login, password)” value=”Authenticate” />
 </div>
 <div ng-if=”UserSID != ””>
   <hr>
   <label>Connected</label><br />
   <hr>
   <label>Door: </label><select ng-model=”door” ng-options=”x.Name for x in doors” ></select><br />
   <input type=”button” ng-click=”DoorCommand(‘DoorAccessIn’,  door)” value=”DoorAccessIn”  /><label>Unlock door for single entrance</label><br />
   <input type=”button” ng-click=”DoorCommand(‘DoorAccessOut’, door)” value=”DoorAccessOut” /><label>Unlock door for single exit</label><br />
   <input type=”button” ng-click=”DoorCommand(‘DoorUnlock’,    door)” value=”DoorUnlock”    /><label>Unlock door for multiple entrances and exits (free pass mode)</label><br />
   <input type=”button” ng-click=”DoorCommand(‘DoorBlock’ ,    door)” value=”DoorBlock”     /><label>Lock door and grant access to security service only</label><br />
   <input type=”button” ng-click=”DoorCommand(‘DoorLock’,      door)” value=”DoorLock”      /><label>Lock door and grant access to enabled cards (default door mode)</label><br />
   <hr>
<label>Software controlled device output: </label><select ng-model=”output” ng-options=”GetDeviceOutputName(x) for x in outputs | softwareControlledOutputs” ></select><br />
<input type=”button” ng-click=”DeviceOutputCommand(‘DeviceOutputActivate’, output)”   value=”DeviceOutputActivate”   /><label>Activate software-controlled device output</label><br />
<input type=”button” ng-click=”DeviceOutputCommand(‘DeviceOutputDeactivate’, output)” value=”DeviceOutputDeactivate” /><label>Deactivate software-controlled device output</label><br />
   <br />
   <input type=”button” ng-click=”Logout()” value=”Logout” />
 </div>988
</form>

Block B

Система U-Prox містить інструменти для інтеграції зі стороннім програмним забезпеченням U-Prox contains tools for integration with third-party software via API with support for SOAP, REST, JSON, XML protocols.

U-PROX software is free, as is the REST API toolkit.

To use the REST API in U-PROX software when interacting with third-party systems, you need to:

• Install U-PROX software components:
  Server, Client, Web Server, Desktop Server
• Follow the logic of operation:
  U-PROX Equipment ⇄ U-PROX Software ⇄ Third-Party Software

The following interaction options are available:

• Two-way integration via web API protocols with any other software (full API integration).
• Data export from U-PROX software reports using standard tools of the program and the operating system, followed by import into third-party software.
• Direct data selection from the U-PROX software database using SQL queries in Transact-SQL (T-SQL) — no authorization required on the database side.

“U-Prox IP” software (also known as “U-Prox WEB”) has two interfaces — the classic Windows interface and the web interface:

• In the classic interface, reports can be exported in text format *.CSV (manual and automatic export), and in Excel format (manual export only), provided that Excel is installed on the PC.
• In the web interface, reports are generated and exported manually in .PDF format, or via API (in PDF or JSONformat).

Recommended software version: v3.057.7988:

Download the ISO image of U-PROX software version 3.57.7988 and install or update your existing version.

ISO image 3.57.7988 of the U-Prox software version:
–  https://drive.google.com/file/d/14kt60eWtgMPhV5VQMBS1jq5MN7l47uxy/view

Update in the following sequence – Server, Client, Web Server, Desktop Server – on the program server;
and Client and Desktop Server on remote client workstations.

• Desktop Server – where the Web Client and U-PROX Desktop USB reader are used.

– and as specified below in the API description

Refresh the page in your browser after upgrading to newer versions – “Ctrl+F5” to reload with cache clearing.

General description of the API

Check out the available information on the “API Integration” page of our website:

–  https://u-prox.systems/software/

Check out the feature guide (available after installing the U-PROX system):

–  http://127.0.0.1:40001/json/help (Eng)

Also, on the installed U-PROX system, in the browser, using the developer window (F12), you can view the interaction of U-PROX WEB with the API.

If there is not enough information, please send your questions by email support@itvsystems.com.ua with topic API integration.

U-PROX WEB Server REST API

The latest versions of U-PROX WEB API examples and documentation are available in the cloud folder:

–  https://drive.google.com/drive/folders/1QpNENLEwYwjy_uOeFmjNmlSlIoVTf33b

The specified folder contains the following files:

U-Prox IP.v3.057.7988.iso – distribution disk image. From this image, you need to install or update the following components:
“U-PROX IP Server”, “U-PROX IP Client”, “U-PROX Web Server”, and “U-PROX Desktop Server”.

Documentation\AcsWebService.doc – a previous version of the Web Service description, which includes descriptions of operations for connecting to the service, receiving event notifications, creating employees, and other operations.

Documentation\html*.html – examples written in JavaScript using the AngularJS library.

• Documentation\html\Authenticate.html – example of authentication and connecting to the server
• Documentation\html\DoorControl.html – example of door control
• Documentation\html\DoorUnlockAll.html – example of emergency unlocking of all doors in the system
• Documentation\html\AdditionalEventFields.html – example of retrieving and creating devices (controllers), additional event fields, and event entries (access records)
• Documentation\html\Employees.html – example of retrieving the list of devices (controllers), doors, access levels, departments, employees (users), cards, their creation, dismissal, and deletion
• Documentation\html\EventGetList.html – example of receiving and displaying events in soft real-time mode
• Documentation\html\EventsReport.html – example of retrieving an event report in both PDF and JSON formats
• Documentation\html\TimeAttendanceReport.html – example of retrieving a time attendance report in both PDF and JSON formats
• Documentation\html\Visitors.html – example of retrieving device lists, doors, temporary access levels, visitors, card creation, and deletion of created objects

Documentation\html\js*.js – used JavaScript libraries

To demonstrate the functionality of web applications such as DoorControl.html, Employees.html, Visitors.html, etc., perform the following steps:

1. Download the U-Prox IP.v3.057.7988.iso distribution disk image from the folder in the cloud:

–  https://drive.google.com/open?id=1QpNENLEwYwjy_uOeFmjNmlSlIoVTf33b

2. Install or update U-PROX IP Server.

3. Install or update U-PROX IP Client.

4. Install or update U-PROX IP Web Server.

5. Install or update U-PROX IP Desktop Server.

6. Open the corresponding HTML file in Chrome and view the list of requests and responses to requests.

Online mode (short description)

Support for external access control modes has been added to the U-PROX IP software version 3.052.6722. It is necessary to have this or a later version installed.

“Entry permitted”:

POST http://localhost:40001/json/DoorAccessIn

{

“UserSID”: 1234567890123456, // session identifier obtained as a result of the Authenticate request

“Token”: 12345, // door token or passage direction token (Door – Entry, Door – Exit) for which the command is issued

“CardCode”: “1234567890” // card code that will be saved in the log for the “Access Granted” event

}

“Exit permitted”:

POST http://localhost:40001/json/DoorAccessOut

{

“UserSID”: 1234567890123456, // session identifier obtained as a result of the Authenticate request

“Token”: 12345, // door token or passage direction token (Door – Entry, Door – Exit) for which the command is issued

“CardCode”: “1234567890” // card code that will be saved in the log for the “Exit Granted” event

}

“No entry”:

POST http://localhost:40001/json/DoorDenyAccessIn

{

“UserSID”: 1234567890123456, // session identifier obtained as a result of the Authenticate request

“Token”: 12345, // door token or passage direction token (Door – Entry, Door – Exit) for which the command is issued

“CardCode”: “1234567890” // card code that will be saved in the log for the “Access Denied (Entry)” event

}

“No exit permitted”:

POST http://localhost:40001/json/DoorDenyAccessOut

{

“UserSID”: 1234567890123456, // session identifier obtained as a result of the Authenticate request

“Token”: 12345, // door token or passage direction token (Door – Entry, Door – Exit) for which the command is issued

“CardCode”: “1234567890” // card code that will be saved in the log for the “Access Denied (Exit)” event

}

Online mode (detailed description)

Below are additional details about the external access control mode of the U-PROX IP400 controller and its support in the “U-Prox IP” software.

The external access control mode, in which access decisions are made by the server based on an operator command or a REST API request, is available in “U-PROX IP” starting from version v.3.052.6833 and in later versions.

There are two modes of external access control:

1. “Operator denies and grants access” – in this mode, the controller sends information about any presented card to the server and grants or denies access only after receiving the server’s response.
2. “Operator confirms access” – in this mode, if a prohibited card is presented, the controller processes it locally and issues a denial signal.
   If a permitted card is presented, the controller sends this information to the server and waits for a few seconds for a command to grant or deny access.
   If no command is received within the specified timeout, the controller automatically grants access to the allowed card.

To ensure correct operation of the second mode (operator confirms access), the controller firmware must be version 7.23/8.23 or higher on U-PROX IP400.

External access control mode is configured in the “U-PROX WEB Client”, available at http://localhost:40001/ after installing both “U-PROX IP Server” and “U-PROX WEB Server”.
Configuration is shown in the following screenshots:

or in the classic client

or in the classic client

After uploading the new configuration to the controller, information about the card elevation can be obtained via REST API in the form of an event:

{

“Event”:[

{

“Device”:{

“Name”:”Turnstile”,

“Token”:23880

},

“Message”:{

“Code”:65555,                          // event code: 65554 – login request, 65555 – logout request

“Name”:”Запит на вихід”,

},

“Sender”:{

“Name”:”Turnstile – exit”,

“Token”:23902

},

“User”:{

“EmployeeNumber”:””,

“Post”:””,

“AdditionalFields”:[

],

“Name”:”Петренко”,

“Token”:6580

},

“Department”:{

“Name”:”Administration”,

“Token”:6566

},

“PhotoToken”:23678,

“IconToken”:23679,

“CardCode”:”0B0016B189″,

“Issued”:”\/Date(1591793191053)\/”,

“FaceMaskDetected”:false,

“Temperature”:0,

“AdditionalFields”:[

],

“Token”:34106,

}

]

}

You can find an example of receiving events in Soft Real Time mode in the files Documentation\html\EventGetList.html and Documentation\html\Photoverification.html in the cloud folder with REST API examples:

–  https://drive.google.com/drive/u/0/folders/1yyYWg8pPimNbYoG1XeOhFfIOMLg6Y2ug

To obtain permission to pass, you must send a request:

POST http://localhost:40001/json/DoorAccessIn чи http://localhost:40001/json/DoorAccessOut

{

“UserSID”: “830730959685833”, // session identifier for connection to the server

“Token”: 23902, // Event[i].Sender.Token – access point token specified in the event

“CardCode”: “0B00123456” // card code that has been granted access

}

To prohibit access, you must send a request:

POST http://localhost:40001/json/DoorDenyAccessIn or http://localhost:40001/json/DoorDenyAccessOut

{

“UserSID”: “830730959685833”, // session identifier for the server connection

“Token”: 23902, // Event[i].Sender.Token – access point token specified in the event

“CardCode”: “0B00123456” // card code that has been granted access

}