Execute an IAS Workflow

After completing configuration and sandbox validation, your organization can execute IAS workflows in production. IAS workflows follow a consistent sequence: identity verification, token validation, retrieval initiation, status monitoring, and result processing.

Step 1: Initiate Identity Verification

Begin by initiating identity verification with your approved Credential Service Provider (CSP).

Your system should:

Generate a correlation identifier for the transaction
Launch the CSP verification process
Capture the verification outcome and reference

Identity verification must meet required assurance levels before proceeding.

Step 2: Validate the IAS Token

After successful verification, validate the signed IAS token. Tokens are time-bound and must be used within their validity window.

Your system should:

Verify the token signature using the CSP JSON Web Key Set (JWKS) endpoint
Validate issuer (iss) and audience (aud) claims
Validate issuance (iat) and expiration (exp) claims
Ensure that demographic attributes in the token match the demographics stored in the tenant Patient resource

If token validation fails or demographic values do not match the stored Patient record, retrieval is rejected.

Step 3: Initiate Retrieval

Once a valid IAS token is available, initiate retrieval in two steps: find the locations that hold the patient’s records, then retrieve from the locations you choose. Locations are the organizations on TEFCA that hold patients’ records, not FHIR Location resources.

For both operations, you need:

The external_docs_retrieval scope
The Prefer: respond-async header
A QHIN query license for your organization and the IAS purpose of use (T-IAS)
A patient in your tenant who passed identity verification and isn’t deceased
The stored IAS identity token for the patient. Without it, $patient-qhin-locations and retrieval from IHE locations fail with a 403.

Find Locations

Call $patient-qhin-locations on the FHIR R4 Patient resource to get the TEFCA QHIN locations that hold records for the patient.

POST /fhir/R4/Patient/{id}/$patient-qhin-locations
Prefer: respond-async
Authorization: Bearer {access_token}

For each location, the response includes:

kind: fhir or ihe
hcid: The home community ID (HCID)
name: The location name
address and authMethod: For FHIR locations, the address and login method for the location

If a QHIN doesn’t respond or a location isn’t available, incomplete is true, and failedHcid lists the HCID for that QHIN. If no QHIN responds, the call fails with a 502. The response doesn’t include patient identifiers from the locations.

Retrieve from Selected Locations

Pass the locations you choose to $patient-retrieve-external-docs, with one location parameter for each location. Each location parameter includes:

hcid for every location
patientId and jwt for FHIR locations: the patient ID at that location and the access token from the patient login at that location

IHE locations don’t require a token. Send IHE locations with only the hcid, within 24 hours of the $patient-qhin-locations call. After 24 hours, the result for that location returns location-not-discovered.

POST /fhir/R4/Patient/{id}/$patient-retrieve-external-docs
Prefer: respond-async
Authorization: Bearer {access_token}
Content-Type: application/fhir+json

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "location",
      "part": [
        { "name": "hcid", "valueString": "{ihe_hcid}" }
      ]
    },
    {
      "name": "location",
      "part": [
        { "name": "hcid", "valueString": "{fhir_hcid}" },
        { "name": "patientId", "valueString": "{patient_id_at_location}" },
        { "name": "jwt", "valueString": "{access_token_from_patient_login}" }
      ]
    }
  ]
}

The response includes a separate result for each location, with:

status: ok or error
The number of documents found, imported, skipped, and failed
Whether the counts are partial, meaning Health Gorilla couldn’t query some patient identifiers at an IHE location
Whether more documents may remain at the location
For errors, a code and an error message

Retrieval from FHIR locations returns only current documents. When tokens fail at one location, other locations still return records. An empty or incomplete result doesn’t mean the patient has no other records.

Your system should:

Persist the locations and HCIDs that $patient-qhin-locations returns for correlation
Check the result for each location, not just the overall response
Persist identifiers that Health Gorilla returns for correlation

Retrieval processing begins asynchronously. Poll the URL in the Location header of the 202 response until the final response returns.

Step 4: Monitor Retrieval Status

IAS retrieval is asynchronous.

Your system must monitor retrieval status until a terminal state is reached.

Terminal states include:

completed
partial
failed

Do not consume results until a terminal state is reached. If status is partial or failed, review associated error details and determine whether retry or operational escalation is required.

For $patient-qhin-locations and $patient-retrieve-external-docs, poll the URL in the Location header of the 202 response until the final response returns, then check the status for each location. These operations don’t use the completed, partial, and failed states.

Step 5: Retrieve Results

After processing completes, retrieve results.

Your system should:

Retrieve results
Follow pagination instructions when applicable
Validate response integrity and completeness

Results include DocumentReference resources and may include Binary resources. Structured data is available only if document import is enabled, after documents are imported into your tenant, via standard FHIR R4 APIs.

Step 6: Persist and Process Data

After retrieval:

Persist required clinical data in your system
Retain provenance metadata as required for compliance
Do not persist IAS tokens beyond operational necessity
Do not reuse identity tokens beyond their validity window

Step 7: Audit and Correlation

For each IAS workflow execution, your system should:

Log correlation identifiers
Persist identifiers returned by Health Gorilla
Capture timestamps and final outcome status
Retain required audit metadata

Strong audit practices support traceability, operational review, and compliance requirements.

Common Failure Scenarios

Operational workflows may encounter:

Expired or invalid IAS identity tokens
Demographic mismatch between token and tenant Patient record
No matching records returned through exchange
Exchange timeouts or transient service disruptions

Your system should follow established operational procedures for each scenario and obtain a new valid IAS token when required.

Token Errors

When tokens that your system supplies fail at a FHIR location, the result for that location has a status of error and a code that gives the reason, which tells your system whether the patient needs to log in again. If tokens stop working after some documents import, the result stays ok, and failed counts the remaining documents.

Code: token-expired

Meaning: The token is past the expiration time.
What to do: Have the patient log in again to get a new token.

Code: token-invalid

Meaning: The location rejected the token.
What to do: Have the patient log in again to get a new token. If the error continues, confirm that the token came from that location.

Code: token-insufficient-access

Meaning: The token doesn’t grant access to the requested records.
What to do: Have the patient log in again at that location and grant the access that the request needs.

These codes replace the error message "The location rejected the supplied token.” If your code checks for that message, update it to check for these codes.