Operate the AEOS Integration

How to check, restart, upgrade and troubleshoot the AEOS integration on your AEOS server. The commands assume a PowerShell started as Administrator, in the install folder:

cd C:\visitorpass-aeos

Is it running?

The service is a Windows service named visitorpass-aeos-integration. In Services (services.msc) it is shown as VisitorPass AEOS Integration.

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

The service answers 204 on / whenever it is up. The answer says the process is serving, not that AEOS, VisitorPass or the AEpus are reachable — those show in the log.

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

With Credential Issued the service serves HTTPS instead:

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

Logs

File	Holds
logs\out.log	everything the service logs, warnings and errors included
logs\err.log	output the Java runtime writes outside the log

Follow the log as it is written:

Get-Content logs\out.log -Tail 50 -Wait

Show only warnings and errors:

Select-String -Path logs\out.log -Pattern ' WARN ',' ERROR ' | Select-Object -Last 50

What a healthy service logs

Log line	Means	Capability
Listening on http://0.0.0.0:8888/	Started and serving	All
Opened the channel to …	Connected to VisitorPass	All
Assigned badge … to carrier …	Badge written to AEOS	Visitor Provisioning, Credential Issued
Connected to AEpu … at …	Connected to a door controller	Door Opening
Emitting badge at AEpu … readerId=…	A door was asked to open	Door Opening
Initiated issuance for worker objectid … as invitation …	A new person was found in AEOS and invited	Credential Issued
Set gdpr_consent=true for employee id …	Consent written to AEOS	Credential Issued

A quiet log is normal: a check of AEOS that finds nobody new logs nothing.

Every call to the service also logs an Incoming: and an Outgoing: line with its path and the status it was answered with.

Start, stop and restart

Restart the service:

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

Stop and start it:

.\servy\servy-cli.exe stop --name visitorpass-aeos-integration
.\servy\servy-cli.exe start --name visitorpass-aeos-integration

Starting, stopping and restarting from Services works the same way.

The service starts with Windows. When it stops on an error, Servy restarts it, up to five times.

A restart is safe at any time. The service resumes where it left off in AEOS, and VisitorPass retries the calls it could not deliver while the service was down. A door cannot be opened from a phone while the service is stopped.

Upgrade

1. Set Partisia's read-only token for its package registry, which Partisia brings to the upgrade:

   Partisia staff

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

   $env:AEOS_PACKAGE_TOKEN = '<package-token>'
   

2. Run the installer. It stops the service, replaces the program with the newest version and starts it again. server.json, conf\ and data\ are kept:

   .\install-service.cmd
   

To install a specific version instead of the newest, set it before step 2:

$env:AEOS_PACKAGE_VERSION = '<version>'

Back up

The service keeps its state in data\. With Credential Issued that is how far it has read in AEOS and whom it has invited. A service started without data\ reads AEOS afresh from that moment: nobody is invited again until they are changed in AEOS, and then a person who was invited but has not yet accepted gets a second invitation. Someone who accepts an invitation sent before then is ignored, and their consent is never recorded in AEOS.

1. Stop the service:

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

2. Copy the state, the configuration and the keystores:

   $to = "D:\backup\visitorpass-aeos-$(Get-Date -Format yyyyMMdd)"
   New-Item -ItemType Directory $to | Out-Null
   Copy-Item -Recurse data, conf, server.json $to
   

3. Start the service:

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

server.json and conf\ hold passwords and keys. Store the backup accordingly.

Uninstall

.\uninstall-service.cmd

This removes the Windows service. The install folder, with its log, configuration and state, is left in place.

Troubleshooting

The service does not start, or keeps restarting

Look for Exception during server configuration. in logs\out.log. The lines after it name the cause.

Log says	Cause
Failed to load webhook TLS keystore …	tls.keyStore names a missing file, or tls.keyStorePassword is wrong
Failed to load AEOS SOAP truststore …	aeos.soapTrustStore names a missing file, or its password is wrong
Address already in use or BindException	Another program holds port. AEOS itself uses 8443
Duplicate AEpu in configuration or Duplicate readerId	An AEpu or a readerId appears twice in dip.aepus
A JSON parse error	server.json is not valid JSON

Windows gives up after five restarts. Correct server.json and start the service again.

Visitor Provisioning: a visitor has no carrier in AEOS

Log says	Cause
Handling carrier.ensure failed	AEOS refused the carrier. The lines after it hold the AEOS response
AEOS SOAP … failed: HTTP …	The SOAP user lacks the rights to add or change visitors, or a template does not exist
Nothing	The request never arrived — see the connection to VisitorPass

Credential Issued: new people are not invited

Log says	Cause
Nothing	The person existed before the service was first started, or has not been changed since
Worker objectid … has no email address; not inviting	The person has no email address in AEOS
Worker objectid … holds none of the required authorization templates …	The person holds none of monitor.requiredTemplateIds
Failed to invite worker objectid …; skipping	VisitorPass refused or could not be reached. The lines after it say which
AEOS SOAP … failed: HTTP …	AEOS refused the call; the response body follows
Unexpected error followed by SSLHandshakeException or certificate	aeos.soapUrl does not use the host name on the AEOS certificate, or the truststore lacks the AEOS certificate authority

A person whose invitation failed is not retried on its own. Changing the person in AEOS — for example correcting their email address — makes the service pick them up again. If invitations failed because VisitorPass could not be reached, contact Partisia.

Partisia staff

PRODUCTION.md in the visitorpass-aeos-integration repository › Credential Issued › Recover skipped workers

Credential Issued: consent is not written back to AEOS

Log says	Cause
Outgoing: method=POST, path=webhooks/credential-issued, status=401	webhook.secret does not match the secret VisitorPass signs with
No Incoming: … path=webhooks/credential-issued line at all	VisitorPass cannot reach the service — check connection 3 in the network requirements
No worker holds invitation …; ignoring callback	The invitation was not sent by this installation
AEOS SOAP changeEmployee failed: HTTP …	The SOAP user cannot write gdpr_consent — check its role

Door Opening: a door does not open

Log says	Cause
Failed to connect to AEpu … retrying in 5000ms	The AEpu cannot be reached on its port, or its GenericDeviceInterface is not deployed
DIP reader loop for AEpu … failed; closing connection	The connection to the AEpu dropped. The service reconnects every 5 seconds
Handling dip.badge failed … Not connected to the AEpu	As above
Handling dip.badge failed … Unknown readerId	The reader is not listed in dip.aepus
Nothing	dip is missing, or dip.enabled is false
Emitting badge at AEpu …, but the door stays closed	AEOS refused the badge — see below

When AEOS refuses the badge:

• Refused at every door. The VisitorPass identifier type is missing, or aeos.identifierTypeId names a different one.
• Refused at one door. That door lacks its identifier type entry, or its data type filter is not ffff.
• Physical cards stopped working at a door. The door's VisitorPass identifier type entry lacks the ffff data type filter.
• The wrong door opens. The order of a readers list in dip.aepus changed.

The service connects but no DipBri block appears in AEmon, or it appears and badges never arrive: check that the device channel address 00000001 is enabled and that the message syntax version is 0, then deploy the configuration again.

The connection to VisitorPass drops

Log says	Cause
Could not open the channel to …	Outbound HTTPS to VisitorPass is blocked, or channel.secret is wrong
The channel to … stopped answering pings; reopening it	The connection was cut, often by a firewall closing idle connections

The service reopens the connection by itself.