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
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
- 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.