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

VRO uses BIP Claim Evidence API to upload evidence PDFs to E-Folder.

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

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

Integration Requirements

  • VRO uploads PDF documents to E-Folder
  • VRO specifies meta data about the document

Open API Specification

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

The only end point used from BIP Claim Evidence API is the /files end-point.

Future Work

It should be possible to activate the Swagger page for the Mock BIP Claim Evidence API similar to Mock BIP Claims API easily. But that has not been yet done.

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 - must be equivalent to Issuer per documentation
  • Expiration (exp)
  • Issued At (iat)

The JWT is created before each API call in BipCEApiService 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_EVIDENCE_USERID through bip.evidenceClientId
  • Issuer: BIP_EVIDENCE_ISS through bip.evidenceIssuer
  • 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_EVIDENCE_SECRET through application.properties bip.evidenceSecret setting.

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

  • BIP_EVIDENCE_USERID: bip.bipEvidenceUserId
  • BIP_STATION_ID: bip.bipStationId
  • BIP_APPLICATION_ID: bip.bipApplicationId
  • BIP_EVIDENCE_SECRET: bip.bipEvidenceSecret

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
ivv https://vefs-claimevidence-ivv.stage.bip.va.gov
stage https://vefs-claimevidence-pat.stage.bip.va.gov
pdt https://vefs-claimevidence-pdt.stage.bip.va.gov
uat https://vefs-claimevidence-uat.stage.bip.va.gov
prodtest https://vefs-claimevidence-prodtest.prod.bip.va.gov
prod https://vefs-claimevidence.prod.bip.va.gov

API Calls

The only end-point that is used is

  • POST /files

The base URL is made available to the application with the environment variable BIP_EVIDENCE_URL through application.properties bip.evidenceBaseURL setting. The corresponding Kubernetes secret is bip.bipEvidenceUrl.

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

BIP Claim Evidence API Service

The API call is implemented in Bip Claim Evidence API Service. Bip Claim Evidence API Service uses the custom RestTemplate bean (qualifier: bipCERestTemplate) described in BIP-APIs.

Bip Claim Evidence 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 Claim Evidence 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 Claim Evidence API related functionality is provided to the rest of the application through BIP Claim Service. The public method uploadPdf is self explanatory.