Appearance
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.
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:
- One file per data stream - providing a dedicated file for Diagnosis Gaps and a second file for all other insight categories, following the standard format used today
- Diagnosis Gaps file introduces additional specifications and configuration that are not relevant for all other insights
- Vim also supports receiving a member eligibility file
- File naming convention -
<customer_name>_<care_insight_data_type>_<yyyy-mm-dd>.<format>
- Ingestion process will begin only for files with the expected naming convention
- Accepted data types are either diagnosis_gaps or care_insights
- The file name will include only lowercase letters, no spaces
- File format - csv, txt, xls
- The file can be zipped
- 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.
Configuration | Relevant Data Set | Description | Mandatory? | Optional values |
---|---|---|---|---|
Gap System | Diagnosis gaps | Defines the primary gap type (ICD, HCC) to be displayed and actioned in the application | Yes | The primary diagnosis gap can be: HCC/ ICD/ Hybrid* |
Gap Model Version | Diagnosis gaps | Defines the default model version of the diagnosis gaps shared | Yes | Vim is supporting the following model versions: CMS HCC V24/ CMS HCC V28/ HHS-HCC/ RX-HCC V08/ Hybrid* |
Gap Status Filtering | Diagnosis gaps, Care Insightss | Specifies which insights will be filtered out based on the insightss status | No | Indicate the statuses Vim should present in the application: Open/ Closed |
Custom fields | Diagnosis gaps, Care Insights | Additional customer-specific information to enrich the data shown in the application (e.g., patient or insight metadata) | No | Details 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 insight), 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 outlines the expected structure and field-level requirements for files shared with Vim. Each file must conform to the specifications below to ensure accurate ingestion and display within the Care Insights application.
To accommodate differences in structure and content, Vim separates Care Insights data into two distinct files: one for Diagnosis Gaps and one for all other insight categories. Customers can choose to share either or both files, depending on which types of insights they wish to display in the Care Insights application.
Diagnosis Gaps File Schema
The table below outlines the required structure and accepted data types for the Diagnosis Gaps file:
Field Name | Description | Required? | Type | Expected values | UI display | Example |
---|---|---|---|---|---|---|
patient_first_name | Patient's first name | Required | String | Letters only, recommended up to 50 characters | TRUE | John |
patient_last_name | Patient's last name | Required | String | Letters only, recommended up to 50 characters | TRUE | Doe |
patient_unique_id | Unique identifier assigned by the customer for the patient. Used to ensure accurate data display, billing, and reporting across Vim systems | Required | String | Letters + digits, recommended up to 50 characters | FALSE | 1234qwehce8fyw4fh |
patient_dob | Patient's date of birth | Required | Date | YYYY-MM-DD | TRUE | 1990-07-19 |
patient_insurance_id | Patient's health plan (member/subscriber ID) | Conditional - At least one of patient_insurance_id, patient_ehr_id, or patient_zip_code must be provided | String | Recommended up to 50 characters | FALSE | 123445455 |
patient_ehr_id | Patient's unique EHR identifier | Conditional - Same as above | String | Up to 50 characters | FALSE | a1b2c3d4 |
patient_zip_code | Patient's Zip code | Conditional - Same as above | String | xxxxx,xxxxx-xxxx or xxxxxxxxx | FALSE | 90210 |
patient_insurer | Patient's insurance provider name | Optional | String | Recommended up to 50 characters | FALSE | United Health Care |
patient_state | Patient's U.S. state of residence | Optional | String | Two-letter U.S. state code | FALSE | FL |
gap_unique_id | Unique identifier per gap and patient assigned by the customer, representing a single gap card in the application. Enables user interaction, tracking, and management | Required | String | Recommended up to 50 characters | FALSE | fhipdusnyr98cenv485j |
gap_system | Defines the coding system (HCC or ICD) used for the gap_unique_id | Conditional - Required only for hybrid files | Enum | HCC or ICD | FALSE | HCC |
hcc_code | HCC code to be displayed for the identified gap | Conditional - Required for HCC gap system | String | Match one of the supported HCC models (see hcc_model_version) | TRUE | 18 |
hcc_description | Description of the HCC code | Optional - Automatically populated by Vim for supported models | String | Up to 250 characters | TRUE | Diabetes with chronic complications |
icd_code | ICD code to be displayed for the identified gap | Conditional - Required for ICD gap system | String | CMS codes only | TRUE | E11.21 |
icd_description | Description of the ICD code | Optional - Automatically populated by Vim for supported models | String | Up to 250 characters | TRUE | DM with nephropathy |
hcc_model_version | HCC 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 Hybrid | Enum | CMS-HCC V24, CMS-HCC V28, HHS-HCC or RX-HCC V08 | TRUE | CMS-HCC V24 |
gap_type | Previously coded vs suspected diagnosis | Optional | Enum | KNOWN or SUSPECTED | TRUE | KNOWN |
gap_status | Current status of the gap, used for filtering | Optional | Enum | OPEN or CLOSED | FALSE | OPEN |
gap_raf_score | Risk adjustment factor associated with the gap | Optional | Numeric | Decimal values only (no dashes or symbols) | TRUE | 2.659 |
gap_source | Origin or source of the gap data | Optional | String | Up to 250 characters | TRUE | 2024 claims |
last_recorded_dos | Most recent date of service related to the diagnosis | Optional | Date | YYYY-MM-DD | TRUE | 1990-07-19 |
last_recorded_npi | NPI of the most recent provider associated with the diagnosis | Optional | Numeric | 10-digit NPI | TRUE | 1234567890 |
last_recorded_npi_name | Name of the provider associated with the most recent service | Optional | String | Letters only, up to 50 characters | TRUE | John Smith |
notes | Free-text field for additional context or comments on the gap | Optional | String | Up to 250 characters | TRUE | Please address all suggested gaps |
Care Insights Data Schema
The table below outlines the required structure and accepted data types for the Care Insights file:
Field Name | Description | Required? | Type | Valid Values/Format | UI display | Example |
---|---|---|---|---|---|---|
patient_first_name | Patient's first name | Required | String | Letters only, recommended up to 50 characters | TRUE | John |
patient_last_name | Patient's last name | Required | String | Letters only, recommended up to 50 characters | TRUE | Doe |
patient_unique_id | Unique identifier assigned by the customer for the patient. Used to ensure accurate data display, billing, and reporting across Vim systems | Required | String | Letters + digits, recommended up to 50 characters | FALSE | 1234qwehce8fyw4fh |
patient_dob | Patient's date of birth | Required | Date | YYYY-MM-DD | TRUE | 1990-07-19 |
patient_insurance_id | Patient's health plan (member/subscriber ID) | Conditional - At least one of patient_insurance_id, patient_ehr_id, or patient_zip_code must be provided | String | Recommended up to 50 characters | FALSE | 123445455 |
patient_ehr_id | Patient's unique EHR identifier | Conditional - Same as above | String | Recommended up to 50 characters | FALSE | a1b2c3d4 |
patient_zip_code | Patient's Zip code | Conditional - Same as above | String | xxxxx,xxxxx-xxxx or xxxxxxxxx | FALSE | 90210 |
patient_insurer | Patient's insurance provider name | Optional | String | Recommended up to 50 characters | FALSE | United Health Care |
patient_state | Patient's U.S. state of residence | Optional | String | Two-letter U.S. state code | FALSE | FL |
insight_unique_id | Unique identifier per insight and patient assigned by the customer, representing a single insight card in the application. Enables user interaction, tracking, and management | Required | String | Recommended up to 50 characters | FALSE | fhipdusnyr98cenv485j |
insight_category | The category of the insight | Required | Enum | RISK, QUALITY, RX, SDOH, CARE MANAGEMENT, UTILIZATION, ADT or CLINICAL INSIGHTS | TRUE | QUALITY |
insight_title | The name of the insight as it will be displayed in the application | Required | String | Recommended up to 100 characters | TRUE | Controlling High Blood Pressure |
insight_code | The code of the insight, will be displayed in the application next to the title | Optional | String | Recommended value from an official code set | TRUE | CBP |
insight_description | General information about the insight | Optional | String | Recommended up to 250 characters | TRUE | Assesses adults 18–85 years of age who had a diagnosis of hypertension and whose blood pressure was adequately controlled (<140/90 mm Hg) |
insight_type | The type/ program of the insights (HEDIS, ACO, STAR etc.) | Optional | String | Recommended value of a standardized terminology | TRUE | HEDIS |
medical_codes | The medical codes related to the insight (e.g. CPT/ ICD). Each medical code should have a system code and description | Optional | Array | [{"medical_code_system": "string", "medical_code": "string", "medical_code_description": "string"}] | TRUE | [{"medical_code_system": "CPT", "medical_code": "3074F", "medical_code_description": "Systolic BP < 130 mm Hg}] |
insight_date | Most recent date of service related to the insight | Optional | Date | YYYY-MM-DD | TRUE | 2024-07-19 |
insight_provider_npi | NPI of the most recent provider associated with the insight | Optional | Numeric | 10-digit NPI | TRUE | 1234567890 |
insight_provider_name | Name of the provider associated with the most recent service | Optional | String | Letters only, recommended up to 50 characters | TRUE | John Smith |
insight_source | The source of the insight | Optional | String | Recommended up to 250 | TRUE | 2024 claims |
insight_required_action | The action that is expected next by the provider | Optional | String | Recommended up to 100 characters | ||
notes | Free-text field for additional context or comments on the gap | Optional | String | Recommended up to 250 characters | TRUE | Please address all suggested gaps |
custom_field_<field_name> | Additional customized and specific information to be presented in the application.The title of the field will be the <field_name> | Optional | To be defined per custom field | Recommended up to 250 characters | TRUE | custom_field_<Total_RAF> 2.56 |
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:
- The file is not received in the expected format, naming convention, or delimiter
- The file is empty
- The file is missing headers
- The file is missing a required column
- Data types in the file do not match the definitions outlined or agreed upon
- 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:
- Any required fields are empty
- The unique patient ID or gap/ insdight ID is not unique (all duplicate rows will be excluded)
- At least one of the following fields is missing: member_id, ehr_patient_identifier, or zip_code
Failed 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/ insight closure and sends structured feedback files back to the customer. These files support ongoing reporting and data quality improvements by indicating which gaps/insights 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:
- File name - <customer_name>YYYY_MM_DD__HH_MM_SS<insight_type_name>_report
- File type - CSV
- File delimiter - Pipe, Commac can also be supported
- Cadence - Daily, weekly or monthly to your preference
- Recommendation - Align with the cadence of your file submissions
- Coverage timeframe - Day, week, or month to your preference
- Recommendation - Align with the cadence of your file submissions
- 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 gaps and insights datasets. Feedback files are generated and shared separately for each data 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 Feedback file:
Field Name | Description | Required? | Type | Diagnosis Gaps Example | insight Example |
---|---|---|---|---|---|
organization_name | Name of the organization in session, as defined in Vim's system | Required | String | Scott's Clinic | Scott's Clinic |
vim_organization_key | Unique identifier for the organization in Vim | Required | String | 8i7owzgbgo6zJHYNxkNLRc | 8i7owzgbgo6zJHYNxkNLRc |
organization_tins | The TINs of organization in session | Optional | String | 438759 | 438759 |
ehr_type | The EHR system in session | Required | String | ||
user_first_name | First name of the user in session | Optional | String | Atena | Atena |
user_last_name | Last name of the user in session | Optional | String | Smith | Smith |
ehr_username | EHR username of the user in session | Optional | String | scott.smith | scott.smith |
user_npi | NPI of the user in session | Optional | String (10-digit) | 1848495833 | 1848495833 |
user_roles | The roles of the user, as degined in the Vim system | Optional | String | Medical Doctor | Medical Doctor |
encounter_id | ID of the patient's EHR encounter associated with the session | Optional | String | 859574 | 859574 |
encounter_date | Date of the patient's EHR encounter associated with the session (based on the organization's timezone) | Optional | Date (YYYY-MM-DD) | 2023-10-17 | 2023-10-17 |
encounter_npi | The NPI of the patient's EHR encounter associated with the session | Optional | String (10-digit) | 1495738475 | 1495738475 |
gap_system | Coding system of the gap applicable to Diagnosis Gaps only | Required for Diagnosis Gaps only | String | hcc | N/A |
gap_id | The unique ID of the gap/insight selected during the session | Required | String | 32fn48f | 347g4rg |
gap_code | The code of the gap/insight selected during the session | Required | String | 82 | CBP |
gap_description | The description of the gap selected during the session | Optional | String | Assess Drug Dependence | Controlling Blood Pressure |
selected_medical_codes | The medical code(s) selected during the session | Optional | String | ||
action_timestamp | The date and time of the reported action (EST) | Required | YYYY-MM-DD HH:MM:SS | 25-07-06 08:42:22 | |
25-07-06 08:42:22 | |||||
action_type | The type of the reported action | Required | text | accept | dismiss |
action_reason | The reason of the reported action | Optional | String | ADD | EVALUATE_NEXT_VISIT |
action_additional_comments | The free text added by the user for the reported action. Available only for the "dismiss" action_type | Optional | String | not seen today | |
vim_patient_token | The unique encrypted Vim internal patient identifier | Required | String | fj958tu94jgieorjf | fj958tu94jgieorjf |
patient_customer_id | The unique customer internal patient identifier received by the customer | Required | String | 738463 | 738463 |
- 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].