Eka Care Ekascribe Java SDK Integration

This guide explains how to integrate the Eka Care Ekascribe Java SDK.

Overview

Eka Care provides an Ekascribe service that allows you to transcribe audio files into structured medical data. The Java SDK simplifies this integration process.

Quick Start

The integration process follows these main steps:

  1. Set up webhook registration (one-time setup)
  2. Install the SDK
  3. Implement authentication
  4. Upload audio files
  5. Process the webhook callback
  6. Retrieve and parse the Ekascribe results

Prerequisites

  • Java 8 or higher
  • Maven or Gradle for dependency management
  • Client credentials (client ID and secret) from Eka Care

Installation

You can add the Eka Care Java SDK to your project in two ways:

Option 1: Using dependency management

Maven

<dependency>
    <groupId>care.eka</groupId>
    <artifactId>ekacare-java-sdk</artifactId>
    <version>latest-version</version>
</dependency>

Gradle

implementation 'care.eka:ekacare-java-sdk:latest-version'

Option 2: Direct download

Download the Eka Java SDK from Maven repository Here

Step 1: Register Webhook (One-time Setup)

Before using the Ekascribe service, register a webhook to receive notifications when transcription is complete:

curl --request POST \
  --url https://api.eka.care/notification/v1/connect/webhook/subscriptions \
  --header 'Authorization: Bearer <auth_token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "event_names": [
      "v2rx.completed"
    ],
    "endpoint": "your-endpoint-url",
    "signing_key": "supersecretkey",
    "protocol": "https"
  }'

Step 2: Authentication

Initialize the client with your credentials and obtain access tokens:

import care.eka.EkaCareClient;
import com.fasterxml.jackson.databind.JsonNode;

// Initialize the client
EkaCareClient client = new EkaCareClient("your_client_id", "your_client_secret");

// Login to get tokens
JsonNode tokenResponse = client.getAuth().login();
String accessToken = tokenResponse.get("access_token").asText();
String refreshToken = tokenResponse.get("refresh_token").asText();

// Set access token manually if needed
client.setAccessToken(accessToken);

// Refresh token when needed
JsonNode refreshedTokens = client.getAuth().refreshToken(refreshToken);
String newAccessToken = refreshedTokens.get("access_token").asText();

Step 3: Upload Audio Files

Upload audio files for transcription:

import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;

// Collect all audio files in a list
List<String> audioFiles = new ArrayList<>();
audioFiles.add("<full file path>");
audioFiles.add("<full file path 2>");

// Set your own txn id
String transactionId = "unique_transaction_id";

//Custom keys , you'll get back the exact same in result API
Map<String, Object> extraData = new HashMap<>();
extraData.put("mode", "dictation");
extraData.put("uhid", "unique_patient_id");
extraData.put("hfid", "unique_health_facility_id");

// Define the output format for the V2RX action
Map<String, Object> outputFormat = new HashMap<>();
outputFormat.put("input_language", Arrays.asList("en-IN", "hi"));

// output template ids
Map<String, Object> templateMap1 = new HashMap<>();
templateMap1.put("template_id", "<your_template_id>");
templateMap1.put("language_output", "en-IN");
// set true if you need codified data (if out supports that)
templateMap1.put("codification_needed", true);

// Sample second template id
Map<String, Object> templateMap2 = new HashMap<>();
templateMap2.put("template_id", "clinical_notes_template");
templateMap2.put("language_output", "en-IN");

outputFormat.put("output_template", Arrays.asList(templateMap1, templateMap2));

// Keep this the same
String action = "ekascribe-v2";

// Upload files
JsonNode responses = client.getV2RX().upload(audioFiles, transactionId, action, extraData, outputFormat);

// Process responses
for (JsonNode response : responses) {
    // Handle response data as needed
}

Step 4: Handle Webhook Callback

When the transcription is complete, Eka Care will send a webhook notification to your registered endpoint. Here’s a sample of what you’ll receive:

{
  "event": "v2rx.completed",
  "data": {
    "transaction_id": "unique_transaction_id",
    "status": "completed",
    "session_id": "session_id_123",
  },
  "timestamp": "2023-07-20T10:30:00Z"
}

Step 5: Retrieve Ekascribe Results

After receiving the webhook notification, retrieve the transcription results:

// Get the transactionId from the webhook callback
String transactionId = "session_id_123";
String action = "ekascribe-v2"

// Fetch session status and results
JsonNode sessionStatus = client.getV2RX().getSessionStatus(transactionId, action);

// Sample response structure
'''{
    "data": {
        "output": [
            {
                "template_id": "eka_emr_template",
                "value": "base64_encoded_data",
                "type": "eka_emr",
                "name": "Eka EMR Format",
                "status": "success",
                "errors": [],
                "warnings": []
            }
        ],
        "additional_data": {}
    }
}'''

// Extract and decode the FHIR data
if (sessionStatus.has("data") &&
        sessionStatus.get("data").has("output") &&
        sessionStatus.get("data").get("output").isArray() &&
        sessionStatus.get("data").get("output").size() > 0) {

    JsonNode outputNode = sessionStatus.get("data").get("output");
    Integer step = 0;
    for (JsonNode node : outputNode) {
        if (node.has("value")) {
            step++;
            String encodedFhir = node.get("value").asText();
            byte[] decodedBytes = Base64.getDecoder().decode(encodedFhir);
            String fhirJson = new String(decodedBytes);
            System.out.println("Decoded Data " + step + " :" + fhirJson);
        } else {
            System.out.println("No value found in output node "+ step+ " :"+ node.toPrettyString());
        }
    }

}

Complete Example

Here’s a complete example integrating all the above steps:


import care.eka.EkaCareClient;
import com.fasterxml.jackson.databind.JsonNode;

import java.io.IOException;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;
import java.util.Arrays;
import java.util.Base64;

public class EkascribeIntegrationExample {
    public static void main(String[] args) {
        try {
            // Initialize the client
            EkaCareClient client = new EkaCareClient("your_client_id", "your_client_secret");
            
            // Authenticate
            authenticateClient(client);
            
            // Upload audio files

            // Collect all audio files in a list
            List<String> audioFiles = new ArrayList<>();
            audioFiles.add("<full file path>");
            audioFiles.add("<full file path 2>");

            // Set your own txn id
            String transactionId = "unique_transaction_id";

            Map<String, Object> extraData = new HashMap<>();
            extraData.put("mode", "dictation");

            //Custom keys , you'll get back the exact same in result API
            extraData.put("uhid", "unique_patient_id"); 
            extraData.put("hfid", "unique_health_facility_id");

            // Define the output format for the V2RX action
            Map<String, Object> outputFormat = new HashMap<>();
            outputFormat.put("input_language", Arrays.asList("en-IN", "hi"));

            // output template ids
            Map<String, Object> templateMap1 = new HashMap<>();
            templateMap1.put("template_id", "<your_template_id>");
            templateMap1.put("language_output", "en-IN");
            // set true if you need codified data (if out supports that)
            templateMap1.put("codification_needed", true);
            
            // Sample second template id
            Map<String, Object> templateMap2 = new HashMap<>();
            templateMap2.put("template_id", "clinical_notes_template");
            templateMap2.put("language_output", "en-IN");
            
            // Add both templates to the output_template list
            outputFormat.put("output_template", Arrays.asList(templateMap1, templateMap2));
            
            // Keep this the same
            String action = "ekascribe-v2";

            uploadAudioFiles(client, transactionId, action);
            
            // NOTE: At this point, wait for the webhook callback
            // This would typically be handled by your web server
            
            // Once webhook is received, fetch results
            // The sessionId would come from the webhook payload
            String transactionId = transactionId;
            getTranscriptionResults(client, transactionId, action);
            
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
    
    private static void authenticateClient(EkaCareClient client) throws IOException {
        JsonNode tokenResponse = client.getAuth().login();

        // Extras
        System.out.println("Access Token: " + tokenResponse.get("access_token").asText());
        System.out.println("Refresh Token: " + tokenResponse.get("refresh_token").asText());

        client.setAccessToken(tokenResponse.get("access_token").asText());

        // Refresh token when needed
        JsonNode refreshedTokens = client.getAuth().refreshToken(tokenResponse.get("refresh_token").asText());
        
        // Extras
        System.out.println("New Access Token: " + refreshedTokens.get("access_token").asText());
    }
    
    private static void uploadAudioFiles(EkaCareClient client, String transactionId, String action) throws IOException {
        List<JsonNode> responses = client.getV2RX().upload(audioFiles, transactionId, action, extraData, outputFormat);
        System.out.println("Upload Responses: " + responses.toString());
    }
    
    private static void getTranscriptionResults(EkaCareClient client, String sessionId, String action) throws IOException {
        JsonNode sessionStatus = client.getV2RX().getSessionStatus(sessionId, action);
        System.out.println("Session Status: " + sessionStatus.toPrettyString());
        
        if (sessionStatus.has("data") &&
                sessionStatus.get("data").has("output") &&
                sessionStatus.get("data").get("output").isArray() &&
                sessionStatus.get("data").get("output").size() > 0) {

            JsonNode outputNode = sessionStatus.get("data").get("output");
            Integer step = 0;
            for (JsonNode node : outputNode) {
                if (node.has("value")) {
                    step++;
                    String encodedFhir = node.get("value").asText();
                    byte[] decodedBytes = Base64.getDecoder().decode(encodedFhir);
                    String fhirJson = new String(decodedBytes);
                    System.out.println("Decoded Data " + step + " :" + fhirJson);
                } else {
                    System.out.println("No value found in output node "+ step+ " :"+ node.toPrettyString());
                }
            }

        }
    }
}

Additional Resources

Troubleshooting

Common Errors

  1. Authentication Failed: Verify your client ID and secret are correct
  2. File Upload Failed: Ensure file paths are valid and files are readable
  3. Webhook Not Received: Check your endpoint is publicly accessible and correctly registered

Support

For additional support, contact the Eka Care developer support team at support@eka.care.