Integration

To integrate SmartFace and Nedap Aeos together, some steps are needed on the Aeos server, each Aeos AEpu used that will work with cameras and on the SmartFace server. All of these changes can be used within your project or within the Sample project.

Supported version#

SmartFace integration supports Aeos version AEOS 2023.2.6 and newer.

Aoes Configuration#

Changes necessary for the Aeos server are as below:

• Enabling Webservices
• Creating new Identifiers
• Creating new Free Fields
• Setup User Roles

Enabling Webservices#

With the Aeos SOAP WebService, third parties can receive and change data in Aeos with SOAP calls. This includes the SmartFace.

Once the Aeos Server is installed you need to access https://server-hostname:8443 to access the Aeos server, as the Aeos prefers to work with the hostnames instead of ip addresses. The default user is admin with default password aeosrules. This password needs to be changed to a custom one to be able to start using the Aeos.

Set up the AEOS to allow SOAP connections

1. During the Aeos software installation (setup), select SOAP WebService in the “Select the desired options for the AEOS” application window.

   If the AEOS is already installed, just run the setup again and don’t change any settings except the selection of the SOAP WebService.

   NOTE: From AEOS 2023.1, all options (including SOAP) are installed by default and are only activated as necessary. You do not have to select SOAP during the setup anymore.

2. In AEOS, enable SOAP in the system properties.
   a) Go to Administration > Maintenance > Settings > System properties
   b) Select the SOAP WebService checkbox (44.15).
   c) Click OK.
   d) Restart the AEOS application server service .

Allow AEOS to SmartFace sync port 8443
You need to ensure the firewall rule enables the port 8443 from and to the AEOS server on the Windows firewall to ensure the communication is possible. Once enabled you can test out the connection using the telnet command on the linux environment:

telnet 192.168.17.10 8443

where 192.168.17.10 is the IP Address of the AEOS server.

Create or modify system users in AEOS to handle SOAP calls
The program that sends SOAP calls to AEOS (such as the SmartFace integration), needs to ‘log in’ to AEOS as a system user in order to have the rights to access or change information there.

For this reason, you need to create one or more system users in AEOS and give these users a user role with the correct authorities to ‘access the correct menu options’ from within AEOS.

1. Log in to AEOS.
2. Go to Management > System users > Maintain user role
3. Create a user role (or edit an existing one) for the SOAP client, and select at least these functions:

• Administration, Integrations, AEOS WebService, External calls
• Person, Employee, * - all functions starting with Person, Employee

The first function is necessary to make WebService calls. The other functions allow find/add/update/delete actions on contractors, employees, visitors and/or cars.

NOTE: See also Required user role functions for each SOAP call.

3. If necessary, define an Entrance filter to restrict the entrances that can be seen, changed, deleted, or used for carrier authorization by the SOAP client.
4. Create or modify system users for use with the SOAP client.

• If you will use only one system user for the SOAP client, create this user and assign them the correct user role and any filters you may have defined.
• If people will log in with their own system user account through SOAP, add the correct functions and filters to their existing user role.

Creating new Free Fields#

The Free Fields are used as custom fields, to add additional SmartFace integration related data without disturbing any existing installation.

We need to add new Free Fields into our employees: BiometricEnrollmentStatus, SmartFaceKeepUser and SmartFaceId. The names used for the Free Fields are customizable in the sense that you can set them up in the .env.aeos to match the AEOS setup. Unless needed, use the default names.

Add new Free Field Category#

1. Click on Administration in the top AEOS menu, then the Maintenance > Free fields > Free field categories.
2. Create a Free field category called SmartFaceFields

Add Free Fields#

For each Free Field:

1. Open Maintenance > Free fields > Free fields
2. Click New
3. Define the Free Field
4. Click OK

The new Free Field’s name must match AeosSync__Aeos__Integration__Freefield value in the docker configuration in the .env.aeossync environmental variables file. If you are using the default values, use values as below:

SmartFaceKeepUser#

SmartFaceId#

BiometricEnrollmentStatus#

Asign Free Fields to User Roles#

Once the free fields are set, you need to allow them for each user role.

1. Go to Management > System users > Maintain user role > Configuration
2. Open each role.
3. Click on the Configuration tab within the user role.
4. Ensure the newly created Free Fields are added and enabled to a user as seen below:

Creating new Identifiers#

We will add new identifier to server as “SmartFace Badges” for the virtual IPBadge component. Each person to use the SmartFace Facial Recognition needs to have such badge. The badges will be managed by the Aeos Sync component of the SmartFace, we need to define such identifier first.

1. Open Administration > Maintenance > Identifiers > Identifier types
2. Choose Generic type and click New
3. Define the identifier as below

The new Identifiers name must match AeosSync__Aeos__Integration__Identifier value in the .env.aeossync docker configuration. Use default values as below:

Do not forget to log out and log in to reload the new Identifiers and Freefields configuration.

Creating new users#

To create a new user compatible with the SmartFace Facial Recognition, the Employee needs to have at least these attributes below:

AEpu Configuration#

To configure your project to be compatible with the SmartFace you need to add IP Badges that serve as input points for the SmartFace in your project setup.

Adding IP Badges#

Virtual IP Badges serve as connection point between the Aeos and SmartFace. SmartFace uses them to trigger Nedap workflows.

In the Aeos Aemon open the diagram of your AEpu. From the Miscellaneous, pick up the IP Badge and add it into the project. Connect components so the IP Badge is a badge input within your project.

Configure it using the Generic Badge and note the Listening port. In our sample project we will use the ports 11020 and 11021. Each camera should be mapped to one IP Badge using a distinct port.

SmartFace Server#

Please see below steps needed within the SmartFace system. These changes are already set within the sample project.

• Adding Aeos Connector
• Adding Aeos Sync

Aeos Connector#

Aeos Connector is a module used on top of the SmartFace that provides communication between the SmartFace and the Aeos and its AEpus. If a person is identified by a camera and the access is granted based on the SmartFace configuration (Access Controller) then a signal is sent into the IPBadge within an AEpu mapped to the camera. Based on the Aeos configuration the door/locker/turnstile is opened/unlocked the access is denied.

Add Aeos Connector to SmartFace#

To add the Aeos Connector into the SmartFace, update the main docker-compose.yml file by adding the new service:

  aeos-aepuconnector:
    image: ${REGISTRY}integrations-aepuconnector:latest
    container_name: SFAeosAepuConnector
    restart: unless-stopped
    env_file: .env.aeosaepu

Enable the changes by applying the docker compose up -d command.

NOTE: in the package provided for the sample project it is already set

AEpu mapping#

Part of the package is the Aeos Connector that serves as a connector between the SmartFace and a physical device - the AEpu. Each camera used for Facial Recognition with the Nedap Aeos needs to be mapped within the .env.aeosaepu docker environment variables file. If such file does not exists yet within the same folder where is the docker-compose.yml, create the file.

NOTE: in the package provided for the sample project it is already set

Sample file would look like below:

AccessController__Schema=http
AccessController__Host=192.168.17.11
AccessController__Port=5050

AEpuMapping__0__StreamId=6b7b8f5c-6c28-4ccb-1b9e-08db2952c2b7
AEpuMapping__0__AepuHostname=aepu.aeos.com
AEpuMapping__0__AepuPort=11020

AEpuMapping__1__StreamId=f9de3d6b-8f98-4bef-13bb-08db0aa598ba
AEpuMapping__1__AepuHostname=aepu.aeos.com
AEpuMapping__1__AepuPort=11021

AccessController__Schema
This is the schema used for communication with the Access Controller, please keep the default value http

AccessController__Host
This is the ip address of the machine where the Access Controller is running, in a common or default installation it is the same as the SmartFace Platform’s host machine. In the sample project it is 192.168.17.11.

AccessController__Port
This is the port used to communicate with the Access Controller. You can use the default value 5050.

Each line starts like this, using camera index, starting at 0: AEpuMapping__0__. For each camera a new mapping is added, incrementing the index, replacing the X, such as __0__,__1__ etc. Each mapping has the fields below:

Apply any changes by using the command docker compose up -d within the package directory.

Aeos Sync#

Aeos Sync is a module used on top of the SmartFace that provides synchronization between the database of users in the Nedap Aeos and the Watchlist Members in the SmartFace.

Add Aeos Sync to SmartFace#

To add the Aeos Sync into the SmartFace, update the main docker-compose.yml file by adding the new service:

  AeosSync:
    image: ${REGISTRY}integrations-AeosSync:latest
    container_name: SFAeosSync
    restart: unless-stopped
    env_file: .env.aeos

Enable the changes by applying the docker compose up -d command.

NOTE: in the package provided for the sample project it is already set

Sync configuration#

The synchronization can be configured and it has several parameters that can be updated. To configure them, update the .env.aeossync docker environment variables file.

NOTE: in the package provided for the sample project it is already set

The SmartFace integration allows for 2 different ways:
A. The AEOS is the source of truth
B. The SmartFace is the source of truth

For complex Nedap Aeos projects we use the type A, where the AEOS is the source of truth.

Sample file would look like below:

Serilog__MinimumLevel__Default=Warning
AeosSync__DataSource=AEOS
AeosSync__SyncPeriodMs=60000
AeosSync__SmartFace__FirstNameOrder=first
AeosSync__SmartFace__RestApi__ServerUrl=http://<smartface-ip-address>:8098
AeosSync__SmartFace__RestApi__PageSize=100
AeosSync__SmartFace__GraphQL__ServerUrl=http://<smartface-ip-address>:8097/graphql
AeosSync__SmartFace__GraphQL__PageSize=100
AeosSync__SmartFace__Import__Watchlist=innovatrics
AeosSync__SmartFace__Import__DefaultThreshold=40
AeosSync__SmartFace__Import__FaceDetectorConfig__MaxFaces=1
AeosSync__SmartFace__Import__FaceDetectorConfig__MaxFaceSize=600
AeosSync__SmartFace__Import__FaceDetectorConfig__MinFaceSize=30
AeosSync__SmartFace__Import__FaceDetectorConfig__ConfidenceThreshold=400
AeosSync__SmartFace__Import__KeepAutoLearnPhotos=false
AeosSync__Aeos__Server__Wdsl=https://<aeos-ip-address>:8443/aeosws?wsdl
AeosSync__Aeos__Server__PageSize=100
AeosSync__Aeos__Server__User=<aeos-user>
AeosSync__Aeos__Server__Pass=<aeos-password>
AeosSync__Aeos__Integration__Freefield=SmartFaceId
AeosSync__Aeos__Integration__Identifier=SmartFaceBadge
AeosSync__Aeos__Integration__SmartFaceKeepUser=SmartFaceKeepUser
AeosSync__Aeos__Integration__BiometricEnrollmentStatus=BiometricEnrollmentStatus
AeosSync__Aeos__NoImageWarningNotification=false
AeosSync__Aeos__AutoBiometryEnablement=true
AeosSync__Aeos__AutoBiometryPrefix=inno_
AeosSync__Aeos__KeepPhotoUpToDate=true

Terms used:
<smartface-ip-address> - the IP address of the SmartFace Platform server
<aeos-ip-address> - the IP address of the Nedap Aeos server
<aeos-user> - the user used for the AEOS API
<aeos-password> - the password used for the AEOS API

Please see the tables below for further description. They are organized by the prefixes:

AeosSync__#

AeosSync__SmartFace__#

AeosSync__SmartFace__Import__#

AeosSync__Aeos__Server__#

AeosSync__Aeos__Integration__#

AeosSync__Aeos__#

Additional configuration#

Once the SmartFace and Aeos integration is configured additional options are available. This includes for example the Liveness / Spoof checks and specific Access Controller configuration. For more information read the specific sections of the documentation.

Sample Project#

Here is sample project with lower complexity showing you how to setup 1 door entrance with 2 SmartFace Edge cameras and card readers for both entrance and exit. A more complex projects generally expect additional setup from the Nedap Aeos' side. If the project grows in size, more cameras need to be mapped to additional IPBadges.

Before you start with this project ensure you went through the integration steps and you have both Nedap Aeos and Innovatrics SmartFace installed and ready to be used.

AEpu setup#

Setup you AEpu, define it’s hostname to aepu.aeos.com if using the Nedap Integration Package. Open AEMON and connect to the AEpu. Follow the steps below to set up the AEpu. You can also download existing configuration from the AEpu project configuration file.

Project overview

Please add the components as per table below.

IP Badges
Set Badge device type as Generic Badge

Click on ... next to the Generic Badge and set listening port 11020 for the Entrance and 11021 for the Exit.

Entrance setting

Entrance port

Exit setting

Exit port

2Readers

Aeos setup#

Create Entrance#

We need to create the entrance in the AEOS system.

1. Navigate to Configuration > Maintenance > Entrances
2. Click New

3. Fill out the Name and click on the Add access points

4. Click Search, choose the Doors entrance.
5. Click Ok, confirm Ok again

Add an Employee#

Add employees for your project. The easiest way to achieve this, anounce an employee at Person > Employee > Announce.

Add First name and Last name. Add a suitable photo. Click OK to finalize the creation of the profile.

Add Entrance to Employee#

To enable the sample demo project setup working with the doors, you need to add the doors to a user profile.

SmartFace setup#

If you have followed all the steps from the guide, and you are using the Nedap Integration Package, you are all set up for the Sample project.

How to use the Aeos Integration Package#

When the package is set, up and running you can approach the door and camera, the door is opened and you can seamlessly enter the door as long as you are enrolled into a Watchlist that is synced with the Edge cameras.