BIP Claims API - department-of-veterans-affairs/abd-vro GitHub Wiki

VRO uses BIP Claims API to get information about and do updates to VBA Benefit Claims.

currently it exposes two endpoints via RabbitMQ. To connect, use exchange name bipApiExchange. The end points are following.

  • queue name: getClaimDetailsQueue. Expects a long collectionId as input. Returns a BipClaim object.
  • queue name: setClaimToRfdStatusQueue. Expects a long collectionId as input. Returns a BipUpdateClaimResp object.
  • queue name: updateClaimStatusQueue. Expects a RequestForUpdateClaimStatus object as input. Returns a BipUpdateClaimResp object.
  • queue name: getClaimContentionsQueue. Expects a long collectionId as input. Returns a BipUpdateClaimResp object.
  • queue name: updateClaimContentionQueue. Expects an UpdateContentionModel object as input. Returns a BipUpdateClaimResp object.

Access to BIP Claims API is available only within VA firewall.

BIP Claims API uses mTLS. VRO's mTLS implementation is detailed in BIP-APIs.

Integration Requirements

The following benefit claim data is retrieved

  • Temporary station of jurisdiction
  • Existence of contentions' special issues "Rapid Decision Rating Version 1" (RDR1) and "Rapid Ready Decision" (RRD)

The following are the updates to claim data

  • Removal of contentions' special issue RDR1
  • Update of lifecycle status to "Ready for Decision" (RFD)

Open API Specification

BIP Claim API's Open API Specification is available from the Swagger page.

All the end-points that are used within the VRO application is also available from the Mock Bip Claim Api Swagger page in the local development environment.

Code Walkthrough

Security Requirements

BIP requires a Bearer JWT for access. Following claims are used

  • Subject (sub)
  • User Id (userID): Custom - VRO system user
  • Issuer (iss)
  • Station Id (stationID): Custom - VRO system user facility (?)
  • Application Id (applicationID): Custom - VRO application name
  • Expiration (exp)
  • Issued At (iat)

The JWT is created before each API call in BipApiService createJwt method.

Subject claim is hard-coded in createJwt. Expiration and Issued At claims are dynamicaly created in createJwt. The other claims are made available to the application with environment variables through application.properties.

  • User Id: BIP_CLAIM_USERID through bip.claimClientId
  • Issuer: BIP_CLAIM_ISS through bip.claimIssuer
  • Station Id: BIP_STATION_ID through bip.stationId
  • Application Id: BIP_APPLICATION_ID through bip.applicationId

JWT is signed by a secret provided by the BIP API team. The secret is made available to the application with the environment variable BIP_CLAIM_SECRET through application.properties bip.claimSecret setting.

In the VRO Kubernetes environment the related Kubernetes secrets for the BIP environment variables are

  • BIP_CLAIM_USERID: bip.bipClaimUserId
  • BIP_CLAIM_ISS: bip.bipApplicationIss
  • BIP_STATION_ID: bip.bipStationId
  • BIP_APPLICATION_ID: bip.bipApplicationId
  • BIP_CLAIM_SECRET: bip.bipClaimSecret

Note that due to an issue in the application (BIP_CLAIM_ISS is not specied in Helm charts) bip.bipApplicationIss is not functional. The hard coded value in application.properties bip.claimIssuer setting is used. This is in the list of issues for future fixes.

A set of BIP environment variables are available for local development by sourcing the setenv.sh script. There were attempts to move these to application-local.properties but failed. Please see the note in setenv.sh script.

API Hostnames

Environment Hostname
dev https://claims-dev.dev.bip.va.gov
test https://claims-test.dev.bip.va.gov
int https://claims-int.dev.bip.va.gov
ivv https://claims-ivv.stage.bip.va.gov
uat https://claims-uat.stage.bip.va.gov
pat https://claims-pat.stage.bip.va.gov
pdt https://claims-pdt.stage.bip.va.gov
demo https://claims-demo.stage.bip.va.gov
perf https://claims-perf.prod.bip.va.gov
preprod https://claims-preprod.prod.bip.va.gov
prodtest https://claims-prodtest.prod.bip.va.gov
cola https://claims-cola.prod.bip.va.gov
prod https://claims-prod.prod.bip.va.gov

API Calls

The following end points are used

  • GET /claims/{claimId}
  • GET /claims/{claimId}/contentions
  • PUT /claims/{claimId}/contentions
  • PUT /claims/{claimId}/lifecycle_status

The base URL is made available to the application with the environment variable BIP_CLAIM_URL through application.properties bip.claimBaseURL setting. The corresponding Kubernetes secret is bip.bipClaimUrl.

For local development and testing a Mock Server is available in docker compose with host name mock-bip-claims-api.

BIP API Service

All API calls are implemented in Bip API Service. Bip API Service uses the custom RestTemplate bean (qualifier: bipCERestTemplate) described in BIP-APIs.

Bip Api Service is available to rest of the application as a Spring service. The only current customer is Bip Claim Service which uses it through Bip Api Service Interface. This is mostly for historical progression of the implementation but also makes it possible to unit test Bip Claim Service more easily as Bip Api Service Interface is overridden in a test configuration.

BIP Claim Service

BIP Claims API related functionality is provided to the rest of the application through BIP Claim Service. The public methods hasAnchors, removeSpecialIssue, and markAsRFD should be recognizable from the VRO-v2-Roadmap. The public method completeProcessing is used to double check temporary station of jurisdiction as specified in requirements.

VBMS

VBMS (provided by VA's BIP (Benefits Integration Platform) team) has the following APIs:

  • Claim Service - specs for Release 23.1 (version 35.0, 08/23/2021) are in a 0003AE_5.2.2.d_Claims v4.0 SCD 23.1.pdf
    • update claims, contentions
    • dependent on BEP (Business Enterprise Platform), BGS (Benefits Gateway Service, where claims and contentions are persisted), and Oracle 11G DB
    • Claims API Swagger spec has more accurate info; code base
  • Claim Evidence API (see prior section)

BAM Shared Services

VRO will need to mark a claim as eligible for being assessed for fast-tracking (via a VBMS/BGS special issue?) so that users don't work on the claim.

  • We should investigate and ask if Lighthouse's Benefits Claim API can be updated to include the capability.

VRO will need to mark a claim or contention as ready-for-decision (RFD) so it can be adjudicated and fast-tracked.

MPI

When VRO checks for fast-track-ability, VRO queries an API (probably MPI) to map a given veteran identifier into an ICN, which is needed to query Lighthouse for health data.

  • Lighthouse has a connection to MPI, so VRO should leverage it
  • Benefits Claims API v2 provides a way get a veteran's ICN using MPI, but the veteran's SSN, name, and DOB is needed. Working with Kayla and Derek Brown (Lighthouse) to enable lookup by file number (a.k.a., BIRLS ID)

Note from a Slack post:

MPI queries straight from vets-api are mocked on localhost. This is necessary because MPI can only be accessed on the VA network, so our local machines don’t have direct access, even to the MPI test stacks.