HIS Nedap AEOS Agent

Introduction

This document describes how to install, configure, and operate the Nedap AEOS PACS Agent for integration with the HID Integration Service (HIS / AIS).

Prerequisites

Required PACS

• Nedap AEOS

• AEOS SOAP API must be accessible from the agent

• For supported Nedap AEOS version, please see the HID Knowledge Base compatibility matrix: Requirements.

Configuration

PACS Configuration

Creating the Technical User

1. Open AEOS Web Administration

2. Create a new role with required permissions
   The technical user must have access to:

   • Employees

   • Visitors

   • Identifiers (Credentials)

   • Authorizable Carrier Groups

   • Free Fields

   • PIN management

   • Images (optional, if enabled)

3. Create a user and assign the role

4. Store credentials for agent configuration

Access Unit Setup

In AEOS, Access Units are represented as:

Authorizable Carrier Groups

Ensure:

• Required carrier groups exist

• They are used for assigning access to employees and visitors

Creating Technical Custom Fields

Refer to Extension Field Setup (Manual)

Required Fields

Default Validity Period for Carriers

A default validity period may be configured inside AEOS. If left unconfigured the validity period will not be set with an EndDate for either Visits or Identities.

Agent Configuration

General Startup

Step 1: Download

To obtain the pacs-agent_{pacs-name} Docker image, follow the HID Agent Administration Guide for End-Customer.

Step 2: Create environment

Create a file named .env with the following content:

Agent__TenantId=example-tenant-id
Agent__PacsId=example-pacs-id
Auth__ClientId=your-client-id
Auth__ClientSecret=your-client-secret

In case you are connecting to a different environment than HID production, you need to set the proper URLs:

Auth__AuthNProvider=https://auth.example.com
Agent__PlatformUrl=https://platform.example.com

Step 3: Run Docker image

docker run -d \
  --env-file .env \
  pacs-agent-{pacs-name}:latest

Step 4: Check that the Docker image is running

docker ps

Environment variables description

Related to HIS

• Agent__PlatformUrl: HID Integration Service URL (https://his.hidglobal.com/ais/v1).

  • This information is provided by HID. By default, this is set automatically to the production environment value and does not need to be set manually in most cases.

• Agent__TenantId: Tenant ID within HID Integration Service.

  • This information is provided by HID.

• Agent__PacsId: Unique ID assigned to the agent during registration.

  • This information is provided by HID.

  • If you registered your PACS on your own, this would be the ID you gave to the PACS.

Related to HID Authentication Service

• Auth__AuthNProvider: HID Authentication Service URL (https://auth-us.api.hidglobal.com/idp/t89d23e0b2445510399335/authn).

  • This information is provided by HID. By default, this is set automatically to the production environment value and does not need to be set manually in most cases.

• Auth__ClientId: Client ID obtained during registration.

  • This information is provided by HID.

• Auth__ClientSecret: Client secret obtained during registration.

  • This information is provided by HID.

Agent-specific configuration

All AEOS-related settings are configured under the Aeos section.

These can be provided via:

• Environment variables (Aeos__*) for Docker deployments

• appsettings.json ("Aeos": {}) for local development

Environment variables description:

Connection Settings

External ID Configuration

Notes

• These must match AEOS free field names exactly

• Fields must exist and be assigned to the API role

Extension Field Mapping

The agent requires explicit configuration of extension fields to map AEOS free fields to AIS data types.

Behavior:

• Only configured fields are processed

• Field names must exactly match AEOS free field names

• Fields must exist in AEOS and be assigned to the API role

Configuration:

"Aeos": {
  "IdentityExtensionFields": {
    "FieldName": "Type"
  },
  "VisitExtensionFields": {
    "FieldName": "Type"
  }
}

Example:

"Aeos": {
  "IdentityExtensionFields": {
    "Department": "String",
    "IsActive": "Boolean",
    "HireDate": "DateTime"
  },
  "VisitExtensionFields": {
    "Purpose": "String",
    "ExpectedArrival": "DateTime"
  }
}

Free Field Categories

Explanation. In AEOS:

• Free fields are grouped into categories

• Each category is assigned to a carrier type:

  • Employee (Identity)

  • Visitor (Visit)

These variables must reference the categories where the configured extension fields are defined.

Behavior Settings

Optional Features

SSL Configuration

1. Recommended (Secure):

2. Development Only (Not Recommended):

Agent-specific .env file part example:

Aeos__Url=https://aeos.example.com/soap
Aeos__UserName=api-user
Aeos__Password=secure-password

Aeos__IdentityExternalIdFieldName=ExternalId
Aeos__VisitExternalIdFieldName=ExternalId

Aeos__IdentityFreeFieldCategoryId=10
Aeos__VisitFreeFieldCategoryId=20

Aeos__DefaultActiveDays=30
Aeos__AccessUnitType=AuthorizableCarrierGroup

Aeos__EnablePictures=true
Aeos__EnableEvents=true

Aeos__IdentityExtensionFields__Department=String
Aeos__IdentityExtensionFields__IsActive=Boolean
Aeos__IdentityExtensionFields__HireDate=DateTime

Aeos__VisitExtensionFields__Purpose=String
Aeos__VisitExtensionFields__ExpectedArrival=DateTime

Agent-specific appsettings.json example:

{
  "Aeos": {
    "Url": "https://aeos.example.com/soap",
    "UserName": "api-user",
    "Password": "secure-password",

    "IdentityExternalIdFieldName": "ExternalId",
    "VisitExternalIdFieldName": "ExternalId",

    "IdentityFreeFieldCategoryId": 10,
    "VisitFreeFieldCategoryId": 20,

    "DefaultActiveDays": 30,
    "AccessUnitType": "AuthorizableCarrierGroup",

    "EnablePictures": true,
    "EnableEvents": true,

    "IdentityExtensionFields": {
      "Department": "String"
    },
    "VisitExtensionFields": {
      "Purpose": "String"
    }
  }
}

Limitations

General limitations

• Extension fields must be created manually in AEOS

• Identifier Types must exist before use

• Extension fields are not supported on:

  • PINs

  • Credentials

Unsupported Operations

N/A

Limited Operations

The proper behavior could not be confirmed for all visit-related operations. There is a chance that access is not being propagated to the control panels.

Naming Mapping

Entities

Operations

Creation of Extension Fields

Supported Entities and Data Types

Manual for Creating an EF in the PACS

Identity

1. Open AEOS Administration

2. In the Menu on the left, navigate to Maintenance > Free Fields

3. Create or select category assigned to Employee

4. Create field:

   • Name: ExternalId

   • Type: String

5. Save

6. Assign to API role

7. Record:

   • DefinitionId

   • Name

Creation:

Assignment:

Read/Write to Employee:

Read only to Person:

Read/Write to Contact person:

Visit

1. Open AEOS Administration

2. Navigate to Free Fields

3. Create or select category assigned to Visitor

4. Create field:

   • Name: ExternalId

   • Type: String

5. Save

6. Assign to API role

7. Record:

   • DefinitionId

   • Name

Creation:

Assignment:

Read/Write to Visitor:

Read Only to Person:

Miscellaneous

Credential Model

A credential in AEOS is uniquely identified by:

Card Number + Identifier Type (Format)

Implication

• The same card number may exist in different formats

• Both values are required for correct identification

Identifier Types

Identifier Types (Card Formats):

• Must exist in AEOS before use

• Are not created by the agent

Examples:

• MIFARE

• DESFire

• Wiegand

Events

• Event forwarding depends on configuration

• When enabled:

  • AEOS events are sent to HIS