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

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

Limitations

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. (SwiftConnect API cannot provide the required combined filtering semantics.)

  • The total number of results is not available.

ListIdentities

  • The modifiedSince filter parameter does not work. (SwiftConnect API cannot provide the required combined filtering semantics.)

  • The total number of results is not available.

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.

Other 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).

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

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 (Hirsch Velocity)

Boolean

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

Integer

Text (emulated)

String

Text (emulated)

Decimal

Text (emulated)

DateTime

Text (emulated)

Events

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

Miscellaneous

N/A