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:

<!DOCTYPE html>
<html>
  <head>
    <title>Self Assessment Integration</title>
  </head>
  <body>
    <!-- Container for the Self Assessment app -->
    <div id="sa-container"></div>

    <!-- Include the Self Assessment SDK -->
    <script src="https://api.eka.care/sa-fe/main.js"></script>

    <script>
      // Your integration code will go here
    </script>
  </body>
</html>

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

Patient-Initiated Assessment

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

practice_info: {
  patient_uuid: "9531778f-030c-11223344-38488c",
  unique_identifier: "17345678765"
}

You can provide either patient_uuid, unique_identifier, or both.

Doctor-Initiated Assessment

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

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:

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

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:

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:

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:

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:

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

{
  success: boolean;
  data?: {
    assessment_id: string;
    workflow_id: number;
  };
  error?: string;
}

Example:

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:

{
  success: boolean;
  data?: {
    assessment_id: string;
    workflow_id: number;
  };
  error?: string;
}

Example:

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:

{
  data?: {
    assessment_id: string;
    workflow_id: number;
  };
  error?: string;
}

Example:

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:

{
  success: boolean;
  data?: {
    assessment_id: string;
    workflow_id: number;
    new_workflow_id: number;
  };
  error?: string;
}

Example:

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

<!DOCTYPE html>
<html>
  <head>
    <title>Self Assessment Complete Example</title>
    <style>
      body {
        font-family: Arial, sans-serif;
        margin: 20px;
      }
      #sa-container {
        width: 100%;
        height: 600px;
        border: 1px solid #ccc;
        margin: 20px 0;
      }
      .button {
        padding: 10px 20px;
        margin: 5px;
        cursor: pointer;
      }
    </style>
  </head>
  <body>
    <h1>Self Assessment SDK Demo</h1>

    <button class="button" onclick="startAssessment()">Start Assessment</button>
    <button class="button" onclick="showSubmissions()">Show Submissions</button>
    <button class="button" onclick="closeAssessment()">Close Assessment</button>
    <button class="button" onclick="fetchData()">Fetch Assessment Data</button>

    <div id="sa-container"></div>

    <script src="https://api.eka.care/sa-fe/main.js"></script>
    <script>
      // Configuration
      const config = {
        workflow_id: 4014,
        container_id: "sa-container",
        auth_token: "your-jwt-auth-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",
      };

      function startAssessment() {
        window.runSaApp({
          ...config,
          onSaInitCallback: (params) => console.log("Initialized:", params),
          onEndCallback: (params) => console.log("Closed:", params),
          onSaSubmitCallback: (params) => console.log("Submitted:", params),
          onSaRedirectCallback: (params) => console.log("Redirected:", params),
        });
      }

      function showSubmissions() {
        window.showSaSubmission({
          container_id: "sa-container",
          auth_token: config.auth_token,
          refresh_token: config.refresh_token,
          assessment_ids: ["sa_250387576868696698"],
        });
      }

      function closeAssessment() {
        window.closeSaApp();
      }

      function fetchData() {
        window
          .fetchAssessment({
            status: "COMPLETED",
            unique_identifier: "17345678765",
          })
          .then((response) => {
            if (response.data) {
              console.log("Assessment data:", response.data);
            } else {
              console.error("Error:", response.error);
            }
          });
      }
    </script>
  </body>
</html>

Type Definitions

TRunSaApp

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

interface TShowSaSubmission {
  container_id: string;
  auth_token: string;
  refresh_token: string;
  assessment_ids: string[];
}

Assessment Response

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

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

<div
  id="sa-container"
  style="width: 100%; height: 600px; border: 1px solid #ccc;"
></div>

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

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

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

​Assessment TS SDK Implementation

​Overview

​Installation

​Prerequisites

​Setup

​Core Functions

​1. runSaApp

​Practice Info Configuration

​2. closeSaApp

​3. showSaSubmission

​4. closeSaSubmissionApp

​5. fetchAssessment

​6. getWorkflowList

​Callback Functions

​onSaInitCallback

​onSaCloseCallback (onEndCallback)

​onSaSubmitCallback

​onSaRedirectCallback

​Complete Implementation Example

​Type Definitions

​TRunSaApp

​TShowSaSubmission

​Assessment Response

​Workflow List Response

​Error Handling

​Troubleshooting

​Common Issues

​1. Container Not Found

​2. Authentication Errors

​3. Workflow Not Found

​4. Missing Required Parameters

Assessment TS SDK Implementation

Overview

Installation

Prerequisites

Setup

Core Functions

1. runSaApp

Practice Info Configuration

2. closeSaApp

3. showSaSubmission

4. closeSaSubmissionApp

5. fetchAssessment

6. getWorkflowList

Callback Functions

onSaInitCallback

onSaCloseCallback (onEndCallback)

onSaSubmitCallback

onSaRedirectCallback

Complete Implementation Example

Type Definitions

TRunSaApp

TShowSaSubmission

Assessment Response

Workflow List Response

Error Handling

Troubleshooting

Common Issues

1. Container Not Found

2. Authentication Errors

3. Workflow Not Found

4. Missing Required Parameters