1 SAFR-Gallagher Integration Guide

1.1 Introduction

Integrated SAFR Gallagher is only available on Windows.

Deploying and configuring SAFR and Gallagher will allow SAFR to import Gallagher Cardholders and Credentials to be used on SAFR SCAN face authentication readers. SAFR SCAN is using the imported Cardholder picture, converted into a biometric signature, to verify a person identity when presented at a SAFR SCAN reader. When a person’s identity has been verified the SAFR SCAN reader transmits the imported Access Credentials to the access control panel via Wiegand or OSDP signaling.

Please note that SAFR will not import a person record if it does not have a card access credential. Likewise, if the access credential is removed from the cardholder, SAFR will delete the person record in SAFR. SAFR only supports one card access credential per person record. If multiple credentials exist, the most recently updated credential is imported.

To integrate and use the SAFR SCAN RTSP video feed in your VMS for surveillance please see the SAFR VMS Integration Guides.

This Guide does not include the Installation of the SAFR Server (SAFR Platform) or the Gallagher Command Centre. This guide specifically describes:

• Install and Configure SAFR Gallagher Integration Middleware.
• Configure Gallagher to allow SAFR server to import Cardholders and Access Credentials.
• Configure the External Identification Synchronization in SAFR server.

For complete SAFR and SAFR SCAN documentation please visit http://docs.real.com.

1.2 Integration Overview

A typical deployment requires the following:

• A machine running Gallagher Command Centre.
• A machine running SAFR Platform (Server and Desktop Client) and SAFR Gallagher Integration Middleware.

SAFR Server and SAFR Gallagher Integration Middleware perform a 1-way synchronization of Gallagher Cardholders and Credentials, and biometric signatures are created for all cardholders. SAFR Server distributes cardholders and credentials to all connected SAFR SCAN devices. SAFR SCAN devices then use the biometric signature to perform authentication of the cardholder using one or more authentication factors and passes the stored credentials to the panel. The panel evaluates access and optionally panel feedback is used to display feedback to cardholders.

2 System Requirements

2.1 Field Hardware

• Install reader data cables to cater for OSDP (or Wiegand) according to Gallagher system specifications to connect SAFR SCAN units to Gallagher Controller units.
• Take note that OSDP wiring differs from Wiegand wiring and this must be concluded in advance.
• OSDP connects to the GGL Controller and offers daisy chain where Wiegand requires H-Bus – Wiegand units for each (1/2) SAFR SCAN unit.

2.2 Software

• Windows 10 or later.
• Licensed Gallagher Command Centre version v9.
• Licensed SAFR Platform version 3.24 .
• SAFR-Gallagher Integration version 1.3.13 or later.

All applications can be run on the same computer or separate computers. Typically, SAFR Platform and SAFR Gallagher Middleware Integration can be run on the same computer.

2.3 Server Hardware

Gallagher has the following system requirements:

• Gallagher Configuration Client and optionally Gallagher Command Centre applications.
• Additional system requirements as described in the Gallagher documentation.

SAFR has the following system requirements:

• Machine running SAFR Platform (Server and Desktop Client) for SAFR SCAN units meeting the following requirements:
  • Windows 10 or later.
  • CPU with 4 available cores of 2.5 GHz of greater (i5 or faster).
  • 8 GB of System RAM minimum (16 GB recommended, more as needed).
  • SAFR Platform version 3.20 or later (in point 2.1 it is quoted as v 3.24).
  • SAFR Gallagher Integration Middleware version 1.3.13 or later.

2.4 Networking Requirements

Following network connections are required between services.

From	To	From Port	To Port	Transport
SAFR Gallagher Integration Middleware	Gallagher server	-	8904	tcp
SAFR Gallagher Integration Middleware	SAFR Platform Server	-	8080	tcp

• Ports may be customized on either SAFR or Gallagher servers.

2.5 Photos

Gallagher user must have a photo added via the Custom.

Following are guidelines to ensure accurate facial matching. Reduced quality will work but may not produce reliable results.

1. Face Size: At least 150px wide from ear to ear (220px photo frame).
2. Center pose: Face gaze within 30° of camera lens.
3. Contrast: Sufficient and uniform lighting on face.
4. Occlusion: No significant occlusions.

2.6 Licensing

2.6.1 Gallagher Software Licensing Requirements

SAFR-Gallagher integration uses the Gallagher REST APIs. The integration requires Cardholders and Alarms & Events APIs. Contact your Gallagher Account Manager for details on acquiring a license.

To use this integration, ensure the following license strings for a site to be able to use it:

• RESTCardholders=1
• RESTEvents=1

Contact Gallagher for these licenses.

2.6.2 SAFR Gallagher Integration Middleware Licensing Requirements

SAFR Gallagher Integration Middleware requires a license key. Contact your SAFR Account Manager for details on acquiring a license.

3 Install and Configure the Gallagher Command Centre

Following, configuration is performed in Gallagher Configuration Client.

3.1 Verify License Features Enabled

1. Go to File Menu > Server Properties
2. Go to Licensing > Features
3. Make sure following enabled.
   1. RESTCardholders
   2. RESTEvents (if you need events output)
4. Contact Gallagher if these features are not enabled
5. Go to Web Services page (Menu > File > Server Properties > Web Services)
   1. Check Enable Local Network Connections from REST API section.
   2. If SSL Certificates are not used, check “Enable REST Clients with no client certificate” (recommended for initial configuration).
   3. Save the Server Base Port (8904) for use during SAFR Gallagher Integration Middleware Installation.

3.2 Create new REST Operator

1. Create API Operator User.
   1. Go to Manage Menu > Cardholders.
   2. Right click and choose New > Cardholder.
   3. Provide a first and last name (this guide uses “API Operator”).
   4. Save the new Cardholder.
   5. Leave the Cardholders window open for use in step below.
2. Create API Operator Group.
   1. Go to Manage > Operator Groups.
   2. Right click and chose New > Operator Group.
   3. Provide a name (this guide uses “REST Operator”).
   4. In the Cardholders (Operators) page, drag the “API Operator” Cardholder from Cardholders window into the newly created “REST Operator Group.
   5. Click on the Operator Privileges page.
   6. Open Operator Privileges from Manage Menu.
   7. Drag following two privileges into the REST API Operator Operators Privileges list:
      1. Advanced User.
      2. Launch Configuration Client.
   8. Save the new Operator Group.
3. Create REST Client.
   1. Go to Configure Menu > Services and Workstations.
   2. Right click and choose New > REST Client.
   3. Provide a name (this guide uses “REST Client”).
   4. Go to API Key page.
   5. Select Rest Client created above in the REST Client Operator dropdown (name will be “API Operator”).
   6. Delete the “Client Certificate Thumbprint”.
   7. Save the API Key for use during SAFR Gallagher Integration Middleware Installation.

3.3 Create Access Group and Access Zone (or use existing relevant Group and Zone)

1. Create Access Group
   1. Go to Manage > Access Groups
   2. Right click and select New > Access Group
   3. Provide a name. Do not limit schedule (this guide uses “All Doors All Zones”).
2. Create Access Zone for SAFR SCAN related zones.
   1. Go to Configure Menu > Access Zones
   2. Right click and select New > Access Zone
   3. Provide a name. Do not limit schedule (this guide uses “SAFR OSDP Reader Zone”)
   4. Go to Access Mode and select “24/7 Secure No PIN” (or an existing appropriate Schedule) Schedule
3. Open “All Doors All Zones” Access Group and go to “Access” page.
4. Drag both Access Zones created above into the Access Group and select the appropriate Schedule.

3.4 Create Cardholder Properties

By default, Gallagher does not include a custom field attributes that are synchronized to SAFR. The most important of which is the photo. These fields must be added to Gallagher and then assigned to the can edit this field within either Gallagher itself or another application, ensuring that the name remains consistent. (If you have an existing Photo field with photos allocated to Cardholders but it doesn’t meet the minimum resolution requirements, you’ll need to create this new Photo and allocate it to the SAFR SCAN related access doors.)

1. Go to Configure Menu > Personal Data Fields (PDF).
2. Right click and select New > Personal Data Field.
3. Set the field name to “Photo”.
4. Go to the Type page and set type to “Image”.
   1. Image frame Width: 220px (150px face).
   2. Image frame Height: 220px.
5. Go to Group Membership page.
6. Open Access Groups Window.
7. Drag the Access Group (“All Doors All Times”) into the Group Membership list for the new photo Personal Data Field.
8. Save the new photo Personal Data Field.
9. Repeat above steps as desired for following fields (these are optional).
   1. Company Name (Type=Text).
   2. Phone (Type=Phone).
   3. Email (Type=Email).
10. Record the names used for each field. You will need these later for the SAFR Gallagher Middleware Integration Configuration File.
11. Add Properties to Access Group
    1. Go to Manage Menu > Access Groups
    2. Open the “All Doors All Times” Access Group created above.
    3. Go to Personal Data page.
    4. Open Personal Data Fields window from Configure Menu.

3.5 Reader Configuration

This section describes basic configuration to add a SAFR Reader to Gallagher. Consult Gallagher documentation for further details.

3.5.1 Create a Card Type

SAFR has been configured and tested with Wiegand Card Type. Below describes creating a basic card type for use with SAFR SCAN. As part of the Card Type setup, a facility code is defined.

1. Create a Card Type for SAFR.
   1. Go to Configure > Card Types.
   2. Right click and select New > Card _Type.
   3. Enter a name (this guide uses “SAFR”).
   4. Open Setup page.
      1. Enter Region Code “A”.
      2. Enter Facility Code value desired (must be <255 for Wiegand-26 format).
      3. Range should be set appropriately for card format used (e.g. Wiegand-26 supports 1 to 65535).
   5. Save the new Card Type.
2. Create Card Format for SAFR (Optional – Alternatively use existing format such as “Wiegand 26/8 bit”).
   1. Go to Configure > Universal Card Formats.
   2. Right click and choose New > Universal Card Format.
   3. Provide a name (for this guide we will use “SAFR”).
   4. Open Format page.
   5. Enter the desired format. In example below, Wiegand-26 is defined in lab tested example below:
      
   6. Save the Universal Card Format

3.5.2 IF THIS IS A NEW SITE, Create a Controller, Door and Locks for SAFR Reader

Otherwise connect to the existing Controller, Door and Locks.

Refer to Gallagher documentation to create a Controller, Door and Lock for the SAFR reader. SAFR readers support either Wiegand or OSDP with Gallagher Panels. Wiegand connection requires a Gallagher Wiegand Module.

1. Go to Configure > Hardware
2. Create a new Controller and Indicate the controller SAFR will be connected.
   1. Open Controller and set following
      1. Outputs
      2. HBUS Devices
      3. OSDP Devices
      4. Card Formats

4 Install and Configure SAFR

1. Go to the SAFR Download Portal.
   1. To acquire SAFR credentials, log a call with SAFR Distribution agent to initiate SAFR account process.
   2. You can use a SAFR SCAN license to acquire login details for SAFR Platform.
      1. Provide a SAFR SCAN MAC Address to the distribution agent for account processing.
2. Download and install Windows SAFR Platform.

• When installing SAFR Platform, at “choose component” section, open “SAFR Peripheral Sub-systems” and deselect “SAFR Video Recognition Gateway (VIRGO)”. (If only using SAFR SCAN units on this server)

• Next, scroll down to “GPU Support” and deselect “GPU Support”.

• Click “Install” to continue.
• When installing the SAFR Platform, the default SAFR port assignments sometimes conflict with other software port assignments. If a port conflict occurs, the error message shown below will pop up in the middle of your installation.

If this happens, do the following:

1. Click OK to edit port configurations.
2. Notepad will open, displaying the safrports.conf file.
3. Edit any conflicting ports to new values. (e.g. CoviHTTP=18080)
4. Save and exit Notepad.

The Platform installer will then restart, and the new port values will be used. You can find the modified safrports.conf file at C:\Program Files\RealNetworks\SAFR\.

After the installation finishes, two icons will appear on your desktop: one labeled SAFRActions and another labeled SAFR. SAFRActions launches SAFR Actions, while SAFR launches the Desktop Client. The SAFR Server (when installed as part of a local deployment) automatically runs as a collection of background services.

Immediately following installation, the installer opens the Desktop Client and prompts you to log in with your SAFR Account credentials. Make sure to log in, it’s important in acquiring the SAFR license.

5 Install and Configure SAFR-Gallagher Middleware

Run the SAFR-Gallagher Middleware Integration installer. (File will be supplied along with integration license purchase)

Filename: SAFR-Gallagher-HLI_1_3_13.exe

Important Installation wizard inputs are described below.

• Use your SAFR Account credentials for SAFR ID and SAFR Password. These are the credentials you use to sign into SAFR Server.
• App License Key is obtained from RealNetworks. This is required for installation to proceed.
• Other settings can be left default

• Check “Remove region code from Facility Code” and “For SAFR SCAN” for use with SAFR SCAN.
• Leave SAFR Covi Server and SAFR Event Server default unless SAFR is running on different computer or SAFR ports have been customized. (See below)

• Leave Gallagher API URL default unless Gallagher is running on a different computer or Gallagher REST API Port is not default. REST API Port is defined in Gallagher Configuration Client > File Menu > Server Properties > Web Services tab under REST API > Server Base Port
  • Note: Make sure Enable REST Clients with no client certificate is checked if not using SSL Certificates.
• Gallagher API Key is the key associated with the REST API user created above. See Create New REST API Operator above. The value is a 32 character GUID separated by dashes as shown above.

• Select the default Gallagher Card Format for use with Gallagher

Remaining screen allows selection of the file location.

5.1 [OPTIONAL] Set Cardholder Properties to Import

Open SAFR Gallagher Middleware Integration Configuration file (see below)

Update the following with the names of the Personal Data Fields set above.

# JSON key definition for A personal data.

gallagher.json-photo-key=Photo

gallagher.json-company-key=Company Name

gallagher.json-email-key=Email

gallagher.json-phone-key=Phone

5.2 [OPTIONAL] SAFR Gallagher Middleware Integration Configuration File

Modifications to the SAFR Gallagher Middleware Integration are performed by editing the application.propertiles file located in C:\Program Files\Geutebruck Pacific\SAFR-Gallagher-HLI\config\.

After editing this file, restart the Windows “SAFR-Gallagher-HLI” Service for changes to take effect. If changing settings that impact imported person records, delete existing person records already imported from Gallagher before restarting service.

Image Quality Configuration

The following settings allow control over what photos will be imported based on image quality. If photo does not meet indicated minimum threshold, then photo is not imported.

safr.min-cpq=0.35

safr.min-fsq=0.35

safr.min-fcq=0.35

safr.max-occlusion=0.50

#minimum image size of the face detected.

safr.min-detect-face-size=-1

safr.min-insert-face-size=-1

Minimum detection threshold affects the ability of SAFR to detect faces in the scene.

#0 is system default.

safr.faces-detect-threshold=0

SAFR SCAN specific settings.

# Following configuration should be enabled for SAFR-Scan

# Moniker will be a 'facility-code'

safr.access-origin=Gallagher

safr.home-location=Gallagher

safr.use-moniker=true

• Set above properties as shown unless instructed otherwise.

Set the following to customize delete person operations.

#Delete user if user or card expire

safr.delete-user-or-card-expired=true

#Gallagher doesn't provide delete cardholder information via Event API.

# second, minute, hour, day of month, month, day(s) of week

gallagher.cardholder-resync-scheduled=0 * * * * *

• Scheduled uses standard UNIX cron format

Customize card types

#If you want to use specific card type for facial recognition.

# Comma Separated List

gallagher.card-type-names=

# It should be applied for same timezone only

gallagher.card-validator-expiry-date=true

Define person data fields mappings

# JSON key definition for A personal data.

gallagher.json-photo-key=Photo

gallagher.json-company-key=Company Name

gallagher.json-email-key=Email

gallagher.json-phone-key=Phone

Modify gallagher.ignore to skip users who are not cardholders. If REST API operator is named otherwise, change name below.

#It should number format and the cardSerialNumber (don�t use the latter with the FTCAPI)

gallagher.use-card-number=true

gallagher.ignore-user-names=REST, System Operator

More SAFR SCAN Specifci settings

# Following configuration should ONLY be enabled when using SAFR SCAN

# Wiegand-26, Wiegand-32, Wiegand-35,

# HID-Prox-HID0008P

# RFID-ISO14443-A, RFID-ISO14443-A-32-Bit, RFID-ISO14443-A-56-Bit

# MIFARE-Classic-1K, MIFARE-Classic-4K, Raw-Card-ID

# Custom

gallagher.card-format=Wiegand-26

#

gallagher.card-for-safr-scan=true

gallagher.card-delimiter-for-facility-code=-

gallagher.remove-region-code-from-facility-code=true

# If the facility code save in hex code

gallagher.use-numeric-for-facility-code=false

6 Troubleshooting

6.1 Logging

Application errors for the SAFR Gallagher Middleware can be viewed in the following log files. It’s a good idea to review the Application and Service Error logs after initial installation.

All log files are in C:\Program Files\Geutebruck Pacific\SAFR-Gallagher-HLI\logs

6.1.1 Application Log

Contains errors related to sync activities.

Filename: app.log

6.1.2 Service Error Log

Contains errors related to the background windows service.

Filename: service-error.log

6.2 Gallagher Event Viewer

Gallagher Event Viewer can be helpful in viewing communication from SAFR reader to the Gallagher Panel or REST API errors. To open the Event Viewer, go to Monitor > Event Viewer.

7 SAFR SCAN Settings Guide

7.1 Add SAFR SCAN To SAFR Platform

1. Connect to SAFR SCAN via IP address via Web browser and upon first login, you will set password.
2. Login again on next page using the new password.
3. Link up SCAN unit with SAFR Platform
   1. Navigate to System -> SAFR Server
   2. Add IP address and Login details of the SAFR Platform Server
      1. Change ports if needed.

3. Click “Connect” and once connected, Server status will change to “OK”.

7.2 SAFR SCAN OSDP Connection Guide

• To locate SCAN units, in SAFR Platform Software, navigate to “Tools > Video Feeds”

• To the right of the scanner that you want to edit OSDP settings, select the action button menu.
• Select “Edit Operation Settings…”

• Navigate to “Card Format” and set “Card Format” to WIEGAND-26.

• Navigate to “OSDP” and set to Enabled.

• Verify Baud Rate is still default 115200 and Apply.

• Enable “OSDP feedback from Control Panel”.

• Once enabled, change “Access Feedback Timeout” from 350 ms to 500 ms. Then select “Apply”.
  • This is to ensure that the SAFR SCAN LED feedback colours match the Gallagher Access Granted/Denied statusses.

• Overview of OSDP settings.

7.3 Gallagher Settings Overview

1