Bosch Access Systems

ACE 4.9.20007 Version Page

ACE API 1.1.5a 1/69
Author Date
Software 15.03.2023
Development

Content
1 Abstract .................................................................................................................................................... 4
2 Compatibility............................................................................................................................................ 5
3 Concept .................................................................................................................................................... 7
3.1 Object Types .................................................................................................................................... 8
3.2 Important Object Methods ............................................................................................................... 8
4 Getting Started ....................................................................................................................................... 10
4.1 ACE ................................................................................................................................................ 10
4.2 AMS ............................................................................................................................................... 10
4.3 Writing own software applications ................................................................................................ 10
5 Deployment ............................................................................................................................................ 11
5.1 In C++ ............................................................................................................................................ 11
5.2 In C# ............................................................................................................................................... 11
5.3 Sample Application: [Link] ........................................................................ 11
5.4 Sample Application: [Link]........................................................................... 11
6 Tour: ACE API Object Life Cycle ......................................................................................................... 13
6.1 Hints for C# programmers.............................................................................................................. 16
6.2 Persons, Visitors and Cards database tables ................................................................................... 18
6.2.1 Card description ..................................................................................................................... 19
6.2.2 Some examples about cardholder related tables..................................................................... 22
7 Example: How to Receive Events .......................................................................................................... 24
7.1 Error Handling ............................................................................................................................... 26
7.2 Event Messages .............................................................................................................................. 26
8 Example: How to Send Commands ....................................................................................................... 29
8.1 Execution of commands for devices MAC, AMC, doors or readers.............................................. 29
8.2 API command execution: parallel changing of device parameters ................................................ 30
9 Clients .................................................................................................................................................... 32
10 Custom Fields..................................................................................................................................... 33
10.1 New custom fields since ACE 4.5 ................................................................................................. 33
10.2 Using former custom fields RESERVE1 to RESERVE10 ............................................................ 33
10.3 Using Custom fields (AdditionalFields) ........................................................................................ 34
11 How to use AutoCreateMobileCard ................................................................................................... 35
12 Documentation ................................................................................................................................... 36
13 Troubleshooting ................................................................................................................................. 37
14 Known Issues\Limitations\Recommendation .................................................................................... 38
14.1 Multi MAC Systems & Authorizations .......................................................................................... 38
14.2 Deletion of Authorizations ............................................................................................................. 38
14.3 Max number of API Clients ........................................................................................................... 38
14.4 Max number of cards per person\visitor......................................................................................... 38
Bosch Access Systems

ACE 4.9.20007 Version Page

ACE API 1.1.5a 2/69
Author Date
Software 15.03.2023
Development

14.5 Max picture size ............................................................................................................................. 39

14.6 Known not solved bugs .................................................................................................................. 39
15 Using ACE API in hierarchical systems ............................................................................................ 39
16 Multithreading .................................................................................................................................... 42
16.1 API in multithreading applications ................................................................................................ 42
16.2 Example how to use API in multithreading .NET application ....................................................... 43
17 OTIS Elevators ................................................................................................................................... 46
17.1 Authorizations ................................................................................................................................ 46
17.2 Additional OTIS fields for persons ................................................................................................ 46
18 PegaSys Offline System Support ....................................................................................................... 48
18.1 PegaSys base class ......................................................................................................................... 49
18.2 PegaSysCard .................................................................................................................................. 50
18.3 PegaSysDoors and PegaSysGroups (for testing only) ................................................................... 50
18.4 PegaSysDoorGroup (for testing only) ............................................................................................ 51
18.5 PegaSysAuthPerPerson .................................................................................................................. 51
18.5.1 Assign Authorization for a single door or group .................................................................... 51
18.5.2 Assign multiple authorizations to a person ............................................................................ 52
18.6 PegaSysGroupsPerAuth ................................................................................................................. 52
18.7 Best Practice how to use the PegaSys API ..................................................................................... 54
19 Set the directory for logging............................................................................................................... 55
20 Release Notes ..................................................................................................................................... 55
20.1 ACE API Version 4.1.7777.0 ......................................................................................................... 55
20.2 ACE API Version 4.1.8401.0 ......................................................................................................... 56
20.3 ACE API Version 4.1.8410.0 ......................................................................................................... 56
20.4 ACE API Version 4.1.8420.0 ......................................................................................................... 57
20.5 ACE API Version 4.2.8617.0 ......................................................................................................... 57
20.6 ACE API Version 4.2.8800.0 ......................................................................................................... 57
20.7 ACE API Version 4.2.8860.0 ......................................................................................................... 57
20.8 ACE API Version 4.3.8953.0 ......................................................................................................... 57
20.9 ACE API Version > 4.3.9005.0 (patch) ......................................................................................... 58
20.10 ACE API Version > 4.3.9061.0.................................................................................................. 58
20.11 ACE API Version > 4.3.9076.0.................................................................................................. 58
20.12 ACE API Version > 4.3.9079.0.................................................................................................. 58
20.13 ACE API Version 4.4 ................................................................................................................. 58
20.14 ACE API Version 4.4.9091.0 ..................................................................................................... 58
20.15 ACE API Version 4.5.9310.0 ..................................................................................................... 59
20.16 ACE API Version 4.5.9456.0 ..................................................................................................... 59
20.17 ACE API Version 4.5.9562.0 ..................................................................................................... 60
20.18 ACE API Version 4.6.9895.0 ..................................................................................................... 60
20.19 ACE API Version 4.6.10052.0 ................................................................................................... 61
Bosch Access Systems

ACE 4.9.20007 Version Page

ACE API 1.1.5a 3/69
Author Date
Software 15.03.2023
Development

20.20 ACE API Version 4.6.10281.0 ................................................................................................... 61

20.21 ACE API Version 4.6.10363.0 ................................................................................................... 63
20.22 ACE API Version 4.7.10409.0 ................................................................................................... 63
20.23 ACE API Version 4.7.10574.0 ................................................................................................... 63
20.24 ACE API Version 4.7.10714 ...................................................................................................... 63
20.25 ACE API Version > 4.7.10764................................................................................................... 64
20.26 ACE API Version > 4.8.11077................................................................................................... 64
20.27 ACE API Version > 4.9.11120................................................................................................... 64
20.28 ACE API Version > 4.9.11177................................................................................................... 64
20.29 ACE API Version > 4.9.11306................................................................................................... 64
20.30 ACE API Version > 4.9.20000................................................................................................... 65
21 Document History .............................................................................................................................. 66
Bosch Access Systems

ACE 4.9.20007 Version Page

ACE API 1.1.5a 4/69
Author Date
Software 15.03.2023
Development

1 Abstract
The Access Engine (ACE) represents the access control part of the Bosch Building Integration System
(BIS). To allow others to access the ACE without user interaction Bosch Access Systems provides a set of
classes, the ACE API, to read and/or write this data. This interface is a Win32 interface written in unman-
aged C++ using Microsoft’s Visual Studio 2019. If you are using a preceding version of Visual Studio,
make sure that the newest Visual C++ Redistributable Packages
vcredist_x86.exe is installed.
Since BIS\ACE 4.1 TU1 the API can also be used from .NET applications. The wrapper is part of the
W32_ACEInterface library, uses .NET Framework 4 and contains the same functionality as the unman-
aged variant.
The API also can be used with the AMS (Access Management System) which represents the standalone ac-
cess control system version.
Bosch Access Systems

ACE 4.9.20007 Version Page

ACE API 1.1.5a 5/69
Author Date
Software 15.03.2023
Development

2 Compatibility

ACE API (SDK) compatibility matrix 1/2

Product BIS BIS BIS BIS BIS BIS

version 4.1 4.2 4.3 4.4 4.5 4.6

(Build) (8100) (8800) (9000) (9111) (9310) (9906)

SDK

4.1 ✔
(8100)

4.2 ✔
(8800)

4.3 ✔
(9000)

4.4 ✔
(9111)

4.5 ✔
(9310)

4.6 ✔
(9906)

✔ 100% compatible, but if you try a functionality not provided in the older version it cannot work
(✔) Compatible with the old functionality (see description details in “ACE [Link]” what have changed)
Bosch Access Systems

ACE 4.9.20007 Version Page

ACE API 1.1.5a 6/69
Author Date
Software 15.03.2023
Development

ACE API (SDK) compatibility matrix 2/2

Product BIS BIS BIS BIS BIS BIS

version 4.6 4.7 4.8 4.9 4.9.1 5.0

(Build) (10363) (10430) (10900) (11200) (12000) (20000)

AMS AMS
3.0/3.0.1 4.0/4.0.1
SDK

4.6 ✔ (✔)
(10363)

4.7 ✔ ✔
(10430)

4.8 (✔) (✔) ✔ (✔) (✔) (✔)

(10900)

4.9 (✔) (✔) (✔) ✔ (✔) (✔)

(11200)

4.9.1 (✔) (✔) (✔) (✔) ✔ (✔)

(12000)

4.9.3 (✔) (✔) (✔) (✔) (✔) ✔

(20000)

✔100% compatible, but if you try a functionality not provided in the older version it cannot work
(✔) Compatible with the old functionality (see description details in “ACE [Link]” what have changed)
Bosch Access Systems

ACE 4.9.20007 Version Page

ACE API 1.1.5a 7/69
Author Date
Software 15.03.2023
Development

3 Concept
Reading and writing ACE data in an application using the ACE API is done by instantiating objects. These
are directly derived from their database counterparts. The ACE API encapsulates several types of data ob-
jects (as shown in the table Object Types below): Persons, Visitors, Companies, Cards, several PegaSys
(offline locking system) objects and 4 types dealing with authorizations.
Reflecting the database tables each object has a unique identifier. This identifier is used to load or delete an
object. If an object has to be inserted into the database, the identifier is not necessary because it will be cre-
ated by the software automatically when the instance is added to the database and can afterwards be ac-
cessed through the object instance.
To load data objects that meet certain conditions you have to load their unique identifiers beforehand. For
this purpose you might want to use a query object. Afterwards you can instantiate the objects using the
Get-Method.
To allow the data and query objects to work properly, an interface object has to be passed on instantiation.
This interface object has to be instantiated and initialized once. It must be available in order for the objects
to remain addressable (“alive”).

See chapter Documentation, in particular the mentioned windows help files, for more detailed information
about data objects and return values using the managed or unmanaged interface.

See chapter ACE API object life cycle for an example of how these classes work together.
Bosch Access Systems

ACE 4.9.20007 Version Page

ACE API 1.1.5a 8/69
Author Date
Software 15.03.2023
Development

3.1 Object Types

The following object types are available:

Object type C++ Object type C# Category Comments

CW32_ACEInterface AccessEngine Interface ob- Needed for all object instantiations
ject Provide Start/Stop event messages
Query ACEQuery Query object Encapsulating a database SELECT
statement. Needed for loading sub-
sets of objects
Persons ACEPersons Data object Encapsulating persons
Visitors ACEVisitors Data object Encapsulating visitors
Companies ACECompanies Data object Encapsulating companies
Cards ACECards Data object Encapsulating cards
Authorizations ACEAuthorizations Data object Encapsulating authorizations
TimeModels ACETimeModels Data object Encapsulating time models
DayModelsAC ACEDayModelsAC Data object Encapsulating day models
SpecialDays ACESpecialDays Data object Encapsulating special days (e.g.
Easter)
Commands ACECommands Interface ob- Provides methods to open doors,
ject change modes
PegaSys ACEPegaSys Data object Basic methods for PegaSys offline
systems
PegaSysCard ACEPegaSysCard Data object Methods to add/update/delete
sacards
PegaSysDoor ACEPegaSysDoor Data object Methods to add/update/delete sa-
doors
PegaSysGroup ACEPegaSysGroup Data object Methods to add/update/delete sa-
groups
PegaSysDoorGroup ACEPegaSysDoorGroup Data object Methods to add/delete sadoorgroups
PegaSysGroupsPerAuth ACEPegaSysGroupPerAuth Data object Methods to add/delete sagroup-
sperauth
PegaSysAuthPerPerson ACEPegaSysAuthPerPerson Data object Methods to add/delete saauthperper-
son

3.2 Important Object Methods

Name Object Type Description

Bosch Access Systems

ACE 4.9.20007 Version Page

ACE API 1.1.5a 9/69
Author Date
Software 15.03.2023
Development

Add All data object types Adds an object into the database
Update All data object types Updates an object in the database
Delete All data object types Deletes an object from the database. The object
remains in the database marked as deleted
Get All data object types Method to load an object from the database using
its unique ID
GetPersonId Persons Returns the unique identifier of a person
GetVisitorId Visitors Returns the unique identifier of a visitor
GetCompanyId Companies Returns the unique identifier of a company
GetCardId Cards Returns the unique identifier of a card
GetAuthorizationId Authorizations Returns the unique identifier of an authorization
GetTimeModelId TimeModels Returns the unique identifier of a time model
GetDayModelId DayModelsAC Returns the unique identifier of a day model
GetSpecialDayId SpecialDays Returns the unique identifier of a special day
GetPegaSystemId PegaSys Returns the identifier of the sa system
SetPegaSysOption PegaSys Enable PegaSys option for given card
ResetPegaSysOption PegaSys Disable PegaSys option for given card
GetSaCardId PegaSysCard Returns the unique identifier of a sacard
GetCardId PegaSysCard Returns the identifier of the corresponding card
GetSaDoorId PegaSysDoor Returns the unique identifier of the sadoor
GetSaGroupId PegaSysGroup Returns the unique identifier of the sagroup
GetSaDoorGroupId PegaSysDoorGroup Returns the unique identifier of the sadoorgroup
GetSaGroupPerAuthId PegaSysGroupsPerAuth Returns the unique identifier of the
sagroupsperauth
GetSaAuthPerPersonId PegaSysAuthPerPerson Returns the unique identifier of the saauthperper-
son
Bosch Access Systems

ACE 4.9.20007 Version Page

ACE API 1.1.5a 10/69
Author Date
Software 15.03.2023
Development

4 Getting Started
To use the ACE API you must meet the following requirements:

4.1 ACE
1. Ensure that your BIS configuration allows you to use the ACE API. On the BIS server open BIS
Configuration Browser -> Administration > ACE Licenses > Advanced Programming Interface
(API) for Master Data. This field must be set to Yes.
2. Specify a user that is entitled to use the ACE API. We recommend a dedicated user (e.g.
‘ACE_API’). On the BIS server open BIS Configuration Browser -> Administration > Operators
> Tab ACE API Access rights. Click Unlimited Access.

4.2 AMS
Ensure that your AMS configuration allows you to use the AMS SDK(API). Specify a user that is enti-
tled to use the AMS SDK(API). We recommend a dedicated user (e.g. ‘ACE_API’). On the AMS client
go to -> Configuration > Operators and Workstations > User rights. Select the dedicated user (e.g.
‘ACE_API’) and set the ‘API usages’ to Unlimited Access.

4.3 Writing own software applications

1. You must have a functional installation of Microsoft Visual Studio 2019.
2. For writing your own software you must copy the contents of the BIS installation medium folder
_Install\AddOns\ACE\API to your local hard drive.
Bosch Access Systems

ACE 4.9.20007 Version Page

ACE API 1.1.5a 11/69
Author Date
Software 15.03.2023
Development

5 Deployment
For deploying the ACE API you must have a Microsoft Visual Studio 2019 project.

5.1 In C++
1. Make sure that you are compiling with Unicode enabled.
2. Each source file using the ACE API must include W32_ACEInterface.h.
3. Make sure that the compiler and linker settings have access to the contents of the folders CPlusPlus
API\Inc and CPlusPlus API\Lib on your local hard drive.
4. When starting an ACE API application, the contents of the folder
_Install\AddOns\ACE\API\CPlusPlus API\Bin must be in the application’s folder or in
another folder in your path.

5.2 In C#
1. Before creating a .NET framework solution, the contents of the folder
_Install\AddOns\ACE\API\CPlusPlus API\Bin must be copied to your local hard disk.
2. Create a new .NET framework solution using .NET framework in (at least) version 4.0. At the moment
the API supports the .NET frameworks up until version 4.8.
3. Add a reference to the local file “W32_ACEInterface.dll” to the solution.
4. Assert that the “Copy local” property for the reference is set to “true”.

5.3 Sample Application: [Link]

For your convenience Bosch Access Systems provides you with a sample application:
[Link]. It lets you navigate through most of the functionality and enables you to
modify the ACE data interactively.

1. Copy the contents of the BIS installation medium folder _Install\AddOns\ACE\API to your
local hard drive.
2. Double click on _Install\AddOns\ACE\API\CPlusPlus Sam-
ple\[Link]
3. Build and run the application.

5.4 Sample Application: [Link]

The sample application [Link] shows how to use the .NET wrapper. This sample
provides a simple visual dialog and shows how to create a visitor with card and authorization assignment.
On other pages it shows how to activate and deactivate a threat level in a MAC and send some specific de-
vice commands to MAC and readers.
Bosch Access Systems

ACE 4.9.20007 Version Page

ACE API 1.1.5a 12/69
Author Date
Software 15.03.2023
Development

1. Copy the contents of the BIS installation medium folder _Install\AddOns\ACE\API to your
local hard drive.
2. Double click
_Install\AddOns\ACE\API\CS Sample\[Link]
3. Build and run the application.
Bosch Access Systems

ACE 4.9.20007 Version Page

ACE API 1.1.5a 13/69
Author Date
Software 15.03.2023
Development

6 Tour: ACE API Object Life Cycle

In order to give you a better understanding how to use the ACE API we discuss the ACE API lifecycle of a
person, a card and an authorization. That means we instantiate these objects and save their content in the
ACE database, assign a card and an authorization to the person before we finally delete all of them from the
ACE database. The following code snippets used originate from function ACEObjectLifeCycle in
[Link] and are using C++ code. For better readability the code snippets in
this document does not contain any error handling.

First of all, instantiate the ACE interface object and log in.

CW32_ACEInterface ac; // The ACE interface object

API_RETURN_CODES nAPIRetCode = [Link](_T("ACE_API"), _T("ACE_API"), _T("VM-WIN2008EN-MS"));

Instantiate a person, fill some of its attributes and insert the person in the ACE database.

Persons person ( ac );

[Link] = _T("Doe");
[Link] = _T("John");
[Link] = _T("New York");
[Link] = _T("Belvedere Avenue 20");
[Link]( 17 /* day */, 3 /* month */, 1990 /* year */ );

nAPIRetCode = [Link]();

Instantiate a card, assign a card number and code data to it and save the card to the ACE database.

Cards card(ac);

[Link] = _T("1000");
[Link] = _T("0123456789");

nAPIRetCode = [Link]();

Assign that card to the person by passing the card’s unique identifier to the person’s AddCard method.

nAPIRetCode = [Link]([Link]());
Bosch Access Systems

ACE 4.9.20007 Version Page

ACE API 1.1.5a 14/69
Author Date
Software 15.03.2023
Development

Instantiate a new authorization, fill the attributes NAME und SHORTNAME and save the authorization to
the ACE database.

Authorizations authorization(ac);

[Link] = _T("Access to gate 2");

[Link] = _T("Gate 2");

nAPIRetCode = [Link]();

Authorizations can be limited. Here the person is granted access to “Gate 2” for one year from today. We
have to pass the authorization’s unique identifier to the person’s AddAuthorization method.

DateC dateStart (DateC::Today());

DateC dateEnd = dateStart;

[Link]++;

nAPIRetCode = [Link]([Link](), dateStart, dateEnd);

Verify that the person exists by querying the database. When deleting objects many of them are only
marked as deleted but still exist in the database. Therefore, we must exclude them explicitly by specifying
DATEDELETED is NULL.

Query query (ac);

[Link](
_T("persid"),
_T("persons"),
_T("DATEDELETED is NULL and ")
_T("LASTNAME='Doe' and FIRSTNAME='John' and ")
_T("CITY='New York' and STREETHOUSENO='Belvedere Avenue 20'"));

while ([Link]())
{
Persons person(ac);
ColumnValue persId;

// Get the person's unique identifier

[Link](0, persId);
[Link]([Link]);

_tprintf(_T("\nPerson with id '%s' and last name '%s' successfully retrieved"),

[Link](), [Link]);
}
Bosch Access Systems

ACE 4.9.20007 Version Page

ACE API 1.1.5a 15/69
Author Date
Software 15.03.2023
Development

In the last step we delete the objects. We have to take care to delete them in the right order. In case of the
assigned authorization, we have to remove it from the person before we can delete the object. Otherwise
deletion would fail due to database constraints.

nAPIRetCode = [Link]();
nAPIRetCode = [Link]([Link]());
nAPIRetCode = [Link]();
nAPIRetCode = [Link]();

Finally close the ACE interface object.

nAPIRetCode = [Link]();
Bosch Access Systems

ACE 4.9.20007 Version Page

ACE API 1.1.5a 16/69
Author Date
Software 15.03.2023
Development

6.1 Hints for C# programmers

The AccessEngine object is the main (interface) object to handle interactions with the data objects in C#.
An instance of this object is passed to several other objects that will need the reference during their lifetime,
therefore the AccessEngine instance can only be destroyed when all those objects have run out of scope.
For these purposes the AccessEngine instance is not disposable but only garbage collected.
Objects that use the main interface object (e.g. for accessing the database) are disposable. Instances of these
objects should be disposed as soon as they are not needed any longer because the interface object cannot be
released while there is any existing object using a reference to it.
Here is an example how to use the object for the manipulation of visitor data

try
{
// Create the interface object
AccessEngine accessEngine = new AccessEngine();

// Do login
if([Link](“User”, “Password”, “Machine”) !=
API_RETURN_CODES_CS.API_SUCCESS_CS)
{
// No login interface object will be automatically
// garbage collected
return;
}
// Prepare a visitor object to receive the visitors data
// The object takes a reference to the ACE access object so
// assert that it will be disposed after usage
using (var ace_Visitor = new ACEVisitors(accessEngine))
{
// Try to get the data from the database now
API_RETURN_CODES_CS result = ace_Visitor.Get(visitorId);
// When the data were loaded successfully
if (API_RETURN_CODES_CS.API_SUCCESS_CS == result)
{
// Your visitor manipulations here
…
}
} // The visitor instance runs out of scope and is disposed here
// Do a logout
[Link]();
// The interface object can be garbage collected
}
catch (Exception e)
{
// Handle the exception
}

The keyword using calls the dispose method of the instance as soon as it runs out of scope. There might be
the necessity to manually dispose of object instances, e.g. if these are used as class members. This can be
done by calling the Dispose method of the object when it is not needed any longer:
Bosch Access Systems

ACE 4.9.20007 Version Page

ACE API 1.1.5a 17/69
Author Date
Software 15.03.2023
Development

// Dispose the object here

ace_Visitor.Dispose();

Mind that the object is invalid and can no longer be used after disposal.

Disposable objects are:

• ACEAuthorizations
• ACECards
• ACECommands
• ACECompanies
• ACEDayModelsAC
• ACEPegaSys
• ACEPegaSysCards
• ACEPegaSysCardStatus
• ACEPegaSysDoor
• ACEPegaSysGroup
• ACEPegaSysDoorGroup
• ACEPegaSysAuthPerPerson
• ACEPegaSysGroupsPerAuth
• ACEPersons
• ACEQuery
• ACESpecialDays
• ACETimeModels
• ACEVisitors
Bosch Access Systems

ACE 4.9.20007 Version Page

ACE API 1.1.5a 18/69
Author Date
Software 15.03.2023
Development

6.2 Persons, Visitors and Cards database tables

Details about the table structure and all column names are found in the document “ACE API Database
[Link]”.

Here we try to describe how persons, visitors and cards are related in our access system and mapped to da-
tabase:

The database tables PERSONS and ACPERSONS are related 1:1. The PERSONS table contains the most
important part to identify a person and ACPERSONS table contains the access part to find out if a lock ex-
ists or estimates the general access time validity. To create and change these tables entries please use the
ACEPersons object (or class Persons in C++).
To load and find all persons you can use the ACEQuery objects (or class Query in C++) (see example in
chapter 14.1 how to use Query objects).

A visitor is a person with additional information like the visited person, the reason and time of a visit and
so on. These further details about a person/visitor are saved in the table VISITORS and it has a 0..1:1 rela-
tion to table PERSONS. The column ‘persclass’ in the table PERSONS shows if the entry is part of a visitor
or person type. For example: Persclass=‘V’ is used for visitors and “E” or “G” for persons. The persclass
“W” is for guard types, but the SDK does not support any modification of guards.
The ACEVisitors object (or class Visitors in C++) loads all visitor details from the three tables “VISI-
TORS”, “PERSONS” and “ACPERSONS” and provides methods to manipulate.
Every VISITORS table entry is related to one PERSONS entry only, so only one visit can be stored for a
visitor.

Additional person\visitor information like lockouts are stored in the LOCKOUTS table which can contain
multiple entries per person. The lockouts contain an entry for the reason and a time range validity. If no
time limitation is set, then it will be unlimited.
One distinction exists for visitors and persons: The assigned authorizations are mapped to different tables.
Visitors have an own table “AUTHPERVISITOR” and persons are using the table “AUTHPERPERSON”.
Entries in both tables can contain an optional time limitation. The accuracy is per day and the activa-
tion\deactivation is done by background services after midnight. Therefore depending on number of card-
holders the system will need some time to transfer the permission changes.

But in all cases the persons and visitors are using the table ACPERSONS. The table contains the infor-
mation if any active lock is assigned because the status column will switch from 1 (=valid) to 0 (=locked)
and vice versa.
The authfrom and authuntil columns in ACPERSONS can be used to limit the time range where the card-
holder can use any assigned card. All cards and authorizations of a person are first of all restricted by these
values.
Bosch Access Systems

ACE 4.9.20007 Version Page

ACE API 1.1.5a 19/69
Author Date
Software 15.03.2023
Development

The authorizations assigned to a person\visitor are always person related and therefore valid for all assigned
cards. Only one exception exists: if a card was used with pin code and the pin code was entered incorrectly
too often then only for the used card the column pinlock is set to 1 in cards table but the ACPER-
[Link] will not switch.

The CARDS table contains the card information (see card description 6.2.1) and is related directly to
PERSONS table. It is used independent if ‘persclass’ is of type visitor or person.
Multiple cards can be assigned to a person or visitor. All assigned authorizations are valid for a per-
son/visitor independent of used card.
The main difference between visitor cards and person cards is the card handling. Visitor cards are not per-
sonalized so they can be reused. Person cards can be printed with photos and so they cannot be reused. The
database (and SDK) provides to create unassigned cards so they can be assigned later to a visitor. The
CARDS column ‘persid’ is NULL in such cases. The SDK do not force this visitor<>cards behavior so you
could ignore it and the access system will let the cardholder in depending on assigned permissions. But the
dialogs in BIS/AMS could be a little confusing for the operator then and configurations like “remove card
on leaving” will work in the original way: “Visitor cards are removed for reuse (‘persid’ set to null) and
person cards are deleted (datedeleted=timestamp).”

If a card is blacklisted that means “the card is stolen”. The BLACKLIST table will be filled with the card
information and for the original card entry in table Cards DateDeleted is set. After some time, the entry in
CARDS is deleted permanently but the BLACKLIST entry will never be removed so it could happen that a
BLACKLIST entry has no corresponding CARDS row anymore.

For all tables with a column “DateDeleted” the rows will not be deleted directly (time is configurable but in
normal case it will be deleted complete after some month). The column “DateDeleted” is NULL as default
until someone deletes the object then the current timestamp is set here.
Status columns will switch to zero (value = “0”) if timestamp of deletion is set in column “DateDeleted”.

The decision whether a person will obtain an access with his card is done by using the following priority:
- [Link] / authUntil
- [Link]/validUntil (normally used by temporary cards only)
- [Link]/validUntil or [Link]/validUntil

6.2.1 Card description

All supported cards must be mapped to 64 bits (named codedata) where the number must be unique to iden-
tify the cardholder. A physical card can contain different information like an access card number and a seri-
al number (=CSN). That is the reason why the columns “CodeData”, “CodeVar” and “CodeLen” exist mul-
tiple times like “CodeData2”, “CodeVar2” and “CodeLen2”.
Bosch Access Systems

ACE 4.9.20007 Version Page

ACE API 1.1.5a 20/69
Author Date
Software 15.03.2023
Development

The main access system (at AMC controller side) does not care about card types as long as the codedata is
unique and the cardholder can be identified by the first column “CodeData” because the readers using Wie-
gand interface or RS485 protocols like OSDP get only a card number.
To support different subsystems the different information details about a card are remembered if they are
enrolled by dialog station reader like “LECTUS enroll 500 MD”, “HID Omnikey reader” or the “PegaSys
readers”. SDK provides to read and set all these card details too.

Example how a card is saved in ACE cards database:

Card of type Mifare Classic => CodeType = ‘MifareClassic’

1. Code of card => CodeData = 0x0102030400000055

1. Code sub type => CodeVar = ‘Bosch code’
1. Code bit length => CodeLen = 63

2. Code of card => CodeData2 = 0x0000000034231267

2. Code sub type => CodeVar2 = ‘Serial number’
2. Code bit length => CodeLen2 = 32

The column “codetype” exist one time only.

If the dialog station reader “LECTUS enroll 5000 MD” or one of the “PegaSys readers” is used then a
Bosch coded Mifare\Legic card is saved in ‘codedata’ and the CSN of this card in the other ‘codedata2’.
But this behavior is configurable on reader side or on access system side, so it is the best to search for a
specific card in both codedata columns.
The codedata3 and codedata4 columns and their related columns are not used until now.

Here are the allowed values for columns ‘codetype’ and ‘codevar’:

Enum codetype:
CardType_Unknown = 0,
CardType_MifareClassic,
CardType_MifareDesfire,
CardType_LegicPrime,
CardType_LegicAdvant,
CardType_IClass,
CardType_HIDProx,
CardType_EM,
CardType_Hitag,
CardType_MobileAccess
Bosch Access Systems

ACE 4.9.20007 Version Page

ACE API 1.1.5a 21/69
Author Date
Software 15.03.2023
Development

Enum codevar:
CardVariations_Unknown = 0,
CardVariations_CSN,
CardVariations_BOSCH

The value NULL is mapped to zero (=Unknown).

The column “USAGETYPEID” is a reference to the CARDUSAGETYPE table where the purpose of the
card is described.

Card type Description

“Personal card” Main access card
“Temporary card” A personal card can be replaced by a temporary card, for example he forgot the
card at home
“Parking card” Access card used for parking gates where we believe that a ‘long range reader’
and special card is used. Sub systems like offline locking systems (= PegaSys)
do not support such cards.
“Alert card” Alert cards have no access permissions. They are used to start an alarm only.
“Virtual card” PIN only access cards are using the virtual card type.
“Mobile access card” Card number used by mobile phones.

Codedata(X) column:
As default the Bosch coded cards are coded as 63 bits where the first high bit of the 64 bit ‘codedata’ col-
umns is not set.

Bosch cards are using 63 bits where

the highest 31 bits are interpreted as facility code
the lowest 32 bits are interpreted as card number.

Example:
0x00 00 00 FF 00 00 00 09
^^^^^^^^^^^ ^^^^^^^^^^^
Facility Card number
Bosch Access Systems

ACE 4.9.20007 Version Page

ACE API 1.1.5a 22/69
Author Date
Software 15.03.2023
Development

CSN numbers should be encoded from right to left

Example:
0x00 00 00 00 02 22 22 23
^^^^^^^^^^^ ^^^^^^^^^^^
CSN 26 bit, dec. 35.791.395

For this example the CodeLen should contain value 26

if an EM card with max 26 bit is used.

Example:
0x00 1C 35 8F 02 22 22 23
^^^^^^^^^^^ ^^^^^^^^^^^
CSN 56 bit

For this example the CodeLen should contain value 56

if a Mifare Desfire card is used.

Be aware that highest and lowest part of CSN are interpreted by some reader manufacturer different. The
ACE supports an optional reversion of the serial number interpretation for most dialog station readers. In-
dependent the CSN must be written from right to left in codedata(X) columns.

6.2.2 Some examples about cardholder related tables

Cardholders last known access (entered area with timestamp)

SELECT [Link], [Link], [Link] FROM

currentaccessstate join PERSONS on ([Link]=[Link]) join
AREAS on ([Link]=[Link])

The table “CURRENTACCESSSTATE” contain the last time a cardholder entered an area (and parking ar-
ea). If an access system does not have exit readers the cardholder will be moved to area OUTSIDE after a
configurable time (example “24 hours” none used any card).

Cards validity (valid time range, pin lock active\deactive, locked other reason)

SELECT [Link], [Link], [Link], [Link] FROM

CARDS join ACPERSONS on ([Link]=[Link]) where [Link]=1

“[Link]=1” <= All cards not deleted or blacklisted or temporary disabled

Bosch Access Systems

ACE 4.9.20007 Version Page

ACE API 1.1.5a 23/69
Author Date
Software 15.03.2023
Development

“status=2” <= temporary disabled ([Link] and [Link] are valid now)
“status=0” <= Deleted

The statement will fetch all valid cards for the access system. But the cards could contain pin locked state
‘1’ (=locked because pin entered incorrect) or the cards could have an invalid time range. (= “is not valid
anymore” or “not yet valid”).

Cards blacklisted
Check if card with number 0x1234567890123456 is in blacklist or not.

SELECT [Link] FROM blacklist WHERE

codedata=convert(binary,0x1234567890123456) or
codedata2=convert(binary,0x1234567890123456)

The returned column “DateReported” is only the timestamp where the card was registered as stolen. If noth-
ing is returned the card with this card number is not in BLACKLIST.

Fetch cardholder details by codedata

SELECT [Link], [Link], [Link], [Link] FROM persons

join cards on ([Link]=[Link]) right outer join photos on
([Link]=[Link]) WHERE
[Link]=convert(binary,0x1234567890123456)

To fetch the optional signature of a person\visitor replace table name ‘photos’ with table name ‘signatures’.
The image itself is a jpeg file saved as binary in column image.
Bosch Access Systems

ACE 4.9.20007 Version Page

ACE API 1.1.5a 24/69
Author Date
Software 15.03.2023
Development

7 Example: How to Receive Events

The following lines of code show how to start/stop event message distribution in C#:

AccessEngine aceLocal = new AccessEngine();

// Login as usual to the AccessEngine server

//
if (API_RETURN_CODES_CS.API_SUCCESS_CS == [Link]("BIS", "BIS", "BIS4181000DE"))
{
// Before the event message distribution is started
// another thread or application should run and open an tcp port at given computer name and ip-port.
//
String strHostName = "ac3x1011rc2"; // The computer name or ip-address where the tcp server should
// run and wait for events
String strIPPort = "1234"; // The port number of the tcp server, waiting for events

// StartThreadToWaitForTcpMessages(strHostName, strIPPort); // <== This has to be implemented here

// or as external programm
// see next example

uint iLogNumber = 0; // The start event message number (in this case '0'= the latest one)
int iEncrypt = 0; // The type of encryption (should be '0' now, means none encryption;
// for future use to select encryption type)

// Informs the access engine to start the event distribution

//
if ([Link](iLogNumber, strHostName, strIPPort, iEncrypt))
{
// Now we should receive events,
// because the tcp connection from AccessEngine server to the destination could be established.
// As first message the start message with the given iLogNumber will be received: START="0"
}

// If we want to stop the event messages again we can call StopEventMessageDistribution()

// or the tcp service closes the tcp connection as long as the alive ping timeout needs
[Link]();
}
Bosch Access Systems

ACE 4.9.20007 Version Page

ACE API 1.1.5a 25/69
Author Date
Software 15.03.2023
Development

Instead of an own thread here is an example how an application can receive the event messages on the serv-
er ‘ac3x1011rc2’:

// Create tcp listener on server ‘ac3x1011rc2’ with port 1234

//
IPEndPoint ep = new IPEndPoint([Link], 1234);
TcpListener listener = new TcpListener(ep);
[Link]();

// Create memory buffer and accept tcp client connection

//
byte[] buffer = new byte[2*8192];

var sender = [Link]();

// Set the receive buffer size to 2 * 8 KB

[Link] = 2*8192;

// Set the timeout for synchronous receive methods to

// 40 second (1000 milliseconds.) because after 30 seconds without any new message an ALIVE message
// should be received
[Link] = 40*1000;

// Forever read messages..

//
while (true)
{
// Accept connection again
//
if ((sender == null) || ![Link])
sender = [Link](); // blocking call ...

// Try to read received message

//
int iReadNum = 0;

iReadNum = [Link]().Read(buffer, 0, bytesize);

// Any message received?

if (iReadNum == 0)
{
// Here simple retry again.. Timeout and reconnect handling should be implemented
continue;
}

// Message received .. it is always of type unicode!

string message = [Link](buffer).Substring(0, iReadNum / 2);

// The format of the received message string is described in the next chapter “Event messsages”
}
Bosch Access Systems

ACE 4.9.20007 Version Page

ACE API 1.1.5a 26/69
Author Date
Software 15.03.2023
Development

7.1 Error Handling

If a message cannot be sent to the destination IP-Address the connection will be released.
The API user should then recreate the IP-listener service and start the communication with StartEvent-
MessageDistribution(<last log number received>, ...) again.
By receiving the last log number the external service knows that the event distribution is working.
Every message contains "lgnr" so the last used log number is always known.

The log number between two messages is not incremented by one, because there are other events (of other
categories) in the Access Engine which are not sent to that IP-Address. It is only sure that a higher log
number is newer then lower log numbers.
Be aware that there is no protection if you call StartEventMessageDistribution(1, ...) . Using number '1' you
will get every message of your categories since the first time the system was installed. Normally the Access
Engine messages are deleted after 1 year (in this case you will get all messages of the last year).

7.2 Event Messages

The normal message format is: “/{parameter}={value}..\r\n”

{parameter} is the name of the parameter

{value} the value for the parameter.

These blocks are separated by spaces: “/{parameter}={value} /{parameter}={value}..\r\n”.

And every message end with CR/LF (= carriage return/line feed) (= "\r\n").

The START and ALIVE messages have a similar format:

The first start message looks like 'START="<lognumber>"\r\n'

Example: 'START="50"' or
Example: 'START="0"'

This start message is used to verify that the TCP connection works.

If no further event arrives for about 30 seconds an ALIVE message like 'ALIVE=YYYYMMDDHHMMSSs' is
sent.

After the start message every event message received always contains the following items:
- lgnr - the log number, unique identification (1 to max 32 bit) (0 is not possible)
- cats - the categories of this message (should not be used)
- ltim - time, the log process handled the event
- levl - level of the message (should not be used)
- ctim - creation time, time the event was produced
- msid - unique identification number of the event (message number as decimal)
A complete list of all possible message identification numbers can be found
Bosch Access Systems

ACE 4.9.20007 Version Page

ACE API 1.1.5a 27/69
Author Date
Software 15.03.2023
Development

• on the ACE server path “c:\Mgts\Access Engine\AC\cfg” in the file

“[Link]” (< BIS 4.5)
• in the database table eventtypes (since BIS 4.6)

The file “[Link]” e.g the database table eventtypes contains all messages ev-
er used by the ACE today or in the past.

To find the messages from MAC subsystem you can search for all symbols starting
with “ACS_”.
The given IDs are coded hexadecimally but are identical with the value of the item
“msid”.
- sndr - the name of the sender (for MAC messages it is always 'MAC-n' where n
is the instance number 1..10)
One exception is the value "ACSP-x" where ‘x’ is a number from 1 to 10.
In this case the message is generated by the interface process ACSP.
ACSP is responsible for the communication to the MAC and sends events like ‘MAC is of-
fline’. (The ACSP-1 communicates with MAC-1, ACSP-2 with MAC-2 …)

Most messages contain details like:

- MSGTEXT - the description for the message
- [Link] - the database identifier in table devices
Example of a MAC message:
/lgnr=336860 /cats=!0000000000000000040000000000000000000000000000000000300000000000
/ltim=20150805092307S /levl=0 /msid=16777221 /ctim=20150805091550S /sndr="MAC-1"
/[Link]="FF00003300000003" /MSGNR=16777221 /MSGTEXT="connection OK" 1 /[Link]="FF00003300000003"
/[Link]="000003" /[Link]="$/AC" /[Link]="MAC" /[Link]="MAC"
/host="workstationXXX"

An exception in the message format “/{parameter}={value}” is the character “1” used as marker (see example
above). After the marker " 1 " optional parameter fields occur depending on message identifier. Even mul-
tiple parameters are possible e.g. /[Link] in the example is used twice in this message.

Date and time format in ALIVE message:

Format: ALIVE=”YYYYMMDDhhmmssX”

Example: ALIVE="20150805092307S"

Definition “X”: The character 'S' is used for summer and 'W' for winter time. In the first part of the year
(January until summer start) the space character ' ' is used instead of 'W'.

Another example for an event message concerning a guard tour looks like:
Bosch Access Systems

ACE 4.9.20007 Version Page

ACE API 1.1.5a 28/69
Author Date
Software 15.03.2023
Development

/lgnr=336737 /cats=!0000000000000000040000000000000020000000000000000000080000000000
/ltim=20150805092307S /levl=0 /msid=16778269 /ctim=20150804150012S /sndr="MAC-1"
/[Link]="0012D1CA7A0F75A5" /MSGNR=16778269 /MSGTEXT="Guardtour Card registered"
/[Link]="0012DE73BF4BA6FA" /[Link]="0012D1CA7A0F38B1" 1
/[Link]="0012DE73BF4BA6FA" /[Link]="000001234567" /[Link]="0012DE73BE1B71D9"
/[Link]="Guard" /[Link]="Wächter" /[Link]=! /[Link]=!
/[Link]=87 /[Link]=! /[Link]=! /[Link]=!
/[Link]=! /[Link]="0012D1CA7A0F75A5" /[Link]="000016" /[Link]="$/AC"
/[Link]="DT7020" /[Link]="I-BPRO" /[Link]="0012D1CA7A0F38B1"
/[Link]="DM 05" /host="workstationXXX"

All items with a dot in the name like '[Link]' are referring to database fields (Notation: <ta-
ble>.<column>).
In the example above you can see items beginning with '!' after the equal sign (like /[Link]=!). This
notation is used to describe a NULL value in the database.
If a field like “[Link]” is of type date, the format will be: “RDDYYYYMMDD” where “RDD”
is a fixed string.

All messages except ALIVE and START messages will contain the first 7 parameters (lgnr ... sndr).
Whether other message details appear depends on the information in the database when the event is sent to
the central ‘Loggifier’ service of the Access Engine (see parameter ltim for the log time of an event).

So it can happen that an old message arrives (because the controller was offline for a long time) with an in-
ternal [Link], and the card has already been deleted permanently in the database, so no fur-
ther data can be provided.
In this case the message contains details like [Link] instead of all the other fields (like per-
[Link]) which are normally provided by that type of message.
Bosch Access Systems

ACE 4.9.20007 Version Page

ACE API 1.1.5a 29/69
Author Date
Software 15.03.2023
Development

8 Example: How to Send Commands

8.1 Execution of commands for devices MAC, AMC, doors or readers
The API-SDK provides a new class Commands (or for .NET see object ACECommands) with the following
functionality:

1. RequestStartMAC => COLDSTART or WARMSTART of a MAC

2. RequestStartAMC => COLDSTART or WARMSTART of an AMC

3. RequestSwitchMAC => Switch between MAC and redundant MAC (=RMAC)

4. RequestSynchronizeMAC => Synchronize complete database with MAC and redundant MAC
without cold start of the MAC system.

5. RequestGrantAccess => Grants access (once) for a specific card reader

6. RequestGrantDoorIn => Grants access (once) for a specific door (ingress)
7. RequestGrantDoorOut => Grants access (once) for a specific door (egress)

8. RequestAccessReply => Grants access (or denies) to a card at a reader where an addi-
tional request was sent from AMC controller (like ‘VIDEO’ verification required)

9. SetDOP => Set digital output to ON or OFF

10. SetArea => Change person’s area or parking area

11. SetAllArea => Change area or parking area for all persons.
Limitation: Be aware that this method is used to set all to ‘unknown’ location, so
they can make an one-time access without access sequence monitoring. If you use it
to change the location to outside it will work, but the upper system is not informed
so the dialog preview will not display correctly the position until the card is
used.
12. SetAntiPassback => Set anti-passback for a reader ON or OFF
13. SetVideoVerification => Set video verification for a reader ON or OFF
14. SetRandomScreening => Set random screening for a reader

15. ActivateThreatLevel => Activate a threat level in a MAC

16. DeactivateThreatLevel => Deactivate threat level in a MAC

17. ReaderCmd => Change card reader mode (blocked, access control monitored, ...)
18. ReaderCmdBlockedOnTM => Block\unblock card reader by time model

19. DoorCmd => Change door mode (blocked, opened)

20. DoorCmdOnTM => Block\unblock door by time model

21. RequestVerificationPersId => allow access for specific persons

22. RequestVerificationCardId => allow access for specific card
Bosch Access Systems

ACE 4.9.20007 Version Page

ACE API 1.1.5a 30/69
Author Date
Software 15.03.2023
Development

The following lines of code show how to restart a MAC in C#:

AccessEngine aceLocal = new AccessEngine();

// Login as usual to the AccessEngine server

//
if (API_RETURN_CODES_CS.API_SUCCESS_CS == [Link]("BIS", "BIS", "BIS4181000DE"))
{
// Initialize the Commands class with the connected AccessEngine
//
using(ACECommands execute = new ACECommands(aceLocal))
{
int iMacNo = 0; // The first MAC starts here with number 0

if (API_RETURN_CODES_CS.API_SUCCESS_CS ==
[Link](iMacNo, Commands.MAC_WARM_START))
{
// The command was send to the MAC and is executed asynchron now
}
} // The command object is disposed
// The AccessEngine object will be disposed by the garbage collector
}

8.2 API command execution: parallel changing of device parameters

BIS 4.9 supports a new feature concerning the execution of commands, respectively the storage of the mod-
ified parameters.
The door- and reader parameters send by commands are not stored directly in database table Devices, but in
a new database table called CurrentDeviceMode. A new command option for door/readers-commands can
be used to restore the default configuration from table Devices.
That means if the user wants to make permanent changes to the devices, he has to use the device-
configurator dialog of the BIS/AMS-System. Changing the door parameter by using the API-SDK-
commands, can be reverted by using the command option RESTORE_CONFIGURATION.

For compatibility reasons the API-SDK still supports older BIS/AMS-installations. There the former behav-
ior will not changed. If no table CurrentDeviceMode is found, then the changed parameters are stored in ta-
ble Devices as before.
Bosch Access Systems

ACE 4.9.20007 Version Page

ACE API 1.1.5a 31/69
Author Date
Software 15.03.2023
Development

The following lines of code show how to switch between temporary and default parameters:

AccessEngine aceLocal = new AccessEngine();

if (API_RETURN_CODES_CS.API_SUCCESS_CS == [Link]("APIUSER", "APIUSER", "BIS49EN"))
{
// Initialize the Commands class with the connected AccessEngine
//
using(ACECommands execute = new ACECommands(aceLocal))
{
[Link](strReaderId, 1,(int)[Link]);
// The reader-parameter ENTRBLOK is stored in tbl CurrentdeviceMode and send to MAC
[Link](strReaderId, 1,(int)[Link].RESTORE_CONFIGURATION);
// The CurrentdeviceMode-entry of the reader is removed and the default parameters from table
// Devices are send to MAC

[Link](strDoorId, 1,(int)[Link]);
// The door-parameter ENTROPEN is stored in tbl CurrentdeviceMode and send to MAC
[Link](strDoorId, 1,(int)[Link].RESTORE_CONFIGURATION):
// The CurrentdeviceMode-entry of the door is removed and the default parameters from table
// Devices are send to MAC
}
// The command object is disposed
}
// The AccessEngine object will be disposed by the garbage collector
Bosch Access Systems

ACE 4.9.20007 Version Page

ACE API 1.1.5a 32/69
Author Date
Software 15.03.2023
Development

9 Clients
An ACE installation can be shared by several clients. That means that certain objects (e.g. Persons) are as-
signed to a specific client. By default, all objects belong to the client Common. When not specified differ-
ently all API calls refer to that client. However, if an installation consists of several clients it must change
the client before performing operations. To switch the client the code must call the AccessEngine object’s
method SetCurClientId. To retrieve a client id the database table CLIENTS must be searched. The cur-
rently active client is accessible by the AccessEngine object’s method GetCurClientId. The common cli-
ent id can be retrieved by AccessEngine object’s method GetCommonClientId.

The following C# snippet shows the mechanism:

// This is a user defined client's identifier obtained by a SELECT in database table CLIENTS.
String userDefinedClientId = "00131E7C96C877FC";

// At this point the global object accessEngine (class is AccessEngine)

// has been constructed and initialized.
// Set the user defined client as the current one.
[Link](userDefinedClientId);

using(ACEPersons person = new ACEPersons(accessEngine))

{
[Link] = "Person API C# " + userDefinedClientId;

// This person will now be inserted as a user defined client's person.

[Link]();

// The next person will be inserted as a user defined client's person, too.
[Link] += "(2)";
[Link]();

// The common client’s id is a constant but can be found in the database as well.
// It can be retrieved by calling the method GetCommonClientID().
String commonClientId = [Link]();

[Link] = "Person API C# Common Client";

// Reset the common client as the current one.

[Link](commonClientId);

// This person will now be inserted as a common client's person.

[Link]();
} // The person object runs out of scope and will be disposed here
Bosch Access Systems

ACE 4.9.20007 Version Page

ACE API 1.1.5a 33/69
Author Date
Software 15.03.2023
Development

10 Custom Fields
10.1 New custom fields since ACE 4.5
As of version 4.5 the ACE supports up to 80 custom fields whereas previous versions could handle only 10.
Until BIS 4.4 the custom fields were stored in database table persons using the columns RESERVE1 to RE-
SERVE10. Since ACE 4.5 there are 2 new database tables AdditionalFieldDescriptors and AdditionalFields
to configure the custom fields and store their values.

10.2 Using former custom fields RESERVE1 to RESERVE10

In the API these fields were addressed by person objects using the fields RESERVE1 to RESERVE10. This
mechanism still works for migrated installations of ACE. However, a recompilation of client applications is
mandatory.
The fields were transferred by database migration into the new tables and configured as text fields to be
used in reports with sequence number 1 to 10. So they can be accessed by older API applications as well.
But be aware that changing the configuration of these custom fields concerning the sequence number or the
field type could lead into problems. So if you change the configuration of migrated additional fields it is
recommended to use the new methods described later in this document.

Persons myPerson(ac);

[Link] = _T("API Person AddField");

myPerson.RESERVE1 = _T("one");
myPerson.RESERVE2 = _T("two");
myPerson.RESERVE3 = _T("three");
myPerson.RESERVE4 = _T("four");
myPerson.RESERVE5 = _T("five");
myPerson.RESERVE6 = _T("six");
myPerson.RESERVE7 = _T("seven");
myPerson.RESERVE8 = _T("eight");
myPerson.RESERVE9 = _T("nine");
myPerson.RESERVE10 = _T("ten");

nAPIRetCode = [Link]();
// set value in custom field identified by sequence no 1 to 10
// only text fields are supported

// just for compatibility migrated ACE 4.5

// do not change the migrated configuration

// otherwise it is recommended to use the new methods
Bosch Access Systems

ACE 4.9.20007 Version Page

ACE API 1.1.5a 34/69
Author Date
Software 15.03.2023
Development

10.3 Using Custom fields (AdditionalFields)

The new custom fields support different field types (e.g. Text, Datetime, Date, Time). The configuration of
the fields, stored in table AdditionalFieldDescriptors, must be done by the BIS Configuration Browser and
cannot be changed by API.
The API Persons object provides new methods GetCustomFieldValue, SetCustomFieldValue and ResetCus-
tomFieldValue to access these fields by passing the configured field label and an appropriate field value.

The following lines of code show how to change the custom field values:

// Please note that the custom field label is case sensitive

// API_PERS_INVALID_CUSTOM_FIELD_NAME is returned if fieldname is not found

Persons myPerson(ac);

CustomC stringValue;
stringValue = _T("my Value");
nAPIRetCode = [Link](_T("MyAddText"), stringValue);
// set text value in custom field labeled "MyAddText"
nAPIRetCode = [Link](_T("MyAddCombo"), stringValue);
// get value from custom field labeled "MyAddCombo"
nAPIRetCode = [Link](_T("MyAddCombo"));
// reset custom field labeled "MyAddCombo"

bool boolValue=true;
nAPIRetCode = [Link](_T("MyCheckBox"), boolValue)
// set bool value in custom field labeled "MyCheckBox"

DateC dateValue(17, 9, 2017);

nAPIRetCode = [Link](_T("MyAddDateField"), dateValue);
// set date value in custom field labeled "MyAddDateField"
nAPIRetCode = [Link](_T("MyAddDateField2"), dateValue);
// get date value from custom field labeled "MyAddDateField2"

TimeC timeValue(23, 50, 0);

nAPIRetCode = [Link](_T("MyAddTimeField"), timeValue);
// set time value in custom field labeled "MyAddTimeField"
nAPIRetCode = [Link](_T("MyAddTimeField2"), timeValue );
// get time value from custom field labeled "MyAddTimeField2"

DateTimeC dateTimeValue(31, 12, 2018, 23, 50, 0);

nAPIRetCode = [Link](_T("MyAddDateTimeField"), dateTimeValue);
// set datetime value in custom field labeled "MyAddDateTimeField"
nAPIRetCode = [Link](_T("MyAddDateTimeField2"), dateTimeValue);
// get datetime value from custom field labeled "MyAddDateTimeField2"

C# programmers must handle the retrieval of custom fields slightly different. The custom fields can contain
one of the following 5 data types:
• string
• boolean
• ACEDateT
• ACETimeT
• ACEDateTimeT

To retrieve values the variables of the correct type need to be passed with the keyword out to the function:
Bosch Access Systems

ACE 4.9.20007 Version Page

ACE API 1.1.5a 35/69
Author Date
Software 15.03.2023
Development

// Create interface object to Access Engine

AccessEngine ace = new AccessEngine();
// Log on
API_RETURN_CODES_CS test = [Link]("User", "Password", "MachineName");
// Create an object to handle the persons table
using (ACEPersons pers = new ACEPersons(ace))
{
// Load a person
if ([Link]("00123456789ABCDE") == API_RETURN_CODES_CS.API_SUCCESS_CS)
{
// Get a string type value from the custom field "SpecialData"
string content;
[Link]("SpecialData", out content);
[Link](content);
}
} // Persons object runs out of scope
// Log out
[Link]();
// Interface runs out of scope and can be garbage collected

11 How to use AutoCreateMobileCard

The API Persons object provides a new method to create a mobile access card. The method is called Au-
toCreateMobileCard. With a given PERSID the function creates a card record; the CODEDATA are gener-
ated randomly. A parameter of the method will return the corresponding CARDID.
Sample code:

// Prepare person
Persons person(ACEInterface);
// Create object in database
CreatePersonTest(person);

IdC cardId = PersonsAutoCreateMobileCard([Link]());

... // more code

}

IdC PersonsAutoCreateMobileCard(IdC persId)

{
Cards card(ACEInterface);

[Link] = persId;

Persons person(ACEInterface);
[Link](persId);

IdC cardId;
API_RETURN_CODES iError = [Link](persId, cardId);
Bosch Access Systems

ACE 4.9.20007 Version Page

ACE API 1.1.5a 36/69
Author Date
Software 15.03.2023
Development

//...

12 Documentation
The documentation files are on the BIS installation medium in folder
_Install\AddOns\ACE\API\Help.

1. The documentation of the ACE API is available as a Windows help file: W32_ACEInterface.chm.
You’ll find all available classes and their methods together with their return values here.

2. The documentation of the sample application “Win32ClientApplication” can be found in

[Link]. This help includes the source code of the sample application.

3. For queries on objects you might need some knowledge of the ACE database model.
Please refer to the latest document ACE API Database 4_X_XXXX.pdf. This diagram is a subset of
the whole database, and contains the most important tables used by the API concerning persons. The
modified e.g. new database tables before ACE 4.X are highlighted.
The database documentation files concerning former versions of the ACE are provided as well. See for
example ACE API Database 4_1_8100.pdf, which is valid for ACE 4.1 and 4.2. Since ACE 4.3 the
document ACE API Database 4_3_8953.pdf is provided.

An additional document ACE API Database Devices 4_X_XXXX.pdf is attached to get a better data-
base overview concerning the ACE Devices and ACE API Database Calendar 4_X_XXXX.pdf for
all database tables concerning calendar definition.

For the documentation of the Pegasys database model an additional document

ACE API Database Pegasys 4_X_XXX.pdf is attached

4. The DotNet_ACEInterface.chm describes the interface wrapper for .NET applications like C#, man-
aged C++ or Visual Basic. You’ll find all available classes and their methods together with their return
values here.

5. The documentation of the sample application “ClientACEInterfaceCS” can be found in

[Link]. This help file also includes the source code of the sample application.
Bosch Access Systems

ACE 4.9.20007 Version Page

ACE API 1.1.5a 37/69
Author Date
Software 15.03.2023
Development

13 Troubleshooting
1. If an API method returns a value of type ACE_RETURN_CODES you can obtain a human readable
error message by calling the interface object’s method GetErrorString().

CW32_ACEInterface ac;
API_RETURN_CODES nAPIRetCode = [Link]();

[Link](nAPIRetCode);

C#:

// Create interface object to Access Engine

AccessEngine ace = new AccessEngine();
// Log on
API_RETURN_CODES_CS test = [Link]("Username", Password", "Machinename");
// Show the error data
[Link]([Link](test));

2. If there are errors whose reasons are not obvious you can take a look into the log file of the ACE API:
“%TEMP%\MasterAPI_<Your ApplicationName>.log” on the computer, where the ACE API is
running.
Further sources of information are the server log files [Link] and [Link] for database transac-
tions and [Link] for database queries. These log files can be found in folder
“C:\MgtS\AccessEngine\AC\Log” of the ACE server.
Hint: The API will write more details to the debug log file if logging for the server is activated in the
ACE configuration.
3. If the ACE API cannot write to its log file, the API tries to write to the current directory. If neither
works you will have to start the application in administrator mode.
4. If a Query object returns too many objects it is possible that you did not filter deleted objects in your
where clause (“DATEDELETED is NULL”).
5. The API interface of the BIS V4.1 and later cannot be used with BIS V4.0 and earlier. The API login
will fail.
6. In ACE 4.2 the name of the W32_ACEInterface-3 library has been changed to W32_ACEInterface.
Bosch Access Systems

ACE 4.9.20007 Version Page

ACE API 1.1.5a 38/69
Author Date
Software 15.03.2023
Development

14 Known Issues\Limitations\Recommendation
14.1 Multi MAC Systems & Authorizations
Authorizations objects have an attribute MACID. This value denotes the MAC which is responsible for
that authorization. Customers who only run a single MAC system simply call the Add method of the Au-
thorizations object. Customers, however, who have several MACs must initialize the MACID attribute be-
fore adding an authorization. For retrieval of MAC identifiers they must use a query as shown in the snippet
below:

Query query (ac);

[Link](_T("id"), _T("devices"), _T("DATEDELETED is NULL AND type=’MAC’"));

while ([Link]())
{
ColumnValue MACId;

// Get the MAC’s unique identifier

[Link](0, MACId);

_tprintf(_T("\nMAC with id '%s’ successfully retrieved"), [Link]);

}

14.2 Deletion of Authorizations

Always delete a person’s authorizations before deleting the person object itself, because it may be impossi-
ble to delete authorizations that reference a non-existent person.

int nAPIRetCode;

nAPIRetCode = [Link]([Link]());
nAPIRetCode = [Link]();

14.3 Max number of API Clients

The recommendation is to use up to 10 API Clients. If more are required and no dialog workstations are
used at the same time it is possible to use more (about 10 further). Be aware that some workstations
(=clients) have to be licensed in the BIS otherwise it could happen that the first API Client connection re-
quest will fail.

14.4 Max number of cards per person\visitor

The API will not limit the number of cards attached to a person\visitor. But if hundreds of cards are as-
signed no guarantee can be given that the access system will work 100% in all cases. The API will not limit
and verify every case otherwise the efficiency will be reduced too dramatically.
Bosch Access Systems

ACE 4.9.20007 Version Page

ACE API 1.1.5a 39/69
Author Date
Software 15.03.2023
Development

Please check the data sheets of the products if unsure. Most times the ACE system can do more than speci-
fied but not all unusual cases outside of the data sheet are tested. Please check to verify try the ACE dialogs
afterwards.
We guarantee in this case that 10 cards will work in the ACE even if the dialogs and reports are optimized
for max. 5 cards as described in the data sheets.

14.5 Max picture size

The picture size is not reduced by the API. But be aware that JPEG picture sizes above 600KB are not use-
ful in the ACE.
Bigger pictures will
- reduce the display performance on the workstations
- fill your SQL database dramatically (Do not forget to increase the MAX size)
- decrease the replication performance in hierarchical systems

The ACE dialogs and the upgrade process limit the picture size automatically. A card can be printed in
600dpi without reduced quality nevertheless. No tests are done to guarantee that picture larger than a MB
will not crash parts of the system in the future.
The recommendation is to reduce the pictures before adding them to the ACE database over API.

14.6 Known not solved bugs

1. (243210) API transaction fails
If visitors are created and the related IDs ATTENDANTID or VISITEDPID are not set with invalid da-
ta the error will be returned but the entry of the visitor is created in the database.
2. (218694) [Link] without effect
The [Link] can be set and get and will be saved and loaded from database but not all val-
ues are shown in the visitor dialogs.

15 Using ACE API in hierarchical systems

1. The ACE API can establish a connection to each server in the three-level hierarchy. But for adding or
changing data the replication paths have to be considered. Data is always replicated downwards the hi-
erarchy. The API should always connect to the highest level where the data has to be known.
1.1 Cardholder data (persons, visitors, cards, companies)
1.2 Timemodels including daymodels and special days
1.3 Authorizations
Bosch Access Systems

ACE 4.9.20007 Version Page

ACE API 1.1.5a 40/69
Author Date
Software 15.03.2023
Development

1.4 Device data:

The ACE Commands
- ReaderCmd
- ReaderCmdBlockedOnTM
- DoorCmd
- DoorCmdOnTM
cause an update of the device parameters in your database table DEVICES.
The changes will be sent only to the active MAC if this MAC is located on same level or
downwards.

2. The MAC instance number stored in the database of the device top level server (Level-2) isn’t unique
anymore in hierarchical systems with redundant MACs. Therefore the command
RequestStartMAC using the instance number as parameter shouldn’t be called in hierarchical systems.
An additional method using the MAC device ID as parameter is provided now. You always have to
specify of the device ID of the MAC. The decision whether the MAC or the redundant MAC is active
and has to receive the command is done by the internal ACS client interface.

3. There is one new command which can be used with redundant MACs.
3.1 RequestSwitchMAC will cause a switch between MAC and redundant MAC

4. Domain:
The internal database columns ‘DOMAIN’ is now used in a different way. The value of this column has
been changed in hierarchical systems. Cardholder dependent data uses domain=0, which means that the
data will always be replicated downwards. Device dependent data uses the domain value which has
been configured within the hierarchy tool and will only be replicated within their domain. The values
can’t be changed by the ACE API.
Bosch Access Systems

ACE 4.9.20007 Version Page

ACE API 1.1.5a 41/69
Author Date
Software 15.03.2023
Development

5. Event messages:
5.1 The sender of MAC events in none hierarchical systems is shown as “MAC-1” …”MAC-n”.
But in hierarchical systems with redundant MACs the name of the sender can change to “Serv-
[Link]-1”…”[Link]-n”
5.2 All messages have a new parameter “/macdevid” now, so the received MAC identification can
be done by ID (see table column [Link]) instead of the name.
5.3 If you start the event message distribution you will receive the events from all MACs which are
connected to the server or the level below (if device data replication is active with redundant
MACs).
5.4 The local events which are forwarded to a higher level server contains 2 new items:
- slvl – the level of the sender
- efwd=1 – indicates forwarded messages
5.5 Forwarded messages includes the information of the original message. Therefore some item
like e.g. lognr could appear twice. You should consider only the first appearance of the item
because this one refers to the server you are connected to.
5.6 Example – event message distribution connected to server level 2:

/lgnr=372444 /cats=!0000000000000000040000000000000000000000000000000000000000000000
/ltim=20170407131255S /levl=0 /msid=16777987 /ctim=20170407131255S /sndr="[Link]-1"
/lgnr=78288 /cats=!0000000000000000040000000000000000000000000000000000000000000000
/ltim=!6612bae78fafd201 /msid=16777987 /ctim=!80d5b8e78fafd201 /sndr="[Link]-1"
/macdevid="0030003300000003" /[Link]="00230E4BB5390E68" /MSGNR=16777987 /MSGTEXT="access, via remote
command \"GRANTAC\"" /MACSYST=1 /[Link]="00230E4BB5389271" 1
/[Link]="00230E4BB5390E68" /Devices.id02=! /[Link]="$/AC" /[Link]="WIE1"
/[Link]="Reader APITest" /[Link]="00230E4BB5389271"
/[Link]="RCP APITest" /host="VM-W12ENL1-BS"
/slvl=1 /efwd=1
Bosch Access Systems

ACE 4.9.20007 Version Page

ACE API 1.1.5a 42/69
Author Date
Software 15.03.2023
Development

16 Multithreading
16.1 API in multithreading applications

Since BIS 4.6.2 and API Version 4.6.10360.0 multithreading is supported.

The following ways of working are tested:

A) 1. Start worker thread
2. Inside the thread:
Create the ACE instance, Login and use the provided classes and methods
3. Create 3-10 worker threads using the previous steps in parallel

B) 1. Create ACE instance and Login

2. Start worker thread
3. Inside the thread:
Use the provided classes and methods
4. Start another worker thread, if the first thread does not exist anymore
and continue step 3

Performance:
If the first variant is used you can start more worker threads but then we recommend to adjust on server side
the number of threads to access the SQL server in parallel from 3 to a higher value.
Change the registry key
HKLM/Software/Wow6432Node/Micos/SPS/Default/QuerySrv/NumThreads/@value and restart the system
so the value is used on next startup.
If you do not increase the value the parallel executed SQL read jobs are serialized including all other work-
station clients, OPC-Servers and so on.

Warning: If you use LoadLibrary to load the libraries provided in this API, you should do that on start of
the application otherwise Microsoft thread local storage is not initialized and the API can crash.

Example how to do that:

A) Use a static member and in the constructor of this member load the libraries.
B) Better is not to load the libraries dynamic and put a dependency in your project to let the system
load the “W32_ACEInterface.dll” including all dependent libraries on startup of your application.
Bosch Access Systems

ACE 4.9.20007 Version Page

ACE API 1.1.5a 43/69
Author Date
Software 15.03.2023
Development

16.2 Example how to use API in multithreading .NET application

The following code snippet shows an example for using the API from multithreaded .NET applications.

using [Link];
using System;
using [Link];

namespace [Link]
{
/// <summary>
/// Provides access to the ACE API using a shared <see cref="AccessEngine"/> instance.
/// </summary>
public sealed class AceApi : IDisposable
{
private readonly AceApiOptions _options;
private readonly Lazy<AccessEngine> _accessEngine;

private readonly StaTaskScheduler _scheduler;

private readonly TaskFactory _taskFactory;

public AceApi(IOptions<AceApiOptions> options)

{
if (options == null)
{
throw new ArgumentNullException(nameof(options));
}

_options = [Link];
_accessEngine = new Lazy<AccessEngine>(CreateAccessEngine);

// Set up a single-threaded task scheduler because the AccessEngine object is VERY sensitive
w.r.t. threading context
_scheduler = new StaTaskScheduler();
_taskFactory = new TaskFactory(_scheduler);
}

public static void EnsureSuccess(API_RETURN_CODES_CS returnCode)

{
if (returnCode != API_RETURN_CODES_CS.API_SUCCESS_CS)
{
throw new InvalidOperationException($"ACE API operation failed with return code
{returnCode}.");
}
}

public static string GetQueryColumnValue(ACEQuery query, string colName)

{
var columnValue = new ACEColumnValue();

var returnCode = [Link](colName, columnValue);

EnsureSuccess(returnCode);

return [Link];
}

public Task ExecuteAsync(Action<AccessEngine> operation)

{
if (operation == null)
{
throw new ArgumentNullException(nameof(operation));
}
Bosch Access Systems

ACE 4.9.20007 Version Page

ACE API 1.1.5a 44/69
Author Date
Software 15.03.2023
Development

return _taskFactory.StartNew(() => operation(_accessEngine.Value));

}

public Task<TResult> ExecuteAsync<TResult>(Func<AccessEngine, TResult> operation)

{
if (operation == null)
{
throw new ArgumentNullException(nameof(operation));
}

return _taskFactory.StartNew(() => operation(_accessEngine.Value));

}

public void Dispose()

{
// Note that this may block until all scheduled operations have completed
_scheduler.Dispose();

if (_accessEngine.IsValueCreated)
{
_accessEngine.[Link]();
}
}

private AccessEngine CreateAccessEngine()

{
var ace = new AccessEngine();

try
{
var returnCode = [Link](_options.User, _options.Password, _options.Host);

if (returnCode != API_RETURN_CODES_CS.API_SUCCESS_CS)
{
throw new InvalidOperationException($"Login to ACE failed, return code:
{returnCode}.");
}
}
catch
{
[Link]();
throw;
}

return ace;
}
}
}
Bosch Access Systems

ACE 4.9.20007 Version Page

ACE API 1.1.5a 45/69
Author Date
Software 15.03.2023
Development

using System;
using [Link];
using [Link];
using [Link];
using [Link];

namespace [Link]
{ /// <summary>
/// Task scheduler that schedules queued work onto a single STA worker thread.
/// </summary>
public sealed class StaTaskScheduler : TaskScheduler, IDisposable
{
private readonly BlockingCollection<Task> _tasks = new BlockingCollection<Task>();
private readonly Thread _thread;

public StaTaskScheduler()
{
_thread = RunThread();
}

public void Dispose()

{
if (!_tasks.IsAddingCompleted)
{
_tasks.CompleteAdding();
_thread.Join();
_tasks.Dispose();
}
}

protected override IEnumerable<Task> GetScheduledTasks()

{
return _tasks.ToArray();
}

protected override void QueueTask(Task task)

{
_tasks.Add(task);
}

protected override bool TryExecuteTaskInline(Task task, bool taskWasPreviouslyQueued)

{
return !taskWasPreviouslyQueued &&
[Link] == _thread.ManagedThreadId &&
TryExecuteTask(task);
}

private Thread RunThread()

{
var thread = new Thread(() =>
{
foreach (var task in _tasks.GetConsumingEnumerable())
{
TryExecuteTask(task);
}
});
[Link]([Link]);
[Link] = true;
[Link]();
return thread;
}
}
}
Bosch Access Systems

ACE 4.9.20007 Version Page

ACE API 1.1.5a 46/69
Author Date
Software 15.03.2023
Development

17 OTIS Elevators
Since BIS V4.7 the ACE supports OTIS elevators.

The OTIS elevator data can be used in API after the configuration has been done by ACE dialogs for
- OTIS elevators devices
- authorizations which include OTIS elevators
- additional OTIS custom fields for persons

17.1 Authorizations
Authorizations which are using OTIS floors can be assigned to a persons object by using the
Persons::AddAuthorization method as usual. There is no difference between authorizations with or without
OTIS floors.

17.2 Additional OTIS fields for persons

For using OTIS elevators in the ACE it is possible to configure some additional custom fields for persons.
There are 3 additional fields concerning DES selection, home floor and exit door of a person and up to 8
option flags.
For now the option 1 stands for standard user and option 2 stands for handicapped user. Note that these
flags shouldn’t be set both at the same time!
The OTIS custom fields are displayed in an additional elevator tab in ACE persons dialog. To use these
fields with the API, they can be set/get by using the custom field methods as described in 10.3Using Cus-
tom fields (AdditionalFields)( page 34).

Example of configured OTIS options in persons dialog and in API application:

Bosch Access Systems

ACE 4.9.20007 Version Page

ACE API 1.1.5a 47/69
Author Date
Software 15.03.2023
Development

var person = new ACEPersons(accessEngine);

result = [Link]("myOTIS DES Selection", strDESId); // DES ID from DB-table devices
result = [Link]("myOTIS Home Floor", "5"); // home floor of person
result = [Link]("myOTIS Exit door", "01"); // exit door : "01" = front door
// "10" = rear door
result = [Link]("myOTIS Option 1", true); // option 1 for normal user
result = [Link]("myOTIS Option 2", false); // option 2 for handicapped user
result = [Link]("myOTIS Option 3", false);
result = [Link]("myOTIS Option 4", false);
result = [Link]("myOTIS Option 5", false);
result = [Link]("myOTIS Option 6", false);
result = [Link]("myOTIS Option 7", false);
result = [Link]("myOTIS Option 8", false);

result = [Link]();

string myDES, myHomefloor, myExitdoor;

bool bOption2;

result = [Link]("myOTIS DES Selection", out myDES);

result = [Link]("myOTIS Home Floor", out myHomefloor);
result = [Link]("myOTIS Exit door", out myExitdoor);
result = [Link]("myOTIS Option 2", out bOption2);

// Release the object

[Link]();
Bosch Access Systems

ACE 4.9.20007 Version Page

ACE API 1.1.5a 48/69
Author Date
Software 15.03.2023
Development

18 PegaSys Offline System Support

Since BIS V4.8 and AMS V3.0 the ACE API supports PegaSys offline systems.

The PegaSys functionality can be used within the API after the device configuration of a PegaSys system
has been done using the proper ACE configuration dialogs. Only one PegaSys configuration per customer is
supported now. The API implementation is independent from the used card technology. The developer us-
ing the API must know what cards are compatible or not if he switches the ‘PegaSys card option’.

Naming convention:
All ACE database tables starting with the letters “SA” are PegaSys related tables, like SASystems
Some ID columns are using the same convention like [Link]

Following actions can be done using the new PegaSys objects:

• Creating of a SACARD record for a given person’s badge.

=> By doing so the specific PegaSys offline data can be set for this badge

• Managing of PegaSys doors and groups (intended for auto tests only)

• Creating of PegaSys door groups (intended for auto tests only)

• Assignment of PegaSys doors or groups to persons

=> By doing so the offline permissions are defined for that persons

• Assignment of PegaSys groups to access authorizations

=> By doing so every cardholder with these access authorizations will get the assigned groups (=
offline authorizations) on the next card update

Before any of the following PegaSys classes can be used a valid [Link]() is required.
Bosch Access Systems

ACE 4.9.20007 Version Page

ACE API 1.1.5a 49/69
Author Date
Software 15.03.2023
Development

18.1 PegaSys base class

The ACEPegaSys class provides a method to retrieve the SASYSTEMID (internal ID) of the configured
PegaSys offline system.
Also the system values which define the maximum number of doors and groups allowed in the system and
the maximum of single door assignments to a person can be retrieved.
The following lines of code show how to retrieve the SASYSTEMID which is needed to create related SA-
Doors, SAGroups and SACards:

// Referencing the PegaSys system is important.

// The system identifier is used to select the PegaSys system
// if we support in future multiple of them.
// As long we support only one PegaSys sytem, you can fetch the SASystemId once and use it forever.
// By creating an ACEPegysys object it will be initialized retrieving the SystemId an the values
// for maxLSDoors, maxDoors and maxGroups from the system defined by license or rather facility card

ACEPegaSys pegasys = new ACEPegaSys (accessEngine);

String saSystemId = [Link]();

var iMaxDoors = [Link](); // gets max. single door authorizations per person
var iMaxGroups = [Link](); // gets maximum groups
var iMaxLSDoors = [Link](); // gets maximum doors

// Release the object

[Link]();

Furthermore, the ACEPegaSys class can enable or disable the ‘PegaSys card option’ to mark the card as
PegaSys compatible or not. Methods are:

• SetPegaSysOption (TCHAR* cardId);

• ResetPegaSysOption (TCHAR* cardId);

It is important to take notice that the PegaSys card option will be changed directly in the database by calling
these methods. That means that the OPTIONS field of your local cards object, which is related to that data-
base field, will not be refreshed until you reload your card object. This should be kept in mind in case you
would like to do some changes to your local card object and save them in database.
The OPTIONS field in database is used to store not only the PegaSys flag, but also flags for other options
e.g. guard cards or parking tickets by setting the according bits. The interpretation of the stored value is
done by the ACE software and therefore to prevent errors the [Link] should not be changed di-
rectly,
Bosch Access Systems

ACE 4.9.20007 Version Page

ACE API 1.1.5a 50/69
Author Date
Software 15.03.2023
Development

18.2 PegaSysCard
This functionality offers methods to add, update or delete a PegaSys card.

ACEPegaSysCard pegasysCard = new ACEPegaSysCard (accessEngine);

[Link] = saSystemId; // Select the previously loaded PegaSys system

[Link] = [Link](); // Select the person

[Link] = [Link](); // Select the card

[Link] = 1; // Permission to leave the door open or not

[Link] = 24; // The access permission time in hours
// written by card reader at main entrance

// As start time… we appreciate to set the current time

// minus 5 minutes so even if the time is not set 100% correct in PegaSys devices
// it will let you in
[Link] = [Link](-5);;

// As end time the absolute end time like friday next week must be set.
// The AMC at the main entrance will set this time depending on the DURATION set above
[Link] = [Link](8);

API_RETURN_CODES_CS iError = [Link]();

// Release the object

[Link]();

18.3 PegaSysDoors and PegaSysGroups (for testing only)

PegaSysDoors and PegaSysGroups provide functions to add, update or delete an offline door or permission
group (in database tables ‘SADoors’ and ‘SAGroups’).

The example shows how to add a PegaSys group:

ACEPegaSysGroup pegaSysGroup = new ACEPegaSysGroup (accessEngine);

[Link] = saSystemId; // Select the previously loaded PegaSys system

[Link] = "Test Group";

[Link] = "Test Organization";
[Link] = 10;

[Link]();

// Release the object

[Link]();
Bosch Access Systems

ACE 4.9.20007 Version Page

ACE API 1.1.5a 51/69
Author Date
Software 15.03.2023
Development

This class is made for easier testing in an automated environment. There are no validity checks implement-
ed like if the GROUPNO is unique and in valid range.

18.4 PegaSysDoorGroup (for testing only)

This object allows to add or delete PegaSys door group (table ‘SADOORGROUPS’).
Example:

// Note: create or load door(s) and group before…

ACEPegaSysDoorGroup pegaSysDoorGroup = new ACEPegaSysDoorGroup (accessEngine);

[Link] = [Link]();
[Link] = [Link]();

[Link]();

// Release the object

[Link]();

This class is made for easier testing in an automated environment. There are no validity checks implement-
ed like if the IDs are valid.

18.5 PegaSysAuthPerPerson

18.5.1 Assign Authorization for a single door or group

The class offers the possibility to assign a PegaSys door or group as authorization to a person.
Example:

// Note: create or load door (or group) and person before…

ACEPegaSysAuthPerPerson pegaSysAuthPerPerson = new ACEPegaSysAuthPerPerson (accessEngine);

[Link] = [Link](); // or group id

[Link] = [Link]();

[Link]();

// Release the object

[Link]();

How many doors, groups or single-doors asignments to persons are allowed for the PegaSys system is de-
fined by the PegaSys facility card and can be different for each customer (example: doors 2-8 and groups
255-1024). The current max numbers can be fetched from PegaSys base class.
Bosch Access Systems

ACE 4.9.20007 Version Page

ACE API 1.1.5a 52/69
Author Date
Software 15.03.2023
Development

The PegaSysAuthPerPerson class provides method to load from database:

Get (string from table SAAuthPerPerson column SAAuthPerPersonId)
To remove the permission use the Delete() method.
There is no update method available and must be implemented by Delete() and Add() methods.

18.5.2 Assign multiple authorizations to a person

An additional method SetAuthorizations allows to assign multiple PegaSys authorizations to a person in

one transaction. The performance of the interface to the MAC subsystems is increased, if this method is
used instead of calling multiple times the methods Add() and Delete() .
After a successful call of SetAuthorizations, the person should have exactly the authorizations set with this
function call, i.e. missing authorizations are assigned and additional authorizations are revoked.

ACEPegaSysAuthPerPerson pegaSysAuthPerPerson = new ACEPegaSysAuthPerPerson (accessEngine);

ACEPersons person = new ACEPersons(accessEngine);
...
string[] authList;
authList = new string[3];
authList [0] = [Link]();
authList [1] = [Link]();
authList [2] = [Link]();
[Link] = [Link]();

[Link](authList);

// Release the object

[Link]();

Not that the group-ids and door-ids in the list must exist in the database. Duplicate entries are not allowed.

18.6 PegaSysGroupsPerAuth
Creates or deletes a link between a PegaSys group to an existing access authorization. This is an alternative
to the PegaSysAuthPerPerson permission described before.
Example:

// Note: create or load group and person before…

ACEPegaSysGroupsPerAuth pegaSysGroupsPerAuth = new ACEPegaSysGroupsPerAuth (accessEngine);

[Link] = [Link]();
[Link] = [Link]();

[Link]();

// Release the object

[Link]();
Bosch Access Systems

ACE 4.9.20007 Version Page

ACE API 1.1.5a 53/69
Author Date
Software 15.03.2023
Development

The PegaSysGroupPerAuth class provides method to load from database:

Get (string from table SAGroupsPerAuth column SAGroupPerAuthId)
To remove the permission use the Delete() method.
There is no update method available and must be implemented by Delete() and Add() methods.
Bosch Access Systems

ACE 4.9.20007 Version Page

ACE API 1.1.5a 54/69
Author Date
Software 15.03.2023
Development

18.7 Best Practice how to use the PegaSys API

Preconditions using the PegaSys API objects:

The PegaSys functionality can be used after a device configuration of a PegaSys system has been created
using the proper ACE configuration dialogs. All PegaSys offline doors and/or groups should exist. Fur-
thermore, the PegaSys authorization(s) (= relation between doors and groups) should have been configured
already.

Note:
The API implementation is independent from the used card technology but the developer using the API has
to know which cards are compatible or not if he switches the ‘PegaSys card option’.

Limitations:
- Only one PegaSys configuration per customer is supported.
- PegaSys cards are not valid for visitors or guards.
- Only one PegaSys card per cardholder allowed.
- The API for PegaSys is not meant to configure PegaSys time models and black lists.
- The creation of battery replacement- and event-log cards has to be done using the proper ACE dia-
log also.

How to authorize a cardholder to a PegaSys door:

• Create AccessEngine class and Login()

• Create or load cardholder to assign PegaSys authorizations using the API
• Assign or load the access card of the selected person from previous step.
• Initialize the PegaSys base class (see chapter 18.1).
• Use an appropriate Query like ACEQuery to load the access card from cardholder.
• Set the PegaSys option for the loaded card (see chapter 18.1).
• Assign a PegaSys card for every access card using the attributes of the persons and their cards (see
chapter 18.2).
• Use an appropriate Query like ACEQuery to load the PegaSys doors or groups
• Now the authorizations (=doors and groups) can be assigned to the loaded person (see chapter
18.5).
• The PegaSys cards will be coded when they are offered to an access reader.

An overview about the PegaSys tables needed in the ACEQuery objects is provided in a separate overview.
Bosch Access Systems

ACE 4.9.20007 Version Page

ACE API 1.1.5a 55/69
Author Date
Software 15.03.2023
Development

19 Set the directory for logging

When the API is used the default directory for logging will be the Temp directory of the logged in user
(%temp%). The directory can be changed calling the function SetLogDirectory of the CW32_ACEInterface
(AccessEngine) object:

C++:

// Set the directory for logging

CW32_ACEInterface ace;
if ([Link](_T("c::\\temp")) != API_RETURN_CODES::API_SUCCESS)
{
AfxMessageBox(_T("Couldn't change logging directory"));
}

C#:

/// <summary>
/// Tries to change the log directory
/// </summary>
public void ChangeLogDirectory()
{
// Let the operator choose a new folder for logging
using (FolderBrowserDialog folder = new FolderBrowserDialog() )
{
[Link] = "Select new logging folder";
if ([Link] == [Link]())
{
// Try to set the new logging path
if(m_accessEngine.SetLogDirectory([Link]) !=
API_RETURN_CODES_CS.API_SUCCESS_CS)
{
[Link]($"Couldn't change logging folder to {[Link]}");
}
}
}
}

When setting the new log directory succeeded the function returns API_SUCCESS and starts logging in the
new directory immediately. The log file name will always be MasterAPI_ApplicationName.log where the
ApplicationName is the name of the executable that hosts the API.

20 Release Notes
20.1 ACE API Version 4.1.7777.0

1. The ACE login has been simplified (see chapter 3.1 “ACE").
2. The types of all string members of ACE objects have been changed. The direct assignment of values to
these members is now possible: Persons person; [Link] = _T("Doe");
Bosch Access Systems

ACE 4.9.20007 Version Page

ACE API 1.1.5a 56/69
Author Date
Software 15.03.2023
Development

3. As a side effect the string copy functions are no longer available. A statement like wcscpy_s (
[Link], _T("Doe")); produces an error.

6. For an easier migration we recommend the following procedure:

• Open a source file containing wcscpy_s statements in Developer Studio 2010
• Open “Find And Replace”.
• Enable “Match case”.
• Enable “Use” and select “Regular expressions”.
• In the “Find what” field enter: wcscpy_s[ \t]*\([ \t]*{[^,]*}[ \t]*,[ \t]*{.*}\)[ \t]*;
• In the “Replace with” field enter: \1 = \2;
• Click “Replace” rather than “Replace all” to ensure that each replacement is correct.

7. The identifiers passed from an ACE object are no longer static. A statement like
TCHAR * cardId = [Link](); is now invalid. Instead, use IdC cardId = [Link]();

8. The type of date objects has been changed from DateT to DateC. This affects the methods
Persons::AddAuthorization, Visitors::AddAuthorization and Persons::SetPin.

20.2 ACE API Version 4.1.8401.0

1. The division can be changed via API too (database column ‘clientId’). The new methods
SetCurClientId(), GetCurClientId() and GetCommonClientId() are provided in
ACEInterface class
2. The person object now allows you to assign a time model, set the extended open time for handi-
capped persons and set the VIP flag (see AddTimeModel(), fields [Link]
and [Link]). The AddLockout() method checks that the reason field is not empty.
3. All AddToBlackList() methods now require a second parameter ‘reason’.
4. The PIN methods SetPIN() and SetIDSPIN() encrypt the PIN now, so a valid PIN is sent to the
MAC subsystem. The method ClearPin() clears both PINs. Be sure to configure the additional
IDSPIN in the configuration dialog, including the PIN length.
5. Duplicate cards with the same CardNo and CodeData combination cannot be inserted or up-
dated (Error code API_CARD_INVALID_KEYCODE).

20.3 ACE API Version 4.1.8410.0

1. Added two further methods “StartEventMessageDistribution(..)“ and „StopEventMessageDistri-
bution()” to the CW32_ACEInterface class (or for .NET see object AccessEngine).
With the start method a TCP connection will be established to forward all events from the MACs and the
Guard-Tour messages directly to the given TCP-Address.
Limitation: Only one API client can use these methods at one time. If a second API client starts to use
them simultaneously the last distribution will be stopped and a new distribution is started.
Bosch Access Systems

ACE 4.9.20007 Version Page

ACE API 1.1.5a 57/69
Author Date
Software 15.03.2023
Development

20.4 ACE API Version 4.1.8420.0

The API provides a new class Commands (or for .NET see object ACECommands). With this interface you
can send commands to the MAC subsystem, such as open door or block door.

20.5 ACE API Version 4.2.8617.0

The API uses Visual Studio 2015 Update 1.
The library name changed in ACE 4.2 from W32_ACEInterface-3 to W32_ACEInterface.

20.6 ACE API Version 4.2.8800.0

The API provides the new method “SetAuthorizations” (can be found in class Persons and Visitors).
The new method allows to assign multiple authorizations to a person or visitor in one step. The perfor-
mance of the interface to the MAC subsystems is increased, if the new method is used instead of calling
multiple times the methods “AddAuthorization” and “DeleteAuthorization”.
After a successful call of “SetAuthorizations”, the person should have exactly the authorizations set
with this function call, i.e. missing authorizations are added and additional authorizations are deleted.

20.7 ACE API Version 4.2.8860.0

- The API method “SetAuthorizations” does now some additional plausibility checks e.g. if all au-
thorization exists or if an authorization is given twice. The method now ensures that the given author-
izations will be correctly assigned to several persons in case of using a loop.
- The registry entry PS_MASTER is not needed anymore. The API always uses the server address which
has been specified with the login method.

20.8 ACE API Version 4.3.8953.0

- Add new database table overview for devices named “ACE Database Devices 4_3_8953.pdf”.
- Optimization of database table DEVICESINGROUPS: the columns DEVICEFROM and DEVICETO have
been removed, the column DEVID has been added. This provides a faster way to determine all devices
belonging to a device group.
- Bugfix: The Persons/Visitors attributes ‘AUTHFROM’ and ‘AUTHUNTIL’ were restricted to dates up to
the year 2038. Now later dates are accepted.
- The internal database columns ‘DOMAIN’, ‘SUBDOMAIN’ are now used in a different way, so we ad-
vise to use the latest API for BIS V4.3.
- Bugfix: The API sends commands in the past to the first MAC only. Now multiple MACs are supported.
- Bugfix: Previously all the API connections were shown in the BIS manager as connected users. Now on
login verification an entry is shown for some seconds only.
Bosch Access Systems

ACE 4.9.20007 Version Page

ACE API 1.1.5a 58/69
Author Date
Software 15.03.2023
Development

20.9 ACE API Version > 4.3.9005.0 (patch)

- Bugfix: The update of the Cards attributes COLLECT and DATEPRINTED failed. Now the conversion to
the internal used date format has been adjusted.
- Bugfix: The API [Link] uses ColumnValue with the restricted length 255. This leads to an
error while getting the row [Link] which could have a length up to 4096. Now the
length of ColumnValue has been enhanced.

20.10 ACE API Version > 4.3.9061.0

- Another method RequestStartMAC using the MAC device ID as parameter is provided now

20.11 ACE API Version > 4.3.9076.0

- Method RequestSwitchMAC and RequestSynchronizeMAC are provided now

20.12 ACE API Version > 4.3.9079.0

- Bugfix: Previously the method GetAllLockoutIds for persons and visitors called from
DotNet_AceInterface failed. Now the internal use of the parameters has been adjusted.
- Bugfix: The date parameters validFrom and validUntil passed by method AddAuthorization for per-
sons and visitors are stored in the tables authPerPerson e.g. authPerVisitor as dateTime. Previously for
both dates the timestamp 00:00:00 has been added. Now for validTill the timestamp 23:59:59 is used.
This is the same behavior as used by ACE Dialog Manager.
- Add new database table overview for calendar definition named “ACE Database Calendar
4_3_9079.pdf”.

20.13 ACE API Version 4.4

- Connection to more than one ACE is supported now. The ACECommands will be send to the corre-
sponding MACs.
- Bugfix: ACECommands without preceding valid login will return now API_LOGIN_REQUIRED instead of
API_ACSCI_CMD_FAILED.
- Bugfix: ACECommands should only be executed when the user has assigned ‘ACE API access rights
with unlimited access’. In case of ‘read-only access’ they will return API_ACCESS_RESTRICTED.
- Bugfix: The Persons/Visitors attributes ‘AUTHFROM’ can use dates before the year 1.1.2000 now. In
the past BIS releases the from date was sent to the subsystem MAC and AMC and lead to an access er-
ror, because the AMC do not support older dates.

20.14 ACE API Version 4.4.9091.0

- Bugfix: Previously the method addCard filled the database fields CODADATA2 / CODEDATA3 and COD-
EDATA4 with “0000000000000000”. Now the fields will be set to NULL if no codedata is provided.
- Added further additional information about StartEventMessageDistribution in hierarchical systems
- Added new MAC commands to ‘synchronize’ and ‘switch’
- All event messages have a new parameter “/macdevid” now, so the received MAC identification can
be done by ID (see table column [Link]) instead of the MAC name itself.
Bosch Access Systems

ACE 4.9.20007 Version Page

ACE API 1.1.5a 59/69
Author Date
Software 15.03.2023
Development

20.15 ACE API Version 4.5.9310.0

- Bugfix: The API did not support the field PHONEPRIVATE field for visitors.
- Users of the API must recompile their client applications.
- Added further additional information about using Custom fields
- Added database description ‘ACE Database 4_5_9269.pdf’
- New tables to manage Custom fields: AdditionalFieldDescriptors and AdditionalFields
- New columns country, state, streethousenoext in table Companies
- New table BioData to store biometric data of persons

20.16 ACE API Version 4.5.9456.0

The API uses Visual Studio 2015 Update 3
Applications using API V4.5.9310.0 should be compatible with BIS 4.5.9456.0 too. New database columns
are set automatic to default values (= NULL).

- Added database description ‘ACE API Database 4_5_9456.pdf’

- Most important database changes:
- New column for table PERSONS: IDENTIFICATIONMODE
▪ Enum value:= Unknown = 0, Finger only = 1, Card only = 2, Card and Finger = 3
- New columns for table ACPERSONS:
▪ PERMOPEN => grant permission to set office mode (= unlock doors)
▪ REMOTECTRL1 and REMOTECTRL2 => Used for person related remote control output
1 and 2 (see IO functions in AMC configuration)
- Three new methods are available to change the person object:
- SetPermitToOpenDoorPermanently(bool bSet);
- SetRemoteCtrl1(bool bSet);
- SetRemoteCtrl2(bool bSet);
- The ACECommands class received three new methods:
- SetAntiPassback(String strReaderId, bool bIsAntiPassback);
- SetVideoVerification(String strReaderId, bool bIsVideoVerification);
- SetRandomScreening(String strReaderId, bool bIsRandomScreening,
int iScreeningRate, int iScreeningTimeout);

- Note on the prerequisite for using the command SetVideoVerification:

Before the video verification of a reader can be switched by using the command SetVideoVerifica-
tion, the parameter “Additional verification” must be activated and saved once by using the de-
vice configuration dialog for the reader / door control. The device configuration dialog creates all
required device parameters for video verification in the device database table. Even if the flag
“Additional verification” was deactivated again in the device configurator, the command SetVide-
oVerification will switch the necessary device parameter from now on.
Bosch Access Systems

ACE 4.9.20007 Version Page

ACE API 1.1.5a 60/69
Author Date
Software 15.03.2023
Development

20.17 ACE API Version 4.5.9562.0

The previously added methods
- SetPermitToOpenDoorPermanently(bool bSet);
- SetRemoteCtrl1(bool bSet);
- SetRemoteCtrl2(bool bSet);

are replaced by the following Persons attributes

“PERMOPEN”, “REMOTECTRL1“, “REMOTECTRL2“

Applications using API V4.5.9310.0 should be compatible with BIS 4.5.9562.0 except the Set-\Get- Photo
methods. These methods changed because the photos are now saved in the ACE database instead of the
hard disk.

- Added database description ‘ACE API Database 4_5_9562.pdf’

- Most important database changes:
- New columns for table CARDS: CODETYPE, CODELEN, CODEVAR, CODELEN2, CODEVAR2
=> Used to identify the card type the bit length and code variant of the vales found in columns
codedata and codedata2
If not changed the cards are marked as <unknown> and should work as before.
- New tables: PHOTOS and SIGNATURES

To find easier API problems the API will write more details to the debug log file if logging for the server is
activated in the ACE configuration.

20.18 ACE API Version 4.6.9895.0

Applications using API 4.6.9604.0 should be compatible with BIS 4.6.9598.0. New database columns are
set automatic to default values (= NULL).

- Added database description ‘ACE API Database 4_6_9895.pdf’

- Most important database changes:
- New column for table CARDS: TEMPCARDID
=> Used by ACE-dialogs for temporary cards
- New column for table AUTHORIZATIONS: MAXUNUSEDTIMEINDAYS and
new column for table AUTHPERPERSON: LASTUSEDDATE
=> Used by Authorization monitoring process
Bosch Access Systems

ACE 4.9.20007 Version Page

ACE API 1.1.5a 61/69
Author Date
Software 15.03.2023
Development

20.19 ACE API Version 4.6.10052.0

Changes in the unmanaged C++ API:
- The following member variables changed type from DateC to DateTimeT:
- Persons::DATELASTCARD
- Visitors::ARRIVALEXPECTED
- Visitors::DEPARTEXPECTED
- Visitors::ARRIVALDATE
- Visitors::DEPARTDATE
- Visitors::DATELASTCARD
- The Commands class has two new methods:
- ActivateThreatLevel(TCHAR* strMACDevId, int iThreatLevel)
- DeactivateThreatLevel(TCHAR* strMACDevId)

Changes in the managed C++ API:

- The following member variables changed type from ACEDateT^ to DateTime:
- [Link]
- [Link]
- [Link]
- [Link]
- [Link]
- [Link]
- The ACECommands class has two new methods:
- ActivateThreatLevel(String^ strMACDevId, int iThreatLevel)
- DeactivateThreatLevel(String^ strMACDevId)

20.20 ACE API Version 4.6.10281.0

Applications using API 4.6.10281.0 are compatible with BIS 4.6.9906.0 except if they are using the changed
member variables as mentioned below and do not change the door or reader modes.
The API now supports multithreading (see Multithreading chapter)

The following bugfixes are done:

- Bugfixes: the following members will now provide Date and Time. Applications using these members,
have to be recompiled and the source has to be adapted to use datetime instead of date.
- [Link]
- [Link]
- [Link]
- [Link]
- [Link]
- [Link]
Bosch Access Systems

ACE 4.9.20007 Version Page

ACE API 1.1.5a 62/69
Author Date
Software 15.03.2023
Development

Persons myPerson(myACE);
[Link] = _T("Smith");
[Link] = DateTimeC(30, 6, 2019, 12, 27);
[Link]();

Persons myPerson2(myACE);
[Link]([Link]());

DateTimeC dt = (long)[Link];
_tprintf(_T("\nPerson with id '%s' and last name '%s' : DateLastCard = %d.%d.%d %d:%d "),
[Link]().GetBuffer(),
[Link](),
[Link], [Link], [Link], [Link], [Link]);

var visitor = new ACEVisitors(accessEngine);

[Link] = "Datetest";

[Link] = new DateTime(2019, 8, 14, 12, 25, 0);

[Link] = new DateTime(2019, 8, 14, 18, 55, 0);
[Link] = new DateTime(2019, 8, 14, 12, 45, 0);

result = [Link]();

var visitor2 = new ACEVisitors(accessEngine);

result = [Link]([Link]());

[Link]("Successfully reloaded visitor personid='{0}'",

[Link]());
[Link]("Arrival Date = {0}", [Link]());
[Link]("Departure Date = {0}", [Link]());
[Link]("Date Last Card = {0}", [Link]());

- Bugfix: [Link] and [Link] will now also update the according fields in table
ACPERSONS.
- Bugfix: [Link](refers to table [Link]) and [Link] (refers to table per-
[Link]) were interchanged according to the usage in ACE dialogs.
- Bugfix: [Link] wasn’t properly saved before. Now the value will be saved in table
persons.
- Bugfix: persons. MARITALSTATUS and [Link] weren’t handled correctly before .
Now getting and setting of the values have been adjusted.
- Bugfix: Visitors::Update(). Previously the method didn’t update the columns in table visitors but only
in table persons. Now both tables will be updated.
- Bugfix: The import and export of photos for persons and visitors using managed code failed before.
Now SetPhoto and GetPhoto will also work using managed code.
Bosch Access Systems

ACE 4.9.20007 Version Page

ACE API 1.1.5a 63/69
Author Date
Software 15.03.2023
Development

20.21 ACE API Version 4.6.10363.0

Applications using API 4.6.10363.0 are compatible with BIS 4.6.10363.0 and 4.7.x versions. The connected
BIS server version is checked on Login and will fail if it is not compatible.

The created debug help file “[Link]” name is now “MasterAPI_<YourApplicationName>.log”. Mul-
tiple applications can now use the API and for everyone another debug file will be generated.

20.22 ACE API Version 4.7.10409.0

Applications using API 4.7.10409.0 are compatible with BIS 4.6.10363.0 and BIS 4.7.x versions. The con-
nected BIS server version is checked on Login and will fail if it is not compatible.

Bugfix: For the persons and visitors objects the methods add, update and delete methods now are explicit-
ly done as one transaction.
The event messages are stored in a new database table eventtypes (since BIS 4.6) instead of the former
used file “C:\MgtS\AccessEngine\AC\Cfg\[Link]”.
The ACE now supports OTIS elevators. For further information refer to chapter 17OTIS Elevators (page
46).

20.23 ACE API Version 4.7.10574.0

Applications using API 4.7.10409.0 are compatible with BIS 4.6.10363.0 and BIS 4.7.x versions. The con-
nected BIS server version is checked on Login and will fail, if it is not compatible.

Bugfix: Fetching data from database columns which exceeded the length of 4096 byte failed in former ver-
sions. Now bigger contents of database fields are possible.

20.24 ACE API Version 4.7.10714

The API uses Visual Studio 2019 now.
Applications using API V4.7.10714.0 should be compatible with BIS V4.6 – BIS V4.8 and AMS V3.0, if the
functionality exist in the BIS or AMS Version on the server.
- Added support for offline system “PegaSys”. Prerequisite is a configured PegaSys offline system with
all offline devices.
- New interface support Biometric 3rdParty systems to be part of the access control system. Different
types of integrations are available and described in more detail in additional documents.
Two commands are added to allow specific persons access:

- RequestVerificationPersId(access reader device id, person id)

- RequestVerificationCardId(access reader device id, card id)
Bosch Access Systems

ACE 4.9.20007 Version Page

ACE API 1.1.5a 64/69
Author Date
Software 15.03.2023
Development

20.25 ACE API Version > 4.7.10764

Applications using API > V4.7.10764.0 should be compatible with BIS V4.6 – BIS V4.7 and AMS V3.0, if the
functionality exist in the BIS or AMS Version on the server.
- Added Database description ACE API DATABASE Pegasys 4_7_10714.pdf
- Changes to class PegaSys:
- SASYSTEMID is now defined as a private member. Use method GetPegaSystemId() to get the
sasystemid to your local application.
- New methods GetSAMaxLSDoors(),GetSAMaxGroups(), GetSAMaxDoors() will provide the re-
strictions of your system concerning the number of allowed doors defined by license or rather
the maximum number of allowed groups or single-door-assignments defined by facility card.
- New method PegaSysAuthPerPerson. SetAuthorizations() for setting multiple authorizations for a per-
son in one transaction to increase performance is available now.
- Bugfix: The values of [Link] and PegaSysCard .VALIDUNTIL have to be in between
the values of [Link] and [Link], but the check didn’t work correctly in some
cases. This bug is fixed now.

20.26 ACE API Version > 4.8.11077

- The directory name of the sample applications in the installation folder has been renamed.
- New method for the SetLogDirectory for directing the output of an API-application to a specific direc-
tory.
- Bugfix and functional change: Using the Visitors (ACEVisitors) objects function SetPersClassId will no
longer directly write the changes to the database but will only be saved when the function Add is
called on new visitor instances or the function Update on modified visitor instances.

20.27 ACE API Version > 4.9.11120

- The new feature CMD execution of parallel device parameter is supported now.
For further information refer to chapter 8.2 API command execution: parallel changing of device pa-
rameters (page 30).
- Added Database description “ACE Database Devices 4_9_11120.pdf” with new database table Cur-
rentDeviceMode

20.28 ACE API Version > 4.9.11177

- New feature: Add a mobile access card to a person/visitor. If the SDK connects to older access system
it is not possible to create there a mobile card.

20.29 ACE API Version > 4.9.11306

Applications using API > V4.9.11306.0 support BIS 4.9.1 and AMS 4.0. They also should be compatible with
BIS V4.6 – BIS V4.9 and AMS V3.0 / 3.0.1, if the functionality exist in the BIS or AMS Version on the server.
For further information refer to chapter 2 Compatibility (page 4).
Bosch Access Systems

ACE 4.9.20007 Version Page

ACE API 1.1.5a 65/69
Author Date
Software 15.03.2023
Development

20.30 ACE API Version > 4.9.20000

New method for persons and visitor ChangeClientId is provided now.
Background information: The ‘clientId’ is the internal identifier for a ‘division’.
Please note:
Not only the clientId of the persons/visitors entry in table persons/visitors will be changed, but also
related data like company, cards, sacards, authorizations and pathes could be adjusted! After execut-
ing the ChangeClientId method, the person/visitor object must be reloaded from the database in or-
der to be able to make further changes if necessary.

// To obtain all available divisions you can use the ACEQuery select in database table CLIENTS
// Prerequisite: these division are assigned to the APIUser
string div_red = "0013A8436A28B799";
string div_blue = "0013A8436A2F85C2";

[Link](div_red);

var myPers = new ACEPersons(myAce);

[Link] = "Pers-RED";
int iRetVal = [Link]();
string myPersId= [Link]();

// change the clientId for the person

iRetVal = [Link](div_blue);

// reload person after changeClientId !!

iRetVal = [Link](myPersId);

[Link] = "Pers-BLUE";
iRetVal = [Link]();

.
Bosch Access Systems

ACE 4.9.20007 Version Page

ACE API 1.1.5a 66/69
Author Date
Software 15.03.2023
Development

21 Document History

Version Date Notes

1.0.1 22.04.2014 Initial version
1.0.2 05.06.2014 Added this history.
Added hints ‘Registry entries for connection to ACE’
1.0.3 07.08.2014 Credential management not needed any more (>BIS V4.0)
1.0.4 06.11.2014 Simplified login; added release notes.
1.0.5 13.01.2015 Microsoft Visual Studio 2013 SP3 can be used too
1.0.6 06.03.2015 New API wrapper for .Net languages added
1.0.7 12.05.2015 Extended chapter known issues (Divisions)
1.0.8 30.07.2015 Removed issue and added division support
1.0.9 25.08.2015 Added event distribution support
1.0.10 01.09.2015 Added commands support
1.0.11 07.09.2015 Adjust code snippet for AddAuthorization
1.0.12 18.09.2015 Added example how to receive events
1.0.13 05.10.2015 Review and corrections
1.0.14 29.10.2015 Inserted language corrections
1.0.15 04.11.2015 Improved event and command description
1.0.16 12.11.2015 Review and clarification
1.0.17 08.03.2016 Usage of Visual Studio 2015, Renaming of W32_ACEInterface
1.0.18 18.04.2016 Added method “SetAuthorizations”
1.0.19 07.07.2016 Adjust “SetAuthorizations”
1.0.20 07.09.2016 Removed using of registry entry “PS_MASTER”
1.0.21 14.10.2016 BIS Release V4.3
1.0.21a 31.01.2017 Bugfix [Link], [Link],
(patch) length of ColumnValue used by Query
1.0.22 15.12.2016 BIS Release V4.4
1.0.23 13.01.2017 Added Bugfix: ‘AUTHFROM’
1.0.24 28.02.2017 Added method RequestStartMAC by deviceID
Inserted chapter about ACE API in hierarchical systems
1.0.25 14.03.2017 Added new method RequestSwitchMAC and
RequestSynchonizeMAC
1.0.26 23.03.2017 Added Bugfix: GetAllLockoutIds (DotNet_AceInterface)
Added Bugfix: persons/[Link]
validFrom/validTill
Added calendar description ACE Database Calendar 4_3_9079.pdf
1.0.27 07.04.2017 Added Bugfix: set CODEDATA2 / CODEDATA3 / CODEDATA4 to
NULL instead of “0000000000000000” if no value is provided.
Bosch Access Systems

ACE 4.9.20007 Version Page

ACE API 1.1.5a 67/69
Author Date
Software 15.03.2023
Development

Added further information on using event message forwarding in hierar-

chical systems.
12.04.2017 Updated hierarchical description and release notes
1.0.28 02.10.2017 Added Bugfix: API now supports field PHONEMOBILE for visitors.
Added new chapter ‘Custom Fields’.
12.10.2017 BIS Release 4.5:
Updated chapter ‘Custom Fields’
Added database description ‘ACE Database 4_5_9269.pdf’
1.0.29 01.12.2017 Added chapter ‘Clients’
1.0.30 28.03.2018 Added new changes to chapter 4.5.x
1.0.31 13.04.2018 Updated changes to chapter 4.5.9456.0 (New commands and compatibil-
ity description)
1.0.32 13.04.2018 API using service pack 3 of VS2015 now
1.0.33 25.04.2018 Multithreading problems with “Query” objects fixed. CardPersonaliza-
tion comments about problems removed.
1.0.34 19.05.2018 Updated latest changes: New persons and cards fields. New photo meth-
ods. Added new reference to database overview for BIS Release V4.6.
1.0.35 22.06.2018 Added existing API limitations and ACE recommendations.
1.0.36 14.11.2018 Added database description ‘ACE Database 4_6_9895.pdf’
1.0.37 22.03.2019 New Commands methods for threat level management
1.0.38 22.08.2019 Added new chapter: Getting started AMS
Multithreading:
- All method calls are using a semaphore from the ACE instance.
- Class attributes are not saved by the semaphore.

Added several bugfixes:

- persons / visitors DATELASTCARD
- [Link]
- [Link]
- [Link]
- [Link]
- [Link] and [Link]
- [Link] and [Link]
- [Link]
- persons/ visitors MARITALSTATUS
- [Link]()
- Managed code API: persons/visitors GetPhoto and SetPhoto

1.0.39 20.09.2019 Described Multithreading support

Added “known not solved bugs”
Bosch Access Systems

ACE 4.9.20007 Version Page

ACE API 1.1.5a 68/69
Author Date
Software 15.03.2023
Development

1.0.40 25.09.2019 New server compatibility check added.

Debug file name “[Link]” extended by <Application name>.
1.0.41 20.11.2019 Bugfix: For persons and visitors objects the add/update/delete methods
are now explicitly done as one transaction
Document update: For usage of event messages refer to database table
eventtypes (since BIS 4.6) instead of file
“C:\MgtS\AccessEngine\AC\Cfg\[Link]“ (up to BIS 4.5)
Added new chapter for OTIS support
Updated compatibility check
1.0.42 04.03.2020 Bugfix: Fetching data from database columns which exceeded the length
of 4096 byte failed in former versions. Now bigger contents of database
fields are possible.
1.0.43 05.06.2020 Added support of offline system “PegaSys”
Using Visual Studio 2019
Added new commands:
- RequestVerificationPersId(device id, person id)
- RequestVerificationCardId(device id, card id)
1.0.44 30.07.2020 Modification of PegaSys class:
- SASYTEMID is now defined as a private member and can be ob-
tained by calling GetPegaSystemId
- New methods GetSAMaxDoors, GetSAMaxGroups, GetSA-
MaxLSDoors to retrieve the system settings.

Added new method SetAuthorizations to class PegaSysAuthPerPerson

Added Database description
ACE API DATABASE Pegasys 4_7_10714.pdf

1.0.45 01.09.2020 Added code example for using API in multithreaded .NET application
1.0.46 06.01.2021 Document update : revision of C# usage description
1.0.47 03.05.2021 Add new function SetLogDirectory to change the directory for API log-
ging.
Add Bugfix for [Link].
Path for sample application changed.
1.1.0 25.05.2021 Added compatibility matrix
Updated version numbers
1.1.1 27.05.2021 Added description of new behavior when setting device parameters by
sending API-SDK-Commands
Command “Restore configuration” added for doors and readers.
Added database description ACE Database Devices 4_9_11120.pdf
1.1.2 21.06.2021 AutoCreateMobileCard added to create mobile access card for a person.
Bosch Access Systems

ACE 4.9.20007 Version Page

ACE API 1.1.5a 69/69
Author Date
Software 15.03.2023
Development

1.1.3 03.08.2021 Added new chapter 6.2 with a description about the person, visitor and
card tables and their relationship. Followed by some examples how to get
the current cardholder area, find a cardholder by internal card number and
check the card validity.
1.1.4 01.09.2021 BIS 4.9.1 and AMS 4.0 are supported now.
Updated compatibility matrix and version numbers
1.1.5 03.11.2021 Added more detailed description of how to use the command
SetVideoVerification
1.1.5a 15.03.2023 Add Description of new method ChangeClientId for persons and visitors
Update compatibility information matrix and version numbers