Integration with 
 
Suprema BioStar
 
 
 
 
Implementation and Deployment Guide
 
 
 
 

PGMSSBS-4_40SP1-ICG-EN-V1_0 created April 2021 © PACOM Systems

Disclaimer
PACOM Systems Pty Ltd makes no warranty of any kind with regard to this product, including, but not 
limited to, the implied warranties of merchantability and fitness for a particular purpose. PACOM 
Systems Pty Ltd shall not be liable for errors contained herein or for incidental consequential damages 
in connection with the furnishing, performance, or use of this product. This document contains 
proprietary information and is protected by copyright. The information contained within this document 
is subject to change without notice. The PACOM website (www.pacom.com) contains the latest 
documentation updates.

Some options, compliance claims or procedures described herein may not be supported if old versions 
of device firmware and/or software is used.   

Copyright notices
No part of this work may be reproduced, transmitted, transcribed, stored in a retrieval system, or 
translated into any language in any form by any means without the prior written consent of PACOM 
Systems Pty Ltd.

Compliance and accreditations

PACOM products comply with Advanced Encryption Standard (AES) FIPS 197 (encryption version 1.1).

Underwriters Laboratories Inc. (UL) and Intertek Electrical Testing Laboratories (ETL) are product 
safety standards/accreditors for North America. Product samples are tested to certain safety 
requirements, and periodic checks of the manufacturers' facilities are done.    

Software license notice

Your license agreement with PACOM Systems Pty Ltd, which is included with this product, specifies the 
permitted and prohibited uses of the product. It is protected by Australian and international copyright 
laws and international treaty obligations. Your rights to use the Software are limited by the terms 
stated below, and your use of the Software indicates your acceptance of these terms. If you do not 
agree with them, you must return, delete or destroy all copies of the Software.

Your rights to use the Software terminate immediately if you violate any of the following terms:

 l Any unauthorized duplication or use in whole or in part, in print, or in any other storage and 
retrieval system is forbidden.
 l You may not reverse-engineer, disassemble, decompile, or make any attempt to discover the 
source code of the Software.
 l You may not modify the Software in any way whatsoever.

Trademarks
All trademarks, brand and product names are the property of their respective owners.

PACOM Support
For product support, go to the PACOM Support Portal (support.pacom.com).   
.

PGMSSBS-4_40SP1-ICG-EN-V1_0 created April 2021 © PACOM Systems

Table of Contents

Disclaimer 2

Overview 5

Functional Overview 6
Deployment Scenario 6
Single Factor and Dual Factor Authentication 7
BioStar Concepts of Access Control 7
Mapping Between GMS and Suprema Domains 8
GMS Cardholders - BioStar Users and Cards 8

Suprema Terminals 11
Sites 13
Time Zones 13
User Groups 13
Bulk Operations 13
Audit Log 14
Reporting Cardholders Without Biometric Data 16

Implementation Overview 18
Integration Components 18
Proxy 18
Listener 18
Extender 18

Prerequisites 19
Availability of Files 19

Installation and Configuration 20
BioStar Setup 20
Configuring MariaDB for External Access 20
Other Tasks 21

GMS Setup 22
Add a Suprema Reader Type 22
Add a Special Stored Procedure 22
Add Suprema Doors to Site Maps 22
Enforce PersonalID uniqueness 22

Proxy Service Setup 23
Create the Service 23

Disclaimer
Implementation and Deployment Guide - GMS-BioStar Integration v1.0 3
 Install the BioStar Service HTTPS Certificate 24
Create an ODBC DSN for the BioStar Database 25
Configuration 26

Listener Setup 27
Configuration 27
Configure the OnNewCard Behavior 27

Extender Setup 29
Configuration 29

Configure Card Conversion Between GMS and BioStar 29
Verifying the Conversion Rules 32

Hints and Tips 33
Deleting Cards 33

Troubleshooting 34

Disclaimer
Implementation and Deployment Guide - GMS-BioStar Integration v1.0 4
Overview
The integration between PACOM GMS and Suprema BioStar enables GMS cardholders and their access 
cards to be registered (manually and automatically) with BioStar to capture and authenticate 
biometric data using facial recognition and finger scans. 

Once a person is registered, they can be authenticated by a biometrics terminal. The authorization is 
performed by PACOM Controllers.

Overview
Implementation and Deployment Guide - GMS-BioStar Integration v1.0 5
Functional Overview

Deployment Scenario

A single BioStar Server manages several Suprema Biometrics terminals. The integration interacts with 
the terminals through the API, but not directly. 

The integration is designed for environments where Suprema terminals connect, as a Wiegand card 
reader, to PACOM Controllers. A door is wired to a PACOM Controller. In the above diagram, there is a 
physical door where a Suprema biometrics terminal is used for controlling access, which is connected 
to a PACOM Controller. 

The integration creates users and cards within the BioStar system, which represent GMS cardholders 
and their cards. The information flow is from GMS to BioStar.

When a user is authenticated, a terminal sends the card code to the controller. A PACOM Controller 
executes all the relevant checks (time zone, card status, etc) and authorizes access. The controller 
maintains ultimate control over the user authentication decision.

If a door is wired directly into a Suprema terminal (for example, Suprema Terminal Y in the above 
diagram), with the terminal making the authentication and authorization decisions, so there is no 
need for this integration. The integration does not support mapping from GMS time zones, GRGs and 
GAGs into BioStar access control items. In this case, it is your responsibility to maintain access control 
using BioStar.

Functional Overview
Implementation and Deployment Guide - GMS-BioStar Integration v1.0 6
Single Factor and Dual Factor Authentication
A Suprema terminal can be configured for:

 l single factor (bio)
or

 l dual factor (card + bio) - a terminal uses a built-in card reader.
authentication.

There is no reason to combine Suprema's terminal biometric capabilities with a PACOM Controller for 
dual factor authentication to read a card; as Suprema terminals natively support dual factor 
authentication.

BioStar Concepts of Access Control
BioStar's access control is based on:

 l a door has a 1:1 association with a terminal.
 l DoorGroup (DG) is a group of doors.

A door can only belong to one door group.

 l UserGroup (UG) is a group of users.

A user can only belong to one user group.

 l AccessLevel (AL) contains one or more {door group : schedule} pairs.
 l AccessGroups (AG) associate one or more access levels with one or more user groups.
So to give a user access to a particular door, there must exist an AccessLevel referencing the door's 
DoorGroup, as well as an AccessGroup which pairs the AccessLevel with the user's UserGroup.

Recommendations
We recommend the following approach to make the integration environment simpler to manage. 

Assume that a customer has 3 specific areas:

 l Armoury
 l IT Server Room
 l Common Area
with certain people who require access to these areas.

Functional Overview
Implementation and Deployment Guide - GMS-BioStar Integration v1.0 7
  1.  Create an Always schedule.

It does not have to be 24hoursx7x365; but realistic. It should cover times when people really 
can go through any of the Suprema protected doors.

 2.  Create dedicated DoorGroups for DG_Armoury, DG_IT and DG_Common.
 3.  Create UserGroups (which can initially be empty) for UG_ARMS, UG_IT, UG_Common and 
UG_DELL.
 4.  Create AccessLevels combining DoorGroups with the Always schedule for AL_Armoury, AL_IT 
and AL_Common.
 5.  Create a single AccessGroup called PACOM.

AccessLevel UserGroup
AL_Armoury UG_ARMS

AL_Common UG_ARMS

AL_IT UG_IT

AL_Common UG_IT

AL_Common UG_Common

AL_IT UG_DELL

Note: All these steps only need to be done once, usually during deployment.

Mapping Between GMS and Suprema Domains

GMS Cardholders - BioStar Users and Cards

A GMS cardholder can be optionally associated with a BioStar user. This is a 1:1 association, with the 
cardholder's PersonalID used as a unique reference.

The uniqueness of the PersonalID is enforced by GMS. GMS v4.40 SP1 and later includes this as a 
built-in feature. For GMS versions v4.40 and earlier, a special validator must be used.

Functional Overview
Implementation and Deployment Guide - GMS-BioStar Integration v1.0 8
The integration automatically creates a new BioStar user when a GMS cardholder is first registered 
with BioStar. The registration can be triggered explicitly by an operator using the Extender or 
automatically by the Listener. A new BioStar user is not created if a BioStar user with the same 
PersonalID already exists.

The following infomation will help you understand the principles of the integration approach.

Cards
In GMS:

 l A single cardholder can have one or more cards.
 l A cardholder cannot be created without having at least one card.
 l Cards do not exist independently from cardholders. This means that you cannot have a card that 
is not associated with a cardholder.
In BioStar:

 l A user can have zero or more cards.

On successful biometric authentication, a Suprema terminal reports the first card registered with 
the user. When authenticated by access card + biometrics, a Suprema terminal reports the 
actual card.

 l Cards exist independently from users.
 l A card must be created first, before it can be associated with a user. 
 l A user can exist without having a single card.
Once a BioStar card is created, it remain in BioStar. It is not possible to delete a card from the BioStar 
system. A workaround solution is to purge the card directly from the database. 

When required, the integration automatically creates a new BioStar card representing a GMS card. A 
newly created card is automatically associated with its user. 

Note: The integration never creates a BioStar card without it immediately being associated with 
an existing user.

A new BioStar card is created when:

 l a GMS cardholder is first registered with BioStar.

This can be a manual operation (using the Extender) or an automatic operation (using the 
Listener).

 l a registered GMS cardholder is issued with yet another card (re-issued, replaced).

This can be a manual operation (using the Extender) or an automatic operation (using the 
Listener).

Re-issued (linked) cards

When registering a new user from the Extender interface, an operator can select to create BioStar 
cards for every card that belongs to this cardholder.

A BioStar card is created regardless of whether a GMS card has access to a Suprema door or not.

Functional Overview
Implementation and Deployment Guide - GMS-BioStar Integration v1.0 9
Alternatively, a specific cardholder's card can be associated with the corresponding BioStar user 
within the Extender interface, by clicking Add.

A new BioStar card is created for a new re-issued GMS card by the Listener if it is configured to 
automatically create new cards for existing cardholders.

Replacement cards
In GMS:

 l A replaced card is when a broken, lost or stolen card is replaced by another card. A replaced 
card is marked as such in GMS and blocked in RTUs.
 l A replacement card is a newly issued card.
If the Listener is configured to do so, it will automatically create a new BioStar card for a replacement 
card. The replaced card is automatically removed from the user's cards list.

Deleting cards and users

When a card is deleted from GMS, the associated BioStar card is automatically removed from the 
user's list by the Listener. If the user is left with no cards, then they will be automatically deleted by 
the Listener.

A BioStar card can be deleted using the Extender interface. In this case, the BioStar user remains 
even if they have no cards left.

Functional Overview
Implementation and Deployment Guide - GMS-BioStar Integration v1.0 10
Blocking / unblocking cards and users
A BioStar user has a status of enabled/disabled. A disabled user will not be authenticated by Suprema 
terminals.

A status of a blocked / unblocked GMS card is reflected by the BioStar card's status.

 l Block card - added to the Blacklist Card list, but remains associated with the user.
 l Stolen card - de-associated from the user and added to the Blacklist Card list.
 l Broken card - de-associated from the user.
 l Expired card - rejected by the PACOM Controller, so there is no need to change the card status / 
association within BioStar. When the card is finally deleted from GMS, it will be de-associated 
from the user.
 l Restored to valid - included and associated with a user.
It is also possible to block / unblock a BioStar user without changing the status of a GMS card. The 
Extender interface displays an Enable / Disable button which is only visible for existing users. The 
status of the button reflects the current user's status.

Suprema Terminals
An AccessControl terminal is a Suprema device used for access control.

An Enrollment terminal is a Suprema device used for capturing and enrolling user's biometric data into 
the system.

Note: A Suprema terminal must be explicitly configured as an Enrollment terminal.

The same terminal can be used for both AccessControl and Enrollment.

In GMS, every AccessControl terminal must be represented by a special reader type on a site map.

 l The reader represents both the terminal and the associated door.
 l Suprema must be selected as the reader's Model.

Functional Overview
Implementation and Deployment Guide - GMS-BioStar Integration v1.0 11
  l The reader's Serial No. must be set to the terminal ID.

To enable an association between a GMS cardholder and BioStar user, the cardholder's card GAG must 
reference at least one Suprema door. 

Suprema terminal online / offline status

GMS shows the Online / Offline status for those Suprema terminals which are represented as readers 
on site maps. The Listener periodically polls the BioStar server to obtain the status.

When GMS starts up or when the Events Publisher restarts, GMS receives a separate Online / Offline 
message for every Suprema reader. The message is received even if the status remains the same as it 
is already known to GMS. A message is also generated when a terminal's status changes.

It is possible to add / delete Suprema readers from GMS site maps without having to restart the 
Events Publisher.

The same reader can be placed on multiple site maps (for example, the main map and an area map).

Security critical terminals

The integration periodically polls the BioStar audit log to inform GMS operators about security critical 
events that happen at Suprema door locations. It is possible to configure the polling logic to accept 
only certain event types if they originate from a 'security critical' terminal.

To designate a terminal as security critical, add an exclamation mark !, anywhere to the reader's 
Location field.

Detecting and representing terminal tamper conditions

Terminal tamper can only be detected by retrieving events from the BioStar log. The event codes are 
16384 (ON) and 16640 (OFF). The integration handles these events and injects card reader tamper 
notifications to GMS.

Functional Overview
Implementation and Deployment Guide - GMS-BioStar Integration v1.0 12
Sites
BioStar does not have a concept of sites. So the number of GMS sites in a deployment does not 
matter. It is not a requirement that all Suprema readers are located within the same site.

Time Zones
There is no correlation or association between GMS time zones and BioStar schedules.

User Groups
A UserGroup is a critical attribute of a user and a mandatory parameter when a user is created. 

The integration supports a phonetic correlation between the cardholder's department or UserType and 
the suggested / default BioStar UserGroup.

 l If a cardholder's department is DDD, and there is a BioStar UserGroup called Department_DDD, 
then this UserGroup is used as the default for a new user.

The Department part of the UserGroup name must be in English.

 l If by_department matching does not produce a result - if the cardholder's UserType is UUU and 
there is a BioStar UserGroup called UserType_UUU, then this UserGroup is used as the default 
for a new user.

The UserGroup part of the UserGroup name must be in English.

 l If by_department and by_userType matching does not produce a result, use the GMS_Default 
group as the default for a new user.
The Extender interface contains a list of available BioStar UserGroups. For a new user, the list is 
automatically set to a group which is considered the default for the user. The operator can change it to 
another UserGroup.

The Listener uses this same logic for choosing a UserGroup, when creating a new user.

Bulk Operations
There are 3 ways to perform bulk operations:

Bulk enroll by the list

It is possible to enroll multiple cardholders in a single operation which is available from the Extender 
interface.

Functional Overview
Implementation and Deployment Guide - GMS-BioStar Integration v1.0 13
Click Bulk enroll to be prompted for a CSV file. Typically the file is generated by exporting GMS card 
search results.

Properties of the CSV file:

 l The file must contain entries with the cardID in the first column.
 l The file can have a single line header. This is skipped if the first token does not follow the cardID 
format of code / issue / facility.

Bulk enroll by relevance

Tip: This is not currently available in v1.0.

The integration scans the GMS database for all relevant cards - those that have at least one Suprema 
reader in the access profiles. Then enrolls both the users and cards that are not yet enrolled.

Bulk enroll by irrelevance

Tip: This is not currently available in v1.0.

The integration scans the GMS database for all irrelevant cards - those that do not have any Suprema 
readers in the access profiles. Then un-enroll.

Audit Log
GMS TxLog displays card swipe notifications generated by Suprema terminals connected to PACOM 
Controllers.

A notification is generated by Suprema terminals only if a user is successfully authenticated. A 
terminal does not send Wiegand data if authentication failed (unless the terminal is configured to work 
in bypass mode). 

Tip: In bypass mode, a terminal sends card data every time a card is badged. But bypass mode 
cannot be used for dual-factor authentication.

Functional Overview
Implementation and Deployment Guide - GMS-BioStar Integration v1.0 14
Specifically:

 l it is not possible to view (in real-time, in GMS TxLog) invalid card swipes on Suprema terminal 
readers when a terminal runs in card + biometrics mode.
 l it is not possible to view (in real-time, in GMS TxLog) when authentication failed due to a 
mismatch between a card and a biometric.

Accessing BioStar logs

The BioStar server retains audit logs which can be viewed and exported into a file, using the web 
interface.

The integration periodically (at least once every 10 seconds) polls the BioStar audit log. If there are 
any security related events logged since the last poll, it forwards the messages to GMS.

Certain events are processed regardless of their source terminal. Other specific events are processed 
only if they originate from a security critical device. 

The following table lists the possible errors:

Is Is
Security
cardI UserI
Event critical Trigger
D D Mapping Comments
code or any condition
know know
device
n? n?
640 ACCESS_ Any A  No Yes txBlocked Lookup 
2 DENIED_ disabled  cardID by 
DISABLED user  user's ID 
presents  (PersonalI
their  D). Use 
credenti the first 
als card that 
matches 
this user.

640 ACCESS_ Any An  Yes Yes txExpired  

3 DENIED_ expired 
EXPIRED user 
presents 
their 
credenti
als.

640 ACCESS_ Any An  No No txBlocked for a  cardID or 

4 DENIED_ excluded  fake card. userID are 
ON_ card. not 
BLACKLIS reported 
T even 
when a 
card is 
associated 
with a 
valid user.

Functional Overview
Implementation and Deployment Guide - GMS-BioStar Integration v1.0 15
 Is Is
Security
cardI UserI
Event critical Trigger
D D Mapping Comments
code or any condition
know know
device
n? n?
435 VERIFY_ Securit An  No No CardNotProgram Use of a 
4 FAIL_ y-cr unknown  med fake 
CARD card has  dedicated 
been  cardID.
presente
d.

588 DUAL_            
9 AUTH_
FAIL

614 AUTH_ Any Swipe  No Yes CardInvalidDoorBl  

7 FAILED_ userX  ocked
TIMEOUT card and 
show 
someone 
else's 
face or 
do not 
show the 
face at 
all.

537 IDENTIF Any Enroll  No Yes Duress for a card   

7 Y_ duress  owned by this 
DURESS_ finger  user.
FINGERPR and 
INT present 
this 
finger to 
the 
terminal.

Reporting Cardholders Without Biometric Data
The assumption is that a cardholder can be first registered with BioStar and enroll biometric data at a 
later stage. When a person joins a company, a cardholder is created in GMS and at the same time a 
BioStar user is created. The biometric enrollment happens later when the new starter visits Human 
Resources to present their face or finger to the enrollment device.

The Extender interface has a button to generate a CSV file listing the PersonalID of users who are as 
yet to be biometrically enrolled. The CSV file contains only entries for those users who are associated 
with GMS cardholders.

Functional Overview
Implementation and Deployment Guide - GMS-BioStar Integration v1.0 16
 

Functional Overview
Implementation and Deployment Guide - GMS-BioStar Integration v1.0 17
Implementation Overview
Schematic of the system architecture:

Integration Components

Proxy

A component which serves as a single connection point to BioStar. The Proxy uses BioStar web APIs. 
WCF is used to communicate with the Extender and the Listener. It runs as a Windows service 
(although a command line application is also possible for troubleshooting).

In addition to using BioStar web APIs, the Proxy runs queries on the BioStar database. As BioStar can 
use SQL Server or MariaDB., the Proxy relies on the configured ODBC.

There must be only one instance of the Proxy. It can run on any computer. It is recommended to 
install it on the same computer which runs the GMS Events Publisher.

Listener

The Listener handles CardCreate, CardModify and CardDelete notifications.

The Listener polls BioStar for the online / offline status of Suprema terminals and notifies GMS (using 
the AlarmInjection interface).

Extender

The Extender offers an interface to manage cardholder / card enrollment, as well bulk user 
enrollment. A CSV report file can be generated listing registered cardholders who have not done 
biometric enrollment.

Implementation Overview
Implementation and Deployment Guide - GMS-BioStar Integration v1.0 18
Prerequisites
The following must be installed and operational:

 l GMS 4.40 SP1 or later

GMS 4.40 or 4.30 can be used, but the customer is responsible for enforcing the uniqueness of 
cardholders' PersonlID using the special validator.

 l GMS Events Publisher

 l GMS API License

 l Suprema BioStar2 v2.8.9

This integration is compatible with the BioStar server regardless of whether it connects to the 
SQL Server or Maria database.

Availability of Files
The GMS integration with Suprema BioStar is available as a set of zip files. There is no dedicated 
installer.

Contact PACOM Support for the files.

Prerequisites
Implementation and Deployment Guide - GMS-BioStar Integration v1.0 19
Installation and Configuration

BioStar Setup
The BioStar Server can use SQL or MariaDB, as the integration uses ODBC to access the database.

At this stage, if the BioStar database is encrypted (this is the default installation option), an external 
application has no documented way of extracting data from the database. For this reason, 
encryption must be disabled.

Configuring MariaDB for External Access

By default, when the BioStar server is installed, MariaDB listens to 127.0.0.1. To expose this internet 
address, it must be changed.

 1.  Follow the instructions in https://linuxhint.com/expose_mysql_server_
internet/#:~:text=MariaDB%2FMySQL%20database%20server%20only,local%20network
%20or%20the%20internet
 2.  Go to C:\Program Files\BioStar 2(x64)\ta\mariadb-10.1.10-
winx64\my.ini
 3.  Bind the address to 0.0.0.0.
 4.  Use Navicat or a similar tool to add users to the MariaDB server.
When creating a user, the UserName@% notation should be used to allow access from any 
computer, and set this user with all privileges.

Installation and Configuration

Implementation and Deployment Guide - GMS-BioStar Integration v1.0 20
Other Tasks

 1.  Configure the BioStar Access Control environment.
 2.  Configure each Access Control terminal to generate Wiegand output.
 3.  Select user ID to be numeric or text.

The choice of numeric or text is based on the PersonalID used for GMS cardholders.

 4.  Select the Automatic User Synchronization to be Specific Devices (Only devices

belonging to the access group).

 5.  Configure the terminal as an enrollment device.

 6.  Create a user group named GMS_Default.

Installation and Configuration

Implementation and Deployment Guide - GMS-BioStar Integration v1.0 21
GMS Setup

Add a Suprema Reader Type

 1.  Edit the file on an active GMS server.

The file is automatically synched to other GMS servers.

Add a Special Stored Procedure

A special stored procedure must be installed, GmsGetLinkedCards.sql. This file is found 
together with the integration deliverables.

This stored procedure must be manually added to every GMS database using SQL Management Studio 
or similar tool.

Add Suprema Doors to Site Maps

Add card readers representing Suprema doors to GMS site maps. 

Add these card readers to GRGs and GAGs as normal.

Enforce PersonalID uniqueness

From GMS v4.40 SP1, GMS can enforce the uniqueness of PersonalIDs.

Installation and Configuration

Implementation and Deployment Guide - GMS-BioStar Integration v1.0 22
For GMS v4.40 or earlier, a special PersonalID validator must be used to achieve the same results. The 
validator is available from the PACOM FTP site.

Proxy Service Setup

Create the Service

 1.  Copy the Proxy files to a folder on a designated computer.
 2.  Create the Windows service.

 a.  Run the command prompt as admin.
 b.  >sc create GmsBioStarProxy binPath=
“c:\Pacom\BioStarProxy\Pacom.BioStarService.exe”
There must be a space between binPath= and the actual path.

 3.  Run Services and configure credentials for GmsBioStarProxy.

The credentials must be sufficient for:

 o opening a listening socket for WCF connectivity between the Proxy and Listener and 
Extenders.
 o connecting to the BioStar database if trusted authentication is used.

Installation and Configuration

Implementation and Deployment Guide - GMS-BioStar Integration v1.0 23
Install the BioStar Service HTTPS Certificate

You must install the BioStar service HTTPS certificate on the Proxy computer.

By default, BioStar uses HTTPS. During installation, a self-signed certificate is automatically 
generated.

Note: This certificate is NOT added to the BioStar trusted certificate store.

BioStar can be accessed via HTTPS using a browser running on another computer, if the security 
warning is addressed and non-trusted certificate sites are accepted.

If the Proxy is on another computer, you must connect to the BioStar Web API via HTTPS. Therefore, 
the BioStar service certificate must be added to the trusted certificates of the Proxy computer. This 
can be done by exporting the current certificate to a file (click the browser's address bar, (not secure), 
view certificate then select Copy To File) then importing the file into the Proxy's trusted certificates.

Or you can use the certificate enrollment application supplied by BioStar.

Installation and Configuration

Implementation and Deployment Guide - GMS-BioStar Integration v1.0 24
  1.  Use an internet browser on the Proxy computer, click the link on the BioStar login screen.

 2.  Run the application.

The CER file is generated in the root folder of this application.

 3.  Import the file into TrustedRoots on the Proxy computer.

Create an ODBC DSN for the BioStar Database

The Proxy must have an ODBC DSN pointing to the BioStar database server.

Note: As the Proxy normally runs as a service, the DSN must be created as a System DSN.

Microsoft SQL
If BioStar uses an Microsoft SQL Server, create an ODBC as normal.

You may need to download and install the ODBC Driver for the SQL Server.

Set the default database to BioStar_AC (the name can be different).

MariaDB
 1.  If BioStar users MariaDB, download and install the ODBC driver.

Installation and Configuration

Implementation and Deployment Guide - GMS-BioStar Integration v1.0 25
  2.  Set the database name to BioStar_AC (the database name may be different from the 
default).

 3.  Test the ODBC driver.
 4.  Configure the MariaDB to allow external connections.

Configuration
 1.  Edit Pacom.BioStarService.exe.config.

<appSettings>
<add key ="BioStar Host Url" value="https://192.168.1.1"/>
<add key ="BioStar Login" value="admin;Pacom01!"/> <!--
loginId;loginPwd-->
<add key ="BioStar Timeout" value="10"/> <!--value in seconds-->
<add key ="BioStarDSN" value="MyMariaDB"/>
<add key ="BioStarDbUsername" value="root"/>
<add key ="BioStarDbPassword" value="Pacom01!"/>
</appSettings>

where
BioStarDSN must reference the BioStar ODBC DSN.
If trusted authentication is used for accessing the database, both the 
BioStarDbUsername and BioStarDbPassword parameters must be commented out.
 2.  Enter the real IP address of the computer.

<endpoint
name="endPoint1" address="net.tcp://127.0.0.1:9007/BioStarUrl1"

This is required for WCF clients (the Extender and Listener) to be able to connect to the 
Proxy.
 3.  Configure CardConversionRules.ini.

Installation and Configuration

Implementation and Deployment Guide - GMS-BioStar Integration v1.0 26
Listener Setup

Configuration

 1.  Copy the Listener files to a folder on the computer running GMS Events Publisher.
 2.  Add a Listener entry to the Events Publishing section of the 
Customer\Updatable\GMS32_Common.ini file.
Listener1=Suprema;C:\BioStarListener\Pacom.BioStarListener.dll;B
ioStarListener
 3.  Configure Pacom.BioStarListener.dll.config.

<appSettings>
<add key ="GmsOperatorName" value="a"/>
<add key =" AutoCreate BioStar user" value="always"/>
<add key ="SupremaReaderTypeId" value="32"/>
</appSettings>

The SupremaReaderTypeId value must be set to the ID of the Suprema entry in 
CRType.str.

Configure the OnNewCard Behavior

Valid values for the AutoCreate BioStar user parameter:
 l IfSupremaDoor - create a new card and a new user if this card has access to at least one 
Suprema door.
 l IfUserExists - create a new card only if the BioStar user already exists.
 l IfUserExistsAndSupremaDoor - create a new card only if the BioStar user already exists, 
and the new card has access to at least one Suprema door.
The EventsMapping section in the Listener configuration defines mapping rules for representing 
certain BioStar events in GMS.

Note: This section is not meant to be modified by the end-users. It is designed as a flexible 
mechanism to accommodate new events as we learn more about how to generate them, 
without having to change the code. The information in this section is provided as a reference 
for PACOM Support and developers.

<EventsMapping>
<add key="ACCESS_DENIED_DISABLED=6402" value="cardTx,ByUserID,CardBlocked"
/>
<add key="ACCESS_DENIED_EXPIRED=6403" value="cardTx,ByUserID,CardExpired"
/>
<add key="ACCESS_DENIED_ON_BLACKLIST=6404" value="cardTx,0/0/0,CardBlocked"
/>

Installation and Configuration

Implementation and Deployment Guide - GMS-BioStar Integration v1.0 27
 <add key="VERIFY_FAIL_CARD=4354" value="cardTx,0/0/0,CardNotProgrammed,!"
/>
<!--<add key="DUAL_AUTH_FAIL=5889" value="cardTx,0/0/0,CardNotProgrammed"
/> -->
<add key="AUTH_FAILED_
TIMEOUT=6147" value="cardTx,ByUserID,CardInvalidDoorBlocked" />
<add key="IDENTITY_DURESS_
FINGERPRINT=5377" value="cardTx,ByUserID,DuressSwipe" />
<add key="TAMPER_ON=16384" value="device,3,0" />
<add key="TAMPER_OFF=16640" value="device,4,0" />
</EventsMapping>

The key references a particular BioStar even which is of interest.

The value defines what kind of cardTx message is injected into GMS. It consists of 3 or 4 tokens 
separated by a comma:
 l The first token must always be cardTx.
 l The second token can be ByUserID or a specific cardID.

 o If ByUserID, the integration uses the BioStar user ID to find an associated GMS 
cardholder, and takes the cardholder's cardID (the top 1 card) to inject a cardTx message 
to GMS.
 o A specific cardID is used directly for injection.
 l The third token must be one of the following:
ValidSwipe
DuressSwipe
CardBlocked
CardExpired
CardNotProgrammed
CardInvalidDoorBlocked
 l The fourth token is optional.

The only value which is permitted is '!' to designate the rule as only applicable to security critical 
terminals (that is, the event must originate from a security critical terminal, otherwise it is 
ignored).

Tamper rules are for handling terminal tamper on/off events. This must not be changed.

Installation and Configuration

Implementation and Deployment Guide - GMS-BioStar Integration v1.0 28
Extender Setup

Configuration

 1.  Copy the Extender files to a folder on every GMS workstation.
 2.  To the Customer\Updatable\GMS32_Common.ini file on the GMS server, add

[Cardholder GUI Extenders]

SupremaEnroll=Existing,"C:\BioStarGMS\Extender\BioStar_
GmsCardAccExtender.exe", %CardDetailsTab% %api%
 3.  Configure BioStar_GmsCardAccExtender.exe.config which is found in the 
Extender folder.

<appSettings>
<add key ="SupremaReaderTypeId" value="31"/>
<add key ="BioStar Facestation Id" value="542356739"/>
<add key ="BioStar FingerprintReader Id" value=""/>
</appSettings>

where
The SupremaReaderTypeId value must be set to the ID of the Suprema entry in 
CRType.str.
The BioStar Facestation Id references a Suprema terminal used for face biometrics 
enrollment at this GMS workstation location.
The BioStar FingerprintReader Id references a Suprema terminal used for finger 
scan enrollment at this GMS workstation location.

 4.  Enter the IP address to point to a computer running the Proxy service.

<client>
<endpoint name="endPoint1"
address="net.tcp://127.0.0.1:9007/BioStarUrl1"

Configure Card Conversion Between GMS and BioStar
The integration must be able to convert from code / issue / facility notation used by GMS, to Suprema 
card representation.

The conversion logic is based on the configuration rules within the 
CardFormatsConversionRules.ini file. The file must exist in the Proxy service folder. PACOM 
supplies the default version of the file.

Each conversion rule is described in a separate section of the file. 
The Mapping section is used to map between a card's FacilityCode and a conversion rule. Several 
FacilityCodes can use the same conversion rule.

Installation and Configuration

Implementation and Deployment Guide - GMS-BioStar Integration v1.0 29
 Note: BioStar does not require the parity bits in encoded card values. The card conversion syntax 
supports this.

The applicationReference parameter must be set as follows: (used to set wiegand_
format_id:id when sending the CreateCard command)

;0 for 26 bit format

;1 for HID 37 bit-H10302
;2 for HID 37 bit-H10304
;3 for HID Corporate 1000 (35 bit)
;4 for HID Corporate 1000 (48 bit)
;5~14 for Custom formats
[Mapping]
;maps FacilityCode to required encoding format
99=Generic 26 no parity
2389=Corporate 1000
4095=Corporate 1000
1677=Corporate 1000

[Generic 26]
Total=26
;start,len
CardCode=9,16
;start,len
Facility=1,8
P1=0,even,{1,2,3,4,5,6,7,8,9,10,11,12}
P2=25,odd,{13,14,15,16,17,18,19,20,21,22,23,24}
applicationReference=0

[Generic 26 no parity]
Total=24
;start,len
CardCode=8,16
;start,len
Facility=0,8
;P1=0,even,{1,2,3,4,5,6,7,8,9,10,11,12}
;P2=25,odd,{13,14,15,16,17,18,19,20,21,22,23,24}
applicationReference=0

[Corporate 1000]
Total=35

Installation and Configuration

Implementation and Deployment Guide - GMS-BioStar Integration v1.0 30
 ;start,len
CardCode=14,20
;start,len
Facility=2,12
;first, calculate Bit1 parity
; Bit 2 is an even parity covering bits
3,4,6,7,9,10,12,13,15,16,18,19,21,22,24,25,27,28,30,31,33,34.
P2=1,Even,{2,3,5,6,8,9,11,12,14,15,17,18,20,21,23,24,26,27,29,30,32,33}
; Bit 35 is odd parity, covering bits
2,3,5,6,8,9,11,12,14,15,17,18,20,21,23,24,26,27,29,30,32,33
P35=34,Odd,{1,2,4,5,7,8,10,11,13,14,16,17,19,20,22,23,25,26,28,29,31,32}
; Bit 1 is an odd parity bit that covers all 35 bits
P1=0,Odd,
{
1
,
2
,
3
,
4
,
5
,
6
,
7
,
8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28,29,30,31,32,33,34}
applicationReference=2

The applicationReference parameter must store the wiegand_ID of the BioStar2 card format:

Installation and Configuration

Implementation and Deployment Guide - GMS-BioStar Integration v1.0 31
Verifying the Conversion Rules

The easiest way to check that card conversion rules are correctly configured:

 1.  Create a card in GMS.
 2.  Use the Extender to add this card to BioStar.
 3.  Go to the BioStar web interface, Settings > Cards.
 4.  Make sure that the newly added card is displayed.

Example
Adding a GMS card 1333/0/90:

Installation and Configuration

Implementation and Deployment Guide - GMS-BioStar Integration v1.0 32
Hints and Tips

Deleting Cards

At this stage, it is not possible to delete a card either from the BioStar interface or from the API.

If required while testing, a card can be deleted using a query.

Using this method merges the field as one. So if you are using a 26-bit format, you will have the 2 
fields combined into one. For example, card 11-11 will be stored as 720907.
delete from t_usrcrd where crduid in (select crduid from t_crd where
crdcsn= '720907');
delete from t_crdisshis where crduid in (select crduid from t_crd
where crdcsn='720907');
To purge all cards, truncate the following tables:
truncate table t_usrcrd;
truncate table t_crdisshis;
truncate table t_crd;
For truncate T_CRD, SQL displays an error saying that it is referenced by a foreign key. Rows can be 
manually deleted from SMSS and Navicat's  clear table command can be used.

Hints and Tips

Implementation and Deployment Guide - GMS-BioStar Integration v1.0 33
Troubleshooting
To troubleshoot any issues with the GMS integration with Suprema BioStar, use DbgView running 
AsAdmin and with the CaptureWin32 option enabled (so as to capture traces from services).

Tip: Make sure that DebugAppender is active, so as to be able to view output in DbgView.

As each integration component uses Log4Net, contact PACOM Support for advice on configuring 
Log4Net tracing according to your requirements.

The Proxy can be run as a service or a command line application. Running as an application can help to 
resolve issues with Service Credentials.
Go to the folder with the Proxy files and run >Pacom.BioStarService.exe/debug

Troubleshooting
Implementation and Deployment Guide - GMS-BioStar Integration v1.0 34