PACS Request Processing

• The Access Integration Service (AIS) works as a proxy between the client (API consumer) and the PACS Agent (which exposes the PACS functionality to the client through the integration service).

• To be able to provide reliable communication, an asynchronous processing model is used.

• Client requests are stored in the message queue, from which they are picked up by agents. Once an agent processes the request, the result is sent back and stored in another message queue from where it is picked up by clients.

Client-Side Request processing

1. The client sends a request through the integration service API.

2. Client request is stored in the request message queue.

3. Client receives response with address where to pick up request result from Agent/PACS (response with 202 HTTP status and Location header containing the result address)

   • The integration service has an internal mechanism for retries and automatically handles stored request lifecycles. So once a message has been successfully accepted, the client need not repeat the call unless it receives a final error response for the request.

4. Clients open requests to the received result address and wait until the result is provided.

   • Waiting is periodically interrupted by the platform to avoid connection timeout issues. In this case the client receives a response with 307 HTTP redirect status (i.e., common HTTP clients will transparently repeat the request and continue to wait).

   • In case the connection is interrupted by an unexpected error without receiving the result, the client is expected to open the connection again and continue to wait.

5. The client receives the result.

Agent-Side Request Processing

1. The agent opens a request to the integration service API to receive client PACS requests and waits until some PACS request appears.

   • Waiting is periodically interrupted by the platform to avoid connection timeout issues. In this case, the agent receives a response with a 307 HTTP redirect status (i.e., common HTTP clients will transparently repeat the request and continue to wait).

   • In case the connection is interrupted by an unexpected error without receiving a PACS request, the agent is expected to open the connection again and continue to wait.

2. The client receives the PACS request.

3. The request is forwarded to the PACS system.

   • The way the request is processed depends on the particular PACS and request type, ranging from REST API invocation to low-level integration through direct PACS database access.

4. Once the request is processed on the PACS system, the agent writes the result through the integration service API.

5. The result is stored in the result message queue.

6. The agent opens a request to the integration service API to receive the next client PACS request.

PACS Request Prioritization

PACS requests are processed by agents one by one in the order they appeared, but to provide reliable and secure functionality, there is additional prioritization based on operation type:

1. Batch changes have the lowest priority

   • Batch changes might take a long time to finish, so we need to be sure that it does not stall common usage of the API.

   • Each operation from the batch is run one by one (or by count, if allowed by the PACS system itself for single call) only if there are no other pending requests with higher priority.

2. Write operations (create, update, delete) have the highest priority

   • From a security perspective, it is important to be able to make access changes as fast as possible without waiting for the other operations to be finished.

3. Read operations have medium priority

   • They are not blocked by batch operations.

   • They cannot block write operations (e.g., revoking access by one user cannot be blocked by browsing the system UI by other users).

Message Lifecycle

• Both PACS request and response messages are persistently stored in message queues, ensuring messaging reliability in case of unexpected connection problems.

• AIS also provides a (configurable) mechanism to prevent queues from being blocked by undeliverable or stuck messages (see Advanced Tenant Configuration).

Request Message Lifecycle

Result Message Lifecycle

Batch Importing and Reconciling Data for Identities and Visits

When processing attributes, credentials, and accesses for a single entity at once, using the standard API may result in performance issues. This is caused by the need for properly chained requests, which introduce overhead. Furthermore, correct implementation of "upsert" (update existing or create new) can be slow, as it requires multiple chained operations. In cases where large numbers of entities must be imported simultaneously, this overhead can lead to significant performance challenges.

To address these scenarios, the AIS provides a dedicated endpoint that optimizes the required operations internally. This results in faster and more efficient request processing.

Processing Limits and Behavior

• A maximum of 100 entities may be submitted for processing in a single request.

• The first entity in the batch is processed with the highest (write) priority.

  • This ensures integrations involving combined updates of identities/visits, including credentials and accesses, can be completed within a single request.

• Remaining entities are processed with the lowest (batch) priority.

  • These operations are handled in the background, ensuring they do not block common API usage.

Example: Data Import Request

The data import endpoint allows all identity/visit-related data for multiple entities to be passed in a single request (as a list of nested documents):

• {URL} is the production environment of HIS: https://his.hidglobal.com/ais/v1

• {TENANT_ID} is user-chosen tenant identification, which must be globally unique.

• {PACS_ID} is the unique ID of the specific PACS in which you are assigning the access unit.

• {BATCH_ID} is the unique ID of a specific data import batch.

curl --request PUT \
  --url {URL}/tenant/{TENANT_ID}/pacs/{PACS_ID}/[identity|visit] \
  --header 'Authorization: Bearer {token}' \
  --header 'Content-Type: application/json' \
  --data '[
      {
        "externalId": "...",
        "removeUnlisted": false,
        "attributes": {
          "state": "active",
          "firstName": "...",
          "lastName": "...",
          "email": "...",
          "phoneNumber": "...",
          "picture": "...",
          "extensionFields": {
            "...": "..."
          }
        },
        "credentials": [
          {
            "state": "active",
            "format": "...",
            "cardId": "...",
            "facilityId": "...",
            "extensionFields": {
              "...": "..."
            }
          },
          {"...": "..."}
        ],
        "accessUnits": [
          {"accessUnitId":"..."},
          {"...":"..."}
        ],
        "pin": {
          "state": "active",
          "value": "",
          "extensionFields": {
              "...": "..."
          }
        }
      }

Each import document consists of the following sections:

• externalId

  • Mandatory, unique identification of identity/visit.

• removeUnlisted

  • Governs how credentials and access are handled.

  • If set to true, existing items not included in the import will be removed.

  • If set to false (default), only new items are created or matching items are updated. Existing items not included in the import remain unchanged.

• attributes

  • Mandatory if the identity/visit with the given externalId does not already exist (a new record will be created).

  • Optional for existing entities. If omitted, attributes are not changed.

  • If provided, attributes are set exactly as defined. Missing values are added, existing ones updated, and any extra attributes stored in PACS but not included in the document are removed.

  • Optionally it is possible to pass desired entity state. If not provided, entity state is unchanged (or default initial state in case of creation is used)

• credentials

  • Optional. If omitted, existing credentials remain unchanged.

  • If provided, credentials are updated according to the list. Non-existing credentials are created, existing ones are updated, and if removeUnlisted is true, credentials not included in the document are removed.

  • Optionally it is possible to pass desired credential state. If not provided, credential state is unchanged (or default initial state in case of creation is used)

• accessUnits

  • Optional. If omitted, existing accesses remain unchanged.

  • If provided, accesses are updated according to the list. Non-existing accesses are added, and if removeUnlisted is true, extra accesses not included in the document are removed.

• pin

  • Optional. If omitted, the PIN remains unchanged.

  • If set as an empty object, the PIN is deleted.

  • If defined with structure, the PIN is updated or created.

  • Optionally it is possible to pass desired PIN state. If not provided, PIN state is unchanged (or default initial state in case of creation is used)

Retrieving the Result

As with other asynchronous requests, the result is available at the address provided in the response to the data import request. By default, retrieving the result is non-blocking (consistent with other asynchronous requests) and provides the current processing state of the batch:

curl --request GET \
  --url {URL}/tenant/{TENANT_ID}/pacs/{PACS_ID}/[identity|visit]Batch/response/{BATCH_ID} \
  --header 'Authorization: Bearer {token}'

{
  "total": 100,
  "queued": 42,
  "running": 3,
  "succeeded": 50,
  "failed": 5,
  "results": [
    {
      "status": "succeeded"
      "id": "..."
    },
    {
      "status": "failed",
      "errorId": "...",
      "errorCode": "...",
      "errorMessage": "...",
      "id": "..." // in case of failure after externalId was resolved
    },
    {
      "status": "running"
    },
    {
      "status": "queued"
    }
  ]
}

Waiting for the Final Result

If the client prefers to wait for the final response without periodically checking the processing status (most useful for imports with only a single or a few items), this behavior can be enforced by including an additional query parameter in the result request:

curl --request GET \
  --url {URL}/tenant/{TENANT_ID}/pacs/{PACS_ID}/[identity|visit]Batch/response/{BATCH_ID}?wait=true \
  --header 'Authorization: Bearer {token}'