8. Search Encounters in Oracle Health

package gov.va.mobile.fhirstarter.v1.client;

import ca.uhn.fhir.rest.client.api.IClientInterceptor;
import ca.uhn.fhir.rest.client.api.IHttpRequest;
import ca.uhn.fhir.rest.client.api.IHttpResponse;
import com.fasterxml.jackson.annotation.JsonProperty;
import gov.va.mobile.fhirstarter.v1.AppProperties;
import org.springframework.http.HttpHeaders;
import org.springframework.http.MediaType;
import org.springframework.util.LinkedMultiValueMap;
import org.springframework.util.MultiValueMap;
import org.springframework.web.client.RestClient;
import org.springframework.web.client.RestClientException;

import java.time.Instant;
import java.util.concurrent.atomic.AtomicReference;

/**
 * HAPI FHIR client interceptor that authenticates requests to Oracle Health (Cerner) with an OAuth 2.0 access token.
 *
 * <p>The token is requested with the client credentials grant and cached until shortly before it expires. This class is
 * deliberately not a Spring bean: the Mobile Framework registers every {@link IClientInterceptor} bean with every FHIR
 * client. {@code CernerConfig} registers it with the {@code cerner} FHIR client only.
 *
 * @since 1.0
 */
public class CernerAuthInterceptor implements IClientInterceptor {

    /**
     * Settings of the Oracle Health API, including the token endpoint and the client credentials.
     */
    private final AppProperties.Cerner settings;

    /**
     * REST client used to request access tokens.
     */
    private final RestClient restClient;

    /**
     * The current access token, or {@code null} before the first request.
     */
    private final AtomicReference<AccessToken> accessToken = new AtomicReference<>();

    /**
     * Creates the interceptor.
     *
     * @param settings the settings of the Oracle Health API
     * @param restClient the REST client used to request access tokens
     */
    public CernerAuthInterceptor(final AppProperties.Cerner settings, final RestClient restClient) {
        this.settings = settings;
        this.restClient = restClient;
    }

    @Override
    public void interceptRequest(final IHttpRequest request) {
        request.removeHeaders(HttpHeaders.AUTHORIZATION);
        request.addHeader(HttpHeaders.AUTHORIZATION, "Bearer " + getAccessToken());
    }

    @Override
    public void interceptResponse(final IHttpResponse response) {
        // Nothing to do
    }

    /**
     * Returns the current access token, and requests a new one when it is about to expire.
     *
     * @return the access token
     */
    private String getAccessToken() {
        final AccessToken current = accessToken.get();
        if (current != null && Instant.now().plus(settings.getTokenRefreshMargin()).isBefore(current.expiresAt())) {
            return current.value();
        }
        final AccessToken requested = requestAccessToken();
        accessToken.set(requested);
        return requested.value();
    }

    /**
     * Requests an access token from the OAuth 2.0 token endpoint with the client credentials grant.
     *
     * @return the access token and when it expires
     * @throws RestClientException if the token request fails or the response contains no access token;
     *         {@link CernerClient} translates it into HTTP 503
     */
    private AccessToken requestAccessToken() {
        final MultiValueMap<String, String> form = new LinkedMultiValueMap<>();
        form.add("grant_type", "client_credentials");
        // Oracle Health expects the scopes separated by commas
        form.add("scope", String.join(",", settings.getScopes()));
        final TokenResponse token = restClient.post()
                                              .uri(settings.getTokenUrl())
                                              .headers(headers -> headers.setBasicAuth(settings.getClientId(), settings.getClientSecret()))
                                              .contentType(MediaType.APPLICATION_FORM_URLENCODED)
                                              .accept(MediaType.APPLICATION_JSON)
                                              .body(form)
                                              .retrieve()
                                              .body(TokenResponse.class);
        if (token == null || token.accessToken() == null) {
            throw new RestClientException("The token response contains no access token");
        }
        return new AccessToken(token.accessToken(), Instant.now().plusSeconds(token.expiresIn()));
    }

    /**
     * An access token and the time it expires.
     *
     * @param value the access token
     * @param expiresAt when the access token expires
     */
    record AccessToken(String value, Instant expiresAt) {
    }

    /**
     * The response of the OAuth 2.0 token endpoint.
     *
     * @param accessToken the access token
     * @param expiresIn the number of seconds until the access token expires
     */
    record TokenResponse(@JsonProperty("access_token") String accessToken, @JsonProperty("expires_in") long expiresIn) {
    }
}

package gov.va.mobile.fhirstarter.v1.config;

import gov.va.mobile.boot.fhir.client.FhirRestfulClientCustomizer;
import gov.va.mobile.fhirstarter.v1.AppProperties;
import gov.va.mobile.fhirstarter.v1.client.CernerAuthInterceptor;
import gov.va.mobile.fhirstarter.v1.client.CernerClient;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.client.RestClient;

/**
 * Configuration of the Oracle Health (Cerner) FHIR client.
 *
 * @since 1.0
 */
@Configuration
public class CernerConfig {

    /**
     * Registers the {@link CernerAuthInterceptor} with the {@code cerner} FHIR client.
     *
     * <p>The Mobile Framework applies every {@link FhirRestfulClientCustomizer} bean to each FHIR client it creates, with
     * the registration ID of the client, so the interceptor only authenticates the requests to Oracle Health.
     *
     * @param appProperties the service settings, including the Oracle Health token endpoint and client credentials
     * @param restClientBuilder builds the REST client used to request access tokens
     * @return the customizer of the {@code cerner} FHIR client
     */
    @Bean
    public FhirRestfulClientCustomizer cernerAuthCustomizer(final AppProperties appProperties,
                                                            final RestClient.Builder restClientBuilder) {
        final CernerAuthInterceptor authInterceptor = new CernerAuthInterceptor(appProperties.getCerner(), restClientBuilder.build());
        return (registrationId, client) -> {
            if (CernerClient.REGISTRATION_ID.equals(registrationId)) {
                client.registerInterceptor(authInterceptor);
            }
        };
    }
}

    /** A downstream service failed or couldn't be reached. */
    DOWNSTREAM_UNAVAILABLE("%s is unavailable, try again later"),
    /** More than one patient in a downstream system has the requested ICN. */
    AMBIGUOUS_PATIENT("More than one patient in %s has the requested ICN");

package gov.va.mobile.fhirstarter.v1.client;

import ca.uhn.fhir.rest.gclient.IQuery;
import ca.uhn.fhir.rest.server.exceptions.BaseServerResponseException;
import ca.uhn.fhir.rest.server.exceptions.InternalErrorException;
import gov.va.mobile.boot.fhir.client.FhirClientManager;
import gov.va.mobile.fhirstarter.v1.exception.DownstreamServiceException;
import gov.va.mobile.fhirstarter.v1.exception.ErrorMessage;
import gov.va.mobile.security.FhirSystems;
import lombok.RequiredArgsConstructor;
import lombok.extern.slf4j.Slf4j;
import org.hl7.fhir.r4.model.Bundle;
import org.hl7.fhir.r4.model.Encounter;
import org.hl7.fhir.r4.model.Patient;
import org.hl7.fhir.r4.model.Resource;
import org.springframework.stereotype.Component;
import org.springframework.web.client.RestClientException;

import java.util.List;
import java.util.Optional;
import java.util.function.Supplier;

/**
 * Client for the Oracle Health (Cerner) Millennium FHIR R4 API.
 *
 * <p>The FHIR client is configured by the {@code va.mobile.fhir.client.registration.cerner.*} properties, and
 * authenticated by the {@link CernerAuthInterceptor}. Local deployments call cerner-mock instead of Oracle Health.
 *
 * @since 1.0
 */
@Slf4j
@Component
@RequiredArgsConstructor
public class CernerClient {

    /**
     * Registration ID of the Oracle Health FHIR client ({@code va.mobile.fhir.client.registration.cerner.*}).
     */
    public static final String REGISTRATION_ID = "cerner";

    /**
     * Name of the downstream system, as shown to clients when it is unavailable.
     */
    public static final String SERVICE_NAME = "Oracle Health";

    /**
     * Provides the FHIR clients of the registrations in the service properties.
     */
    private final FhirClientManager fhirClientManager;

    /**
     * Finds the Oracle Health id of the patient with the given ICN.
     *
     * @param icn the ICN of the patient
     * @return the logical id of the patient in Oracle Health, or empty if Oracle Health has no record of the patient
     * @throws InternalErrorException if more than one patient in Oracle Health has the ICN (HTTP 500)
     * @throws DownstreamServiceException if Oracle Health fails or can't be reached (HTTP 503)
     */
    public Optional<String> findPatientId(final String icn) {
        final Bundle bundle = send(() -> fhirClientManager.getClient(REGISTRATION_ID)
                                                          .search()
                                                          .forResource(Patient.class)
                                                          .where(Patient.IDENTIFIER.exactly().systemAndIdentifier(FhirSystems.ICN_SYSTEM, icn))
                                                          .returnBundle(Bundle.class)
                                                          .execute());
        final List<Patient> patients = resources(bundle, Patient.class);
        if (patients.size() > 1) {
            throw new InternalErrorException(ErrorMessage.AMBIGUOUS_PATIENT.format(SERVICE_NAME));
        }
        return patients.stream().findFirst().map(patient -> patient.getIdElement().getIdPart());
    }

    /**
     * Searches for the encounters of a patient.
     *
     * @param patientId the logical id of the patient in Oracle Health
     * @param status the status of the encounters to return, or {@code null} for every status
     * @return the encounters of the patient
     * @throws DownstreamServiceException if Oracle Health fails or can't be reached (HTTP 503)
     */
    public List<Encounter> searchEncounters(final String patientId, final String status) {
        IQuery<Bundle> query = fhirClientManager.getClient(REGISTRATION_ID)
                                                .search()
                                                .forResource(Encounter.class)
                                                .where(Encounter.SUBJECT.hasId("Patient/" + patientId))
                                                .returnBundle(Bundle.class);
        if (status != null) {
            query = query.and(Encounter.STATUS.exactly().code(status));
        }
        final IQuery<Bundle> search = query;
        return resources(send(search::execute), Encounter.class);
    }

    /**
     * Sends a request to Oracle Health and translates its failures.
     *
     * @param request the request
     * @param <T> the type of the response
     * @return the response
     * @throws DownstreamServiceException if Oracle Health fails or can't be reached (HTTP 503)
     */
    private static <T> T send(final Supplier<T> request) {
        try {
            return request.get();
        } catch (final BaseServerResponseException | RestClientException e) {
            // The HAPI FHIR client throws BaseServerResponseException subclasses for error responses and connection
            // failures, and CernerAuthInterceptor throws RestClientException when it can't get an access token
            final String failure = e.getClass().getSimpleName();
            log.warn("The Oracle Health request failed: {}", failure);
            throw new DownstreamServiceException(SERVICE_NAME, e);
        }
    }

    /**
     * Returns the resources of a type in a Bundle.
     *
     * @param bundle the Bundle
     * @param type the resource type
     * @param <T> the resource type
     * @return the resources of the type, in the order of the Bundle entries
     */
    private static <T extends Resource> List<T> resources(final Bundle bundle, final Class<T> type) {
        return bundle.getEntry()
                     .stream()
                     .map(Bundle.BundleEntryComponent::getResource)
                     .filter(type::isInstance)
                     .map(type::cast)
                     .toList();
    }
}

    /** More than one patient in a downstream system has the requested ICN. */
    AMBIGUOUS_PATIENT("More than one patient in %s has the requested ICN"),
    /** The requested encounter status isn't a FHIR encounter status. */
    INVALID_ENCOUNTER_STATUS("Invalid encounter status: %s");

package gov.va.mobile.fhirstarter.v1.resource;

import ca.uhn.fhir.model.api.annotation.Description;
import ca.uhn.fhir.rest.annotation.OptionalParam;
import ca.uhn.fhir.rest.annotation.RequiredParam;
import ca.uhn.fhir.rest.annotation.Search;
import ca.uhn.fhir.rest.param.ReferenceParam;
import ca.uhn.fhir.rest.param.TokenParam;
import ca.uhn.fhir.rest.server.IResourceProvider;
import ca.uhn.fhir.rest.server.exceptions.InvalidRequestException;
import ca.uhn.fhir.rest.server.servlet.ServletRequestDetails;
import gov.va.mobile.Sanitizer;
import gov.va.mobile.aep.v2.client.web.JwtAudited;
import gov.va.mobile.fhirstarter.v1.client.CernerClient;
import gov.va.mobile.fhirstarter.v1.exception.ErrorMessage;
import gov.va.mobile.security.UserRoles;
import gov.va.mobile.security.web.jwt.JwtRestricted;
import gov.va.mobile.security.web.jwt.JwtRestrictedGroup;
import lombok.RequiredArgsConstructor;
import org.hl7.fhir.exceptions.FHIRException;
import org.hl7.fhir.instance.model.api.IBaseResource;
import org.hl7.fhir.r4.model.Encounter;
import org.hl7.fhir.r4.model.Reference;
import org.springframework.stereotype.Component;

import java.util.List;

/**
 * Encounter resource provider, backed by Oracle Health (Cerner).
 *
 * <p>Access is role based: {@link JwtRestrictedGroup} admits staff and veteran users. The search then validates the
 * ICN and the user's access with {@link PatientAccess}, which results in HTTP 400 for an invalid ICN and HTTP 403 when
 * a veteran requests the records of another patient. Operations that return patient data are audited with
 * {@link JwtAudited}.
 *
 * @since 1.0
 */
@Component
@RequiredArgsConstructor
@JwtRestrictedGroup(oneOf = {
        @JwtRestricted(roles = UserRoles.STAFF),
        @JwtRestricted(roles = UserRoles.VETERAN)})
public class EncounterProvider implements IResourceProvider {

    /**
     * Client for the Oracle Health FHIR API.
     */
    private final CernerClient cernerClient;

    /**
     * Returns the FHIR resource type handled by this provider.
     *
     * @return the Encounter resource class
     */
    @Override
    public Class<? extends IBaseResource> getResourceType() {
        return Encounter.class;
    }

    /**
     * Searches for the encounters of a patient, for example {@code GET [base]/Encounter?patient=10115V737384&status=finished}.
     *
     * <p>The encounters come from Oracle Health; see {@link CernerClient} for the errors it results in.
     *
     * @param requestDetails request details provided by HAPI FHIR
     * @param patient the patient, by the logical id of the Patient in this service, which is the ICN
     * @param status the status of the encounters to return, optional
     * @return the encounters of the patient; HAPI FHIR returns the list as a Bundle of type {@code searchset}
     * @throws InvalidRequestException if the status isn't an encounter status (HTTP 400)
     */
    @Search
    @JwtAudited(JwtAudited.AuditOptions.REQUIRED)
    public List<Encounter> search(
            final ServletRequestDetails requestDetails,
            @Description(shortDefinition = "The patient's ICN, for example 10115V737384 or Patient/10115V737384")
            @RequiredParam(name = Encounter.SP_PATIENT)
            final ReferenceParam patient,
            @Description(shortDefinition = "The encounter status, for example finished")
            @OptionalParam(name = Encounter.SP_STATUS)
            final TokenParam status) {
        final String icn = PatientAccess.validateIcn(patient.getIdPart());
        PatientAccess.verifyPatientAccess(requestDetails, icn);
        final String statusCode = validateStatus(status);
        return cernerClient.findPatientId(icn)
                           .map(patientId -> cernerClient.searchEncounters(patientId, statusCode))
                           .orElseGet(List::of)
                           .stream()
                           .map(encounter -> toServiceEncounter(encounter, icn))
                           .toList();
    }

    /**
     * Prepares an Oracle Health encounter for the clients of this service.
     *
     * <p>The id of a resource read by a FHIR client includes the base URL of the server it came from, and HAPI FHIR uses
     * that id for the {@code fullUrl} of the Bundle entry. Keeping only the id part hides the address of Oracle Health
     * from our clients. The subject is pointed at the Patient in this service instead of the Patient in Oracle Health.
     *
     * @param encounter the encounter from Oracle Health, changed in place
     * @param icn the patient's ICN
     * @return the encounter
     */
    private static Encounter toServiceEncounter(final Encounter encounter, final String icn) {
        encounter.setId(encounter.getIdElement().getIdPart());
        encounter.setSubject(new Reference("Patient/" + icn));
        return encounter;
    }

    /**
     * Validates that the status is an encounter status, before the request is sent to Oracle Health.
     *
     * @param status the status from the request, optional
     * @return the status code, or {@code null} if the request has no status
     * @throws InvalidRequestException if the status isn't an encounter status (HTTP 400)
     */
    private static String validateStatus(final TokenParam status) {
        if (status == null || status.getValue() == null || status.getValue().isBlank()) {
            return null;
        }
        try {
            return Encounter.EncounterStatus.fromCode(status.getValue()).toCode();
        } catch (final FHIRException e) {
            throw new InvalidRequestException(ErrorMessage.INVALID_ENCOUNTER_STATUS.format(Sanitizer.sanitize(status.getValue())), e);
        }
    }
}

curl -s -H "x-vamf-jwt: $STAFF_JWT" 'http://localhost:8080/fhirstarter/v1/fhir/Encounter?patient=10115V737384' | jq

./mvnw clean install -Pwith-skaffold

git add .
git commit -m "Add an Encounter search through cerner-mock"
git push