Forward Deployment

#Introduction

Flexpa Forward Deployment is our collaborative service where our engineers work directly with your team to implement Flexpa into your application. This guide provides a detailed overview of the integration process, requirements, and best practices to ensure a smooth and successful implementation.

This collaborative approach:

Accelerates your implementation timeline (typically 50-75% faster)
Reduces engineering burden on your team
Provides expert guidance throughout the process
Facilitates hands-on knowledge transfer to your engineering team
Enables real-time troubleshooting and decision-making

#Integration Architecture Overview

A complete Flexpa integration involves several key components working together to enable patient data access:

Frontend Layer: Handles user consent UI and initial token acquisition
Backend Processing: Manages token exchange and API interactions
Storage Layer: Stores consents and FHIR data securely
Application Layer: Retrieves and presents data to users

These components work together in a flow that starts with patient consent and ends with your application accessing and utilizing their health records.

Diagram of complete consent and records query

#Implementation Approach

We recommend a backend-first implementation approach for Flexpa integrations. This strategy prioritizes building the foundational components before adding the user-facing elements:

Start with backend and storage infrastructure - Implement token exchange, FHIR resource handling, and data storage before frontend components
Build application logic next - Develop the business logic that processes and utilizes health data
Add frontend components last - Implement the consent UI after backend systems are tested and operational

This approach offers several advantages:

Ensures critical data handling capabilities are robust before user interactions begin
Allows thorough testing of backend components with test tokens
Reduces integration complexity by validating each layer independently
Enables faster iterations on the user experience once data flows are established
Accelerates time-to-value by leveraging Flexpa's real-world testing panel to validate your implementation with actual payer data before frontend deployment
Gets your business capabilities operational sooner with production-quality data processing

The frontend implementation is typically the most straightforward part of a Flexpa integration, with our Link component handling most of the complexity of user consent flows. By focusing on backend components first, you can ensure that when users begin connecting their health plans, your system is fully prepared to securely process and utilize their data.

#Implementation Phases and Timeline

A typical Forward Deployment implementation follows these phases:

#Phase 1: Infrastructure & Planning (1-3 days)

Most intensive collaborative portion requiring significant team engagement
In-person collaboration strongly recommended for more effective decision-making
Review real user field test data
Infrastructure decisions finalized
Environment access established
Requirements defined and documented
Project timeline established

#Phase 2: Data Retrieval & Storage Implementation (2-10 days)

Consent management implemented
FHIR resource retrieval implemented
Storage solution implemented
Data access layer implemented

#Phase 3: Frontend & Authentication (1-2 days)

Frontend consent flow implemented
Token exchange mechanism tested
Error handling implemented
Initial integration tests completed

End-to-end testing
Documentation finalized
Knowledge transfer sessions
Final adjustments and optimizations

The timeline can vary based on your specific requirements, architecture complexity, and team availability. Our goal is to minimize the impact on your development team while ensuring a high-quality integration.

#Implementation Overview

#Backend Components

The backend portion of your Flexpa integration requires several essential components:

#1. Token Exchange Service

A secure service to exchange public tokens for access tokens via the Flexpa API
Proper error handling and retry logic

Store access tokens, refresh tokens (if required), and authorization IDs
Track consent state and manage refresh cycles
Associate consents with your user identifiers

#3. FHIR Data Retrieval and Storage

Request and process health records via the Flexpa API
Process and store FHIR resources

#4. Token Refresh Mechanism

Implement access token refresh
Update stored credentials after refresh
Handle failed refresh scenarios

#5. Data Access Layer

Create endpoints for retrieving health records
Transform data to match your application requirements
Implement appropriate access controls

Token Exchange Example

import FlexpaClient from '@flexpa/node-sdk'

async function exchangeToken(publicToken) {
  try {
    const client = await FlexpaClient.fromExchange(
      publicToken, 
      process.env.FLEXPA_SECRET_KEY
    );
    
    const accessToken = client.getAccessToken();
    const authorizationId = client.getAuthorizationId();
    
    // Store these securely in your database
    await storeConsent({
      accessToken,
      authorizationId,
      userId: 'your-user-id'
    });
    
    return { success: true };
  } catch (error) {
    console.error('Token exchange failed:', error);
    return { success: false, error };
  }
}

#Frontend Implementation

The frontend component of your integration primarily involves implementing Flexpa Link to facilitate the user consent flow:

Strategic placement within your application's user workflow
Clear consent language explaining the purpose

#2. User Identification

Implement user.externalId for cross-application tracking
Ensure consistent user identification across your systems

#3. Integration Methods

Integrate the Consent SDK via the @flexpa/node-sdk package with OAuth 2.0 PKCE. See the Quickstart for implementation examples.

Start OAuth Flow

import FlexpaClient from '@flexpa/node-sdk';

async function startOAuthFlow() {
  // Generate PKCE parameters
  const codeVerifier = await FlexpaClient.generateCodeVerifier();
  const codeChallenge = await FlexpaClient.generateCodeChallenge(codeVerifier);

  // Store verifier for callback
  sessionStorage.setItem('flexpa_code_verifier', codeVerifier);

  // Build authorization URL and redirect
  const authUrl = FlexpaClient.buildAuthorizationUrl({
    publishableKey: 'pk_test_...',
    redirectUri: 'https://yourapp.com/callback',
    codeChallenge,
    externalId: 'usr_1234',
  });

  window.location.href = authUrl;
}

For detailed descriptions of all configuration options, see our Consent SDK documentation.

#Key Infrastructure Decisions

Before beginning the implementation, several key decisions need to be made about your integration architecture:

#1. Storage Infrastructure

You'll need to decide how to store consents and health records:

#Database Options:

Relational Databases (PostgreSQL, MySQL):

Benefits: ACID compliance, transaction support
Considerations: Query performance with large FHIR resources

Document Databases (MongoDB, DynamoDB):

Benefits: Native JSON storage, schema flexibility
Considerations: Query complexity, consistency models

Object Storage (S3):

Benefits: Unlimited scalability, cost-effectiveness
Considerations: Additional retrieval logic required

FHIR Server (Medplum, etc.):

Benefits: Native FHIR support, standardized API
Considerations: Additional infrastructure component

We generally recommend using object storage (like S3) for FHIR resources and a relational database for consent management when initially starting. This approach offers a good balance of performance, cost, and operational simplicity.

Storage Decision Guide

Simple needs, existing SQL DB:
Use your existing relational DB for consents and S3 for FHIR resources
Complex needs, FHIR queries:
Consider a dedicated FHIR server like Medplum
Serverless architecture:
DynamoDB for consents, S3 for FHIR resources

#2. Schema Design

Effective schema design is crucial for managing consents and FHIR resources. The schemas below provide a starting point for your implementation. Your actual schema design may vary based on your specific requirements, existing infrastructure, and application needs.

Field	Type	Description
id	UUID/string	Primary identifier for consent
createdAt	datetime	Creation timestamp
updatedAt	datetime	Last update timestamp
userId	string	Your application's user ID
authorizationId	string	Flexpa's authorization ID
patientId	string	FHIR patient ID (recommended)
accessToken	string	OAuth access token (encrypted)
refreshToken	string	OAuth refresh token (encrypted)
refreshedAt	datetime	Last token refresh timestamp
state	enum	Current consent state

State values might include:

Exchanging: Initial token exchange in progress
Retrieving: Fetching health records
Ready: Active and available for use
Errored: Failed authentication or retrieval
Refreshing: Token refresh in progress

#FHIR Resource Storage Example

If storing FHIR resources in a database rather than object storage:

Field	Type	Description
id	UUID/string	Resource identifier
createdAt	datetime	When resource was stored
resourceType	string	FHIR resource type
authorizationId	string	Associated authorization ID
resource	text	Complete FHIR resource payload

We don't recommend storing FHIR resources as JSON in a relational database. The complex schema and large size of FHIR resources can lead to performance issues. For relational databases, store the resource as text instead.

#3. Service Architecture

Decide how to integrate Flexpa into your application architecture:

#Options:

Dedicated Flexpa Service or Services:

A separate service or collection of microservices handling all Flexpa interactions
Benefits: Clear separation of concerns, isolated scalability
Considerations: Additional service to manage

Integrated Approach:

Build Flexpa functionality into existing services
Benefits: Simplified architecture, fewer services
Considerations: Potential coupling of concerns

Hybrid Approach:

Initial token exchange in existing service, dedicated service for FHIR data
Benefits: Balance of simplicity and separation
Considerations: Existing architecture

Your decision should align with your organization's existing architectural patterns, frameworks, and operational practices.

#Common Integration Challenges

Being aware of potential challenges can help ensure a smooth integration:

#Infrastructure Complexity

Multiple deployment environments
Service discovery and networking
Authentication and authorization

#Data Handling

Varied FHIR resource structures
Large response handling
Efficient storage and retrieval

#Operational Considerations

Monitoring and alerting
Error recovery procedures
Performance at scale

#Team Coordination

Decision-making authority
Access to necessary resources
Maintaining implementation momentum

Our Forward Deployment engineers have experience navigating these challenges across many different environments and architectures. We'll work with you to anticipate and address issues before they impact your implementation.

#Pre-Integration Questionnaire

To prepare for a successful Forward Deployment, please consider these questions:

#Data Requirements

Which specific FHIR resources do you need to access?
How frequently will data be accessed?
What data transformations are required for your use case?

#Infrastructure Context

What are your current deployment patterns?
Which storage technologies do you prefer?
What authentication mechanisms are in place?

#Team Readiness

Who will maintain this integration after implementation?
What is your team's familiarity with FHIR and healthcare data?
Who are the key decision-makers for architectural choices?

#Timeline Expectations

What is your target go-live date?
What is your team's availability for collaborative development?
What are your testing requirements and timeline?

Your Flexpa Forward Deployed Engineer will guide you through these questions in detail before the technical implementation begins.

#Best Practices from Successful Integrations

Based on our experience with numerous successful integrations, we recommend:

#Start with Data Needs Analysis

Begin by defining exactly what data your application requires
Work backward from business use cases to define technical requirements

#Document Infrastructure Early

Map out storage, deployment, and service architecture before coding
Align with your organization's existing patterns

#Cross-Functional Involvement

Include product, engineering, and compliance stakeholders
Ensure alignment on requirements and approach

#Focused Engineering Time

Dedicate uninterrupted engineering resources during implementation
Plan for collaborative working sessions

#Iterative Approach

Build and test incrementally
Validate with real data early in the process