Skip to content

Data Integration With Vim - File-Based Integration

File-based integration enables organizations to securely exchange structured data with Vim over an sFTP connection, allowing the data to be presented within the application at the point of care.

To initiate a file-based integration, customers would share a file following Vim’s defined schema. Once a file is received, Vim validates the data, filters out any invalid rows, and ingests the file into a secure, customer-specific namespace. As care insights are addressed through Vim applications, Vim generates reporting passbacks to inform the data connection. These passbacks help ensure that future files reflect the most up-to-date information.

Integration Flow Diagram

This page will outline in detail the requirements and deliverables for the file-based integration between Vim and a data connection.

Setting Up the sFTP Connection

The first step in enabling file-based integration is establishing a secure sFTP connection between the data connection and Vim. This connection supports bi-directional file exchange: from the data connection → Vim and from Vim → data connection.

Vim will be hosting the sFTP connection supporting public key-based authentication allowing a secure method for logging in via RSA SSH. This authentication method requires:

  • **RSA SSH keys - ** The public key will be shared with Vim, while the private key will use the data connection to connect to the sFTP server
  • IP whitelisting - The data connection will share the IP addresses, or range of addresses, that will be allowed access to the sFTP server. Vim supports up to 20 IP addresses
  • Access details - Vim will define and share with the data connection the username and hosting URL

To authenticate with the Vim sFTP server, the data connection uses the username provided by Vim along with the private key they generated. Vim verifies the connection using the corresponding public key.

The sFTP server will hold two folders:

  • from Vim - All the files sent from Vim to the data connection will be placed in this folder
  • from <data_source_name>: All the files sent from the data connection will be placed in this folder

For public key-based authentication hosted by the data connection, please contact a Vim representative.

Preparing Your File

Before integrating with Vim, you must generate a file that adheres to the specifications outlined in this section. The file should include the data your organization intends to share with providers, structured according to the defined format to ensure accurate processing and ingestion.

File Level Specification and Configurations

Vim supports a variety of file configurations to accommodate different data sharing needs, including file format, delivery cadence, and ingestion logic. These configurations directly impact how data is processed and displayed within Vim applications.

This section outlines the required specifications and supported configurations for successful integration.

File Format and Structure

The following requirements apply to all files shared with Vim for ingestion:

  • A file per insight type - Each insight type to be provided in a separate file: Diagnosis Gaps, Care Gaps, according to the specfications below
    • Vim also supports receiving a member eligibility file
  • File naming convention - <customer_name>_<insight_type_name>_<yyyy-mm-dd>.<format>
    • Ingestion process will begin only for files with the expected naming convention
    • Accepted gap type names are either diagnosis_gaps or care_gaps
    • The file name will include only lowercase letters, no spaces
  • File format - csv, txt, xls
    • The file can be zipped
    • Encrypted files are not supported out-of-the-box, please contact a Vim representative to support encrypted files
  • File delimiter - Comma or pipe
  • Encoding - UTF-8
  • Cadence - Daily, weekly, or monthly to your preference

File Ingestion Configurations

The following table outlines file-level configurations that impact the ingestion process for data shared with Vim. These configurations define how the ingestion logic should interpret and present the data. A separate table will outline the expected data-level fields within the file.

ConfigurationRelevant Data SetDescriptionMandatory?Optional values
Gap SystemDiagnosis gapsDefines the primary gap type (ICD, HCC) to be displayed and actioned in the applicationYesThe primary diagnosis gap can be: HCC/ ICD/ Hybrid*
Gap Model VersionDiagnosis gapsDefines the default model version of the diagnosis gaps sharedYesVim is supporting the following model versions: CMS HCC V24/ CMS HCC V28/ HHS-HCC/ RX-HCC V08/ Hybrid*
Gap Status FilteringDiagnosis gaps, Care gapsSpecifies which gaps will be filtered out based on the gap's statusNoIndicate the statuses Vim should present in the application: Open/ Closed
Custom fieldsDiagnosis gaps, Care gapsAdditional customer-specific information to enrich the data shown in the application (e.g., patient or gap metadata)NoDetails to be provided per custom field: the title of the field to be present in the app, the entity the custom filed relates to (patient or gap), the type of the field (date, string, integer, decimal, URL, cost)
  • Hybrid: when multiple options are expected in a single file. In this case, the values should be specified in the file itseld per row, in the relevant columns, as outlined in the File Schema.

File Content Specifications

This section defines the expected structure and field-level requirements for files shared with Vim. Each file must adhere to the following schema to ensure successful ingestion and display within Vim applications.

Diagnosis Gaps File Schema

The table below outlines the required structure and accepted data types for the Diagnosis Gaps file:

Field NameDescriptionRequired?TypeExpected valuesUI displayExample
patient_first_namePatient's first nameRequiredStringLetters only, up to 50 charactersTRUEJohn
patient_last_namePatient's last nameRequiredStringLetters only, up to 50 charactersTRUEDoe
patient_unique_idUnique identifier assigned by the customer for the patient. Used to ensure accurate data display, billing, and reporting across Vim systemsRequiredStringLetters + digits, up to 50 charactersFALSE1234qwehce8fyw4fh
patient_dobPatient's date of birthRequiredDateYYYY-MM-DDTRUE1990-07-19
patient_insurance_idPatient’s health plan (member/subscriber ID)Conditional - At least one of patient_insurance_id, patient_ehr_id, or patient_zip_code must be providedStringUp to 50 charactersFALSE123445455
patient_ehr_idPatient’s unique EHR identifierConditional - Same as aboveStringUp to 50 charactersFALSEa1b2c3d4
patient_zip_codePatient's Zip codeConditional - Same as aboveStringxxxxx,xxxxx-xxxx or xxxxxxxxxFALSE90210
patient_insurerPatient’s insurance provider nameOptionalStringUp to 50 charactersFALSEUnited Health Care
patient_statePatient’s U.S. state of residenceOptionalStringTwo-letter U.S. state codeFALSEFL
gap_unique_idUnique identifier per gap and patient assigned by the customer, representing a single gap card in the application. Enables user interaction, tracking, and managementRequiredStringUp to 50 charactersFALSEfhipdusnyr98cenv485j
gap_systemDefines the coding system (HCC or ICD) used for the gap_unique_idConditional - Required only for hybrid filesEnumHCC or ICDFALSEHCC
hcc_codeHCC code to be displayed for the identified gapConditional - Required for HCC gap systemStringMatch one of the supported HCC models (see hcc_model_version)TRUE18
hcc_descriptionDescription of the HCC codeOptional - Automatically populated by Vim for supported modelsStringUp to 250 charactersTRUEDiabetes with chronic complications
icd_codeICD code to be displayed for the identified gapConditional - Required for ICD gap systemStringCMS codes onlyTRUEE11.21
icd_descriptionDescription of the ICD codeOptional - Automatically populated by Vim for supported modelsStringUp to 250 charactersTRUEDM with nephropathy
hcc_model_versionHCC model and version for the gap. Displayed in the app and could be used to enrich data (e.g. display gap description when not shred according to official mapping)Conditional - Required for HybridEnumCMS-HCC V24, CMS-HCC V28, HHS-HCC or RX-HCC V08TRUECMS-HCC V24
gap_typePreviously coded vs suspected diagnosisOptionalEnumKNOWN or SUSPECTEDTRUEKNOWN
gap_statusCurrent status of the gap, used for filteringOptionalEnumOPEN or CLOSEDFALSEOPEN
gap_raf_scoreRisk adjustment factor associated with the gapOptionalNumericDecimal values only (no dashes or symbols)TRUE2.659
gap_sourceOrigin or source of the gap dataOptionalStringUp to 250 charactersTRUE2024 claims
last_recorded_dosMost recent date of service related to the diagnosisOptionalDateYYYY-MM-DDTRUE1990-07-19
last_recorded_npiNPI of the most recent provider associated with the diagnosisOptionalNumeric10-digit NPITRUE1234567890
last_recorded_npi_nameName of the provider associated with the most recent serviceOptionalStringLetters only, up to 50 charactersTRUEJohn Smith
notesFree-text field for additional context or comments on the gapOptionalStringUp to 250 charactersTRUEPlease address all suggested gaps
Care Gaps Data Schema

The table below outlines the required structure and accepted data types for the Care Gaps file:

Field NameDescriptionRequired?TypeValid Values/FormatUI displayExample
patient_first_namePatient's first nameRequiredStringLetters only, up to 50 charactersTRUEJohn
patient_last_namePatient's last nameRequiredStringLetters only, up to 50 charactersTRUEDoe
patient_unique_idUnique identifier assigned by the customer for the patient. Used to ensure accurate data display, billing, and reporting across Vim systemsRequiredStringLetters + digits, up to 50 charactersFALSE1234qwehce8fyw4fh
patient_dobPatient's date of birthRequiredDateYYYY-MM-DDTRUE1990-07-19
patient_insurance_idPatient’s health plan (member/subscriber ID)Conditional - At least one of patient_insurance_id, patient_ehr_id, or patient_zip_code must be providedStringUp to 50 charactersFALSE123445455
patient_ehr_idPatient’s unique EHR identifierConditional - Same as aboveStringUp to 50 charactersFALSEa1b2c3d4
patient_zip_codePatient's Zip codeConditional - Same as aboveStringxxxxx,xxxxx-xxxx or xxxxxxxxxFALSE90210
patient_insurerPatient’s insurance provider nameOptionalStringUp to 50 charactersFALSEUnited Health Care
patient_statePatient’s U.S. state of residenceOptionalStringTwo-letter U.S. state codeFALSEFL
gap_unique_idUnique identifier per gap and patient assigned by the customer, representing a single gap card in the application. Enables user interaction, tracking, and managementRequiredStringUp to 50 charactersFALSEfhipdusnyr98cenv485j
gap_codeCode representing the care gapConditional - At least gap_code or gap_display_name are requiredStringProgram or measure codeTRUECBP
gap_display_nameDescription of the care gapConditional - At least gap_code or gap_display name are requiredStringUp to 100TRUEControlling Blood Pressure
cpt_II_codeRecommended CPT II code associated with the gapOptionalStringFour digits followed by 'F'TRUEJohn Doe
cpt_II_descriptionRecommended CPT II description associated with the gapOptionalStringUp to 100, letters onlyTRUEMost recent systolic BP less than 130 mm Hg
gap_statusCurrent status of the gap, used for filteringOptionalEnumOPEN or CLOSEDFALSEOPEN
last_recorded_dosMost recent date of service related to the diagnosisOptionalDateYYYY-MM-DDTRUE1990-07-19
last_recorded_npiNPI of the most recent provider associated with the diagnosisOptionalNumeric10-digit NPITRUE1234567890
last_recorded_npi_nameName of the provider associated with the most recent serviceOptionalStringLetters only, up to 50 charactersTRUEJohn Smith
notesFree-text field for additional context or comments on the gapOptionalStringUp to 250 charactersTRUEPlease address all suggested gaps

How Data Will Be Presented in the Application

Fields from the files will be displayed in the Care Insights application user interface. Below is a demonstration of the data elements that users will see within the application:

Diagnosis Gaps Data

Vim Connect Overview

Care Gaps Data

Vim Connect Overview

File Ingestion Process

Vim ingests the latest file received via sFTP using the configured file name. This process performs a full data refresh, where the newly ingested data completely replaces the existing data without causing downtime. Partial ingestion is not supported, if the ingestion process does not complete successfully, the existing data remains unchanged.

Data Validations

As part of the ingestion process, Vim validates the received file to ensure data quality and integrity. If a file fails validation, it will not be ingested, and Vim will notify the data connection with details about the issue and recommended resolution steps.

A file will be rejected and not ingested if:

  1. The file is not received in the expected format, naming convention, or delimiter
  2. The file is empty
  3. The file is missing required headers
  4. The file schema has changed - including new or deleted columns, modified column names, changes to column data types, or altered column order
  5. Data types in the file do not match the definitions outlined or agreed upon
  6. The file size differs by more than 60% compared to the previously ingested file

During ingestion, Vim also validates individual data entries against the requiremets. Entries that do not meet the requirements will be excluded from ingestion and will not be visible in the application. These excluded rows are collected into a gating file, which is sent back to the customer via the SFTP connection for review and correction.

Data entries will be excluded if:

  1. Any required fields are empty
  2. The unique patient ID or gap ID is not unique (all duplicate rows will be excluded)
  3. At least one of the following fields is missing: member_id, ehr_patient_identifier, or zip_code

Failed Gaps Gating File

After each ingestion (typically daily), Vim generates and shares a gating file that contains all rows that failed validation and were not ingested. This file includes the rejected rows along with specific reasons for each rejection, enabling efficient review and correction by the data provider.

Feedback Loop

Vim tracks user activity related to gap closure and sends structured feedback files back to the customer. These files support ongoing reporting and data quality improvements by indicating which gaps were addressed. Feedback files are delivered via the same sFTP connection used for data ingestion.

File Format and Structure

The following specifications apply to all files shared with Vim for ingestion: File Naming Convention:

  1. File name - <customer_name>YYYY_MM_DD__HH_MM_SS<insight_type_name>_report
  2. File type - CSV
  3. File delimiter - Pipe, Commac can also be supported
  4. **Cadence- ** Daily, weekly or monthly to your preference
    • Recommendation - Align with the cadence of your gap file submissions
  5. **Coverage timeframe - ** Day, week, or month to your preference
    • Recommendation - Align with the cadence of your gap file submissions
  6. Sending time- A time at the end of your business day to ensure all daily user activity is captured
    • Consider coordinating with sFTP sync schedules to ensure timely and complete file transfers

Shared Data Fields

The feedback passback format outlined below applies to both diagnosis and care gaps datasets. Feedback files are generated and shared separately for each gap type.

Each row represents a single user action taken within the Care Insights application. The data includes both patient and session context, enabling customers to reconcile actions, update their systems, and track resolution progress.

The table below outlines the required structure and accepted data types for the Gaps Feedback file:

Field NameDescriptionRequired?TypeDiagnosis Gaps ExampleCare Gaps Example
organization_nameName of the organization in session, as defined in Vim’s systemRequiredStringScott's ClinicScott's Clinic
vim_organization_keyUnique identifier for the organization in VimRequiredString8i7owzgbgo6zJHYNxkNLRc8i7owzgbgo6zJHYNxkNLRc
user_first_nameFirst name of the user in sessionOptionalStringScottScott
user_last_nameLast name of the user in sessionOptionalStringSmithSmith
ehr_usernameEHR username of the user in sessionOptionalStringscott.smithscott.smith
user_npiNPI of the user in sessionOptionalString (10-digit)84957384758495738475
encounter_idID of the patient’s EHR encounter associated with the sessionOptionalString859574859574
encounter_dateDate of the patient’s EHR encounter associated with the session (based on the organization's timezone)OptionalDate (YYYY-MM-DD)2023-10-172023-10-17
gap_systemCoding system of the gapm applicable to Diagnosis Gaps onlyRequired for Diagnosis Gaps onlyStringhccN/A
gap_idThe unique ID of the gap selected during the sessionRequiredString32fn48f347g4rg
gap_codeThe code of the gap selected during the sessionRequiredString82CBP
gap_descriptionThe description of the gap selected during the sessionOptionalStringAssess Drug DependenceControlling Blood Pressure
selected_medical_codesThe medical code(s) selected during the sessionOptionalString
action_dateThe date of the reported action (EST)Requireddate (YYYY-MM-DD)2023-10-192023-10-19
action_typeThe type of the reported actionRequiredtextacceptdismiss
action_reasonThe reason of the reported actionOptionalStringADDEVALUATE_NEXT_VISIT
action_additional_commentsThe free text added by the user for the reported action. Available only for the "dismiss" action_typeOptionalStringnot seen today
patient_customer_idThe unique customer internal patient identifier received by the customerRequiredString738463738463
  • Optional fields will be shared when available

Testing the Integration

Vim supports the data connections with the ability to perform end to end testing of the integration on Vim's mock EHR. If you wish to perform end to end testing in lower environments, please contact a vim representative.

Recommended: to be able to perform a production verification of the integration prior to the rollout, Vim supports adding dummy patients to the production file. A dummy patient should include the word "test" in the patient's first or last name.

Monitoring and Support

Vim is committed to knowledge and identify the root cause upon file ingestion failure within 24 hours from ingestion process start (excluding weekends).

For questions or technical assistance, contact Vim's Support Team at [email protected].