Install the AEOS Integration

Partisia installs the AEOS integration on your AEOS server over remote access. This page is the procedure we follow, so your IT can see what is done on the server and in AEOS. It sets up the service itself; each capability you use is then added from its own page.

Requirements

The network requirements for the capabilities you use are in place.
Remote access to the AEOS server with administrator rights, for example TeamViewer.
.NET Framework 4.8, present on Windows Server 2019 and later.
An AEOS user that can create user roles, application users and identifier types.

Run every command on this page in one PowerShell started as Administrator.

Prepare AEOS

Badge identifier type

Create it once per AEOS installation, before the SOAP user, under Administration → Maintenance → Identifier types → New (Danish UI: Administration → Vedligeholdelse → ID-nøgler → ID-nøgle typer → Ny):

Field	Danish UI	Value
Name	Navn	`VisitorPass`
Sub type	Under type	`3`
Identification type	Identifikation Type	`Hexadecimal`
Identifier length	ID-nøgle længde	`16`
Identifier minimum value	ID-nøgle minimum værdi	`1`
Identifier maximum value	ID-nøgle maksimum værdi	`ffffffffffffffffffffffffffffffff`
Customer code type	Kunde kode type	`Alpha numeric` (`Alfanumerisk`)
Customer code length	Kunde kode længde	`0`

The identification type cannot be changed after the type is created.

SOAP user

Create a user role and an application user for the integration. Nedap recommends one account per integration.

Open General → Maintain user role → New (Danish: Generelt → Vedligehold brugerrolle → Ny) and create the role VisitorPass integration. On its Functions tab, grant only:

Function (English UI) Danish UI

Administration, Integrations, AEOS Web-service, External calls Administration, Integration, AEOS Web-service, Eksterne kald

The page for each capability lists the further functions it needs.
On the role's Password restrictions tab (Danish: Kodeord restriktion), set Expiration days to 0. 0 means the password never expires; an expired password stops the integration.

Open General → Maintain user → New (Danish: Generelt → Vedligehold bruger → Ny) and create the user:

Field	Value
User name	`visitorpass`
Full name	`VisitorPass integration`
User role	`VisitorPass integration`
Change password at next login	Off
Disable account if not logged in for no. of days	`0`

The last field is Bloker konto hvis der ikke logges ind i antal dage in the Danish UI.

On the user's Identifier types tab (Danish: ID-nøgletyper), tick only VisitorPass. The user can only issue badges of the types ticked there.
The user name and password go in aeos.soapUser and aeos.soapPassword in server.json.

Install the service

Install JDK 21, unless it is already there. The Java runtime AEOS ships with, in C:\AEOS\jre, is an older version:

if (-not (Test-Path 'C:\Program Files\Eclipse Adoptium\jdk-21*')) {
  $ProgressPreference = 'SilentlyContinue'
  Invoke-WebRequest 'https://api.adoptium.net/v3/installer/latest/21/ga/windows/x64/jdk/hotspot/normal/eclipse' -OutFile "$env:TEMP\temurin-21.msi" -UseBasicParsing
  Start-Process msiexec.exe -Wait -ArgumentList '/i', "$env:TEMP\temurin-21.msi", '/qn'
}

Choose the JDK and the install folder for this session:

$env:JAVA_HOME = (Get-ChildItem 'C:\Program Files\Eclipse Adoptium\jdk-21*' | Sort-Object Name | Select-Object -Last 1).FullName
$dir = 'C:\visitorpass-aeos'

Download the bundle, with Partisia's read-only token for its package registry, which Partisia brings to the installation:

Partisia staff

PRODUCTION.md in the visitorpass-aeos-integration repository › Before the visit › Package token

$env:AEOS_PACKAGE_TOKEN = '<package-token>'
curl.exe --fail -L -H "PRIVATE-TOKEN: $env:AEOS_PACKAGE_TOKEN" -o "$env:TEMP\aeos-integration-winservice.zip" "https://gitlab.com/api/v4/projects/secata%2Fvisitorpass%2Fvisitorpass-aeos-integration/packages/generic/aeos-integration-winservice/latest/aeos-integration-winservice.zip"

Unpack it into the install folder and create the folder for keystores:

Expand-Archive "$env:TEMP\aeos-integration-winservice.zip" -DestinationPath $dir
New-Item -ItemType Directory "$dir\conf" | Out-Null
cd $dir

Find the host name on the certificate AEOS serves its SOAP API with, and note the Owner: CN= of the first certificate. It goes in aeos.soapUrl:
```
& "$env:JAVA_HOME\bin\keytool.exe" -printcert -sslserver localhost:8443
```

Build the truststore that lets the service trust the AEOS certificate authority:

$req = [Net.HttpWebRequest]::Create("https://localhost:8443/aeosws")
$req.ServerCertificateValidationCallback = { $true }
try { $req.GetResponse().Close() } catch {}
$chain = New-Object Security.Cryptography.X509Certificates.X509Chain
$chain.ChainPolicy.RevocationMode = 'NoCheck'
[void]$chain.Build([Security.Cryptography.X509Certificates.X509Certificate2]$req.ServicePoint.Certificate)
[IO.File]::WriteAllBytes("$dir\conf\aeos-ca.cer", $chain.ChainElements[1].Certificate.Export('Cert'))
& "$env:JAVA_HOME\bin\keytool.exe" -importcert -noprompt -alias aeos-ca -file conf\aeos-ca.cer -keystore conf\aeos-truststore.p12 -storetype PKCS12 -storepass '<truststore-password>'

Look up the id of the VisitorPass identifier type — the <Id> of the type named VisitorPass:

'<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:sch="http://www.nedap.com/aeosws/schema"><soapenv:Body><sch:IdentifierTypeSearchInfo/></soapenv:Body></soapenv:Envelope>' | curl.exe -s -k -u '<soap-user>:<soap-password>' -H 'Content-Type: text/xml; charset=utf-8' -H 'SOAPAction: ' --data-binary '@-' https://localhost:8443/aeosws

Look up the ids of the AEOS authorisation templates, the <Id> next to each <Name>. Visitor Provisioning and Credential Issued each name templates by id:

'<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:sch="http://www.nedap.com/aeosws/schema"><soapenv:Body><sch:TemplateSearchInfo><sch:TemplateInfo><sch:UnitOfAuthType>OnLine</sch:UnitOfAuthType></sch:TemplateInfo></sch:TemplateSearchInfo></soapenv:Body></soapenv:Envelope>' | curl.exe -s -k -u '<soap-user>:<soap-password>' -H 'Content-Type: text/xml; charset=utf-8' -H 'SOAPAction: ' --data-binary '@-' https://localhost:8443/aeosws

Write server.json as described in Configure the service:
```
notepad server.json
```
Install and start the service:
```
.\install-service.cmd
```

Configure the service

The service reads server.json in the install folder. Relative paths in it are resolved against that folder. This is the base configuration; the pages for Door Opening and Credential Issued add to it.

server.json

{
  "port": 8888, // (1)!
  "monitor": { // (2)!
    "enabled": false
  },
  "aeos": { // (3)!
    "soapUrl": "https://<aeos-certificate-host>:8443/aeosws", // (4)!
    "soapUser": "visitorpass", // (5)!
    "soapPassword": "<soap-password>",
    "identifierTypeId": <identifier-type-id>, // (6)!
    "soapTrustStore": "conf/aeos-truststore.p12", // (7)!
    "soapTrustStorePassword": "<truststore-password>"
  },
  "visitorPass": { // (8)!
    "baseUrl": "https://visitorpass.partisia.com"
  },
  "channel": { // (9)!
    "organizationId": "<organisation-id>",
    "secret": "<channel-secret>"
  },
  "webhook": { // (10)!
    "secret": "<webhook-secret>"
  },
  "database": { // (11)!
    "persistenceUnitName": "AeosIntegration",
    "driver": "org.hsqldb.jdbc.JDBCDriver",
    "url": "jdbc:hsqldb:file:./data/aeos-integration;shutdown=true;hsqldb.lock_file=false",
    "user": "SA",
    "password": ""
  }
}

The port the service listens on, on this server.

Used by: the health check in Start and verify, and by Credential Issued, where VisitorPass calls in on it.

Value: 8888, or another free port. Not 8443, which AEOS uses.
Detection of new people in AEOS.

Used by: Credential Issued only.

Value: false. The service needs the section even when the detection is off.
How the service reaches AEOS: its SOAP web service, on this server. Used by every capability.
The address of the AEOS SOAP web service.

Value: https://<host>:8443/aeosws, where <host> is the name on the AEOS certificate from step 5. Not localhost or an IP address: the certificate check fails on those.
The SOAP user from SOAP user, and the password you gave it.
The AEOS identifier type the service writes badges as.

Value: the id of the VisitorPass type, from step 7.
The truststore that makes the service trust the AEOS certificate.

Value: the file built in step 6, and the password you gave it there.
Where VisitorPass is. Used by every capability.

Value: https://visitorpass.partisia.com.

Credential Issued adds its invitation settings to this section.
The connection the service keeps open to VisitorPass: connection 2 in the network requirements. Everything VisitorPass sends to AEOS arrives over it.

Value: Partisia registers the installation with your organisation in VisitorPass: it generates the secret, VisitorPass keeps only a hash of it, and Partisia sends you organizationId, your organisation's id, and secret.
The secret VisitorPass signs its calls into the service with.

Used by: Credential Issued. The service needs the section even without it.

Value: without Credential Issued, nothing checks it and any value works. With it, the secret from Credential Issued.
The service's own state, kept in the data folder: what it has seen in AEOS and whom it has invited. Leave it as shown.

Partisia staff

PRODUCTION.md in the visitorpass-aeos-integration repository › Register the installation in VisitorPass for channel; Credential Issued › Subscribe to credential-issued events for webhook.secret

Start and verify

Check that the service is running:

.\servy\servy-cli.exe status --name visitorpass-aeos-integration

Check that it started and has connected to VisitorPass:

Select-String -Path logs\out.log -Pattern 'Listening on','Opened the channel'

Check that it answers on its port. The answer is 204:

curl.exe -s -o NUL -w '%{http_code}' http://localhost:8888/

The service logs a warning at startup that no tls is configured. Without Credential Issued that is expected.

What's Next

Visitor Provisioning: carriers for visitors registered in VisitorPass.
Door Opening: the AEpu door controllers and the doors.
Credential Issued: inviting employees and recording consent.
Operate the AEOS Integration: checking the service, restarting, upgrading and troubleshooting.