> ## Documentation Index
> Fetch the complete documentation index at: https://ekacare-mintlify-efa94f7d.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Java SDK

# 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

```xml theme={null}
<dependency>
    <groupId>care.eka</groupId>
    <artifactId>ekacare-java-sdk</artifactId>
    <version>latest-version</version>
</dependency>
```

#### Gradle

```groovy theme={null}
implementation 'care.eka:ekacare-java-sdk:latest-version'
```

### Option 2: Direct download

Download the Eka Java SDK from Maven repository [Here](https://central.sonatype.com/artifact/care.eka/ekacare-java-sdk)

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

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

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

```bash theme={null}
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:

```java theme={null}
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:

```java theme={null}
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"));

// 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:

```json theme={null}
{
  "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:

```java theme={null}
// 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:

```java theme={null}

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"));

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

* [Eka Care Java SDK Examples Repository](https://github.com/eka-care/eka-java-sdk-examples/)
* [Eka Care Developer Documentation](https://developer.eka.care/)
* [API Reference for Webhooks](https://developer.eka.care/api-reference/connect/webhooks/register-webhook)
* [API Reference for Ekascribe](https://developer.eka.care/api-reference/health-ai/ekascribe/retrieve-transcribe)

## 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](mailto:support@eka.care).