> ## Documentation Index
> Fetch the complete documentation index at: https://developer.eka.care/llms.txt
> Use this file to discover all available pages before exploring further.
# TS SDK
> Complete implementation guide for the Assessment TS SDK
# Assessment TS SDK Implementation
This guide provides everything you need to integrate the Self Assessment SDK into your application.
## Overview
The Self Assessment SDK allows you to integrate intelligent assessment workflows into your healthcare applications. It provides:
* **Interactive Assessments**: Run dynamic, workflow-based patient assessments
* **Flexible Workflows**: Support for multiple assessment workflows and categories
## Installation
### Prerequisites
* A modern web browser
* A web server or development environment
* Valid authentication tokens from your Self Assessment provider
### Setup
Add the SDK script directly to your HTML:
```html theme={null}
Self Assessment Integration
```
## Core Functions
### 1. runSaApp
Initializes and runs a Self Assessment application.
**Parameters:**
* `workflow_id` (number, required): The ID of the assessment workflow to run
* `container_id` (string, required): The HTML element ID where the assessment will be rendered
* `auth_token` (string, required): JWT authentication token for API access
* `refresh_token` (string, required): Token used to refresh the auth token when it expires
* `params` (object, required): Patient parameters for the assessment
* `age` (number, required): Patient's age
* `gender` (string, required): Patient's gender (e.g., "M", "F", "O")
* `practice_info` (object, required): Practice and patient identification. See [Practice Info Configuration](#practice-info-configuration) below
* `transaction_id` (string, optional): Unique transaction identifier
* `onEndCallback` (function, optional): Callback function called when assessment ends
* `onSaRedirectCallback` (function, optional): Callback function called when assessment redirects
* `onSaSubmitCallback` (function, optional): Callback function called when assessment is submitted
* `onSaInitCallback` (function, optional): Callback function called when assessment is initialized
#### Practice Info Configuration
The `practice_info` object is required and has two different use cases:
When a patient is taking the assessment for themselves:
**Required fields (at least one must be provided):**
* `patient_uuid` (string): Unique identifier for the patient
* `unique_identifier` (string): Alternative unique identifier for the patient
```javascript theme={null}
practice_info: {
patient_uuid: "9531778f-030c-11223344-38488c",
unique_identifier: "17345678765"
}
```
You can provide either `patient_uuid`, `unique_identifier`, or both.
When a doctor is conducting the assessment for a patient:
**Required fields:**
* At least one patient identifier:
* `patient_uuid` (string): Unique identifier for the patient
* `unique_identifier` (string): Alternative unique identifier for the patient
* `practitioner_uuid` (string): Unique identifier for the doctor/practitioner
```javascript theme={null}
practice_info: {
practitioner_uuid: "161461111111111",
patient_uuid: "9531778f-030c-11223344-38488c",
unique_identifier: "17345678765"
}
```
When `practitioner_uuid` is included, the assessment is associated with the doctor's practice.
**Examples:**
```javascript theme={null}
// Patient-initiated assessment
window.runSaApp({
workflow_id: 4014,
container_id: "sa-container",
auth_token: "your-jwt-token",
refresh_token: "your-refresh-token",
params: {
age: 25,
gender: "M",
},
practice_info: {
patient_uuid: "9531778f-030c-11223344-38488c",
unique_identifier: "17345678765",
},
transaction_id: "appt_1234",
onSaInitCallback: (params) => {
console.log("Assessment initialized:", params);
},
});
// Doctor-initiated assessment
window.runSaApp({
workflow_id: 4014,
container_id: "sa-container",
auth_token: "your-jwt-token",
refresh_token: "your-refresh-token",
params: {
age: 25,
gender: "M",
},
practice_info: {
practitioner_uuid: "161461111111111",
patient_uuid: "9531778f-030c-11223344-38488c",
unique_identifier: "17345678765",
},
transaction_id: "appt_1234",
onSaInitCallback: (params) => {
console.log("Assessment initialized:", params);
},
});
```
### 2. closeSaApp
Closes the currently running Self Assessment application.
**Example:**
```javascript theme={null}
window.closeSaApp();
```
### 3. showSaSubmission
Displays assessment submission data in a modal or container.
**Parameters:**
* `container_id` (string, required): The HTML element ID where the submission will be displayed
* `auth_token` (string, required): JWT authentication token for API access
* `refresh_token` (string, required): Token used to refresh the auth token when it expires
* `assessment_ids` (string\[], required): Array of assessment IDs to display
**Example:**
```javascript theme={null}
window.showSaSubmission({
container_id: "sa-container",
auth_token: "your-jwt-token",
refresh_token: "your-refresh-token",
assessment_ids: ["sa_250387576868696698"],
});
```
### 4. closeSaSubmissionApp
Closes the currently displayed submission application.
**Example:**
```javascript theme={null}
window.closeSaSubmissionApp();
```
### 5. fetchAssessment
Fetches assessment data from the server.
**Parameters:**
* `status` (string, required): The status of assessments to fetch (e.g., 'COMPLETED', 'PENDING')
* `unique_identifier` (string, required): Unique identifier for the assessment
**Example:**
```javascript theme={null}
window
.fetchAssessment({
status: "COMPLETED",
unique_identifier: "17345678765",
})
.then((response) => {
if (response.data) {
console.log("Assessment data:", response.data);
} else {
console.error("Error:", response.error);
}
});
```
### 6. getWorkflowList
Fetches the list of available workflows.
**Parameters:**
* `category` (string, optional): Optional category filter for workflows
**Example:**
```javascript theme={null}
// Get all workflows
window.getWorkflowList().then((response) => {
console.log("All workflows:", response.workflows);
});
// Get workflows by category
window.getWorkflowList({ category: "test" }).then((response) => {
console.log("Test workflows:", response.workflows);
});
```
## Callback Functions
### onSaInitCallback
Called when the assessment is successfully initialized and ready to start.
**Parameters:**
```typescript theme={null}
{
success: boolean;
data?: {
assessment_id: string;
workflow_id: number;
};
error?: string;
}
```
**Example:**
```javascript theme={null}
const onSaInitCallback = (params) => {
if (params.success) {
console.log("Assessment initialized successfully");
console.log("Assessment ID:", params.data.assessment_id);
console.log("Workflow ID:", params.data.workflow_id);
} else {
console.error("Failed to initialize assessment:", params.error);
}
};
```
### onSaCloseCallback (onEndCallback)
Called when the assessment is closed or ended by the user.
**Parameters:**
```typescript theme={null}
{
success: boolean;
data?: {
assessment_id: string;
workflow_id: number;
};
error?: string;
}
```
**Example:**
```javascript theme={null}
const onSaCloseCallback = (params) => {
if (params.success) {
console.log("Assessment closed successfully");
console.log("Final Assessment ID:", params.data.assessment_id);
} else {
console.error("Assessment closed with error:", params.error);
}
};
```
### onSaSubmitCallback
Called when the user submits the assessment (completes all questions).
**Parameters:**
```typescript theme={null}
{
data?: {
assessment_id: string;
workflow_id: number;
};
error?: string;
}
```
**Example:**
```javascript theme={null}
const onSaSubmitCallback = (params) => {
if (params.data) {
console.log("Assessment submitted successfully");
console.log("Submitted Assessment ID:", params.data.assessment_id);
} else {
console.error("Assessment submission failed:", params.error);
}
};
```
### onSaRedirectCallback
Called when the assessment redirects to a different workflow.
**Parameters:**
```typescript theme={null}
{
success: boolean;
data?: {
assessment_id: string;
workflow_id: number;
new_workflow_id: number;
};
error?: string;
}
```
**Example:**
```javascript theme={null}
const onSaRedirectCallback = (params) => {
if (params.success) {
console.log("Assessment redirected to new workflow");
console.log("Original Workflow ID:", params.data.workflow_id);
console.log("New Workflow ID:", params.data.new_workflow_id);
} else {
console.error("Assessment redirect failed:", params.error);
}
};
```
## Complete Implementation Example
```html theme={null}
Self Assessment Complete Example
Self Assessment SDK Demo
```
## Type Definitions
### TRunSaApp
```typescript theme={null}
interface TRunSaApp {
workflow_id: number;
container_id: string;
auth_token: string;
refresh_token: string;
params: {
age: number;
gender: string;
[key: string]: any;
};
practice_info: {
patient_uuid?: string;
unique_identifier?: string;
practitioner_uuid?: string;
};
transaction_id?: string;
onEndCallback?: (params: {
success: boolean;
data?: { assessment_id: string; workflow_id: number };
error?: string;
}) => void;
onSaRedirectCallback?: (params: {
success: boolean;
data?: {
assessment_id: string;
workflow_id: number;
new_workflow_id: number;
};
error?: string;
}) => void;
onSaSubmitCallback?: (params: {
data?: { assessment_id: string; workflow_id: number };
error?: string;
}) => void;
onSaInitCallback?: (params: {
success: boolean;
data?: { assessment_id: string; workflow_id: number };
error?: string;
}) => void;
}
```
### TShowSaSubmission
```typescript theme={null}
interface TShowSaSubmission {
container_id: string;
auth_token: string;
refresh_token: string;
assessment_ids: string[];
}
```
### Assessment Response
```typescript theme={null}
interface AssessmentResponse {
data: {
conversations: Array<{
practitioner_uuid: string | null;
patient_uuid: string;
unique_identifier: string;
transaction_id: string;
conversations: Array<{
conversationid: string;
created_at: string;
}>;
}>;
} | null;
error?: {
error_code: string;
display_message: string;
message: string;
};
}
```
### Workflow List Response
```typescript theme={null}
interface WorkflowListResponse {
workflows: Array<{
wflow_id: number;
wflow_name: string;
wflow_desc: string | null;
category: string;
}>;
error?: {
error_code: string;
display_message: string;
message: string;
};
}
```
## Error Handling
All functions return consistent error objects with:
* `error_code`: Machine-readable error code
* `display_message`: User-friendly error message
* `message`: Technical error details
**Common Error Codes:**
* `AUTH_ERROR`: Authentication failed
* `NETWORK_ERROR`: Network connection issues
* `FETCH_ERROR`: Data fetching failed
* `VALIDATION_ERROR`: Invalid parameters
* `UNKNOWN_ERROR`: Unexpected errors
## Troubleshooting
### Common Issues
#### 1. Container Not Found
**Problem**: Assessment doesn't appear in the container.
**Solution**:
* Ensure the container element exists before calling `runSaApp`
* Check that `container_id` matches the actual HTML element ID
* Make sure the container has proper dimensions
```html theme={null}
```
#### 2. Authentication Errors
**Problem**: Assessment fails to initialize due to auth issues.
**Solution**:
* Verify your `auth_token` and `refresh_token` are valid
* Check that tokens haven't expired
* Ensure you're using the correct authentication flow for Self Assessment
#### 3. Workflow Not Found
**Problem**: Assessment fails with workflow-related errors.
**Solution**:
* Verify the `workflow_id` exists and is accessible
* Use `getWorkflowList()` to see available workflows
* Check if the workflow requires specific parameters
```javascript theme={null}
// Check available workflows
window.getWorkflowList().then((response) => {
console.log("Available workflows:", response.workflows);
});
```
#### 4. Missing Required Parameters
**Problem**: Assessment fails to initialize due to missing parameters.
**Solution**:
* Ensure `params` object includes both `age` and `gender`
* Verify `practice_info` contains at least one patient identifier (`patient_uuid` or `unique_identifier`)
* For doctor-initiated assessments, include `practitioner_uuid`
```javascript theme={null}
// Correct: All required fields present
window.runSaApp({
workflow_id: 4014,
container_id: "sa-container",
auth_token: "your-jwt-token",
refresh_token: "your-refresh-token",
params: {
age: 25,
gender: "M"
},
practice_info: {
patient_uuid: "9531778f-030c-11223344-38488c"
}
});
```