User Documentation
User Documentation
Breadcrumbs

HIS SwiftConnect Agent

Introduction

The HIS SwiftConnect Agent connects the HID Integration Service (HIS/AIS) with the SwiftConnect partner API.

SwiftConnect does not have a GUI; it exposes only an API.

Prerequisites

Required Software and service access

  1. A SwiftConnect tenant with partner API access enabled for the integration.

  2. Technical profile (Created by SwiftConnect)

  3. Network reachability from the agent host to the HIS platform and HID Authentication Service, and to the SwiftConnect URL configured for the agent.

Configuration

PACS Configuration

N/A. No extension fields have to be created in SwiftConnect, see Creation of extension fields.

Agent Configuration

General Agent Startup

{pacs-name} = swiftconnect

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

  • Adjust all file parameters according to your setup.

  • It is recommended to store this configuration on an encrypted drive or delete .env file as soon as the Docker image is executed.

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

  • 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.

  • 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.

Don't forget to replace the {pacs-name} placeholders with the actual name of the pact agent.

Payload logging (optional, diagnostic)

  • Agent__PayloadLogEnabled - set to true to log the HTTP request/response payloads exchanged with the Velocity REST API (for troubleshooting). Default false.

  • Agent__PayloadLogPlaintext - set to true to log payloads unmasked. Default false (masked). Payloads may contain personal data - keep disabled unless needed.

Agent-specific configuration

Setting

Description

Required

SwiftConnect__Url

Absolute SwiftConnect API base URL. (for example, http://10.x.x.x:8080/).

Yes

SwiftConnect__Email

Email address of the dedicated SwiftConnect partner API technical user (profile).

Yes

SwiftConnect__Password

Password of the dedicated SwiftConnect partner API technical user.

Yes

SwiftConnect__ExposeMobileFormat

If true, exposes the Mobile credential format.

Default: true. If false, only the Implicit format is exposed.

No

SwiftConnect__TimeZone

Time zone used to interpret date-time values that have no time zone designator, for example the credential Activate and Deactivate extension fields. It must be a time zone ID known to the host operating system (for example UTC or Europe/Prague). Values with a Z designator or a UTC offset are converted to UTC as given.

Default: UTC. An invalid ID prevents the agent from starting.

No

SwiftConnect__EpiNameCacheTtl

Time in seconds for which access level names (EPI names) are cached in memory. The value is read at agent startup, so a change requires an agent restart. 0 disables the cache (every lookup reloads all access levels).

Default: 3600.

No
Example of an agent-specific .env file 
SwiftConnect__Url=https://api.<environment>.swiftconnect.io/
SwiftConnect__Email=<technical-user-email>
SwiftConnect__Password=<technical-user-password>
SwiftConnect__ExposeMobileFormat=true
SwiftConnect__TimeZone=UTC
SwiftConnect__EpiNameCacheTtl=3600

Limitations

  • Extension-field serialization: External extension values are converted to strings before being sent to SwiftConnect custom_fields. See section 6 for entity support and mappings.

  • Minimal photo size: Photo dimensions must be at least 480x480 pixels.

  • Unable to delete technical profile - The agent refuses to remove a profile when an email equals the configured SwiftConnect technical-user email (SwiftConnect__Email).

Unsupported operations

AIS operation / behavior

Note

GetIdentityPin / GetVisitPin

Unsupported-operation by SwiftConnect.

ActivateIdentityPin / DeactivateIdentityPin
&
ActivateVisitPin / DeactivateVisitPin

Unsupported-operation by SwiftConnect.

EventsCollect

Unsupported operation.

ExternalEventsPush

Unsupported operation.

Limited operation

AIS endpoint / operation

Note

ListVisits

  • The modifiedSince filter parameter does not work.

  • The total number of results is not available.

ListIdentities

  • The modifiedSince filter parameter does not work.

  • The total number of results is not available.

CreateIdentity / CreateVisit

  • If the photo upload fails during creation, the newly created profile is deleted and the operation fails.

CreateIdentityCredentials / CreateVisitCredentials

  • If a credential is created with format mobile, the credential is not assigned to the identity/visit immediately. Instead, the mobile_eligible flag of the affected identity/visitor is set to true and SwiftConnect begins issuing the mobile credential.

  • Once SwiftConnect prepares the mobile credential links, the links are appended to the wpp_apple_web_link and wpp_google_web_link extension fields of the identity/visit.

  • When the user opens the link and adds the mobile credential to their Apple or Google wallet, the credential attaches to the identity/visit and becomes visible through standard getCredential HIS operations.

Naming Mapping

Entities

AIS entity name

SwiftConnect term

Identity

Profile with profile_type=employee

Visit

Profile with profile_type=visitor

Credential

Credential

Card format

Credential class; Implicit is the default and Mobile is optional

Access unit

Access level

Extension field

Entry in the profile or credential custom_fields object

PIN

Profile pin field

Picture

Profile photo

Operations

AIS operation

SwiftConnect behavior

Activate Identity

PATCH profile active=true

Deactivate Identity

PATCH profile active=false

Check-In Visit

PATCH visitor profile active=true

Check-Out Visit

PATCH visitor profile active=false

Activate/Deactivate Credential

Call the credential activate/deactivate action

Assign Access Unit

Create a profile access-level assignment

Remove Access Unit

Delete the profile access-level assignment

Creation of extension fields

Manual for Creating an EF in the PACS

SwiftConnect doesn’t support defining extension fields on the platform. Instead, users can send arbitrary key-value (string, string) pairs as extension fields on any record. Therefore each record can include an unlimited number of extension fields, limited to the string data type.

To use these SwiftConnect extension fields, perform the standard HIS mapping and set the Path value to any name prefixed with $.ext (for example, $.ext.test).

Agent-defined extension fields

In addition to the free-form $.ext fields, the agent provides extension fields with the path prefix $.self. They are not stored as custom fields; each one is mapped to a SwiftConnect property. Map them using the standard HIS mapping and set the Path value as shown below.

Path

Entity

Type

Description

$.self.ConnectedSystems

Identity, Visit

String

Partner API systems connected to the profile. JSON array of system IDs, for example ["id1","id2"]. The system IDs are listed in the PACS details (see PACS details).

$.self.ConnectedSystems

Credential

String

Partner API systems connected to the credential. JSON object mapping the system ID to its status (active or inactive), for example {"<systemId>":"active"}. The credential is reported as active when at least one system is active; when no systems are present, the credential's own status is used.

$.self.MaxUses

Credential

Integer

Maximum number of uses of the credential. The value -1, an empty value, or a non-numeric value removes the limit. Not applicable to the Mobile format, for which the agent does not create the credential.

$.self.Activate

Credential

DateTime

Date and time from which the credential is valid. An empty value clears the date. A value without a time zone is interpreted in the time zone set by SwiftConnect__TimeZone. The value is sent to SwiftConnect in UTC.

$.self.Deactivate

Credential

DateTime

Date and time until which the credential is valid. Same rules as $.self.Activate.

  • An empty ConnectedSystems value sends an empty list (identity, visit) or an empty object (credential). A value that is not valid JSON is rejected.

  • New credentials are created inactive in SwiftConnect and are activated afterwards when the requested state is active.

  • The fields are also reported when identities, visits, and their credentials are read.

Supported entities and data types

List of Entities Supporting Extension Fields (Relevant to AIS)

Entity

Supports Extension Fields

Identity

Yes

Visit

Yes

Credential

Yes

PIN

No

Access Unit

No

List of Supported Data Types for Extension Fields

Variable type (AIS)

Variable type (SwiftConnect)

Boolean

Text (emulated as "true" / "false")

Integer

Text (emulated)

String

Text (emulated)

Decimal

Text (emulated)

DateTime

Text (emulated)

Known Issues

N/A

Miscellaneous

PACS details (Partner API systems)

The PACS details reported by the agent contain the vendor SwiftConnect, the access unit type Access Level, and the metadata entry systems. It lists the Partner API systems available to the technical user as pairs of id and name. Use these system IDs in the $.self.ConnectedSystems extension field.

Events

This agent does not subscribe to, emit, or write external PACS events. There is no SwiftConnect-specific event payload structure to configure.

FAQ

N/A