Comprehensive User Guide for API Configuration with Biometric Machines and Admin Tools – A First Time Setup Guide

Setting up the API integration with your biometric machine for the first time is a crucial step to ensure seamless communication between your device and your server. This guide provides a comprehensive, step-by-step walkthrough to configure the server endpoint, link your biometric machine to the API, and validate the data flow.

Whether you’re a developer or a system administrator, this guide will help you configure the necessary tools and settings to establish a robust and reliable connection. By the end of this guide, you’ll have the biometric machine fully integrated, pushing real-time data to your server, and ready to operate without errors.

Before diving into the configuration steps, please ensure that you meet the following prerequisites. These will prepare you for a smooth setup process.

Prerequisites

To ensure a seamless setup and integration process, please review and fulfill the following prerequisites:

1. API Documentation

If you plan to integrate the biometric machine with your own custom software, it is essential to:

• Review the Documentation:
  • Go through the Biometric Web API Documentation to understand how the API works and its capabilities.
• Understand the Data Structures:
  • Familiarize yourself with the Sample Request and Response Structures. This includes:
    • Callback URL Payloads: The format of data transferred from the biometric machine to your server via the callback URL.
    • RESTful URL Payloads: The format of data sent from your server to the biometric machine through the RESTful API.

2. Server Endpoint (Callback URL)

For custom integrations, ensure you have the following ready:

• A Functional Callback URL:
  • This is the server endpoint where the biometric machine will send real-time data (e.g., attendance logs).
  • Make sure the callback URL is accessible over the internet or your local network.

3. Biometric Machine

Ensure the biometric machine is properly set up and ready for integration:

• Physical Availability:
  • The biometric machine should be on-site and accessible for configuration.
• Network Connectivity:
  • Power on the device and connect it to the network via LAN or Wi-Fi.
  • Verify that it is online and can communicate with the server.

Pre-Integrated Products

If you are integrating the biometric machine with platforms like Zoho, BayZat, OrangeHRM, PalmHR, Razorpay, ERPNext, SAP, Odoo, or more similar products:

• Callback URLs Are Preconfigured:
  • You do not need to set up a callback URL manually. These platforms handle the configuration for you.
• No Need to Worry About Payload Structures:
  • Data formats and transfers are automatically managed by the respective integrations.

This streamlined process ensures minimal effort for prebuilt platform integrations.

By adhering to these prerequisites, you can ensure a smooth setup process, whether you’re building your own software integration or using a third-party platform.

---

Lets Get Started

Login into https://CamsBiometrics.com

Device Status Dashboard Overview

After a successful login, the Device Status Dashboard provides users with an overview and control panel for managing biometric devices.

1. Two views of device card

2. Device Status Summary

• Purpose: This view gives a high-level summary of all devices associated with your account.
• Key Features:
  • Status Filters:
    • All: Displays all devices.
    • Online: Devices currently active and connected.
    • Offline: Devices that are not reachable. Refer https://forum.camsbiometrics.com/how-to-bring-the-cams-biometrics-machine-online/ for resolving any connectivity issue in the hardware
    • Queued: Devices with pending actions.
    • Active License: Devices with valid, active licenses.
    • Expiring Soon: Devices with licenses nearing expiration.
    • Expired: Devices whose licenses have expired.
    • Add Verified Devices: Shortcut to add new verified devices.
  • Device Cards:
    • Each card represents a single biometric device, displaying its key details and status.
    • Buttons like “Renew Now” allow for quick license renewal for the expired or getting expired devices
    • Status indicators such as No Attendance, Offline, or Inactive provide insights into the device’s functionality.

3. Individual Device Details

• Purpose: Provides detailed information and actions for each device.
• Key Features:
  • Device Label and ID:
    • Each device is identified by a unique label and serial number.
  • Status and Actions:
    • Queue: Number of pending punches to push to the server.
    • Dispatched: Punches already sent to the device.
    • Received: Punches received from the device.
  • Status Icons:
    • Offline/Inactive: Indicates the device is not currently online.
    • No Queue: Confirms that there are no pending puches for pushing to the server.
    • Last Response: Displays the last response received from the downstream server.
  • Renew Now Button:
    • Allows users to quickly renew device licenses when required.

4. Advanced Device Management

• Purpose: For users who need deeper insights or actions for multiple devices.
• Key Features:
  • Detailed Status Updates:
    • Last connected time, license status, and API configurations.
    • Devices grouped by their current operational states (e.g., Offline, Expired).
  • Additional Options (Show More):
    • Clicking on “Show More” expands to display more detailed device information or configuration options.
  • Bulk Actions:
    • Renew or configure multiple devices directly from this dashboard.

Sidebar Navigation

• Organization Section:
  • Organization Info: View and manage organizational details.
  • Support: Access technical support for troubleshooting.
• Order Section:
  • Order List: Manage and review orders placed for biometric devices or licenses.
• Device Management Section:
  • Device Status: Current view showing the status and details of all devices.
  • API Log: Monitor API interactions and resolve integration issues.
  • Device List: Comprehensive list of all registered devices.
  • Device Command: Send specific commands to devices (e.g., reboot, update).
  • Group Device: Organize devices into groups for easier management.
  • Renew Service: Manage and process license renewals for one or more devices.

How to Use the Dashboard

1. Monitor Device Health:
   • Use the filters to quickly identify devices that need attention (e.g., Offline, Expired Licenses).
2. Perform Actions:
   • Use the “Renew Now” button to update licenses or the “Show More” option to configure devices.
3. Access Logs:
   • Use the API Log and Device List sections to troubleshoot issues or verify connectivity.
4. Group Management:
   • Group devices for specific branches or departments for better organization.
5. Restart Queue
   • Review the Last response and fix to ensure the response is valid as per the API document and then press restart queue to start pushing the data instantly or wait till the next scheduled queue restart time

The dashboard is designed to streamline device management, providing users with quick actions, insights, and advanced tools to maintain optimal operation. Let me know if you’d like to expand on any section or add a walkthrough!

Configuration Page Overview

This page allows you to configure and fine-tune your biometric device for integration with the server. Below is a breakdown of the key sections and settings:

Configuration Page Overview

This page allows you to configure and fine-tune your biometric device for integration with the server. Below is a breakdown of the key sections and settings:

1. Device Information Panel (Top Left)

• Serial Number:
  • Identifies the unique serial number of the biometric device.
  • Example: AIOR18510621.
• Label Name:
  • The custom label or name assigned to the device for easier identification.
  • Example: AIOR18486078.
• Client Name:
  • Displays the name of the client or organization associated with the device.
  • Example: Nalan Garments.

2. Machine Settings (Bottom Left)

This section defines the basic settings for the biometric device.

• Timezone:
  • Set the timezone for the device.
  • Example: (UTC+05:30) Chennai, Kolkata, Mumbai, New Delhi.
• Direction:
  • Determines how the attendance data is transmitted to the server.
  • Choosing the Right Direction Setting
    • Actual: Use when precise attendance states are needed without modification.
    • IN/OUT: Use when only one type of state (e.g., entry or exit) needs to be tracked.
    • Break IN/OUT: Ideal for managing specific events like breaks.
    • First is IN, Rest are OUT: Simplifies attendance data for single-shift environments.
    • ZigZag: Suitable for controlled environments with alternating entries and exits.
  • These options provide flexibility to meet various business or organizational requirements.
• Expected Time:
  • Displays the current time configured on the biometric device.
  • Example: 24-Nov-2024 15:40.
  • If the displayed time in the biometric device after setting correct timezone is incorrect, use the following options:
    • Adjust Time: Synchronize the device’s clock with the server’s time.
  • Enable DLS (Daylight Saving Time): Adjust for daylight saving time if applicable.

3. API Settings (Right Panel)

This section enables API-level configurations for integrating the biometric device with your server.

Callback URL

• Purpose:
  • Specify the server endpoint where real-time data (e.g., attendance logs) will be sent.
• Input Field:
  • Enter the Callback URL of your server or software.

Handle Response

• Toggle Option (YES/NO):
  • YES: Requires the callback URL to return a JSON acknowledgment (status: done) to confirm data receipt. If not received, the data will be pushed repeatedly until acknowledged in every 3 hours.
  • NO: Assumes successful delivery if the HTTP response code is 200 and does not validate the response message

Auth Token

• Purpose:
  • An authentication token sent with each request for secure communication.
• Generate Button:
  • Use this button to generate a unique token for the device.
• Copy Button:
  • Quickly copy the token for use in your server configuration.

Encryption Key

• Purpose:
  • Encrypt all communication between the device and the server using AES ECB 256 encryption.
• Input Field:
  • Specify the encryption key for secure data transfer. Leave blank if encryption is not required.

Origin IP

• Purpose:
  • Restrict requests to the biometric device from a specific IP address.
• Input Field:
  • During testing, you can set this to localhost. In production, replace it with the server’s public IP.

Management API Endpoint

• Details:
  • Lists the API endpoint used to manage the device.
  • Example:
    • https://robot.camsunit.com/external/XXXXXXX/biometric
• Reference:
  • A link to the API Documentation for additional details on endpoint usage.

Steps to Configure

1. Set the Timezone and Direction:
   • Ensure the correct timezone is selected, and the attendance direction is set as required.
2. Synchronize Time (if necessary):
   • Use the “Adjust Time” option if the device’s internal clock is incorrect.
3. Configure the Callback URL:
   • Enter the endpoint provided by your server to receive attendance data.
4. Set Up Secure Communication:
   • Generate and use an Auth Token.
   • (Optional) Enable encryption by setting an Encryption Key.
   • Specify the Origin IP to restrict access.
5. Enable Handle Response:
   • Toggle this option based on your server’s ability to return acknowledgment responses.