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

With Credential Issued, the service also answers 204 on /. The answer says the process is serving, not that AEOS, VisitorPass or the AEpus are reachable — those show in the log. Without Credential Issued the service listens on no port, and only the log shows it.

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
`Credential Issued is off - listening on no port`	Started	All but Credential Issued
`Listening on https://0.0.0.0:8888/`	Started and serving	Credential Issued
`Opened the channel to …`	Connected to VisitorPass	All
`Assigned badge … to carrier …`	Badge written to AEOS	Visitor Provisioning, Credential Issued
`Connected to AEpu …`	Connected to a door controller	Door Opening
`Emitting badge at AEpu …`	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

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>'
```
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
```

An upgrade can change the shape of server.json, and the service does not start with the earlier one. Partisia rewrites server.json with you before such an upgrade.

Partisia staff

PRODUCTION.md in the visitorpass-aeos-integration repository › Upgrade

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.

Stop the service:

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

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

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
`Unrecognized field "…"`	`server.json` has the shape of an earlier version, or a misspelt name. See Upgrade
`server.json has no '…'`	A section or a value the service needs is missing
`Failed to load webhook TLS keystore …`	`credentialIssued.keyStore` names a missing file, or `credentialIssued.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 `credentialIssued.port`. AEOS itself uses `8443`
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 `credentialIssued.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

Log says	Cause
`Outgoing: method=POST, path=webhooks/credential-issued, status=401`	`credentialIssued.webhookSecret` 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
`Could not connect to AEpu … retrying every 5000 ms`	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 on no AEpu in the readers the service holds. Check on the AEOS page that it is on an AEpu, and how the last send went
`Handling dip.readers failed`	The service refused the readers VisitorPass sent, as a whole, and keeps the readers it had. The lines after it say why
No `Connected to AEpu` line at all	VisitorPass has not sent the readers yet. Check that the AEOS page shows the integration connected, and how the last send went
Nothing	The request never arrived — see the connection to VisitorPass
`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.badgeIdentifierTypeId 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. A DipBri output is wired to another door than its label names. Wire each output to the door of its reader, in the order of the AEOS page.

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 `visitorPass.channelSecret` 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.

To check visitorPass.channelSecret, follow Check the secret an installation holds on the AEOS page in VisitorPass.