HIK API 

1. Import API Features
2. Import or update API Persons
3. Import or update API Persons Information
4. Import or update API Devices Information
5. Import or update API Doors Information
6. Import or update API Readers Information
7. MAP HIK devices (doors) to Eco Time devices (option)
8. API Logs
9. Application Service Options

Run the API application by clicking on the Eco HIK API shortcut on the desktop or running the application called EcoHIKAPI32 or EcoHIKAPIMs.

Select the Settings Tab on the Eco Time HIK API Client :

• Server: The API server URL or IP address and port number as supplied by the client.
• Authorization: The code is generated on the HIK server's REST client settings and supplied to Eco Time by teh client.
• Version Number: The current API version number and cannot be changed.
• Client Code: The client code defaults to "HIK" and cannot be changed.
• Receive Format: The receive format is JSON and for information purposes only.
• Stop timed events: This stops time-based events, typically useful when performing fault finding or analysing data on the client response screen.

• Client API Type:This setting defaults to "HIK" and cannot be changed.
• Client API Status:This is the default setting and cannot be changed.
• Events Collect Interval: Events collected interval in hours and minutes.
• Events / API Call: The maximum events collected with every events' API call.
• Events Collect Position: The next position number where the API will collect events from. Set this value back to recollect all events.
• Events Duplicate Threshold(ms): An event will not be saved as an Eco Time clocking if there is already and event with the current event time minus this value (100ms = 1 second). Duplicate events are saved as Info (Status = H) clockings.
• Don't Save Duplicate Events : Duplicated events will be rejected and not be saved as Info clockings.
• Don't Save Events To Clockings Table: Events are only stored in the Events table and not processed for Eco Time.
• Events History Days: The number of days (defaults to 61) events must be stored in the Events table before they are deleted according to the event date.
• Log History Records: The log history will be truncated at this number of records (default 2000).
• Stop timed events: This stops time based events, typically useful when performing fault finding or analysing data on the client response screen.

• Last Sync Date: The last date all persons and persons' info was synced.
• Last Sync Time: The last time all persons and persons' info was synced.
• Last Collect Date: The last date a timed collect of events was performed.
• Last Collect Time: The last time a timed collect of events was performed.
• 1st Sync Time: The 1st time of day all persons and persons info will be synced.
• 2nd Sync Time: The 2nd time of day all persons and persons info will be synced.
• Employee Division: Employees in HIK are allocated to this division.
• Process for this division only: Select this option to limit the import of cardholders and events to the division set above.
• Stop timed events: This stops time-based events, typically useful when performing fault finding or analysing data on the client response screen.

1. After the API Client has been configured, run the application and select Settings tab and then the HIK sub tab.

   

2. Please note that the "Stop timed events" check box is disabled by default on a new API installation. There is no point running timed events until the configuration and device mapping have been completed.

3. Select the APi button next to the Version Number field.  This will open the API Request Window

   

4. Now Press the Post (POST) button
5. You will see the request window is now populated with text. To verify the connection, select the response tab.

   

6. If the connection was successful, you should see at least a full page in the response field. Close API Request Window and verify that the version field is now populated. If there was a connection error, the following message with error description will pop up.

   

7. If the version field is not populated, go back to the API Request Window and look at the response tab or you will get a description of the error as a pop-up message .
8. If the response is very short, then the following errors are possible:
   1. Server connection cannot be opened: The HIK server connection details are incorrect or a firewall is blocking the connection.
   2. 403 Unauthorized: The API operator does not have the privileges to view the monitored items.
   3. 403 Forbidden: The site does not have the API license:
9. The features to the API methods which are available to the POST API operator are controlled by the HIK user privileges. Eco Time needs the following API methods for integration:
   1. Persons
   2. Events
   3. Readers
   4. Doors
   5. Devices
10. The "Do Not Process Response" disables any results processing. No tables will be populated. This is typically used for fault finding and in cases where you want to inspect the request packet and result packet.
11. Once you have established and tested that the HIK API Client is successfully communising with the HIK API Server, the HIK API Client must be loaded with the API information in the following sequence.
    1. Devices
    2. Doors
    3. Readers
    4. Persons

1. Start by populating the following lists in order by pressing the API button on the respective tabs:
   1. Persons- Get Persons List: The persons button brings up the following popup menu:

      

      Select the Get "Persons List" option by clicking on this item.

      
      The persons table contains all the captured employees or visitors on the HIK system
      The following persons table fields will be populated

      1. ID: Internal HIK Person's ID code
      2. Person Code: Person Code
      3. Employee Number: Eco Employee number from the HIK custom field.
      4. firstName: Persons holder first name
      5. lastName: Persons holder last name
      6. Authorised: Is the person authorised
      7. ID Number: Person's ID or Passport number
      8. Import Date: Date added to the Persons Holder's table.
   2. Devices

      

      Devices are HIK's main configuration entity. From here doors' (access devices) reader devices are attached. A device can be enabled or disabled. Events from a disabled device, its doors and its readers will be rejected

   3. Doors

      
      The doors table contains all the device names where employees or visitors can clock
      The following doors table fields will be populated

      1. Enabled: Set to 0 (zero) for disabled and 1 (one) for enabled. If a device is disabled, events will not be saved for that device.
      2. ID: Internal HIK Door ID code
      3. Access Device: HIK Access Device. Clockings are collected from Devices (Doors), but handled via the reader configuration.
      4. Door Name: Door description as per the API sync process
      5. Last Clocking Date Collected: Updated when events are collected for this device
      6. Last Clocking Time Collected: Updated when events are collected for this device
      7. Verified Date: The date on which the last Doors API sync was manually run. If this date does not match the last  date on which the API was run, then the device was removed from the HIK system and can then manually be removed from this list. 

         Note: The HIK devices must be named with the extension Entry or Exit. This will enable the user in EcoTime to configure the corresponding device correctly.

   4. Readers

      

      The readers table contains all the readers names where employees or visitors can clock
      The following reader table fields will be populated

      1. Enabled: Set to 0 (zero) for disabled and 1 (one) for enabled. If a device is disabled, events will not be saved for that device.
      2. ID: Internal HIK Door ID code
      3. Reader Name: Clockings are collected from Devices (Doors) but handled via the reader configuration.
      4. Door ID: Door ID as per the API sync process
      5. Last Clocking Date Collected: Updated when events are collected for this device
      6. Last Clocking Time Collected: Updated when events are collected for this device
      7. Verified Date: The date on which the last Doors API sync was manually run. If this date does not match the last  date on which the API was run, then the device was removed from the HIK system and can then manually be removed from this list. 
          
   5. Persons- PersonsInfo: The persons button brings up the following popup menu:
      1. 
      2. Select the "Get All PersonsInfo". This process will take some time and progress will be displayed at the bottom left of the HIK API Window.
      3. The Persons Info option adds and updates the person's personal and custom information to the HIKPersons table:
         1. Sites: If configured, the HIK Persons site is populated
         2. Emp Number: This field is a mandatory configuration for HIK and Eco Time integration:"
            1. This field is used to match the Eco Time employee number and if a match is found, the Eco Time fields will be populated.
            2. If an Emp Number is not imported, no matching attempt will be made.
            3. If an Emp Number is imported, the corresponding Eco Time details will be populated in the persons table:
               1. Eco Emp Number
               2. Eco Emp First Name
               3. Eco Emp Last Name
            4. If an Emp Number is imported, the API validates the employee surname and employee number.
               1. If employee surname do not match, an error image will appear next to the cardholder.
               2. The AP tries to match first names. If the firstnames do not match, the API tries to resolve initials or initials in combination with firstnames. But if this fails a warning image will appear next to the cardholder.
         3. Division: Divisions which the employee is assigned to in the HIK system.
         4. Department Business Unit: Department/Business Unit which the employee is assigned to in the HIK system.
         5. Job Title: Job Title which the employee is assigned to in the HIK system.
         6. Gender: gender of the employee is assigned to in the HIK system.
         7. Verified Date: The last date the persons info was updated.
      4. "Get Current Persons" Info option updates the currently selected person's personal and custom information to the Cardholders table.
      5. "Get Current Persons Events" retrieves all the events of a selected person and updates the Events table according to the rules configure in the Readers Browse. 

1. The HIK API interface you allows the user to map the HIK devices to a corresponding Eco Time device.
2. In terms of using the HIK API, we recommend setting up and Eco Time API device, but you may use and existing device to ease the process of cutting over.
3. The browse has five fields which may be edited:
   1. Enabled: Only enabled devices' events will be collected and displayed in the Events Browse. Enter a 1 to enable the device.
   2. Name: This is the reader description
   3. Eco Device: To map this device name to the corresponding Eco Time device, for example Eco Time Clock 1, simply enter 1 in this field.
   4. TNA Clock: Update if events for this device must be assigned for TNA.
   5. Access Clock: Update  if events for this device must be assigned for Access.
   6. Clock Direction: Assign direction to an event by enter 0 for not applicable (eg for Access), 1 for In, 2 for Out and 3 for toggle direction -  must always be set
4. Once a HIK device has been mapped to an Eco Time Device, the event collected for that device is allocated all the attributes ascribed to that Eco Time device, for example if it is a Access, TNA or Job etc device. NOTE: The event direction will always be determined by the HIK Device Setting. Always map to an EcoTime API Device
5. If an Eco Time device mapping is not found for an enabled HIK device, the device settings configured in the readers browse for that device, will be used.

1. An API call can be manually triggered at any time by pressing the API button at the bottom of each browse.
2. An API call triggered will depend on the current tab selected (eg Events).
3. All manually triggered API calls are not automated. This means the API Client Request Window will open and you would manually have to press the Res (Get) button. Afterwards press the close button to exit the API call.
   1. API Client Request Window Request:
      
   2. API Client Request Window Response:
      
4. The API Status message at the bottom left of the browse will be updated with the current action or process.
5. Manually triggering an API is used during the configuration and setting up phase of the API.
6. It is also very helpful when performing fault finding. See the FAQ for more details about this.

1. Timed events are automated events trigger either by time or an interval duration, in other words automated API calls.
2. During timed events the API Client Request Window is hidden but the API status message is updated.
3. There are three timed events:
   1. New events are collected from the HIK server every two minutes.
   2. The cards holders list is synced twice a day. Once at 1am and once at 1pm.
   3. The cards holders information is updated once twice a day. Once at 1.30am and once at 1.30pm.
4. Timed events can be disabled be selecting the "Stop timed events" check box on the HIK API Window. 

1. The logs browse displays general information about the API requests, responses and processes.

   

2. The log display information about:
   1. Details about a collected event.
   2. The total events collect with each API call.
   3. If the event was processed or rejected. If rejected, it provides a reason.
   4. If the event was added as a clocking to Eco Time.
   5. When manual or timed events were triggered.

1. In which Eco Time version is this feature available?
   From version 2023.08.29 onwards.
2. How can the API Client Request Window be used for fault finding?
   1. This windows displays the request link in the server fields. You can use his value to determine if the correct link is being used durig the rest call.
   2. Consider selecting the "Do Not Process Response" disables any results processing. No tables will be populated. This is typically used for fault finding and is used in cases where you want to inspec the request packet and result packet. 
   3. The HIK API Server response is displayed in the response window's text field. This response is the raw unprocessed data from the HIK API Server and represents the true data transmitted and received by the APi Client. 
   4. The response packet is JSON and is unformatted (one long string) and is in the body of the response. Copy this body to your clipboard and use an online formatter like https://jsonformatter.org/ to make the response easier to read.
   5. By inspecting the raw formatted JSON response, you can validate the values eventually stored in Eco Time and the HIK API Client.
3. How do you configure the HIK API Server in HIK Central?
   1. Download the demo tutorial from here: How to Configure OpenAPI V2.0.1 and Use OpenAPI Demo.zip