Overview

The Claim Evidence Application Programming Interface (CE API) is file service for handling the storage and management of files supporting VA benefit claims. It serves as a modernized point of entry to files previously only accessible through VBMS eFolder. It is designed for easier implementation by consuming systems, but also with the ability to eventually replace the eFolder logic within VBMS. It is a RESTful API written in Java.

In order to easily connect Caseflow with CE API endpoints, the APPEALS team has created an internal gem: ruby_claim_evidence_api

For the purpose of this wiki, the following information is only concerned with the Ruby CE API and a high level overview of its implementation and usage.

For specific technical implementation, with details on required fields and sample outputs, please see the following Confluence pages:

https://confluence.devops.va.gov/display/VAExternal/Caseflow+-+CE+API+Migration

https://confluence.devops.va.gov/display/VAExternal/eFolder+express+-+CE+API+Migration

Primary Service Classes

For Ruby CE API, we have four primary service classes that serve to encapsulate business logic: claim_evidence_service, veteran_file_fetcher, veteran_file_updater, and veteran_file_uploader. These classes may be initialized in the config/initializers/ruby_claim_evidence_api.rb as needed for each consumer application.

1. ClaimEvidenceService

This file houses the logic for constructing api requests in the proper format. In order to make requests to CE API, we need to construct a request with an authorized jwt token. The token is required to be signed with both the user's css id and station id, token secret, and token issuer. See below for an example format of a valid JWT Token.

Additionally, there are also public methods to retrieve document types and ocr data of a pdf given a series_id.

The public methods for retrieving, uploading and updating a document have been ported to the VeteranFileFetcher, VeteranFileUploader, and VeteranFileUpdater respectively and it is recommended to use those classes for these specific actions. As the need and usage of Ruby CE API grew over time, we created a new parent class, ApiBase, to make configurations for logging and stubbing responses easier.

2. VeteranFileFetcher

The VeteranFileFetcher class contains three methods:

• fetch_veteran_file_list - Retrieves a list of files given a veteran file number and optional filters.
• fetch_veteran_file_list_by_date_range - Retrieves a list of files given a veteran file number and a date range
• fetch_document_file - Retrieves the document content in byte string format for a given series id.

3. VeteranFileUploader and VeteranFileUpdater

These two classes both serve a singular purpose: to upload a document and update a document respectively.

Note that the CE API differs slightly from VBMS with the way uploading and updating documents are done. With VBMS, it is required that we initially retrieve a signed token to authorize the uploading and updating of a document, hence why it was necessary to include InitializeUpload and InitializeUpdate requests. With CE API, we can forego this step allowing us to decrease our code complexity and reduce the total number of async calls we would need to make.

Endpoints Implemented

Request Type	Endpoint	Description
GET	/documenttypes	Retrieves an array of valid non-restricted document types
GET	/files/#{series_id}/data/ocr	Retrieves the OCR data of a pdf file
POST	/files	Uploads a document
POST	/files/#{series_id}	Updates a document
POST	/folders/files:search	Retrieves the folder (array of documents) associated with a Veteran by the veteran's file number
GET	/files/#{series_id}/content	Retrieves the document as a PDF byte string

Usage

The Ruby CE API is used in both Caseflow and Efolder Express applications for the purpose of fetching, saving, and downloading files by using a Veteran file number and a document/record's series_id. It also serves to retrieve and validate document types and retrieve the text data from PDF files.

The migration work is currently wrapped using two FeatureToggles (:use_ce_api and :ce_api_demo_toggle), and majority of the new code will be found in the VBMSService class replacing the corresponding VBMS Requests. The path to the file in question is for both Caseflow and Efolder Express applications is app/services/external_api/vbms_service.rb.

Caseflow

In Caseflow, we use the CE API to connect to Efolder and upload, retrieve, and save documents. We also use it display valid non restricted document types that we can assign to documents to maintain the integrity of the Efolder database.

In Caseflow, documents are fetched through the DocumentFetcher and are saved to the Document ActiveRecord model. Whenever the DocumentFetcher gets initialized, it will call VBMSService#fetch_documents_for.

During the Correspondence intake process a user will be able to edit the metadata of Correspondence Documents. The form dropdown uses the Ruby CE API to fetch a list of all valid document types. At end of the intake process, the correspondence and any other document uploads will also now be handled by Ruby CE API's VeteranFileFetcher instead of making a VBMS SOAP request.

Efolder Express

In Efolder Express, Ruby CE API functionality is utilized when searching for a Veteran File Number on the main page. After a user logs into the application, there will be a search bar prompting them to enter a valid veteran file number. After entering and searching for a veteran file number, Ruby CE API will send a POST request to CE API's /folders/files:search endpoint, passing the veteran file number in the header.

Ruby CE API will then fetch an array of hashes, with each hash representing metadata related to an existing document associated with the veteran file number. Subsequently, after saving the hashes to an OpenStruct in the same format as the record.rb model, we would iterate through each hash and fetch the pdf content through Ruby CE API's fetch_document_file method.

All these actions are performed asynchronously through several jobs that triggered once the Manifest's controller is hit. The control flow is as follows:

• Manifest controller start! is triggered by searching a veteran file number
• Controller calls manifest.start!
• Manifest.start! calls ManifestSource.start! (Note: although there are two manifest sources, VVA and VBMS, VVA manifest source is disabled in production - We only use VBMS source)
• ManifestSource triggers DownloadManifestJob
• DownloadManifestJob calls the ManifestFetcher.process!
• ManifestFetcher then calls VBMS/Ruby CE API to retrieve a list of all documents (/folders/files:search endpoint)
• After the fetcher's process is completed, DownloadManifestJob ends by queueing SaveFilesInS3Job
• SaveFilesInS3Job then iterates through each record and calls VBMS/Ruby CE API to retrieve the file
• Each record calls on the RecordFetcher class to fetch the record.
• File is saved in a temporary folder before being saved to an S3 Bucket