Skip to main content

​
Overview

The HL7 Connectivity Providers Client is a Java Swing desktop application that enables healthcare providers to integrate with HL7 services. This guide will walk you through setting up, building, and running your first HL7 transaction.

​
Prerequisites

Before you begin, ensure you have:
  • Java Development Kit (JDK) 8 or higher
  • Apache Maven 3.6+
  • Git (for cloning the repository)
  • Valid API credentials (email, password, and API key)
  • Access to one of the environments: DEV, QA, PRE, or PRD

​
Quick Setup

1

Clone the Repository

Clone the source code to your local machine:
git clone <repository-url>
cd connectivity-providers-client
2

Build the Application

Use Maven to compile and package the application into an executable JAR:
mvn clean package
This command:
  • Compiles all Java source files
  • Runs the test suite
  • Creates a shaded (uber) JAR with all dependencies included
  • Outputs the JAR to target/connectivity-providers-client-1.0-SNAPSHOT.jar
The build process uses the maven-shade-plugin to create a single executable JAR file containing all dependencies. This makes deployment and distribution much easier.
3

Run the Application

Launch the application using Java:
java -jar target/connectivity-providers-client-1.0-SNAPSHOT.jar
Or use the Maven exec plugin:
mvn exec:java -Dexec.mainClass="com.hl7client.Main"
The application will start and display the login screen.
4

Login to the System

On the login screen, provide:
  • Email: Your user email address
  • Password: Your account password
  • API Key: Your organization’s API key
  • Environment: Select from DEV, QA, PRE, or PRD
Click the login button to authenticate.
The authentication process creates a device token and establishes a session. The application automatically handles token refresh to maintain your session.
5

Perform Your First Transaction

Once logged in, you can perform HL7 transactions:
  • Elegibilidad: Check patient eligibility
  • Registracion: Register a service provision
  • Cancelacion: Cancel a previously registered service
Select the transaction type, fill in the required fields, and submit.

​
Understanding the Login Flow

The authentication process follows this sequence: 
// From AuthService.java:36
public void login(
        String email,
        char[] password,
        String apiKey,
        Environment environment
) {
    // Create unique device identifier
    DeviceRequest device = createDevice();
    
    // Build login request
    LoginRequest request = new LoginRequest(
            apiKey,
            email,
            new String(password),
            device
    );
    
    // Send authentication request
    String url = EnvironmentConfig.getAuthUrl(environment);
    ApiResponse response = apiClient.post(url, jsonRequest, headers);
    
    // Parse response and initialize session
    LoginResponse loginResponse =
            JsonUtil.fromJson(response.getBody(), LoginResponse.class);
    
    initializeSession(loginResponse, environment, device);
}

​
Session Management

The application maintains your session through:
  1. SessionContext: Stores authentication token, environment, and user data
  2. SessionRefreshManager: Automatically refreshes your token before expiration
  3. AuthRefresher: Handles token refresh logic from AuthService.java:95
// From LoginController.java:42
public Hl7Result<Void> login(
        String email,
        char[] password,
        String apiKey,
        String environment
) {
    try {
        Environment env = Environment.valueOf(environment);
        authService.login(email, password, apiKey, env);
        
        // Clear sensitive data from memory
        clearPassword(password);
        
        if (loginListener != null) {
            loginListener.onLoginSuccess();
        }
        
        return Hl7Result.ok(null);
        
    } catch (Exception e) {
        return Hl7Result.error(
            Hl7Error.technical(
                e.getMessage(),
                Hl7ErrorOrigin.TRANSPORTE
            )
        );
    }
}

​
Making Your First HL7 Request

Here’s how to perform an eligibility check: 
// From Hl7Service.java:26
public Hl7Result<ElegibilidadResponse> consultarElegibilidad(
        ElegibilidadRequest request
) {
    return postHl7(
            EnvironmentConfig.getHl7ElegibilidadUrl(
                    SessionContext.getEnvironment()
            ),
            request,
            ElegibilidadResponse.class,
            this::validarElegibilidad
    );
}
The controller layer provides additional validation: 
// From Hl7Controller.java:18
public Hl7Result<ElegibilidadResponse> consultarElegibilidad(
        ElegibilidadRequest request
) {
    if (request == null) {
        return errorRequestInvalido("ElegibilidadRequest");
    }
    return hl7Service.consultarElegibilidad(request);
}

​
Application Startup Process

The application bootstraps in the following order: 
// From Main.java:11
public static void main(String[] args) {
    // Load dental data catalog
    com.hl7client.model.dental.DentalDataLoader.loadAll();
    
    // Start application on Swing EDT
    SwingUtilities.invokeLater(() -> {
        try {
            new Application().start();
        } catch (Exception e) {
            showFatalError(e);
        }
    });
}

// From Application.java:26
public void start() {
    // Initialize FlatLaf theme
    ThemeManager.getInstance().initialize();
    
    // Display login window
    openLogin();
}

​
Environment Configuration

The application supports four environments: 
// From Environment.java:3
public enum Environment {
    DEV,   // Development
    QA,    // Quality Assurance
    PRE,   // Pre-production
    PRD    // Production
}
Each environment has its own base URL configuration managed by EnvironmentConfig.java:12, which constructs endpoint URLs dynamically based on the selected environment.

​
Next Steps

Installation Details

Learn about system requirements, dependencies, and deployment options

Configuration

Configure environments, API endpoints, and application settings

HL7 Transactions

Detailed guide on eligibility, registration, and cancellation operations

API Reference

Complete API documentation and code examples

​
Troubleshooting

If you encounter authentication errors, verify:
  • Your credentials are correct
  • The selected environment matches your account access
  • Your API key is active and not expired
  • Network connectivity to the environment’s base URL

​
Common Issues

Build Failures If Maven build fails, ensure:
  • Java 8+ is installed and JAVA_HOME is set correctly
  • Maven 3.6+ is installed
  • You have internet connectivity for dependency downloads
Runtime Errors If the application crashes on startup:
  • Check Java version: java -version
  • Verify the JAR was built successfully
  • Review logs for specific error messages
Session Expiration Sessions are automatically refreshed, but if you see session expired messages:
  • Check your network connection
  • Verify the authentication server is accessible
  • Re-login with valid credentials

​
Support

For additional help:
  • Review the complete Installation Guide
  • Check the API documentation
  • Contact your system administrator for access issues

Build docs developers (and LLMs) love

Get started for freeTalk to us