SiPass Integrated HR-API Programmers Reference Manual PDF

Access Control
SiPass® integrated
HR-API Programmer’s Reference Manual
MP2.70 SP1
A-100084-1 Building Technologies

02.2018 CPS Fire Safety
Copyright
Technical specifications and availability subject to change without notice.
© Copyright Siemens Switzerland Ltd.
We reserve all rights in this document and in the subject thereof. By acceptance of
the document the recipient acknowledges these rights and undertakes not to
publish the document nor the subject thereof in full or in part, nor to make them
available to any third party without our prior express written authorization, nor to
use it for any purpose other than for which it was delivered to him.
Edition: 02.2018
Document ID: A100084-1
About this document
Contents
1 About this document .............................................................................. 6

1.1 Document Revision History....................................................................... 7
2 Introduction ............................................................................................. 8
2.1 The SiPass integrated API ........................................................................ 9
2.2 Object Model Overview ........................................................................... 10
2.3 Requirements .......................................................................................... 12
3 Using the SiPass integrated API ......................................................... 13

3.1 Establishing an Authenticated Connection ............................................. 13
3.2 Accessing SiPass integrated objects ...................................................... 14
3.2.1 Visual C# ................................................................................................. 14
3.2.2 Visual C++............................................................................................... 14
3.3 Object Reference .................................................................................... 15
3.3.1 Session Object ........................................................................................ 15
3.3.2 Example .................................................................................................. 16
3.4 Server Object .......................................................................................... 17
3.4.1 Example .................................................................................................. 18
3.5 Employee Manager Object ..................................................................... 19
3.5.1 Example .................................................................................................. 21
3.5.2 Example .................................................................................................. 22
3.5.3 Example .................................................................................................. 23
3.6 Employees Object ................................................................................... 25
3.6.1 Example .................................................................................................. 26
3.7 Employee Object ..................................................................................... 27
3.7.1 Example .................................................................................................. 29
3.7.2 Example .................................................................................................. 29
3.7.3 Example .................................................................................................. 32
3.7.4 Example .................................................................................................. 32
3.7.5 Example .................................................................................................. 33
3.7.6 Accessing Employee attributes ............................................................... 35
3.7.7 Fixed Employee properties ..................................................................... 36
3.7.8 Custom Employee Properties ................................................................. 39
3.7.9 Example .................................................................................................. 39
3.8 IAdvCredentialProfileFactory Object ....................................................... 40
3.9 IAdvCredentialFactory Object ................................................................. 40
3.10 IAdvCredentialProfile Object ................................................................... 41
3.11 IAdvCredentialProfileCollection Object ................................................... 42
3.12 IAdvCredential Object ............................................................................. 43
3.13 IAdvCredentialCollection Object ............................................................. 44
3.14 AdvPINMode ........................................................................................... 45
3.15 IAdvCardTechnology Object ................................................................... 45
3.16 IAdvCardTechnologyCollection Object ................................................... 46
3.17 Workgroups Object ................................................................................. 46
3.17.1 Example .................................................................................................. 48
3.18 Workgroup Object ................................................................................... 48
3.18.1 Example .................................................................................................. 49
3.19 IAdvCardLayouts Object ......................................................................... 50
3.19.1 Example .................................................................................................. 50
3
Building Technologies A-100084-1
02.2018
About this document
3.20 IAdvCardLayout Object ........................................................................... 51
3.20.1 Example .................................................................................................. 51
3.21 Access Control Manager Object ............................................................. 52
3.21.1 Example .................................................................................................. 53
3.22 Access Groups Object ............................................................................ 54
3.23 Access Group Object .............................................................................. 55
3.23.1 Example .................................................................................................. 56
3.23.2 Accessing Access Group attributes ........................................................ 56
3.23.3 Access Group attribute names ................................................................ 57
3.24 Access Group Info Object ....................................................................... 57
3.24.1 Example .................................................................................................. 58
3.25 AdvAccessLevelInfo ................................................................................ 58
3.26 AdvAccessLevelItem ............................................................................... 59
3.27 Access Levels Object .............................................................................. 59
3.26.1 Example ....................................................................................................... 60
3.28 Access Level Object ................................................................................ 60
3.27.1 Example ...................................................................................................... 61
3.29 IAdvAccessComponent ........................................................................... 61
3.30 IAdvAccessComponentCollection ........................................................... 62
3.31 IAdvAccessComponentReader ............................................................... 62
3.32 AdvAccessComponentType .................................................................... 63
3.33 IAdvAccessGroupManager ..................................................................... 63
3.33.1 Example .................................................................................................. 64
3.34 IAdvAccessLevelManager ....................................................................... 64
3.35 IAdvAccessPolicy .................................................................................... 65
3.36 AdvAccessRule ....................................................................................... 67
3.37 AdvAccessRuleType ............................................................................... 68
3.38 AdvControlMode ..................................................................................... 68
3.39 AdvArmingRights .................................................................................... 69
3.40 IAdvCommon........................................................................................... 69
3.41 IAdvFilter ................................................................................................. 70
3.42 ComparisonOperator ............................................................................... 71
3.43 AdvFilterEntry .......................................................................................... 72
3.43.1 Field Names to be used in Filtering......................................................... 72

02.2018
About this document
3.44 IAdvTimeSchedule .................................................................................. 74
3.45 IAdvTimeScheduleCollection .................................................................. 74
3.46 IAdvVenue............................................................................................... 75
3.47 IAdvVenueCollection ............................................................................... 75
3.48 IAdvVenueManager ................................................................................ 76
3.49 IAdvVenueBooking ................................................................................. 77
3.50 IAdvVenueBookingCollection.................................................................. 78
3.51 IAdvVenueBookingManager ................................................................... 79
3.52 IAdvWorkgroupManager ......................................................................... 79
3.53 AdvWorkgroupType ................................................................................ 81
3.54 AdvEventType ......................................................................................... 81
3.55 AdvObjectEventInfo ................................................................................ 81
3.56 IAdvObjectEventsCallback ...................................................................... 82
3.57 AdvAccessPolicyEventInfo ..................................................................... 82
3.58 IAdvAccessPolicyEventsCallback ........................................................... 83
3.59 AdvEmployeeWorkgroupsEventInfo ....................................................... 83
3.60 IAdvEmployeeWorkgroupsEventsCallback ............................................ 83
3.61 AdvEmployeeCredential ......................................................................... 84
3.62 AdvEmployeeCredentialEventInfo .......................................................... 84
3.63 IAdvEmployeeCredentialEventsCallback ............................................... 85
3.64 AdvFingerIndex ....................................................................................... 85
3.65 IAdvEmployeeField ................................................................................. 86
3.66 IAdvEmployeeFields ............................................................................... 86
3.67 AdvFieldDataType .................................................................................. 87
4 HR-API Sample program ...................................................................... 88
5 Appendix A: Error Codes ..................................................................... 89
6 Troubleshooting .................................................................................... 92
5
02.2018
About this document
1 About this document
Operation Guide
®
The SiPass integrated HR API Programmer’s Guide has been prepared to provide
you with information concerning how to program a third party application to
interface via the HR API. It has been produced for new and experienced users of
Siemens Building Technologies access control products and systems. This guide
should be used in conjunction with the SiPass integrated Installation and User‟s
manuals.
Disclaimer
Although reasonable care was taken in producing this manual, no responsibility is
accepted by Siemens or its agents or employees for the accuracy or safety of the
material contained herein. None of the equipment described in this guide is
suitable for use in an application where life or health depends on its correct
operation. Siemens reserves the right to vary the specifications, standards and
method of operation of any or all of the equipment described herein at any time
without notice to any party.
No liability can be assumed for direct or consequential losses and third-party
damages arising from the purchase of this product. In all cases, liability is limited to
the purchase price of the product.
The information contained herein was up to date at the time of publication. We
reserve the right to make subsequent changes to technical or organizational
details. Siemens assumes no liability for problems resulting from the use of this
manual.
The information contained in this document may be changed without prior notice.
Siemens reserves the right to publicize any such changes by issuing updated
versions or new editions.
It is not permitted to reproduce this manual in whole or in part or translate it into
another language without our written consent.
Trademarks
SiPass is a trademark of Siemens CPS Fire Safety
Contacting us
If you have questions or suggestions regarding the product or this documentation,
please contact your local SiPass representative.

02.2018
About this document
1.1 Document Revision History
The following table outlines the changes or additions made to this guide since the
previous revision of the guide was released.
Document Revision Changes Made
12/05 Document created
06/07 Modification to file reference
09/09 Modification to manual
10/09 Update to contents
7
02.2018
Introduction
2 Introduction
®
This Reference Manual explains how to access and maintain SiPass integrated
cardholder information from a software application external to SiPass, such as a
Human Resources application.
This guide has been produced as a reference for any personnel developing or
extending software applications that require access to SiPass integrated data. This
guide should be used in conjunction with the SiPass integrated Installation and
User Guide.
®
This chapter provides a brief explanation of the SiPass integrated API object
model, and the requirements that need to be met before you can access these
objects from another programming language.
Information in this chapter includes:
 SiPass integrated API Overview
 Object Model Overview
8
02.2018
Introduction
2.1 The SiPass integrated API
The SiPass integrated automation object model allows SiPass integrated data to
be accessed and maintained from any programming language that supports COM
automation. Examples given in this document are written in C#.
Connections to a SiPass integrated server are made by the creation of a Session
object, through which an EmployeeManager object can be accessed. The
EmployeeManager object in turn controls access to Workgroups and Employees
objects, which are collections of individual records respectively. Similarly, the
AccessControlManager object controls access to AccessGroups and
AccessLevels. The VenueManager object controls fetching and modification of
venues. The VenueBookingManager controls fetching and modification of venue
bookings.
Each object contains methods and properties through which records can be
created, modified, added and saved to the SiPass integrated database.
A valid username and password must be supplied for a successful connection to a
SiPass integrated server. Access to workgroups and cardholders is determined by
the level of access of the username passed to the Session object. For more
information on assigning system functions and access privileges to SiPass
integrated operators, see Operator Groups, SiPass integrated User‟s Guide.
The described methods throughout this document will not change except under exceptional
circumstances, where clear notice will be provided. However, undocumented methods may be subject
to change without any prior notice
9
02.2018
Introduction
2.2 Object Model Overview
The following SiPass integrated objects are available:
Object Description
Session Creates a connection to the SiPass integrated server and allows a

logon to be performed. All other objects are accessed through the
Session object.
Server Represents a connection to the SiPass integrated server.
Employee Manager Provides access to employee related information.
Employees A collection of all the employees that the logged on operator has
permission to manage.
Employee Provides access to information about a single employee.
Workgroups A collection of all of the workgroups that the logged on operator has
Workgroup Provides access to information about a single workgroup.
Access Control Manager Provides access to access group information.
Access Groups A collection of all the access groups that the logged on operator has
Access Group Provides access to information about a single access group
Access Group Info Contains the name, ID and an access level collection of the access
group. The Access Group Info object is a property of each Access
Group object.
Access Levels A collection of all the access levels that the logged on operator has
permission to view.
Access Level Provides access to information about a single access level.
Card Layouts A collection of all the card layouts (templates) that the logged on
operator has permission to view.
Card Layout Represents a card template, with ability to view the name
IAdvAccessComponent Represents a single point or point group
IAdvAccessComponentCollecti Represents a collection of points or point groups

on
IAdvAccessComponentReader Allows queries to fetch points and point groups
IAdvAccessGroupManager Used to create new access group objects, as well as retrieving and
deleting existing access group objects
IAdvAccessLevelManager Used to create new access level objects, as well as retrieving and
deleting existing access level objects
AdvAccessRule Represents a single access rule. Multiple access rules can form an
access policy
IAdvAccessPolicy Represents a collection of access rules associated with an employee,

workgroup or venue
IAdvCommon Supports the creation of IAdvFilter objects
IAdvFilter A filter that can be passed in for various queries to limit the results
10
02.2018
Introduction
Object Description
returned
ComparisonOperator Enumeration for the possible comparison logic for a single filter entry
AdvFilter Entry A single piece of comparison logic. Multiple AdvFilterEntry objects

can be involved in an IAdvFilter.
IAdvTimeSchedule Represents a single time schedule
IAdvTimeScheduleCollection Represents a collection of time schedule objects
IAdvVenue Represents a single venue
IAdvVenueBooking Represents a single venue booking
IAdvVenueBookingCollection Represents a collection of venue bookings
IAdvVenueBookingManager Supports the creation, deletion and retrieval of venue bookings
IAdvVenueCollection Represents a collection of venues
IAdvVenueManager Supports the creation, deletion and retrieval of venues, and

subscription to venue change events
IAdvWorkgroupManager Supports the creation, deletion and retrieval of workgroups, and

subscription to workgroup change events
AdvWorkgroupType Enumeration for possible workgroup types
AdvEventType Enumeration for the possible event types that the server can send the
HR-API application (i.e. insert, modify, delete)
AdvObjectEventInfo Structure representing the details of an object event sent from SiPass
integrated server to the HR-API application
IAdvObjectEventsCallback Callback interface used by SiPass integrated server to notify HR-API

client of object events
AdvAccessRuleType Enumeration for the possible access item types supported in an

access rule
AdvControlMode Enumeration for Intrusion Control Mode
AdvArmingRights Enumeration for Intrusion Arming Rights
AdvAccessPolicyEventInfo Structure representing the details of an access policy event sent from
SiPass integrated server to the HR-API application
IAdvAccessPolicyEventsCallb Callback interface used by SiPass integrated server to notify HR-API

ack client of access policy events
AdvEmployeeWorkgroupsEve Structure representing the details of an employee workgroups event

ntInfo sent from SiPass integrated server to the HR-API application
IAdvEmployeeWorkgroupsEve Callback interface used by SiPass integrated server to notify HR-API

ntsCallback client of employee workgroups events
AdvEmployeeCredential Structure containing the details of an employee credential.

AdvEmployeeCredential is used in employee credential events
AdvEmployeeCredentialEvent Structure representing the details of an employee credential event

Info sent from SiPass integrated server to the HR-API application
IAdvEmployeeCredentialEvent Callback interface used by SiPass integrated server to notify HR-API

sCallback client of employee credential events
AdvFinger Index Enumeration for finger index. Used in biometric functionality
AdvAccessComponentType Enumeration for the possible point and point group types supported in
HR-API
IAdvEmployeeField Holds the information about an employee custom field (e.g. name,
data type)
11
02.2018
Introduction
Object Description
IAdvEmployeeFields A collection of employee custom fields
AdvFieldDataType Enumertion for the possible custom field data types
2.3 Requirements
 It is assumed that the reader is familiar with Microsoft C#, or similar object-
oriented programming language and concepts.
 The programming language you are using to call the SiPass integrated API
must be COM-compatible.
 SiPass integrated Operation Client must be installed on a remote client
computer to run the HR-API application.
12
02.2018
Using the SiPass integrated API
3 Using the SiPass integrated API
This chapter describes each object in detail and explains how to access and
modify SiPass integrated data using the object model.
Information in this chapter includes:
 Accessing SiPass integrated objects
 Object Reference
3.1 Establishing an Authenticated Connection
This section provides a reference for setting up an authenticated connection

between the HR-API application and SiPass integrated. Note that even when just
the HR-API Core feature is installed (no SiPass integrated clients), the
Authentication Management Wizard still runs during the installation process to
configure the configuration files with the certificate information. These files can be
copied later by the HR-API developers to use in their own application.
Note: The steps given below are intended to be performed in the development
environment. If your Release Environment is different, perform the steps given
below in the Development Environment, then copy the HR-API application to the
computer in Release Environment and repeat steps 2 and 3 (to update the
certificate information and server name of the release server).
 Prerequisite: To either develop or run a HR-API application on a particular
computer, at least the HR-API Core feature needs to be installed on it.
1. Install SiPass integrated MP2.70 with at least HR-API Core feature selected.
2. Modify the HR-API Configuration file by following the template of the
hr_api_sample_app.exe.config file available in the SiPass integrated installation
directory. The .NET version in the configuration file can be changed from .NET
4.5.2 if you are using a newer version.
3. Copy the following files from the SiPass integrated installation directory to the
HR-API application directory:
o behaviors.config
o bindings.config
o clients.config
o extensions.config
o SiPass.ClientServices.Interfaces.dll
o SiPass.WcfCoreServices.dll
o SiPass.Exception.dll
4. Recompile the HR-API application.
The HR-API application can now make the required authenticated connection to
SiPass integrated MP2.7.
Note: Ensure that the project's Platform Type is set to 'x86', since we are
referencing 32-bit COM components.
13
02.2018
3.2 Accessing SiPass integrated objects
This section provides a reference for the SiPass integrated objects in the API.
3.2.1 Visual C#
You can refer to SiPass integrated objects directly in VB code or C# by adding

references to two SiPass integrated assemblies from the Add References dialog.
There are two assemblies in the SiPass integrated installation directory:
“Interop.ADVANTAGELib.dll” and “Interop.ADVCOMAPILib.dll” In order to obtain
all of the type information described in this document, both assemblies need to be
referenced in the „Add References‟ dialog.
In addition, optionally you can add a reference to SiPass.Exception.dll, available in
the SiPass integrated installation directory. This will allow you to examine error
codes that could be returned for various HR-API operations (see Appendix A for
more details).
3.2.2 Visual C++
In Microsoft Visual C++ version 5.0 or later, you can use the #import directive to
import information directly from a type library. The type libraries for the SiPass
integrated objects are in “AdvServ.tlb” and “AdvComApi.dll”. These files need to be
loaded in order to obtain all of the type information described in this document.
Refer to the Visual C++ documentation for information on the #import directive.
COM enabled Language Load the following files:
.NET, Visual C#, VB Interop.ADVANTAGELib.dll

Interop.ADVCOMAPILib.dll
SiPass.Exception.dll (optional)
Visual C++ AdvServ.tlb

AdvComApi.dll
SiPass server memory considerations during HR-API operations

When using COM objects in managed code, memory management of COM objects must be
considered. Managed code does not directly reference COM objects, but interacts with Runtime
Callable Wrapper (RCW) objects (in managed code) in a way that each maintains a pointer to a COM
object, and are subject to .NET garbage collection. As .NET memory management is non-
deterministic, this can result in cases where the server-side COM objects are not released as
expected, leading to increased SiPass server memory usage while using the HR-API.
For HR-API applications running for extended periods, it is strongly recommended to use the
C# Marshal.ReleaseComObject() method (or an equivalent call for other managed languages) to
release COM objects when not required.
For more detailed overview of COM object management from managed code, click the link below:
https://msdn.microsoft.com/en-
us/library/office/aa159887(v=office.11).aspx#odc_ofcomplexcomobjectspias_comandnetbasedmemor
ymanagement
14
02.2018
3.3 Object Reference
This section lists a description of each available object and its properties and
methods. A syntax and usage example can be found in each of the descriptions.
3.3.1 Session Object
The Session object is of type AdvSession.

A session object provides a connection to a SiPass integrated server and allows an
operator to log on to the SiPass integrated server. No other SiPass integrated
objects are made available until a successful logon has been performed and the
operator‟s permission to access objects can be verified.
The Session object has the following properties and methods:
 Properties
Property Type Description
ServerName String Used to obtain or set the name of the SiPass integrated server
used by the Connect method. This property cannot be changed
once the session is connected.
To connect to a different SiPass integrated server call

Disconnect, set the server name and then call Connect.
If this property is not set before the call to Connect, the default
SiPass integrated server name (set when SiPass integrated is
installed) will be used
Server IAdvServer Used to obtain the server object to which the session is
connected. If the session is not connected, accessing this
property will cause an error.
LogOnObject IAdvLogOn Used to obtain the logon object to which the session is
connected. If the session is not connected, accessing this
property will cause an error.
 Methods
Method Arguments Description
Connect None Connects a session to a SiPass integrated server. In determining

the name of the server to connect to, this method first checks the
ServerName property and, if this has not been set, the default
server name is then used. If the session is already connected or
if the connection fails, an error is generated.
Disconnect None Disconnects a connected session from a SiPass integrated

server. If the session is not connected, an error is generated.
Logon Allows an operator to log on to the SiPass integrated server. A

Logon dialog box may or may not be displayed, depending upon
the flags argument:
SessionObject.Logon <username>, <password>, <flags>,
<hwnd>
<username> A string representing a valid SiPass integrated operator‟s

username.
<password> A string representing a valid SiPass integrated operator‟s
15
02.2018
corresponding password.
<flags> A series of logon options, from enum AdvLogonFlags. When

specifying multiple flags, the logical OR operator should be used.
AdvLogonUI This flag causes a Logon dialog box to be
displayed. If this flag is not set, and the
username or password is not supplied, then this
method will generate an error.
AdvReLogon This flag causes the current logon attempt to be
verified after a timeout.
AdvCheckPassword This flag prevents a full logon. The
username and password are checked
for validity only.
AdvNewSession This flag forces the user to log on with a new
session.
AdvUseSaved This flag uses the saved username and
password to log on.
AdvAuditTrailOff This flag disables audit trail messages
when logged on.
AdvAuditTrailCache This flag ensures that audit trail
messages are enabled when logged on.
AdvAuditTrailRefresh This flag refreshes the audit trail
messages upon logging in. This flag
is only used internally in SiPass
integrated and should not be used in
custom applications.
<hwnd> A window handle to use as the parent for the Logon dialog box.
This parameter can be null.
Logoff None Logs an operator off from a SiPass integrated server. If the logon
has not been performed for this session, an error is generated.
CancelLogon None Cancels the logon process where the logon is waiting for input
from a user.
3.3.2 Example
The following example shows the creation and the use of a session object:
 Visual C#
//Create session object, set ServerName, connect and log on

ADVCOMAPILib.AdvSession session;
session = new ADVCOMAPILib.AdvSession ();
session.ServerName = “MyComputer”;
session.Connect();
session.Logon("","",1, this.Handle().ToInt32());
// To disconnect from a session, Logoff() must first be called, then Disconnect()

called
session.Logoff();
session.Disconnect();
16
02.2018
3.4 Server Object
The Server object is of type IAdvServer.

A server object provides secure access to other SiPass integrated objects. A
successful logon must be performed before server properties can be accessed.
The Server object has no methods and it has the following properties:
 Properties
EmployeeManager IAdvEmployeeManager Used to obtain an

EmployeeManager object that
allows access to employee
related information.
AccessControlManager IAdvAccessControlManager Used to obtain an

AccessControlManager object
that allows access to Access
Control related information.
VenueManager IAdvVenueManager Obtain an IAdvVenueManager
object that allows fetching and
modification of venues.
Common IAdvCommon Obtain an IAdvCommon
object. Current functionality of
IAdvCommon involves the
creation of an IAdvFilter object.
AccessComponentReader IAdvAccessComponentReader Obtain an
IAdvAccessComponentReader
object that allows fetching of
points and point groups in the
system
AccessGroupManager IAdvAccessGroupManager Obtain an
IAdvAccessGroupManager that
allows fetching and modification
of access groups
AccessLevelManager IAdvAccessLevelManager Obtain an
IAdvAccessLevelManager
modification of access levels
WorkgroupManager IAdvWorkgroupManager Obtain an
IAdvWorkgroupManager
modification of workgroups
VenueBookingManager IAdvVenueBookingManager
Obtain an
IAdvVenueBookingManager
modification of venue bookings
17
02.2018
3.4.1 Example
The following example shows how to access the Server object:
 Visual C#
// Create session object, connect, logon and then set server

ADVCOMAPILib.IAdvServer server;
session = new ADVCOMAPILib.AdvSession ();
session.Connect();
session.Logon("","",1, this.Handle().ToInt32());
server = session.Server
//Accessing the Employee ManagerIAdvEmployeeManager manager =
server.EmployeeManager;
18
02.2018
3.5 Employee Manager Object
The Employee Manager object is of type IAdvEmployeeManager.

An Employee Manager object provides the base mechanism to create a new
employee and to retrieve employees and workgroups from SiPass integrated.
The Employee Manager object supports the following methods:
 Methods
GetEmployees None Returns an Employees object representing the

SiPass integrated employees that the logged on
operator has permission to access via
workgroup access.
If the operator does not have permission to view
any employees, this method will generate an
error.
If the employees are modified elsewhere after
the Employees object is returned, those changes
will not be reflected in the Employees object.
CreateNewEmployee None Returns an Employee object with its properties

initialised to default values. A new employee is
not actually created in SiPass integrated until the
Employee object is added to an Employees
collection.
The logged on operator must have the “create”
permission for employees, otherwise this method
will generate an error.
GetWorkgroups None Returns a Workgroups object representing the

workgroups that the logged on operator has
permission to access.
If the operator does not have permission to view
any workgroups, this method will generate an
error.
If the workgroups are modified elsewhere after
the Workgroups object is returned, those
changes will not be reflected in the Workgroups
object.
FetchCredentialProfil None Returns a read/write collection

es (IAdvCredentialProfileCollection) of all credential
profiles in the system.
FetchUsedCredential None Returns a read/write collection

Profiles (IAdvCredentialProfileCollection) of all used
credential profiles (i.e. where at least one card is
associated with the credential profile).
SaveCredentialProfil Saves the list of AdvCredentialProfile objects.

es
(Please note that after calling this method, all
existing ACCs should be re-initialized if a new
credential profile has been added to the system)
credentialProfiles An IAdvCredentialProfileCollection object
FetchCardTechnolog None Returns a collection

ies (IAdvCardTechnologyCollection) of available
19
02.2018
card technologies in the system.
FetchCredentialProfil Returns an IAdvCredentialProfile object which

eDetails represents an existing credential profile in
SiPass integrated.
name String input representing the name of the

credential profile
GetEmployeesWithFi
lter Return IAdvEmployees object, containing
employees only satisfying the filter conditions
filter IAdvFilter object

GetEmployeeById
Return single IAdvEmployee object matching the
employee id number
empId Employee id number

SubscribeToEmploy
eeEvents Subscribe to employee change notifications,
receiving events on the supplied callback
interface
eventsCallback Object implementing IAdvObjectEventsCallback
interface
cookie Output parameter – integer cookie id

SubscribeToEmploy
eeAccessPolicyEven Subscribe to employee access item change
ts notifications, receiving events on the supplied
callback interface
eventsCallback Object implementing

IAdvAccessPolicyEventsCallback
interface

SubscribeToEmploy
eeWorkgroupsEvent Subscribe to employee workgroup change
s notifications, receiving events on the supplied
callback interface
eventsCallback
Object implementing
IAdvEmployeeWorkgroupsEventsCallback
interface

SubscribeToEmploy
eeCredentialEvents Subscribe to employee credential change
notifications, receiving events on the supplied
callback interface
eventsCallback
Object implementing
IAdvEmployeeCredentialEventsCallback
interface
Unsubscribe Unsubscribe to stop receiving events from a

particular subscription
cookie The original cookie id value returned from the

initial subscription
GetCardLayouts None Returns an IAdvCardLayouts object representing

the card layout collection that the logged on
operator has permission to access.
If the extended HR API license is not installed,
this method will generate an error.
CredentialFactory IAdvCredentialFactory Obtains a factory object, which is used to
20
02.2018
construct credential objects
CredentialProfileFact IAdvCredentialProfileF Obtains a factory object, which is used to

ory actory construct credential profile objects.
Returns an IAdvEmployeeFields object

containing information (e.g. name, data type),
GetEmployeeCusto about the custom fields in the system which can
mFields be viewed and set for an employee using the
HR-API. This doesn‟t include custom fields for
binary attachments/images.
3.5.1 Example
The following example shows the use of the Employee Manager object and its
accessor functions:
 Visual C#
ADVCOMAPILib.IAdvEmployees employees;
ADVCOMAPILib.IAdvEmployee employee;
ADVCOMAPILib.IAdvWorkgroups workgroups;
ADVANTAGELib.IAdvEmployeeManager employeeManager;
employees = server.EmployeeManager.GetEmployees();
employee = server.EmployeeManager.CreateNewEmployee();
workgroups = server.EmployeeManager.GetWorkgroups();
employeeManager =
(ADVANTAGELib.IAdvEmployeeManager)server.EmployeeManager;
21
02.2018
3.5.2 Example
The following example shows the use of IAdvEmployeeManager to obtain all the
Credential Profiles in SiPass integrated.
Visual C#
// Display the details of each credential profile in SiPass

integrated system
IAdvEmployeeManager lEmployeeManager =
(IAdvEmployeeManager)mServer.EmployeeManager;
IIAdvCredentialProfileCollection lCredentialProfiles =
lEmployeeManager.FetchCredentialProfiles();
foreach (IAdvCredentialProfile credentialProfile in

lCredentialProfiles)
{
Console.Out.WriteLine("Id:" +
credentialProfile.Id.ToString());
Console.Out.WriteLine("Name:" + credentialProfile.Name);
Console.Out.WriteLine("IsBase:" +
credentialProfile.IsBase.ToString());
Console.Out.WriteLine("Card Tech Name:" +
credentialProfile.CardTechnology.Name);
Console.Out.WriteLine("FacilityCode:" +
credentialProfile.FacilityCode);
Console.Out.WriteLine("ValidityCode:" +
credentialProfile.ValidityCode);
Console.Out.WriteLine("PINMode:" +
credentialProfile.PINMode.ToString());
Console.Out.WriteLine("PINDigits:" +
credentialProfile.PINDigits.ToString());
Console.Out.WriteLine("-----------------------------");
}
22
02.2018
3.5.3 Example
This example shows the use of IAdvEmployeeManager to create, modify and

delete a Credential Profile.
Visual C#
// 1) Add a new credential profile
IIAdvCredentialProfileCollection lCredentialProfiles =
lEmployeeManager.FetchCredentialProfiles();
IAdvCredentialProfile lNewCredentialProfile =
lEmployeeManager.CredentialProfileFactory.CreateCredentialProfile();
AdvCardTechnology lCardTechnology = null;
// Select a card technology to associate with our new profile. Use

Mifare CSN32 as an example.
foreach (AdvCardTechnology cardTech in

lEmployeeManager.FetchCardTechnologies())
if (cardTech.Name == "Mifare CSN32")
lCardTechnology = cardTech;
break;
lNewCredentialProfile.Name = " MyNewCredentialProfile";
lNewCredentialProfile.CardTechnology = lCardTechnology;
lNewCredentialProfile.FacilityCode = "0";
lNewCredentialProfile.ValidityCode = "0";
lNewCredentialProfile.PINDigits = 4;
lNewCredentialProfile.PINMode = AdvPINMode.AdvCardAndPIN;
lCredentialProfiles.Add(lNewCredentialProfile);
lEmployeeManager.SaveCredentialProfiles(lCredentialProfiles);
// 2) Modify an existing credential profile
23
02.2018
lCredentialProfiles = lEmployeeManager.FetchCredentialProfiles();
foreach (IIAdvCredentialProfile profile in lCredentialProfiles)
if (profile.Name == " MyNewCredentialProfile")
profile.PINDigits = 8;
break;
// 3) Delete a credential profile
lCredentialProfiles = lEmployeeManager.FetchCredentialProfiles();
IAdvCredentialProfile lProfileToDelete = null;
foreach (IIAdvCredentialProfile profile in lCredentialProfiles)
if (profile.Name == " MyNewCredentialProfile")
lProfileToDelete = (IAdvCredentialProfile)profile;
break;
lCredentialProfiles.Remove(lProfileToDelete);
24
02.2018
3.6 Employees Object
The Employees object is of type IAdvEmployees.

An Employees object is a collection of Employee objects. Changes to employees
made from the SiPass integrated client will not be reflected in this collection of
objects.
Members of the Employees collection may be accessed by an index. The first
member of the collection has the index “0”. Supplying an index out of bounds of
current collection will generate an error.
The Employees object has the following properties and methods:
 Properties
Count Integer Used to obtain a count of the Employee objects in the collection.
 Methods
Add Adds an Employee object to the collection and saves the

employee details in SiPass integrated.
<employee> An Employee object. Certain employee properties must be set

before the object can be added to the collection and saved.
Remove Deletes an Employee object from the collection and removes the
employee from SiPass integrated.
EmployeesObject.Remove <employee>
<employee> An Employee object.
Item Retrieves an Employee object given the employee index

position. This method will raise an error if the collection is empty
or an incorrect index was specified.
<Index> An integer which represents the employee index position in the

collection which starts at 0.
SetFilter Restricts the set of employees in the collection based on a set of

values. The filter consists of an array of property names and a
corresponding array of values:
Employees must match all of the criteria before being included in
the collection.
String values, such as names, are matched partially so that the
filter matches all entries that start with the given string.
This method will return an error if the two arrays are of different
sizes or if any of the field names are invalid.
25
02.2018
EmployeesObject.SetFilter <NamesArray>, <ValuesArray>
<NamesArray> An array of strings representing the employee attributes that you

want to use as a filter.
e.g. (“LastName, “StartDate”)
<ValuesArray> An array of variants representing the values of the employee

attributes. Employees with fields matching the values in this
array will be included in the collection.
e.g. (“John”, 1/3/1999)
In addition to the above methods, the Employees object supports the “For Each”
coding statement.
3.6.1 Example
The following examples show how to access the Employees object:
 Visual C#
// print out first name of each employee
foreach (ADVCOMAPILib.IAdvEmployee employee in employees)
{
System.Diagnostics.Debug.Write(employee["FirstName"]);
}
// add new employee
employee = server.EmployeeManager.CreateNewEmployee();
// set properties here for new employee
employees.Add(employee);
// declare name and value arrays

string[] names = new string[2];
object[] values = new object[2];
names[0] = "LastName";
values[0] = "Smith";
names [1] = "StartDate";
values[1] = "1/3/1999";
// set filter
employees.SetFilter(names, values);
26
02.2018
3.7 Employee Object
The Employee object is of type IAdvEmployee. An Employee object represents a

SiPass integrated employee, and allows employee data to be accessed and
modified. The Employee object has the following properties and methods:
 Methods
SaveChanges None Saves changes to an existing employee. The

Employee object must have been retrieved from
an Employees collection for this method to
succeed. To add a new employee to the system,
do not use the SaveChanges() method . Use only
the Add method of the Employees object (see the
"Employees Object" section for more information).
IsUniqueValue Checks if the custom employee field value is

unique. This method will raise an error if an
incorrect custom field was used. This returns true
if the custom field value is unique, and otherwise
false.
<CustomField> The custom field name (string) to check
<CustomValue> The value of the custom field (variant)

Sets the portrait or signature image for an
SetCardholderImage employee. Only .JPG and .BMP images are
allowed. Note that the image selected will always
be saved in .JPG format on the server. This
method can only be called on an employee that
has already been added to the SiPass system.
data Byte array holding the image data
imageFileType AdvImageFileType enum to specify if image data

is .bmp or .jpg format
AdvImageType enum specifying cardholder or
imageType signature image type (i.e. AdvCardholderImage or
AdvSignatureImage)
GetCardholderImage Retrieve the employee‟s cardholder or signature
image. A byte array is returned holding the image
data. If there is no associated image, NULL is
returned.
AdvImageType enum specifying cardholder or
imageType signature image type (i.e. AdvCardholderImage or
AdvSignatureImage)
IsUnique Checks the current employee property value
against the database and returns true or false if
the value is unique. This method will return an
error if the specified employee field is invalid.
bstrName The employee field name (string) to check the

value against.
Credentials IAdvCredentialC Returns a collection of credentials (cards)

ollection belonging to the employee object
GetBiometricData Returns a byte array containing the biometric data

in Bioscrypt format, for the specified finger
index AdvFingerIndex enum specifying the finger to

retrieve biometric data for
27
02.2018
 Properties
AccessGroup IAdvAccessGroup Used to obtain the access

group object assigned to an
employee. This property
returns NULL if the
employee does not have a
single access group
assigned.
CardLayout IAdvCardLayout Used to obtain the card

layout object for an
employee. This property
returns NULL if there is no
card layout associated to an
employee.
BiometricEncodedFingers
AdvFingerIndex array Returns information on which
fingers are used in biometric
encoding
AccessPolicy
IAdvAccessPolicy Returns the employee‟s
access policy
Workgroups
IAdvWorkgroups Returns a collection of
workgroups assigned to the
employee
BiometricData
SAFEARRAY(BYTE)* Returns an array of bytes
representing the Biometric
Credential data (in Bioscrypt
format)
Credentials
IAdvCredentialCollection Returns a collection of
credentials (cards) belonging
to the employee object
28
02.2018
3.7.1 Example
The following examples show how to access the Employee object:

 Visual C#
// Change all StartDate to 1/1/2005
foreach (ADVCOMAPILib.IAdvEmployee employee in employees)
employee[“StartDate”] = new DateTime(2005,1,1);
employee.SaveChanges();
3.7.2 Example
The following examples show how to Create, Modify and Delete a Credential (card)
for an employee:
// 1) Add a new card for "John Smith" in SiPass
AdvCredential lCredential =
lEmployeeManager.CredentialFactory.CreateCredential();
IAdvEmployees lEmployees =
(IAdvEmployees)lEmployeeManager.GetEmployees();
IAdvEmployee lEmployee = null;
// Select "John Smith" employee object
foreach (IAdvEmployee emp in lEmployees)
if (emp["LastName"].ToString() == "Smith" &&
emp["FirstName"].ToString() == "John")
lEmployee = emp;
break;
29
02.2018
lCredential.CardNumber = "222";
lCredential.PINNumber = "1234";
lCredential.StartDate.Date = DateTime.Today;
lCredential.EndDate.Date = DateTime.Today.AddDays(1);
lCredential.CredentialProfile = "MyNewCredentialProfile";
lCredential.Active = true;
lEmployee.Credentials.Add(lCredential);
lEmployee.SaveChanges();
// 2) Modify the card for "John Smith"
lEmployee = null;
AdvCredential lCredentialToEdit = null;
lEmployee = emp;
break;
foreach (AdvCredential credential in lEmployee.Credentials)
if (credential.CardNumber == "222")
lCredentialToEdit = credential;
break;
lCredentialToEdit.CardNumber = "333";
// 3) Delete the card for "John Smith"
lEmployee = null;
30
02.2018
AdvCredential lCredentialToDelete = null;
lEmployee = emp;
break;
foreach (AdvCredential credential in lEmployee.Credentials)
if (credential.CredentialProfile == "MyNewCredentialProfile")
lCredentialToDelete = credential;
break;
lEmployee.Credentials.Remove(lCredentialToDelete);
31
02.2018
3.7.3 Example
The following example shows how to delete all cards belonging to an employee:
// Delete all cards belonging to "John Smith" employee
lEmployee = null;
// Get the employee "John Smith" using filtering
ADVCOMAPILib.IAdvFilter lFilter = mServer.Common.CreateFilter();
lFilter.Add (new ADVCOMAPILib.AdvFilterEntry()
op = ADVCOMAPILib.ComparisonOperator.Equal,
propertyName = "FirstName",
value = "John"
});
propertyName = "LastName",
value = "Smith"
});
lEmployees =
mServer.EmployeeManager.GetEmployeesWithFilter(lFilter);
lEmployee = lEmployees.Item(0);
lEmployee.Credentials.Clear();
3.7.4 Example
The following example shows how to get all cards (credentials) assigned to an
employee:
// Display all cards belonging to "John Smith" employee
lEmployee = null;
32
02.2018
value = "John"
});
value = "Smith"
});
lEmployees =
IAdvCredentialCollection lCredentials = lEmployee.Credentials;
foreach (IAdvCredential credential in lCredentials)
Console.Out.WriteLine("CardNumber:" + credential.CardNumber);
Console.Out.WriteLine("PINNumber:" + credential.PINNumber);
Console.Out.WriteLine("CredentialProfile:" +
credential.CredentialProfile);
Console.Out.WriteLine("--------------------------------");
3.7.5 Example
The following example shows how to get all Workgroups (partition and non-
partition) assigned to an employee:
// We are going to list all workgroups assigned to "John Smith"

employee
IAdvEmployeeManager lEmployeeManager = mServer.EmployeeManager;
IAdvEmployees lEmployees = lEmployeeManager.GetEmployees();
IAdvEmployee lEmployee = null;
// Select "John Smith" employee object
33
02.2018
{
value = "John"
});
value = "Smith"
});
lEmployees =
// Iterate through workgroup collection
IAdvWorkgroups lGroups = lEmployee.Workgroups;
for each (IAdvWorkgroup group in lGroups)
Console.Out.WriteLine("Name:" + group.Name);
if (group.Partition)
Console.Out.WriteLine("This is a partition group");
else
Console.Out.WriteLine("This is a non-partition group");
34
02.2018
3.7.6 Accessing Employee attributes
There are two types of employee attributes:

Fixed properties: These are core properties possessed by every cardholder
programmed in SiPass integrated.
Custom properties: These are site specific custom attributes programmed using
the Custom Page Design feature in SiPass integrated. A list of custom fields
existing in the system can be obtained by calling GetEmployeeCustomFields()
available in IAdvEmployeeManager.
Both types of Employee properties are indexed by a string representing the
attribute name, like a dictionary.
Example 1: To obtain an employee’s first name:

strFirstName = employee[“FirstName”].ToString();
Access to attributes, including the ability to read, modify and delete attributes of the
Employee object is dependent on the access privileges of the operator who is
currently logged in.
Note: All field names are case sensitive
35
02.2018
3.7.7 Fixed Employee properties
The following Fixed Employee properties are available:

 Properties
Name Type Max Read- Required Description

Length only
CardNumber String 19 * No No The number of the card assigned to

the employee for access control. No
two employees can have the same
card number.
If you don‟t want the employee to
have a card number set the
CardNumber property as an empty
string.
This property is associated with the
Base credential.
FirstName String 30 No Yes The employee‟s given name.
LastName String 30 No Yes Employee‟s surname.
EmployeeNumber String 16 No No Employee identification number.
EmployeeId Integer - Yes No Unique employee index in the

database.
CardStatus Integer - Yes No A value indicating the status of the

employee. From enum
AdvCardStatus.
0=Valid
1=Void
2=Expired
3=Before Start
4=WorkGroup Void
StartDate Date - No Yes The date from which the employee

becomes valid.
New credentials created must have
a start date the same or later than
the employee start date.
StartDateTime Date - No Yes Note: This property is the same as

StartDate
EndDate Date - No Yes The date on which the employee‟s

card expires.
EndDateTime Date - No Yes The date and time on which the

employee‟s card expires.
Note: This property is the same as
EndDate
CardTrace Boolean - No No Turns card tracing on or off.
PinNumber String 8* No No The employee‟s PIN number.

Base Credential.
Workgroup Object - No Yes The workgroup to which the

employee belongs.
36
02.2018
primary partition workgroup
assigned.
Title String 30 No No Employee‟s job title.
DateOfBirth Date No No Employee‟s date of birth.
Address String 60 No No Employee‟s address.
PhoneNumber String 16 No No Employee‟s phone number.
MobileNumber String 16 No No Employee‟s mobile phone number.
PagerNumber String 16 No No Employee‟s pager number.
EmailAddress String 80 No No Employee‟s email address.
UseEmail Short - No No Whether the email address should

be available for Message
Forwarding.
PayrollNumber String 16 No No Employee payroll identification

number.
CarRego1 String 10 No No Registration number of employee‟s

first car.
CarModel1 String 20 No No Model name of employee‟s first car.
CarColour1 String 15 No No Colour of employee‟s first car.
CarRego2 String 10 No No Registration number of employee‟s

second car.
CarModel2 String 20 No No Model name of employee‟s second

car.
CarColour2 String 15 No No Colour of employee‟s second car.
CardTemplate String 20 No No Name of the card template to be

used in printing cards for this
employee. Must be a valid card
template that exists in SiPass
integrated.
PrintDate Date - Yes No The most recent date on which a

card was printed for this employee.
PrintNumber Integer - Yes No The number of cards that have been

printed for this employee.
Isolate Boolean - No No The isolation status of the card for

this employee.
Visitor Boolean - No No Whether the employee is a visitor or

not.
Void Boolean - No No Used to set an employee‟s card

status to void. **
LastUpdatedTime Date - Yes No Indicates the date and time the

cardholder record was last updated.
LastUpdatedDateTime Date - Yes No Indicates the date and time the

cardholder record was last updated.
ImageUpdateDate Date - Yes No Indicates the date and time that the
cardholder‟s image was last
updated.
Accessibility Boolean - No No The Disability (ADA) status of the

employee. This indicates whether
the extended latch time should be
used when this employee attempts
access.
37
02.2018
ImageName String - Yes No The UNC filename of the image
stored for this employee.
MobileSP Integer - No No The mobile service provider ID.
PagerSP Integer - No No The pager service provider ID.
GeneralData String 60 No No Employee description.
Reference Long - No No Reference for CerPass support.
PinErrorDisabled Boolean - No No Indicates if PIN error is disabled for

a cardholder. When disabled, any
incorrect PIN input event at an
access point will be ignored.
TimedReEntryExclusion Boolean - No No Indicates if timed re-entry exclusion

is enabled for a cardholder.
Revision Short - No No Indicates the revision number for the

primary card.
PinAsCard Boolean - Yes No Indicates if the Pin as Card mode is

set for this cardholder. It has to be
ensured that the pre-assigned PIN
is unique, or else an exception will
be thrown.
SelfAuthorise Boolean - No No Setting this field will allow the

cardholder to gain access to a door
configured with the Dual Custody
mode of operation, without needing
the accompaniment of another
cardholder.
APBExclusion Boolean - No No Setting this field excludes the

cardholder from any Anti-Passback
areas that have been created.
Supervisor Boolean - No No Sets the cardholder as a

“Supervisor” for doors that are
configured with the Dual Custody
mode of operation
 *Card and PINs
SiPass integrated provides support for up to 19 digit card numbers for all cards.
The maximum number of digits allowed for the CardNumber field depends on the
Card Technology selected in the credential profile.
Similarly, while SiPass integrated provides support for up to 8 digit PIN numbers,
the actual number of digits required in the PinNumber attribute will depend on the
Credential Profile settings.
 Specifying a PIN
In order to select a specific PIN for a cardholder, you will first need to set the card
number. PINs are auto generated after a card number is set to a cardholder. To
override the auto generated PIN, the card number must first be set, otherwise
setting the PIN before the card number will create an automatic PIN.
38
02.2018
 Voiding a Card
The Void property is only ever used to set a card to void status. It should never be
read to find out a card status. To find out the status of a card, the CardStatus
property should be read first.
To set a card to Void, first verify that the CardStatus property either has a value of
“0” (valid) or “1” (void). If it is, you can safely set the Void property to TRUE or
FALSE. If the value of the Cardstatus property is other than 0 or 1, an error will be
generated if an attempt is made to set the Void property value.
3.7.8 Custom Employee Properties
Custom field attributes are determined by the properties defined in the SiPass
integrated Cardholder Custom Page Design dialog during creation.
Fixed Employee Field Attribute Custom Field Equivalent
Name Custom Field name
Type Custom field Data type (text, date, Boolean)
Max. Length Custom Field Max. Length (for strings only)
Read Only False. All custom fields are set to read/write enabled.
Required Custom Field “Compulsory” setting
3.7.9 Example
The following example shows how to access custom and fixed employee
properties:
 Visual C#
IAdvEmployees.IAdvEmployee employee;
string txtLockerNo;
string txtLockerLoc;
employees = server.EmployerManager.GetEmployees();
foreach(ADVCOMAPILib.IAdvEmployee employee in employees)
{
txtLockerNo = employee[“LockerNo”].ToString();
txtLockerNo = employee[“LockerLoc”].ToString();
// comment: Fields “LockerLoc” and “LockerNo” must be
appropriately defined as custom fields in SiPass
System.Diagnostics.Debug.Write(“Locker for ” +
employee[“LastName”] + “, “ + employee[“FirstName”] + “ is
number: “ + txtLockerNo + “ in building : “ + txtLockerLoc);}
39
02.2018
3.8 IAdvCredentialProfileFactory Object
An AdvCredentialProfileFactory Object is of type IAdvCredentialProfileFactory.

It is used to construct credential profile objects.
To add a newly created credential profile object into SiPass integrated, we need to
set our desired credential profile properties, add it to a credential profile collection
(which can be obtained using FetchCredentialProfiles call), and save the credential
profile collection (which can be done using the SaveCredentialProfiles call)
 Methods
CreateCredentialProfile None Constructs and returns an IAdvCredentialProfile

object.
3.9 IAdvCredentialFactory Object
An AdvCredentialFactory Object is of type IAdvCredentialFactory.

It is used to construct credential objects.
To add a newly created credential object into SiPass integrated, we need to set our
desired credential properties, add it to a credential collection (which can be
obtained using Credentials property of an employee object), and save the
credential collection (which can be done using the SaveChanges method in
employee object)
 Methods
CreateCredential None Constructs and returns an IAdvCredential object.
40
02.2018
3.10 IAdvCredentialProfile Object
Represents a credential profile.

Contains the following properties:
 Properties
Name string Gets / sets the name of the credential profile. Please note
that this name cannot contain any spaces.
CardTechnology IAdvCardTechnology Gets / sets the card technology associated with this
credential profile
FacilityCode string Gets / sets the facility code of this credential profile (if
applicable)
ValidityCode string Gets / sets the validity code of this credential profile (if
applicable)
PINMode AdvPINMode Gets / sets an AdvPINMode enumeration representing

the PIN mode of this credential.
PINDigits int Gets / sets the number of PIN digits that this credential
profile uses. If a PIN input is being used in this profile,
then PINDigits should be set to a number between 4 and
8.
IsBase bool Gets a boolean property indicating if this credential profile

is the base profile
Id int Gets the profile‟s ID
41
02.2018
3.11 IAdvCredentialProfileCollection Object
Represents a collection of IAdvCredentialProfile Objects.

Supports iteration over the collection of IAdvCredentialProfile objects using the
„foreach‟ construct.
Supports the following properties and methods:
 Properties
Count int Returns the number of IAdvCredentialProfile objects in

the collection
 Methods
Item Retrieves an (IAdvCredentialProfile) object in the

collection
index Integer representing the zero-based index of the object

to access
Add Adds an (IAdvCredentialProfile) object to the collection
IAdvCredentialProfile The object to add
Remove Removes an (IAdvCredentialProfile) object to the

collection
IAdvCredentialProfile The object to remove
Clear None Removes all items from the collection
42
02.2018
3.12 IAdvCredential Object
Represents a single credential(card) in SiPass integrated. A credential belongs to a

single employee
 Properties
Active boolean Gets / sets a property indicating if the card is in a

voided state. If Active is set to true, the card is not
voided.
StartDate Date Gets/sets the start date of the credential.
EndDate Date Gets/sets the end date of the credential.
CredentialProfile string Gets / sets a string property representing the name of

the credential profile to assign to this credential.
CardNumber string Gets / sets the card number of this credential
Revision int Gets / sets the revision number of the card (if
applicable)
PINNumber string Gets / sets the PIN Number of this credential (if
applicable)
PinErrorDisabled boolean Gets a property indicating if the card is disabled due

to PIN errors. If it is disabled (true), this property can
be set to false to re-enable the card.
LastUsedDate Date Gets the date/time value for the most recent card
badge. If never badged, the value returned is the
base OLE automation date (1899).
LastUsedArea string Gets the name of the area for the most recent card
badge. If no area was involved the value returned is
null.
LastUsedReader string Gets the name of the reader for the most recent card
badge
43
02.2018
3.13 IAdvCredentialCollection Object
Represents a collection of IAdvCredential (card) objects.

Supports iteration over the collection of IAdvCredential objects using the „foreach‟
construct.
 Properties
Count int Returns the number of IAdvCredential objects in the

collection
 Methods
Item Retrieves an (IAdvCredential) object in the collection
index Integer representing the zero-based index of the

object to access
Add Adds an (IAdvCredential) object to the collection
IAdvCredential The object to add
Remove Removes an (IAdvCredential) object from the

collection
IAdvCredential The object to remove
Clear None Removes all items from the collection
44
02.2018
3.14 AdvPINMode
An enumeration that represents the PIN mode in use for a credential profile.
The enumeration constants available are:
AdvPINMode.AdvCardAndPIN,
AdvPINMode.AdvCardOnly,
AdvPINMode.AdvPINOnly
3.15 IAdvCardTechnology Object
Represents details of each card technology that is available in SiPass integrated.

All properties are read-only.
 Properties
Id int Gets the unique ID
Name string Gets the card technology name
FacilityCodeDigits int Gets the number of digits that form the facility code for a given
card technology.
CardNumberDigits int Gets the maximum number of digits in a card number for a
given card technology.
45
02.2018
3.16 IAdvCardTechnologyCollection Object
Represents a collection of IAdvCardTechnology objects.

Supports iteration over the collection of IAdvCardTechnology objects using
the ‘foreach’ construct.
 Properties
Count int Returns the number of IAdvCardTechnology objects in the

collection
 Methods
Item Retrieves an (IAdvCardTechnology) object in the collection
index Integer representing the zero-based index of the object to

access
3.17 Workgroups Object
The Workgroups object is of type IAdvWorkgroups.

A Workgroups object contains a collection of IAdvWorkgroup objects. Any changes
to Workgroups made from a SiPass integrated client will not be reflected in this
collection.
Members of the Workgroups collection may be accessed by an index. The first
member of the collection has the index “0”. Supplying an index greater than the
current count will generate an error.
Supports iteration over the collection of IAdvWorkgroup objects using the
‘foreach’ construct.
The Workgroups object has the following properties and methods:
 Properties
Count Integer Used to obtain a count of the Workgroup objects in the collection.
46
02.2018
 Methods
GetDefaultWorkgroup None Used to obtain the current default Workgroup in SiPass

integrated.
Item Used to retrieve the work group object for a given index.
This method will raise an error if the collection is empty or
an incorrect index was specified.
Index A variant which represents the index in the IAdvWorkgroups

collection, as retrieved from the database.
SetTypeQualifier Sets the work group type so that workgroups retrieved from
the database are filtered on this type only.
<WorkGroup The work group type (short) to filter on. SiPass integrated
Type> has 4 different enumerated group types;
WG_CONTRACTOR = 1, WG_OTHER = 2, WG_VISITOR =
3, WG_DEPARTMENT = 0
GetDefaultVisitorWor Returns the default visitor workgroup in SiPass integrated,

kgroup as an IAdvWorkgroup object
ClearTypeQualifier - Removes the type filter set by a previous call to

SetTypeQualifier()
Add Add the specified workgroup to the collection
pGroup IAdvWorkgroup object
Remove Remove the specified workgroup from the collection
pGroup IAdvWorkgroup object
Clear - Removes all IAdvWorkgroup objects from the collection
47
02.2018
3.17.1 Example
The following example shows how to access the Workgroups object:

 Visual C#
ADVCOMAPILib.IAdvWorkgroup workgroup;
// get workgroups object from employee manager
workgroups = server.EmployeeManager.GetWorkgroups();
workgroup = workgroups.GetDefaultWorkgroup();
System.Diagnostics.Debug.Write(workgroup.Name);
3.18 Workgroup Object
The Workgroup object is of type IAdvWorkgroup.

A Workgroup object represents a workgroup as defined in SiPass integrated.
The Workgroup object supports the following methods and properties:
 Methods
Methods Arguments Description
VoidEntireWorkgroup Sets the Void status of the workgroup. For a voided

partition workgroup,all of the cardholders that are
members of the workgroup will also be voided.
<VoidWorkgroup> Boolean value, set to true to Void the workgroup, or

false to unvoid the workgroup.
Save - Save changes made to the workgroup properties.
 Properties
Name String Get/set the name of a workgroup.
Void Boolean Get/set the void status of a workgroup. Similar

to VoidEntireWorkgroup() method, but setting
this property does not automatically save the
workgroup
Id Int Get the workgroup Id.
ClearCardNo Boolean Get/set the „Clear Card Number‟ property.
48
02.2018
Applicable only for visitor workgroup type.
GroupType AdvWorkgroupType Get/set the workgroup type (e.g. department)
Partition Boolean Get/set the „Partition Work Group‟ setting
IsAntiPassback Boolean For assigned workgroups retrieved from an

employee object, indicates the workgroup used
for Anti Passback for that employee
AccessPolicy IAdvAccessPolicy Get the access policy of the workgroup
PrimaryContactName String Get/set the primary contact name
PrimaryContactAddress String Get/set the primary contact address
PrimaryContactTitle String Get/set the primary contact title
PrimaryContactPhone String Get/set the primary contact phone
PrimaryContactFax String Get/set the primary contact fax
PrimaryContactMobile String Get/set the primary contact mobile
SecondaryContactName String Get/set the secondary contact name
SecondaryContactAddress String Get/set the secondary contact address
SecondaryContactTitle String Get/set the secondary contact title
SecondaryContactPhone String Get/set the secondary contact phone
SecondaryContactFax String Get/set the secondary contact fax
SecondaryContactMobile String Get/set the secondary contact mobile
DisableAccessControl Boolean Get/set the “Disable Access Control” setting. If

true, employees with this workgroup assigned
will not inherit the workgroup access policy
3.18.1 Example
The following example shows how to access the Workgroup object:
 Visual C#
ADVCOMAPILib.IAdvWorkgroup workgroup;
workgroups = EmployeeManager.GetWorkgroups();
// Print out name and void status of each workgroup
foreach(ADVCOMAPILib.IAdvWorkgroup workgroup in workgroups)
{
System.Diagnostics.Debug.Write( “Workgroup void: ” +
workgroup.Void);
}
49
02.2018
3.19 IAdvCardLayouts Object
Contains a collection of IAdvCardLayout objects, which represent card templates in

SiPass integrated.
Members of the IAdvCardLayouts collection may be accessed by index. The first
current count will generate an error.Supports iteration over the collection of
IAdvCardLayout objects using the „foreach‟ construct.
The IAdvCardLayouts object has the following properties and methods:
 Properties
Count Integer Used to obtain a count of the IAdvCardLayout objects in the

collection.
 Methods
Item Used to retrieve the IAdvCardLayout for a given index. This

method will raise an error if the collection is empty or an
incorrect index was specified.
Index A variant which represents the index in the

IAdvCardLayouts collection, as retrieved from the database.
3.19.1 Example
The following example shows how to access the IAdvCardLayouts object:
 Visual C#
ADVANTAGELib.IAdvCardLayouts cardlayouts;
ADVANTAGELib.IAdvCardLayout cardlayout;
// get cardlayouts object from employee manager
cardlayouts = ((ADVANTAGELib.IAdvEmployeeManager)
server.EmployeeManager).GetCardLayouts();
50
02.2018
3.20 IAdvCardLayout Object
An IAdvCardLayout object represents a card template as defined in SiPass

integrated and allows card template information to be retrieved.
The IAdvCardLayout object supports the following property:
 Properties
Name String Used to obtain the name of the card template. This field is
read-only.
3.20.1 Example
The following example shows how to access the Cardlayout object:
 Visual C#
ADVANTAGELib.IAdvCardlayouts cardlayouts;
ADVANTAGELib.IAdvCardlayout cardlayout;
// get cardlayouts object from employee manager
cardlayouts = ((ADVANTAGELib.IAdvEmployeeManager3)
server.EmployeeManager).GetCardLayouts();
// Print out name each cardlayout

foreach(ADVANTAGELib.IAdvCardlayout cardlayout in
cardlayouts)
{
System.Diagnostics.Debug.Write(cardlayout.Name);
}
51
02.2018
3.21 Access Control Manager Object
The Access Control Manager object is of type IAdvAccessControlManager. This

object represents an interface to Access Groups in the SiPass integrated
database, and allows you to assign an access group for a cardholder. The Access
Control Manager object has the following properties and methods:
 Methods
AssignAccessGroupToEmplo Assigns an existing Access Group to an

yee employee.
Only existing Access Groups can be assigned
to an employee. Access Groups can be
retrieved using the GetAccessGroups method.
If the employee has any existing assigned
access, it is cleared before this single access
group is assigned.
<Employee> An IAdvEmployee Object.
<AccessGroup> An IAdvAccessGroup object
CreateAccessGroup Returns an IAdvAccessGroup object with its

properties initialised with the Access Group Info
values.
A new access group is not actually created in
SiPass integrated until the IAdvAccessGroup
object is added to an IAdvAccessGroups
collection.
<AccessGroupInfo A structure (AdvAccessGroupInfo) containing

> the necessary information to create an Access
Group.
GetAccessGroups None Returns an IAdvAccessGroups collection that

contains Access Group objects.
GetAccessGroupAssignedTo Returns the Access Group object assigned to

Employee the supplied Employee object.
If the employee has any assigned access apart
from a single access group, the returned
Access Group object will be null.
<Employee> An IAdvEmployee object.
RemoveAccessGroupFromE Removes the access group assignment for an

mployee Employee object. If the employee has any
assigned access apart from a single access
group, no changes will occur.
<Employee> An IAdvEmployee object.
GetTimeSchedules - Return an IAdvTimeScheduleCollection

containing all the time schedules in SiPass
integrated
GetTimeScheduleById Return an IAdvTimeSchedule given the id
id Time schedule id
52
02.2018
3.21.1 Example
The following example shows how to access the Access Control Manager object:
 Visual C#
// Create session object, connect, logon and then set server

„object
ADVCOMAPILib.IAdvServer server;
session = new ADVCOMAPILib.AdvSession();
session.Connect();
session.Logon(“”, “”, AdvLogonUI, this.Handle().ToInt32());
server = session.Server;
ADVANTAGELib.IAdvAccessGroups accessGroups;
accessGroups =
((ADVANTAGELib.IAdvAccessGroups)server.AccessControlManager).
GetAccessGroups();
ADVANTAGELib.IAdvAccessGroup accessGroup;
// Assuming there‟s at least one acc group in the collection
accessGroup = (ADVANTAGELib.IAdvAccessGroup)
accessGroups.Item(0);
ADVCOMAPILib.IAdvEmployee employee;
// Assuming there‟s at least one employee in the collection
employee = (ADVCOMAPILib.IAdvEmployee) employees.Item(0);
// Assign the first access group from the collection

// to the 1st employee in the collection.
server.AccessControlManager.
AssignAccessGroupToEmployee(employee, accessGroup);
53
02.2018
3.22 Access Groups Object
The Access Groups object is of type IAdvAccessGroups.

An Access Groups object contains a collection of Access Group objects.
Members of the Access Groups collection may be accessed by index. The first
Supports iteration over the collection of IAdvAccessGroup objects using the
The Access Groups object has the following properties and methods:
 Properties
Count Integer Used to obtain a count of the Access Group objects in the
collection.
 Method
Method Argument Description
Item Used to retrieve the access group information for a given index. This
method will raise an error if the collection is empty or an incorrect index
was specified.
<Index> A variant which represents the index in the IAdvAccessGroups

Add Adds an Access Group object to the collection and saves the access
group details in SiPass integrated. This object must be created via the
Access Control Manager object.
<AccessGroup> An IAdvAccessGroup object. All properties for the access group must be
set before the object can be added to the collection and saved.
Remove Removes the specified Access Group object form the collection and
from SiPass integrated.
<AccessGroup> The IAdvAccessGroup object to be removed from SiPass integrated.
54
02.2018
3.23 Access Group Object
The Access Group object is of type IAdvAccessGroup.

An access group consists of one or more access levels.
The Access Group object supports the following properties and methods:
 Properties
Id Integer Get the access group id
Name string Get/set the access group name
 Methods
GetProperties Retrieves the Access Group properties.
<AccessGroupInfo> Output parameter (tagAdvAccessGroupInfo), used to

hold the Access Group information.
GetID Retrieves the Access Group ID for the given

IAdvAccessGroup object.
<ID> Output parameter (int), used to hold the Access Group

ID.
GetAccessLevels - Retrieves the IAdvAccessLevels collection which

contains Access Level objects.
AddAccessLevel Add an access level to the access group
AdvAccessLevelInfo AdvAccessLevelInfo object which contains the

information about the access level
RemoveAccessLevel Remove an access level from the access group
AdvAccessLevelInfo AdvAccessLevelInfo object which contains the

information about the access level
RemoveAllAccessLevels - Remove all access levels from the access group
SaveChanges - Saves any changes made to the IAdvAccessGroup

object to SiPass integrated.
55
02.2018
3.23.1 Example
The following example shows how to access the Access Group object:
Visual C#
ADVANTAGELib.tagAdvAccessGroupInfo accessGroupInfo;
accessGroups =
GetAccessGroups();
// Print out name of each Access Group in SiPass
foreach(ADVANTAGELib.IAdvAccessGroup accessgroup in
accessGroups)
{
accessgroup.GetProperties(out accessGroupInfo);
System.Diagnostics.Debug.Write (accessGroupInfo.bstrName);
}
3.23.2 Accessing Access Group attributes
Access Group objects contain properties which are indexed by a string

representing the attribute name, like a dictionary.
Example 1: To obtain an Access Group’s name:

accessGrpName = accessGroup[“AccGrpName”].ToString();
Access to attributes, including the ability to read and modify attributes of the
Access Group object is dependant on the operator‟s access privileges who is
currently logged in.
Note: All field names are case sensitive
56
02.2018
3.23.3 Access Group attribute names
The following Access Group attributes are available:
Name Type Max Read- Description

Length only
AccGrpId Short - Yes This represents the internal access group id
used in the SiPass integrated database.
AccGrpName String 40 No The name of the access group.

ArraySize Integer - Yes The size of the access level array for the access
group.
AccLevelIds Int Array - No A variable sized array containing the access
level Ids for the access group.
3.24 Access Group Info Object
The Access Group Info object is of type tagAdvAccessGroupInfo.

An Access Group Info object contains the access group Id and name and access
levels details. The Access Group Info object is passed to certain functions as a
“handle” to an Access Group.
The Access Group Info object has the following properties:
 Properties
bstrName BSTR Name of the Access Group
nNumber Short The Access Group Id.
nAccessLevelIds Int The size of the access level array.
pAccessLevelIds SAFEARRAY(int) A safe array of integers.
57
02.2018
3.24.1 Example
The following example shows how to access the AdvAccessGroupInfo object:

 Visual C#
ADVANTAGELib.tagAdvAccessGroupInfo accessGroupInfo;
accessGroups =
GetAccessGroups();
// Print out name of each Access Group in SiPass
foreach(ADVANTAGELib.IAdvAccessGroup accessgroup in
accessGroups)
{
accessgroup.GetProperties(out accessGroupInfo);
System.Diagnostics.Debug.Write (accessGroupInfo.bstrName);
}
3.25 AdvAccessLevelInfo
Structure containing concise details of an access level. This is used as an input

parameter when adding or removing access levels from an access group
The structure members are as follows:
Member Type Description
Id Int Access level id
Name string Access level name
TimeSchedule IAdvTimeSchedule Access level time schedule
58
02.2018
3.26 AdvAccessLevelItem
Structure containing the details of a point or point group, and extra intrusion-
specific configuration. This structure information is used as a parameter when
assigning specific points or point groups to an access level.
accessComponent IAdvAccessComponent Represents a point or point group
controlMode AdvControlMode Enumeration for intrusion control mode
armingRights AdvArmingRights Enumeration for intrusion arming rights
3.27 Access Levels Object
The Access Levels object is of type IAdvAccessLevels.

An Access Levels object contains a collection of IAdvAccessLevel objects.
Members of the Access Levels collection may be accessed by index. The first
The Access Levels object has the following properties and methods:
 Properties
Count Integer Used to obtain a count of the Access Level objects in the
collection.
 Methods
Method Argument Description
Item Used to retrieve the access level information for a given index. This method
will raise an error if the collection is empty or an incorrect index was
specified.
In addition to the above, the Access Levels object supports the “For Each” coding
statement.
59
02.2018
3.26.1 Example
The following example shows how to access the Access Levels object:
 Visual C#
ADVANTAGELib. IAdvAccessLevels accessLevels;
accessLevels =
((ADVANTAGELib.IAdvAccessControlManager)(server.AccessControl
Manager)). GetAccessLevels();
3.28 Access Level Object
The Access Level object is of type IAdvAccessLevel.

An Access Level object represents a SiPass integrated access level. Access
levels can be created, modified and deleted through the HR-API, and the points
and point groups assigned to an access level can also be modified.An
IAdvAccessLevel represents a collection of AdvAccessLevelItem objects. Iteration
over the collection of AdvAccessLevelItem objects can occur using the „foreach‟
construct.
The Access Level object supports the following methods and properties :
 Methods
Methods Arguments Description
AddAccessLevelItem Add an AdvAccessLevel item

to the access level (i.e. point or
point group)
<AdvAccessLevelItem> AdvAccessLevelItem struct
GetAccessLevelItem Returns the AdvAccessLevel

item from the collection at the
specified zero-based index
index Integer index of the collection
RemoveAccessLevelItem Remove a specific

AdvAccessLevelItem from the
collection
<AdvAccessLevelItem> AdvAccessLevelItem struct
RemoveAllAccessLevelItems - Remove all

AdvAccessLevelItem objects
from the access level
Save - Save changes to the access

level
60
02.2018
 Properties
Id Int Get the access level id
Name String Get/set the access level name
Item
<Index> A variant which represents the index in the IAdvAccessGroups

Count Int Count of all the AdvAccessLevelItem objects in the collection
TimeSchedule IAdvTimeSchedule Get/set the access level‟s time schedule
3.27.1 Example
The following example shows how to access the Access Level object:
 Visual C#
ADVANTAGELib.IAdvAccessLevels accessLevels;
accessLevels =
((ADVANTAGELib.IAdvAccessControlManager)(server.AccessControl
Manager)). GetAccessLevels();
foreach(ADVANTAGELib.IAdvAccessLevel accLvl in accessLevels)

{
System.Diagnostics.Debug.Write(accLvl.Name)
}
3.29 IAdvAccessComponent
Represents a point or point group

Supports the following properties:
Id Int Id of the point or point group
Name String Name of the point or point group
type AdvAccessComponentType Enum value for the type of point or point group
61
02.2018
3.30 IAdvAccessComponentCollection
Represents a collection of IAdvAccessComponent objects.

Supports iteration over the collection using the „foreach‟ construct.
 Properties
Count Integer Used to obtain a count of the IAdvAccessComponent objects in

the collection.
 Methods
Item Retrieves an IAdvAccessComponent object given the index

position.
<Index> An integer which represents the index position in the collection

which starts at 0.
3.31 IAdvAccessComponentReader
Used to retrieve a collection of points or point groups of a certain type, in the form
of an IAdvAccessComponentCollection
Supports the following methods:
GetComponents Returns an IAdvAccessComponentCollection object given an

(optional) filter and point/group type
filter Optional IAdvFilter object (e.g. to filter by name)
type AdvAccessComponentType enum, to specify the specific

point or point group type requested.
62
02.2018
3.32 AdvAccessComponentType
Enumeration for the possible point and point group types supported for an
IAdvAccessComponent object
Value Description
AdvAccessComponentType_AccessPoint Access Point
AdvAccessComponentType_AccessPointGroup Access Point Group
AdvAccessComponentType_FloorPoint Floor Point
AdvAccessComponentType_FloorPointGroup Floor Point Group
AdvAccessComponentType_IntrusionArea Intrusion Area
AdvAccessComponentType_IntrusionAreaGroup Intrusion Area Group
AdvAccessComponentType_VirtualPoint Salto doors
AdvAccessComponentType_VirtualPointGroup Salto zones
3.33 IAdvAccessGroupManager
Supports the creation, retrieval and deletion of access groups

The following methods are available:
GetAccessGroups Returns an IAdvAccessGroups object given an

(optional) filter
GetAccessGroupById Returns an IAdvAccessGroup object, given the id
id Integer representing the access group id
CreateNewAccessGroup - Returns a new instance of IAdvAccessGroup object,

which can then be saved after the desired
configuration
DeleteAccessGroup Deletes the input access group
accessGroup IAdvAccessGroup, representing the access group to

delete
63
02.2018
3.33.1 Example
The following example shows how to use IAdvAccessGroupManager to get a

collection of access groups with a specified filter:
// Retrieve all access groups beginning with the word 'All'

ADVCOMAPILib.IAdvFilter filter =
_session.Server.Common.CreateFilter();
filter.Add(new ADVCOMAPILib.AdvFilterEntry()
{ op = ADVCOMAPILib.ComparisonOperator.BeginsWith,
propertyName = "Name",
value = "All"
});
ADVCOMAPILib.IAdvAccessGroups accessGroups =
_session.Server.AccessGroupManager.GetAccessGroups(filter);
3.34 IAdvAccessLevelManager
Supports the creation, retrieval and deletion of access levels
The following methods are available:
GetAccessLevels Returns an IAdvAccessLevels object given an

(optional) filter
GetAccessLevelById Returns an IAdvAccessLevel object, given the id
id Integer representing the access level id
CreateNewAccessLevel - Returns a new instance of IAdvAccessLevel object,

which can then be saved after the desired
configuration
DeleteAccessLevel Deletes the input access level
accessLevel IAdvAccessLevel, representing the access level to

delete
64
02.2018
3.35 IAdvAccessPolicy
Represents a collection of access rules associated with an employee, workgroup

or venue
Supports iteration over the collection of AdvAccessRule objects using the „foreach‟
construct.
The following methods and properties are supported:
 Properties
Count Integer Obtain a count of the AdvAccessRule objects in the collection.
 Methods
Get Returns an access rule from the collection,

given an index
index Integer representing the zero-based

position in the collection
Set Sets an AdvAccessRule at the specified

index in the collection

position in the collection
rule The AdvAccessRule to set in the collection
Add Add an AdvAccessRule to the collection
rule The AdvAccessRule to add
Remove Remove an AdvAccessRule from the

collection, specified by the input index

position in the collection,
Clear - Remove all AdvAccessRule objects
AddAccessGroup Add an IAdvAccessGroup, which will be

internally converted to an AdvAccessRule
when adding to the IAdvAccessPolicy
accessGroup The IAdvAccessGroup object to add
start Start DateTime
end End DateTime
65
02.2018
AddAccessLevel Add an IAdvAccessLevel, which will be
accessLevel The IAdvAccessLevel object to add
end End DateTime
AddAccessComponent Add an IAdvAccessComponent, which will

be internally converted to an
AdvAccessRule when adding to the
IAdvAccessPolicy
accessComponent The IAdvAccessComponent object to add
end End DateTime
timeScheduleId The time schedule id
AddVenueBooking Add an IAdvVenueBooking, which will be

booking The IAdvVenueBooking object to add
AddIntrusionAccessComponent Add an IAdvAccessComponent, which will

be internally converted to an
AdvAccessRule when adding to the
IAdvAccessPolicy
accessComponent The IAdvAccessComponent object to add

(must be of type intrusion area or intrusion
area group)
end End DateTime
timeScheduleId The time schedule id
controlMode AdvControlMode enum, for the Intrusion

Control Mode
armingRights AdvArmingrights enum, for the Intrusion

Arming Rights
66
02.2018
3.36 AdvAccessRule
Structure representing the details of a single access item assigned to an employee,

workgroup or venue.
Each access rule corresponds to a row in the access control grid in the SiPass
client, for the employee, workgroup and venue dialogs.
Id Int Unique id of the access rule
Id of the access item that forms the access

resourceId Int
rule
Type of the access item that forms the access

resourceType AdvAccessRuleType rule (e.g. access group, booking, access
point, etc)
Name of the access item that forms the

resourceName string
access rule
timeScheduleId Int Time schedule id
timeScheduleName string Time schedule name
start DATE Start date
end DATE End date
Intrusion Control Mode (for type intrusion area

controlMode AdvControlMode
and intrusion area groups only)
Intrusion Arming Rights (for type intrusion

armingRights AdvArmingRights
area only)
67
02.2018
3.37 AdvAccessRuleType
Enumeration for the possible access item types supported in an AdvAccessRule

object
Value Description
AdvAccessRuleType_AccessGroup Access Group
AdvAccessRuleType_AccessLevel Access Level
AdvAccessRuleType_VenueBooking Venue Booking
AdvAccessRuleType_AccessPoint Access Point
AdvAccessRuleType_AccessPointGroup Access Point Group
AdvAccessRuleType_FloorPoint Floor Point
AdvAccessRuleType_FloorPointGroup Floor Point Group
AdvAccessRuleType_IntrusionArea Intrusion Area
AdvAccessRuleType_IntrusionAreaGroup Intrusion Area Group
AdvAccessRuleType_OfflineAccessGroupType Offline Access Group
AdvAccessRuleType_VirtualPoint Salto doors
AdvAccessRuleType_VirtualPointGroup Salto zones
3.38 AdvControlMode
Enumeration for the possible Intrusion Control Modes supported in an

AdvAccessRule object (applicable for Intrusion Areas or Intrusion Area Groups)
Value Description
AdvControlMode_Unknown Set if Control Mode is inapplicable

to the AdvAccessRule
AdvControlMode_SecureAndUnsecure Secure and Unsecure
AdvControlMode_SecureOnly Secure Only
AdvControlMode_UnsecureOnly Unsecure Only
68
02.2018
3.39 AdvArmingRights
Enumeration for the possible Intrusion Control Modes supported in an

AdvAccessRule object (applicable for Intrusion Areas)
Value Description
AdvArmingRights_Unknown Set if Arming Rights is inapplicable to the

AdvAccessRule
AdvArmingRights_EntireArea Entire Area
AdvArmingRights_Room1 Room 1 (for Sintony)
3.40 IAdvCommon
Supports the creation of IAdvFilter objects.

 Methods
CreateFilter - Returns a new empty IAdvFilter object
69
02.2018
3.41 IAdvFilter
When retrieving a collection of employees, venues, etc, we may wish to limit the
results we receive, based on a property comparison (e.g. name match), max row
limit, or skipping a specified number of records first (i.e. paging through the
results). An IAdvFilter object can be passed in as an input parameter in the query
to achieve this.
An IAdvFilter consists of one or more AdvFilterEntry objects. The filter result is
determined by satisfying all the AdvFilterEntry objects (i.e. „AND‟ logic across all
AdvFilterEntry objects)
Supports the following methods and properties:
 Methods
Get Returns the AdvFilterEntry object at the

specified index

position index
Add Adds a new AdvFilterEntry object to the

IAdvFilter
filterEntry The AdvFilterEntry object to use
Remove Removes the AdvFilterEntry object at the

specified index

position index
Clear - Removes all AdvFilterEntry objects
Set Sets a AdvFilterEntry object at the specified

index

position index
filterEntry The AdvFilterEntry object to use
70
02.2018
 Properties
Count Integer Get a count of the IAdvAccessComponent objects in the

collection.
SkipObjects Integer Get/set the number of records to skip when retrieving a

collection of records. This property could be used for paging of
results (in conjunction with MaxObjects property)
MaxObjects Integer Get/set the limit of the number of records to retrieve when
retrieving a collection of records. This property could be used for
paging of results (in conjunction with SkipObjects property), or to
limit the max row result for memory or performance reasons.
SortBy string Get/set a field name of the records we are retrieving. If set, the
records will be returned in sorted order according to the field
name (e.g “Name”)
SortDesc boolean If sorting by a field name, set to true if you want to sort in
descending order. The default is false, which means an
ascending sort.
3.42 ComparisonOperator
Enumeration for the possible comparison logic supported in an AdvFilterEntry

object, where the user‟s input value is compared to a field value (e.g. employee
name)
Value Description
Equal The input value exactly matches the field value
NotEqual The input value does not exactly match the field value
Contains The input value is a substring of the field value
LessThan The field value is less than the input value
LessThanOrEqual The field value is less than or equal to the input value
GreaterThan The field value is greater than the input value
GreatherThanOrEqual The field value is greater than or equal to the input value
DoesNotContain The input value is not a substring of the field value
BeginsWith The field value begins with the input value string
EndsWith The field value ends with the input value string
IsEmpty The field value is empty
IsNotEmpty The field value is not empty
AnyOf The field value exactly matches any input value from an
input value collection
71
02.2018
3.43 AdvFilterEntry
Structure representing the details of a single filter, where a field value is compared
to an input value. Multiple AdvFilterEntry objects can be added to an IAdvFilter
object. This IAdvFilter object is then passed in as a parameter for some object
collection queries (e.g. employees, venues, etc).
propertyName string The field name of the object (e.g. Name,

Id). The valid field names that can be
used for various objects are listed in the
next section.
op ComparisonOperator The comparison logic we will be
performing
value object The user‟s input value that will be
compared against the object field
3.43.1 Field Names to be used in Filtering
When constructing an AdvFilterEntry to use in a filter, the “propertyName” should

match a valid object field name. The following are valid field names that can be
used for each object type we are trying to filter.
Object Type Field Name
EmployeeId
FirstName
LastName
EmployeeNumber
Title
Address
PhoneNumber
MobileNumber
PagerNumber
EmailAddress
PayrollNumber
IAdvEmployee
CarRego1
CarModel1
CarColour1
CarRego2
CarModel2
CarColour2
GeneralData
PrimaryWorkgroupId
ApbWorkgroupId
PinNumber (note: for base
credentials only)
2ndPinNumber (note: for all
72
02.2018
base and non-base
credentials)
CardNumber (note: for base
credentials only)
2ndCardNumber (note: for all
base and non-base
credentials)
primaryWorkgroupName
StartDateTime
EndDateTime
UseEmail
Isolate
Visitor
IsVoid
Accessibility
TimedReEntryExclusion
Supervisor
SelfAuthorise
APBExclusion
SmartCardProfileId
MobileServiceProviderId
PagerServiceProviderId
DateOfBirth
CardTrace
Id
IAdvAccessGroup
Name
Id
Name
IAdvAccessLevel
TimeSchedule.Id
TimeSchedule.Name
Id
Name
IAdvWorkgroup
Type
Partition
Id
IAdvAccessComponent
Name
venue_Id
IAdvVenue Name
Description
Id
VenueId
Name
Description
IAdvVenueBooking
RequireAuthentication
StartDateTime
EndDateTime
VenueName
73
02.2018
3.44 IAdvTimeSchedule
Represents a time schedule, used in access level configuration.

Supports the following properties:
 Properties
Id Integer Time Schedule Id
Name string Time Schedule Name
3.45 IAdvTimeScheduleCollection
Represents a collection of IAdvTimeSchedule objects.

Supports iteration over the collection of IAdvTimeSchedule objects using the
 Properties
Count Integer Get a count of the IAdvTimeSchedule objects in the collection
 Methods
Item Retrieves an IAdvTimeSchedule object given the index position.
index Integer representing the zero-based position in the collection
74
02.2018
3.46 IAdvVenue
Represents a venue object, which can be modified, deleted, and created in HR-
API. Supports the following methods and properties:
 Properties
Id Integer Get the venue id
Name string Get/set the venue name
AccessPolicy IAdvAccessPolicy Get the venue‟s access policy.

In order to change a venue‟s access policy, this
IAdvAccessPolicy retrieved can be modified, then the venue
should be saved with the Save() method.
Description string Get/set the venue description
IsExclusive Bool Allows third-party applications to get/set the override standard

access assignment
 Methods
Save - Save changes after modifying the properties of the IAdvVenue

object.
3.47 IAdvVenueCollection
Represents a collection of IAdvVenue objects.

Supports iteration over the collection of IAdvVenue objects using the „foreach‟
construct.
 Properties
Count Integer Get a count of the IAdvVenue objects in the collection
 Methods
Item/Get Retrieves an IAdvVenue object given the index position.
75
02.2018
3.48 IAdvVenueManager
The IAdvVenueManager supports the retrieval, creation and deletion of venues. In

addition it allows users to subscribe to venue events involving database changes to
venues.
 Methods
GetVenues Returns an IAdvVenueCollection

object.
filter Optional IAdvFilter object to limit the

venues retrieved
GetVenueById Returns an IAdvVenue object given

the venue id.
venueId The venue id
CreateVenue - Returns a new instance of an

IAdvVenue object, with properties
initialised to default values.
The venue is not actually created in
SiPass integrated until the venue
object‟s Save() method is called.
DeleteVenue Deletes the venue represented by the

parameter IAdvVenue object.
venue The IAdvVenue object
SubscribeToVenueEvents Notify the server we want to receive

notifications of changes made to
venues, through the
IAdvObjectEventsCallback interface
we pass in as a parameter.
eventsCallback An object implementing the

IAdvObjectEventsCallback interface.
The SiPass server will call the
OnChange() method on a venue
change
pnCookie „out‟ Integer parameter. Unique

number is set on subscription. This
value must be passed in as a
parameter when unsubscribing from
events
SubscribeToVenueAccessPolic Notify the server we want to receive

yEvents notifications of access policy changes
made to venues, through the
interface we pass in as a parameter.
76
02.2018
interface. The SiPass server will call
the OnChange() method on a venue
change

parameter when unsubscribing from
events
Unsubscribe Notify server to stop sending venue

change events
nCookie The cookie value previously received

on the initial subscription
3.49 IAdvVenueBooking
Represents a venue booking, which can be created, modified and deleted using
HR-API
 Properties
Id Integer Get venue booking id
Name String Get/set venue booking name
StartDateTime Date Get/set venue booking start date
EndDateTime Date Get/set venue booking end date
Venue IAdvVenue Get/set the venue used for the booking
Owners IAdvEmployees Get a list of employees that are the owners of this
booking
Attendees IAdvEmployees Get a list of employees that are participants of this

booking
Description String Get/set the venue booking description
Workgroups IAdvWorkgroups Get a list of workgroups that are participants of this

booking
RequireAuthentication Boolean Get/set value indicating if username/password

credentials are required to view a venue booking
77
02.2018
 Methods
AddAttendee Adds a participant to the booking
employee The IAdvEmployee to add
RemoveAttendee Removes a participant from the booking
employee The IAdvEmployee to remove
Save Save the booking (or will be created if a new booking

instance). If the „RequireAuthentication‟ property is true,
then the username and password of one of the booking
organisers needs to be supplied as parameters.
ownerUserName Organiser username
ownerPassword Organiser password.
3.50 IAdvVenueBookingCollection
Represents a collection of IAdvVenueBooking objects.

Supports iteration over the collection of IAdvVenueBooking objects using the
 Properties
Count Integer Get a count of the IAdvVenueBooking objects in the collection
 Methods
Get/Item Retrieves an IAdvVenueBooking object given the index

position.
78
02.2018
3.51 IAdvVenueBookingManager
Supports the creation, deletion and retrieval of venue bookings.

 Methods
GetVenueBookings Returns an IAdvVenueBookingCollection
filter Optional IAdvFilter object to restrict the venue

booking records to return
GetVenueBookingById Returns an IAdvVenueBooking given the booking

id
venueBookingId Venue booking id
CreateNewVenueBooking - Returns a new instance of IAdvVenueBooking,

with properties set to default values.
A new venue booking is not actually created in
SiPass integrated until the venue booking object‟s
Save() method is called.
DeleteVenueBooking Delete the specified venue booking
venueBooking IAdvVenueBooking to delete
ownerUserName Username of a booking organiser. Only required if

„Require Authentication‟ property is set
ownerPassword Password of a booking organiser. Only required if

„Require Authentication‟ property is set
3.52 IAdvWorkgroupManager
Supports the creation, deletion and retrieval of workgroups. In addition it allows

users to subscribe to workgroup events involving database changes to
workgroups.
 Methods
GetWorkgroups Returns an IAdvWorkgroups

object
filter Optional IAdvFilter object to

restrict the workgroup records to
79
02.2018
return
GetWorkgroupById Returns an IAdvWorkgroup given

the workgroup id
wkgId Workgroup id
CreateNewWorkgroup - Returns a new instance of

IAdvWorkgroup, with properties
set to default values.
A new workgroup is not actually
created in SiPass integrated until
the workgroup object‟s Save()
method is called.
DeleteWorkgroup Delete the specified workgroup
workgroup IAdvWorkgroup to delete
SubscribeToWorkgroupEvents Notify the server we want to

receive notifications of changes
made to workgroups, through the
IAdvObjectEventsCallback
interface we pass in as a
parameter.

IAdvObjectEventsCallback
interface. The SiPass server will
call the OnChange() method on a
workgroup change

parameter when unsubscribing
from events
SubscribeToWorkgroupAccessPolicyEvents Notify the server we want to

receive notifications of access
policy changes made to
workgroups, through the
interface we pass in as a
parameter.

interface. The SiPass server will
call the OnChange() method on a
venue change

parameter when unsubscribing
from events
Unsubscribe Notify server to stop sending

workgroup change events
nCookie The cookie value previously

received on the initial subscription
80
02.2018
3.53 AdvWorkgroupType
Enumeration for the possible workgroup types
Value Description
AdvWorkgroupType_Department Department workgroup type
AdvWorkgroupType_Contractor Contractor workgroup type
AdvWorkgroupType_Other Other workgroup type
AdvWorkgroupType_Visitor Visitor workgroup type
3.54 AdvEventType
Enumeration for the possible event types that the server can send the HR-API
application.
Value Description
AdvEventType_Insert, Insert event (new record in database)
AdvEventType_Modify, Modify event (existing property modified in database)
AdvEventType_Delete Delete event (record deleted in database)
3.55 AdvObjectEventInfo
Structure representing the details of an object event sent from SiPass integrated
server to the HR-API application. Events are only sent if event subscription has
occurred.
These object events are supported for employees, workgroups and venues.
Id Integer Id of the object

created/updated/deleted
fieldNames String array List of object property names with
new values, for a creation or
modification.
oldValues Object array List of old property values (before
database change), in the same
sequence as the fieldNames
newValues Object array List of new property values (after
database change), in the same
sequence as the fieldNames
type AdvEventType Type of event
(insert/modify/delete)
81
02.2018
3.56 IAdvObjectEventsCallback
When subscribing to object events, the HR-API application must supply a class
that implements the IAdvObjectEventsCallback interface. The SiPass server will
call this interface‟s OnChange() method when it needs to notify the application of
an event. The OnChange() method must return without exception (returning S_OK)
otherwise the interface will be unsubscribed by the server.
The following are the methods of the interface:
OnChange Called by the SiPass server
info AdvObjectEventInfo containing the event

information
3.57 AdvAccessPolicyEventInfo
Structure representing the details of an access policy event sent from SiPass
integrated server to the HR-API application. Events are only sent if event
subscription has occurred.
These access policy events are supported for employees, workgroups and venues.
Each event shows the addition, deletion, or modification of a single access rule.

objectId Integer Id of the object created/updated/deleted
Detail of the access rule before the
old AdvAccessRule database change. Will be empty if the event
involves addition of a new access rule
Detail of the access rule after the database

current AdvAccessRule change. Will be empty if the event involves
deletion of an access rule.
type AdvEventType Type of event (insert/modify/delete)
82
02.2018
3.58 IAdvAccessPolicyEventsCallback
When subscribing to access policy events, the HR-API application must supply a
class that implements the IAdvAccessPolicyEventsCallback interface. The SiPass
server will call this interface‟s OnChange() method when it needs to notify the
application of an event. The OnChange() method must return without exception
(returning S_OK) otherwise the interface will be unsubscribed by the server.
info AdvAccessPolicyEventInfo containing the event

information
3.59 AdvEmployeeWorkgroupsEventInfo
Structure representing the details of an employee workgroups event sent from

SiPass integrated server to the HR-API application. Events are only sent if event
An event is sent when the workgroups assigned to an employee has changed.
employeeId Integer Employee id

insertedWorkgroupIds Integer array Array of ids of the new workgroups
assigned to the employee
removedWorkgroupIds Integer array Array of ids of the workgroups that
have been removed from the
employee
3.60 IAdvEmployeeWorkgroupsEventsCallback
When subscribing to employee workgroups events, the HR-API application must

supply a class that implements the IAdvEmployeeWorkgroupsEventsCallback
interface. The SiPass server will call this interface‟s OnChange() method when it
needs to notify the application of an event. The OnChange() method must return
without exception (returning S_OK) otherwise the interface will be unsubscribed by
the server.
info AdvEmployeeWorkgroupsEventInfo containing the

event information
83
02.2018
3.61 AdvEmployeeCredential
Structure containing the details of an employee credential. AdvEmployeeCredential

is used in employee credential events (see section
AdvEmployeeCredentialEventInfo)
credentialProfileId Integer Credential profile id
cardNumber string Card Number
pin Integer PIN
voidCard Boolean Card Void
startDate Date Credential start date
endDate Date Credential end date
pinErrorDisabled Boolean PIN error disabled
3.62 AdvEmployeeCredentialEventInfo
Structure representing the details of an employee credential event sent from

SiPass integrated server to the HR-API application. Events are only sent if event
An event is sent when an employee credential has been added, removed or
modified.
employeeId Integer Employee id
old AdvEmployeeCredential Detail of the credential before the

database change. Will be empty if
the event involves addition of a new
credential to the employee
current AdvEmployeeCredential Detail of the credential after the

database change. Will be empty if
the event involves removal of a
credential from the employee
type AdvEventType Type of event (insert/modify/delete)
84
02.2018
3.63 IAdvEmployeeCredentialEventsCallback
When subscribing to employee credential events, the HR-API application must

supply a class that implements the IAdvEmployeeCredentialEventsCallback
interface. The SiPass server will call this interface‟s OnChange() method when it
needs to notify the application of an event. The OnChange() method must return
without exception (returning S_OK) otherwise the interface will be unsubscribed by
the server.
info AdvEmployeeCredentialEventInfo containing the

event information
3.64 AdvFingerIndex
An enumeration listing the fingers. Used as an input parameter when requesting

biometric data for a specific finger (see GetBiometricData method in
IAdvEmployee). Also, an array of AdvFingerIndex enums are returned when
requesting a list of all the biometric encoded fingers (see BiometricEncodedFingers
property in IAdvEmployee)
Value
AdvFingerIndex_LeftLittle
AdvFingerIndex_LeftRing
AdvFingerIndex_LeftMiddle
AdvFingerIndex_LeftIndex
AdvFingerIndex_LeftThumb
AdvFingerIndex_RightThumb
AdvFingerIndex_RightIndex
AdvFingerIndex_RightMiddle
AdvFingerIndex_RightRing
AdvFingerIndex_RightLittle
85
02.2018
3.65 IAdvEmployeeField
Holds the information about a specific employee custom field.
Supports the following read-only properties:
Name String The name of the custom field
The type of data the custom field stores

DataType AdvFieldDataType
(string, date, boolean or integer)
Indicates whether the value of this
custom field should be unique in the
Unique Boolean
system. Only relevant for String and
Date data types
Indicates the maximum possible length
MaxLength Integer of the custom field. Only relevant for
String data type
Indicates whether this custom field must
have a non-empty value for each
Compulsory Boolean
employee. Only relevant for String data
type
3.66 IAdvEmployeeFields
Represents a collection of IAdvEmployeeField objects.
Supports iteration over the collection of IAdvEmployeeField objects using the
 Properties:

The number of
Count Integer IAdvEmployeeField objects
held in the collection
 Methods:

Retrieves an
Item IAdvEmployeeField object
given the index position.
Integer representing the zero-
index
based position in the collection
86
02.2018
3.67 AdvFieldDataType
Enumeration representing the possible data types for an employee custom field
(IAdvEmployeeField)
Value
AdvFieldDataTypeUnknown
AdvFieldDataTypeString
AdvFieldDataTypeDate
AdvFieldDataTypeInteger
AdvFieldDataTypeBoolean
87
02.2018
HR-API Sample program
4 HR-API Sample program
The SiPass integrated CD includes a HR-API Sample program. The features of the
HR-API Sample program reflect most of the capabilities of the HR-API.
Feature Overview
 Connects and Logs onto SiPass integrated server

 Able to create/modify/delete the following objects:
 Employees
 Workgroups
 Access Levels
 Access Groups
 Venues
 Venue Bookings
 Able to add, modify and delete a credential assigned to the employee

 Able to modify the access policy of the following objects:
 Employees
 Workgroups
 Venues
 Able to subscribe and receive information for the following events:

 Employee object
 Employee access policy
 Employee workgroup
 Employee credential
Note:
– SiPass integrated must be installed (with „HR API Core‟ feature) on the computers on which you
want to run the sample application
88
02.2018
Appendix A: Error Codes
5 Appendix A: Error Codes
The SiPass integrated API methods can generate COM Exceptions containing the
following possible error values during logon:
Name Value Description

ADV_E_USER_NAME 0x80040a01 Invalid user name passed to logon.
ADV_E_PASSWORD 0x80040a02 Invalid password passed to logon.
ADV_E_NOT_CONNECTED 0x80040a03 A method was called that required a
session to be connected.
ADV_E_ALREADY_CONNECT 0x80040a04 The Connect method was called on an
ED already connected session.
ADV_E_LOCKOUT 0x80040a05 The operator has been locked out of
SiPass integrated.
ADV_E_RETRIES_EXCEEDED 0x80040a06 The operator has exceeded the allowed
number of invalid logon attempts.
ADV_E_EXPIRED 0x80040a07 The operator logon has expired.
ADV_E_INTERVAL 0x80040a08 The operator is not allowed to logon at
this time.
ADV_E_DIFFERENT_USER 0x80040a09 When logging on again after a timeout, a
different username was supplied.
ADV_E_USER_CANCEL 0x80040a0a The user selected the cancel button on
the Logon dialog box.
ADV_E_TOO_MANY_CLIENTS 0x80040a0b Too many workstations are
simultaneously logged on to the SiPass
integrated server.
ADV_E_VALIDITY_CHECK 0x80040a0c SiPass integrated license information is
invalid.
ADV_E_TOO_MANY_EMPLOY 0x80040a20 The number of employees has reached
EES_FOR_LICENCE the license limit.
ADV_E_CERTIFICATETHUMB 0X80040a66 Server thumbprint does not match the
PRINTMISMATCH expected value.
ADV_E_SERVERCERTIFICATE 0X80040a67 Server certificate or certificate chain is
ORCHAINISNULL null.
ADV_E_SERVERCERTIFICATE 0X80040a68 The server certificate is invalid and
CHAINCONTAINSERRORS contains errors.
ADV_E_SSLPOLICYERROR 0X80040a69 Error detected in SSL policy .
ADV_E_CERTIFICATEHOSTNA 0X80040a70 Server name does not match the
MEMISMATCH expected value.
In addition, the SiPass integrated API methods can generate validation errors of
custom . NET type ValidationException. The validation error codes can be
accessed if the HR-API application has a reference to “SiPass.Exception.dll”
assembly, available in SiPass integrated installation directory.
All possible validation error codes are listed in ErrorCodeEnum (defined in
SiPass.Exception.dll).
89
02.2018
public enum ErrorCodeEnum

{
OK = 0,
// System errors
UNKNOWN = 1,
SERVER_INTERNAL = 2,
UNAUTHORISED = 3,
INVALID_LOGIN = 4,
TOO_MANY_WEB_CLIENTS = 5,
ACCESS_DENIED = 6,
// Venue validation errors

UNKNOWN_VENUE = 100,
VENUE_INACCESSIBLE = 101,
VENUE_HAS_BOOKINGS = 102,
VENUE_OUTDATED = 103,
VENUE_HAS_VIEWS = 104,
VENUE_EMPTY_NAME = 105,
VENUE_DUPLICATE_NAME = 106,
VENUE_NAME_TOO_LONG = 107,
// Venue Booking validation errors

UNKNOWN_VENUE_BOOKING = 200,
VENUE_BOOKING_OUTDATED = 201,
VENUE_BOOKING_EMPTY_NAME = 202,
VENUE_BOOKING_NAME_TOO_LONG = 203,
VENUE_BOOKING_NO_OWNER = 204,
VENUE_BOOKING_INVALID_USERNAME = 205,
VENUE_BOOKING_DUPLICATE_PARTICIPANT = 206,
VENUE_BOOKING_DUPLICATE_OWNER = 207,
VENUE_BOOKING_DUPLICATE_WORKGROUP = 208,
UNKNOWN_RECURRING_VENUE_BOOKING = 209,
RECURRING_VENUE_BOOKING_INVALID_USERNAME = 210,
RECURRING_VENUE_BOOKING_OUTDATED = 211,
RECURRING_VENUE_BOOKING_INCORRECT = 212,
// Employee validation errors

UNKNOWN_CARDHOLDER = 300,
EMPLOYEE_NAME_EMPTY = 301,
EMPLOYEE_END_DATE_BEFORE_START_DATE = 302,
EMPLOYEE_NO_PRIMARY_WORKGROUP = 303,
EMPLOYEE_TOO_MANY_PRIMARY_WORKGROUPS = 304,
EMPLOYEE_NO_APB_WORKGROUP = 305,
EMPLOYEE_TOO_MANY_APB_WORKGROUPS = 306,
EMPLOYEE_CARD_NUMBER_INVALID = 307, // The card number has not been set (i.e 0)
EMPLOYEE_CARD_END_DATE_BEFORE_START_DATE = 308,
EMPLOYEE_CARD_NUMBER_DUPLICATE = 309, // Another employee has the same card
number with the same credential profile
EMPLOYEE_PIN_DUPLICATE = 310, // PIN duplicate detected in unique PIN scenario
(PIN as Card mode)
EMPLOYEE_CARD_CREDENTIAL_PROFILE_DUPLICATE = 311, // The employee has 2 cards
belonging to the same credential profile
EMPLOYEE_LICENSE_LIMIT = 312,
EMPLOYEE_DOES_NOT_EXIST = 313,
EMPLOYEE_INVALID_GID = 314,
// Access level validation errors

ACCESS_LEVEL_DOES_NOT_EXIST = 400,
ACCESS_LEVEL_EMPTY = 401,
// Access group validation errors

ACCESS_GROUP_DOES_NOT_EXIST = 500,
ACCESS_GROUP_EMPTY = 501,
90
02.2018
// Workgroup validation errors
WORKGROUP_DOES_NOT_EXIST = 600,
// Time schedule validation errors

TIME_SCHEDULE_DOES_NOT_EXIST = 700,
// Point/group validation errors

UNKNOWN_POINT_TYPE = 800,
UNKNOWN_POINT_GROUP_TYPE = 801,
// Access rule validation errors

UNKNOWN_ACCESS_RULE = 900,
UNKNOWN_ACCESS_CONTROL_TYPE = 901,
ACCESS_RULE_WITHOUT_TIME_SCHEDULE = 902,
// Dependency errors (for deletion)

DEPENDENCY_ERROR = 1000, // The object we are trying to delete is in use by
other objects (e.g. cannot delete access level if already assigned to access group)
DEPENDENCY_ERROR_CARDHOLDER = 1001,
DEPENDENCY_ERROR_WORKGROUP = 1002,
DEPENDENCY_ERROR_VENUE = 1003,
DEPENDENCY_ERROR_ACCESS_GROUP = 1004,
DEPENDENCY_ERROR_ASP_ACTIVITY = 1005,
// General object validation errors

NO_FIELD_REQUESTED = 1100,
UNKNOWN_FIELD = 1101,
IN_USE_CANNOT_UPDATE = 1102, // Some objects cannot be updated once they are in
use (e.g. credential profile tech/facility)
OBJECT_DOES_NOT_EXIST = 1103
INVALID_ID = 1104
DUPLICATE_NAME = 1105,
FIELD_EMPTY = 1106, // General error where a needed field is missing data
FIELD_LENGTH_EXCEEDED = 1107
}
In addition, .NET exceptions of type System.ArgumentException are produced if a

parameter is not in an expected format (e.g. undefined enum value), or an attempt
was made to set a property that is read-only.
91
02.2018
Troubleshooting
6 Troubleshooting
The following troubleshooting table may help you to overcome errors during the
operation of HR-API and SiPass integrated:
Error Solution
HR-API Callback not The COM Security must be configured on the HR-API client
received to receive callback notifications from the server:
On the client computer:
1. Go to Component Services (click Windows+R button
on the keyboard, type dcomcnfg and press Enter)
The Component Services dialog is displayed.
2. Expand the tree - Component Services > Computers
> My Computer
3. Right-click My Computer and select Properties from
the menu options
4. Select the COM Security tab and click Edit Default
5. Add the SiPass server account name and tick the Allow
checkboxes for Local Access and Remote Access
6. Click OK
Note: The baove procedure has been performed on
Microsoft Windows 7 and may vary depending on the
Operating System you are using. Refer to the Help of your
respective operating system in this case.
92
02.2018
Issued by © Siemens Switzerland Ltd, 2018
Siemens Switzerland Ltd Technical specifications and availability subject to change without notice.
Building Technologies Division
International Headquarters
Gubelstrasse 22
CH-6301 Zug
Tel. +41 41-724 24 24
www.siemens.com/buildingtechnologies
Document no. A100084-1 HR-API Programmer‟s Reference Manual

Edition 02.2018 CPS Fire Safety

SiPass Integrated HR-API Programmers Reference Manual PDF

Загружено:

Сведения о документе

Оригинальное название

Авторское право

Доступные форматы

Поделиться этим документом

Поделиться или встроить документ

Параметры публикации

Этот документ был вам полезен?

Это неприемлемый материал?

Авторское право:

Доступные форматы

SiPass Integrated HR-API Programmers Reference Manual PDF

Загружено:

Авторское право:

Доступные форматы

Access Control

HR-API Programmer’s Reference Manual

A-100084-1 Building Technologies

1 About this document .............................................................................. 6

3 Using the SiPass integrated API ......................................................... 13

Building Technologies A-100084-1

4 HR-API Sample program ...................................................................... 88

5 Appendix A: Error Codes ..................................................................... 89

1 About this document

Building Technologies A-100084-1

1.1 Document Revision History

Document Revision Changes Made

12/05 Document created

06/07 Modification to file reference

09/09 Modification to manual

10/09 Update to contents

09/13 Update to contents

01/14 Update to contents

09/14 Update to contents

11/15 Update to contents

02/17 Update to contents

05/17 Update to contents

11/17 Update to contents

2.2 Object Model Overview

The following SiPass integrated objects are available:

Session Creates a connection to the SiPass integrated server and allows a

Server Represents a connection to the SiPass integrated server.

Employee Manager Provides access to employee related information.

Employee Provides access to information about a single employee.

Workgroup Provides access to information about a single workgroup.

Access Control Manager Provides access to access group information.

Access Group Provides access to information about a single access group

Access Level Provides access to information about a single access level.

IAdvAccessComponent Represents a single point or point group

IAdvAccessComponentCollecti Represents a collection of points or point groups

IAdvAccessComponentReader Allows queries to fetch points and point groups

IAdvAccessPolicy Represents a collection of access rules associated with an employee,

IAdvCommon Supports the creation of IAdvFilter objects

AdvFilter Entry A single piece of comparison logic. Multiple AdvFilterEntry objects

IAdvTimeSchedule Represents a single time schedule

IAdvTimeScheduleCollection Represents a collection of time schedule objects

IAdvVenue Represents a single venue

IAdvVenueBooking Represents a single venue booking

IAdvVenueBookingCollection Represents a collection of venue bookings

IAdvVenueBookingManager Supports the creation, deletion and retrieval of venue bookings

IAdvVenueCollection Represents a collection of venues

IAdvVenueManager Supports the creation, deletion and retrieval of venues, and

IAdvWorkgroupManager Supports the creation, deletion and retrieval of workgroups, and

AdvWorkgroupType Enumeration for possible workgroup types

IAdvObjectEventsCallback Callback interface used by SiPass integrated server to notify HR-API

AdvAccessRuleType Enumeration for the possible access item types supported in an

AdvControlMode Enumeration for Intrusion Control Mode

AdvArmingRights Enumeration for Intrusion Arming Rights

IAdvAccessPolicyEventsCallb Callback interface used by SiPass integrated server to notify HR-API

AdvEmployeeWorkgroupsEve Structure representing the details of an employee workgroups event

IAdvEmployeeWorkgroupsEve Callback interface used by SiPass integrated server to notify HR-API

AdvEmployeeCredential Structure containing the details of an employee credential.

AdvEmployeeCredentialEvent Structure representing the details of an employee credential event

IAdvEmployeeCredentialEvent Callback interface used by SiPass integrated server to notify HR-API

AdvFinger Index Enumeration for finger index. Used in biometric functionality

IAdvEmployeeFields A collection of employee custom fields

AdvFieldDataType Enumertion for the possible custom field data types

3 Using the SiPass integrated API