Genetec Agent Setup Guide

Introduction

About this Document

The HID Visitor Manager Genetec Agent document aims to provide information and instructions for configuring the HID Visitor Manager Genetec Agent for integration with the on-prem Genetec Security Center Systems. The documents also specify tools and techniques that are generally used to troubleshoot any problems that may arise during the integration. It uses a combination of high-level feature descriptions, representative screen images and specific sequences to perform configuration and integration of HID Visitor Manager with Security Center. 

Summary of Agent Functionality 

The agent, once configured, communicates with Genetec Security Center to achieve:

  • Master Data Import (e.g. clearances)

  • Propagation of Visitor, card and clearance details to Security Center (applies to HID Visitor Manager)

  • Note that Readbacks (Automatic Change Detection and Synchronization from the PACS) are currently not supported on the HID Visitor Manager platform

Intended Audience

It is expected that this guide will be used by administrative and technical staff during the integration of HID Visitor Manager with the Genetec Security Center system. In order to get the most from this guide, the readers should have an understanding and familiarity of:

  • The local computer environment at the site where Security Center is installed

  • HID Visitor Manager system, agents and Genetec Security Center systems and its components

Prerequisites

  • IMPORTANT: The agent works by communicating with the Genetec SDK (version 5.1 SR3) installed on the Genetec server. Make sure this is installed in the system.

  • IMPORTANT: The Genetec SDK, which the agent relies upon, requires Microsoft.CCR.Core assembly (Version=2.2.76.0) to be available in the GAC. It can be obtained from the Microsoft Robotics Developer Studio (refer to http://www.microsoft.com/en-us/download/confirmation.aspx?id=29081)

  • HID Visitor Manager account must be enabled with Genetec PACS subscription.

  • The Genetec SDK (the same version/release as the Genetec Server software) should have a licensed installation on the same server hosting the HID Visitor Manager Genetec Agent.

  • Make sure the license has a part number(GSC-1SDK-HID-Safe) corresponding to the Quantum Secure-Genetec Integration certificate.

  • Security Center should be installed and the software should point to an instance of SQL server (remote or local).

  • If there is no unique identifier for the cardholder in Genetec, UDF needs to be added on the cardholder so the agent can use it as an identifier field.

  • Genetec administrator has to closely work with the HID Visitor Manager deployment team to create an operator account in Genetec with appropriate permissions.

  • The HID Visitor Manager Genetec Agent will need to be able to access the Genetec system across TCP port 5500. Ensure that any relevant firewall rules are modified to allow this.

Finding the version of Genetec System

  • Click on the Config Tool option for the Genetec Security Center 5.x to see the version of Genetec (5.1 SR3).

    Version of Genetec System

Finding if the SDK is licensed

  • Log in to the Genetec Server Admin Console and then click the Directory tab in the main left side navigation.

  • Click on the License Information button, a License window appears.

    Finding if the SDK is licensed.png

  • In the License window, validate if WebSDK is supported –if yes then the Genetec Server is licensed to use the SDK to be able to connect to an external system.

    Genetec Server is licensed to use the SDK to be able to connect to an external system

Validate License Update

  • Log in to the Genetec Server Admin Console and then click the Directory tab in the main left side navigation.

  • Click on the 'License Information' button, a License window appears.

  • Click the Certificate tab to see license status.

    Validate License Update

Downloading the Agent Installer

  1. Log in to HID Visitor Manager portal using Visitor Administrator credentials

  2. Navigate to Settings app > Downloads

  3. Click the HID Visitor Manager Agent Installer link and save the file (OnPremAgentSetup.Zip)

  4. Install the HID Visitor Manager Agent installer by following the instructions in the next section

On-prem Installer Guide

The On-Prem agents will need to be installed and configured in a somewhat similar way as every other agent but will happen outside of the scope of the standard SAFE Application Server. Standard SAFE installation will not be required for such IOT Enabled On-Prem agents, and instead, the following installer will perform the requisite duties of initially installing the agent On-Premise. 

From a high level, the workflow of the installer will need to perform the following actions, and will do-so in the following order spelled out by the installation steps below.

System Requirements

Operating System: Windows 10, Windows Server 2016 Standard, or Windows Server 2019 Standard. 
NOTE: The OS must be synchronized with a valid NTP server.

RAM: 4 GB
Processor: Intel Core i3 @ 1.00 GHz
Hard Drive Space: 5 GB

Software: Microsoft .Net Framework 4.8 (https://dotnet.microsoft.com/download/dotnet-framework/net48)

Launch the Installer Application

The downloaded file (OnPremAgentSetup.zip) will need to be copied to the On-Prem server where the agent is intended to be run. From there, once extracted, the Installer Application (OnPremAgentSetup.exe) will need to be launched. The user will be presented with the following screen:

Run the Agent Installer file

PACS Specific Details will be Captured

Enter the HID Visitor Manager URL, Username and Password which is provided to log in to the tenant. Click Next  to continue.

Provide URL and credential details

Validate Operator Credential

When the operator enters the wrong credentials,the operator will be notified immediately and need to enter the correct credentials before trying again.

Invaild Credential Details

Select a System to Install

On this page, choose a PACS system to install from the dropdown menu as required. 

Select the Agent System from the dropdown as required

Specify Installation Path for the Agent

An installation path will be selected to install agent files. This allows the user to specify which directory they would like to install the agent. The default path is set to the standard agent installation location, alternatively, the user can click on the Browse button to select the directory to install, and agent files will be installed on that directory. 

Based on this path, the Windows Service entry for the agent will point to this location, if a custom directory was chosen. Click on the Nextbutton to begin the Agent Installation.

Select the Agent Installer path

Installation Process is Started

The next screen will show the progress bar, as well as the details of the steps being performed along the way. 

Installation Process is started

The steps that will be performed during this installation are as follows:

  • Prerequisite Checks will be Performed
    Based on the agent selected on the previous screen, a customized set of prerequisites will be performed for things such as .NET framework version installation, or other items specific to a given integration.

  • Generate Certificates for IOT Device Registration
    PK/CSR based on the system where this is running, and the agent being installed, will be generated.

  • Call Agent Registration Service
    The PK/CSR generated in the previous step will be used as input to this service, in order to generate and/or match up with the appropriate IOT device that will be used to broker communications between SAFE in the cloud, and the On-Prem service.

  • Extract Device Certificates and Store them into the Windows Certificate Manager
    The certificates relating to the IOT device for this agent will be parsed out of the response to the registration service and installed into the Windows Certificate Store. The AWS Root certificate will be installed in the Local Systems 'Trusted Root', and the actual device certificate will be installed into the Local Systems 'Personal' certificate store. 

  • Create Agent Folder
    The files required for the soon-to-be created service will be installed into the appropriate location on the local file system, based on the system to integrate, chosen on the previous screen of the installer. 

  • Create the Agent Service
    This is where we will create theWindows service (integrated agent) that will act as the communication point to the connected system. Such agents run as Windows services on the operating system and are responsible for processing requests sent from SAFE in order to translate them and provision the specified actions/data into the connected system.

  • Update the Registry
    Some Windows logging features/paths are stored in and loaded from the Windows Registry. These registry keys will be set up at this time, and are primarily used for logging purposes.

Installation Complete

When all of the above steps are completed, the user will be presented with the following screen indicating that the installation has completed successfully.

Note:

In the case of an error, the installer will proceed to the final screen, and details of the error will be presented in order tooutline what occurred. 

Installation has completeed successfully

Configuring Agent  

  1. Log in to HID Visitor Manager.

  2. Click App Launcher and select Settings app.
    Configure Genetec

  3. Click on the Configuration Manager link, the list of integrated systems appears.
    Configuration Manager

  4. Select the Genetec agent system and click the Advanced sub-tab.

  5. Configure the required settings under the Genetec SDK Configuration section.

    Genetec SDK Configuration

  6. Once the configuration is complete please start/restart the HID Visitor Manager Genetec Agent window service. Follow the below steps to navigate to services.

    1. Press Windows  +  R  keys.

    2. In the run dialogue box enter services.msc and click OK.

      Restart genetec service

Agent Verification 

This section explains how the access areas are synced from Genetec to HID Visitor Manager and how they get assigned to a Visitor.

Master Data Import for Access Area

Follow the below steps to verify master data (Access Areas) sync from Genetec to HID Visitor Manager:

  1. Once the Agent is started, navigate to Admin app > Audit tab.

  2. Search for Source as Genetec, it displays an entry for MasterDataFullLoad from Genetec to HID Visitor Manager with the Response as Success.

    Agent Verification

  3. Click on any audit record to open the audit details.

  4. Click on the Request sub-tab, it displays the CLEARANCE(Access Area) read as part of the master data load. Copy one of the Area Names.

    Master Data Import for Access Area

  5. Navigate to Admin app > Access Areas tab.

  6. Search for the Access Area copied from Audit, then it is displayed under Access Areas.

    Master Data Import for Access Area

     

Visitor Provisioning

This section explains how the visitor gets checked in and has access areas provisioned from HID Visitor Manager to Genetec.

Use the following steps to set up a HID Visitor Manager system with access areas imported from Genetec. 

  1. Add a location.

  2. Open Location record, in the Location Details sub-tab, select the Genetec that manages the location from the Managed By field.

    Select the Genetec that manages the location from the Managed By field

     

  3. Navigate to Location record > Preferences sub-tab. Make sure the Allow hosts to request for access for their visits planned for this location setting enabled.

    Allow hosts to request for access areas for their visit

     

  4. Click the Access Areas sub-tab. Search access areas by searching the system name as 'Genetec' and assign access areas for the location.

    Search access areas by searching the system name as 'Genetec'

  5. Click on the Visitor Default Access sub-tab and assign default access areas of the location. The Access Area added defined here can be assigned to a Visitor. Set access areas as Auto Request - the access area will be automatically requested for the visit. 

    Assign default access areas of the location

  6. Create a Visit by going to the Host a Visit quick link from Self Service app. Make sure Issue Access Card to Visitor is selected as Yes. Note that default Visitor Access Areas are visible at the bottom of the page.

    Pre-register a visit

  7. Check-in the visitor from Visitors app > Check-in tab. While checking-in the visitor, make sure to enter the Card Number.

    Check In the Visitor

  8. Navigate to Visitors app > Audit tab.

    1. You should see the Audit entry for the checked-in visitor from HID Visitor Manager to Genetec with the Response as Success. If the response is Pending, wait for few seconds and verify the status by refreshing the page.

      Status of Audit

Uninstallation

File Cleanup

In order to uninstall the On-Prem agent, you must simply delete the entirety of the installed agent folder from the file system at the path where the agent was originally installed.

Windows Service Cleanup

To remove the Windows service from the On-Prem system where the agent was installed, you must do the following:

  • As an administrator, open up a command prompt 'cmd.exe'

  • Run the command 'sc delete <<service name>>'

  • Refresh (or re-open) the Windows services dialog to see the service removed

Troubleshooting

This section provides steps to understand and resolve potential installation complications:

On-prem agent Logs: Use log located at C:\ProgramData\HID Global\SAFE\Common\Logs on agent installation machine to troubleshoot issues with Genetec agent. All Genetec agent-related log entries are stored in 'GenetecAgentLog.txt'.

Error 1 :General Installation Failure - GPO / Application Activation Error

On-Prem agent installation can fail due to some Windows permissions issues related to GPO (Group Policy) settings. The installation fails even when running as an administrator and an error can be seen only within Windows Event Viewer as shown below:

Error while installing On-Prem Agent

This error is caused by a Windows Server group policy configuration, prominently on Windows Server 2016 (but possibly on other versions of Windows as well). Follow the below step to resolve the issue:

  1. Press Windows  +  R  keys.

  2. In the run modal, enter gpedit.msc and click OK.

  3. Navigate to Windows Settings > Security Settings > Local Policy > Security Options.

  4. Locate User Account Control: Admin Approval Mode for the Built-in Administrator Account, and open the same.

  5. Under the Local Security Setting tab select  Enable.

  6. Click on Apply and OK to save.

Error 2: Audit Log

HID Visitor Manager application audit logs can be used to troubleshoot any issues as it logs all transactions that happen between HID Visitor Manager and Genetec. Refer the below screenshots to understand how audit logs can be used to troubleshoot issues. Navigate to Visitors app > Audit tab. On this you can search and filter for specific audit logs you need to analyze. You can search for messages from HID Visitor Manager to Genetec as well as from Genetec to HID Visitor Manager.

The below image shows the list of failed messages from HID Visitor Manager to Genetec.

How audit logs can be used to troubleshoot issues?

The system lists all the messages which have a status of Failure. You can drill down to the details by clicking on the Audit ID as shown below:

Audit Detail

If the Genetec agent successfully processed the XML message, then the result is returned and the response status is recorded as Success.

Error 3: Too many rows returned. Was expecting 0 or 1, but instead received ###

Reason #1

This error might occur when the configured identifier field on a person either does not exist as a valid UDF field within Genetec or the user you are connecting does not have permissions to read/write to this field within Genetec. Instead of the Genetec API throwing an error, it will instead ignore this field in the filter query (and hence return all users). In order to resolve this issue, please confirm that the MSSName of the personnel identifier field is configured within HID Visitor Manager as well as the UDF field within the DefaultValues.xml (located in the same folder as the agent DLL on the HID Visitor Manager Agent server) are correct.

NOTE:  UDF fields in Genetec are case-sensitive, so please ensure that in both locations, the case sensitivity EXACTLY matches that which is configured within Genetec.

Reason #2

This error might occur because the lookup of records in Genetec is performed by the API in a method similar to a 'contains' SQL query. For example, if a lookup is happening for a record with ID = '1', then the result will match every result that contains a '1' within it, such as '10', or '88810'. This means that the identifiers configured to be used within HID Visitor Manager must be 100% unique, such that no single persons identifier could possibly be contained within another user's unique ID. This frequently happens when using QSID as a VMS user's identifier, when QSID's start at a low value. 

Error 4: Errors due to incorrect mappings

Check the agent mappings in the web configurator Data Objects tab to make sure the case is correct for all the field names (e.g. a field name set to 'STATUS' may behave differently than if it were set as mixed case 'Status').