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:

Set up webhook registration (one-time setup)
Install the SDK
Implement authentication
Upload audio files
Process the webhook callback
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

Available Template IDs

Eka Care supports multiple output templates for different medical documentation needs. Choose the appropriate template ID based on your requirements:

Template ID	Description	Use Case
`clinical_notes_template`	Comprehensive clinical notes with structured medical information	General clinical documentation, patient consultations
`eka_emr_template`	EMR-compatible format for electronic medical records	Integration with EMR systems
`transcript_template`	Basic transcription with minimal structuring	Simple audio-to-text conversion

Available model types

Model Type	Description
pro	Our most accurate model
lite	More performant model for lower latency

Supported Input Languages

Eka Care supports transcription in multiple languages. Specify the appropriate language ID in the input_language parameter:

Language ID	Language Name
`en-IN`	English (India)
`en-US`	English (United States)
`hi`	Hindi
`gu`	Gujarati
`kn`	Kannada
`ml`	Malayalam
`ta`	Tamil
`te`	Telugu
`bn`	Bengali
`mr`	Marathi
`pa`	Punjabi

If you’re not offering users a language change option in your UI, use auto_detect for the best results.

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("model_type", "lite");
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")); // If you're not offering users a language change option in your UI, use "auto_detect" for the best results.

// output template ids
Map<String, Object> templateMap1 = new HashMap<>();
templateMap1.put("template_id", "clinical_notes_template");
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", "eka_emr_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": "unique_transaction_id"
  },
  "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 = "unique_transaction_id";  // This comes from the webhook payload
String action = "ekascribe-v2";

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

// Sample response structure
'''{
    "data": {
        "output": [
            {
                "template_id": "clinical_notes_template",
                "value": "<base 64 encoded value>",
                "name": "Clinical Notes Template",
                "status": "success",
                "errors": [],
                "warnings": []
            }
        ]
    }
}'''

// Extract and decode the Template 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 templateId = node.get("template_id").asText();
            String templateName = node.get("name").asText();
            String encodedValue = node.get("value").asText();
            byte[] decodedBytes = Base64.getDecoder().decode(encodedValue);
            String templateJson = new String(decodedBytes);
            System.out.println("Template: " + templateName + " (" + templateId + ")");
            System.out.println("Decoded Data " + step + " :" + templateJson);
        } 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
            String transactionId = "unique_transaction_id";
            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
            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 {
        // Collect all audio files in a list
        List<String> audioFiles = new ArrayList<>();
        audioFiles.add("<full file path>");
        audioFiles.add("<full file path 2>");

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


        //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")); // If you're not offering users a language change option in your UI, use "auto_detect" for the best results.

        // output template ids
        Map<String, Object> templateMap1 = new HashMap<>();
        templateMap1.put("template_id", "clinical_notes_template");
        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", "eka_emr_template");
        templateMap2.put("language_output", "en-IN");
        
        // Add both templates to the output_template list
        outputFormat.put("output_template", Arrays.asList(templateMap1, templateMap2));
        
        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 templateId = node.get("template_id").asText();
                    String templateName = node.get("name").asText();
                    String encodedValue = node.get("value").asText();
                    byte[] decodedBytes = Base64.getDecoder().decode(encodedValue);
                    String templateJson = new String(decodedBytes);
                    System.out.println("Template: " + templateName + " (" + templateId + ")");
                    System.out.println("Decoded Data " + step + " :" + templateJson);
                } else {
                    System.out.println("No value found in output node "+ step+ " :"+ node.toPrettyString());
                }
            }

        }
    }
}

Additional Resources

Troubleshooting

Common Errors

Authentication Failed: Verify your client ID and secret are correct
File Upload Failed: Ensure file paths are valid and files are readable
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.

​Eka Care Ekascribe Java SDK Integration

​Overview

​Quick Start

​Prerequisites

​Installation

​Option 1: Using dependency management

​Maven

​Gradle

​Option 2: Direct download

​Available Template IDs

​Available model types

​Supported Input Languages

​Step 1: Register Webhook (One-time Setup)

​Step 2: Authentication

​Step 3: Upload Audio Files

​Step 4: Handle Webhook Callback

​Step 5: Retrieve Ekascribe Results

​Complete Example

​Additional Resources

​Troubleshooting

​Common Errors

​Support