Augnito Ambient SDK

Use this typescript SDK to integrate Augnito’s Ambient Tech within your EMR. To get access credentials or know more about how Augnito Ambient can benefit you, please visit our website and connect with our sales team: https://augnito.ai/

Installation

Install the library in your project

Typescript

npm install augnitoambientsdk

Vanilla JS

use https://cdn.jsdelivr.net/npm/augnitoambientsdk@latest/dist/augnitoambientsdk.js to import the library from npm using CDN url.

Basic Usage

Import the library

Typescript

import { AugnitoAmbient, AmbientConfig } from "augnitoambientsdk";

Vanilla JS

import { AugnitoAmbient } from "https://cdn.jsdelivr.net/npm/augnitoambientsdk@latest/dist/augnitoambientsdk.js";

Create the configuration file and instantiate Augnito Ambient Manager

private ambientConfig: AmbientConfig = {
    server: '<your server>',
    subscriptionCode: '<your subscriptionCode>',
    accessKey: '<your accessKey>',
    userTag: '<your usertag>',
    enableLogs: false, // set to true to check sdk logs in the browser console
};

const augnitoAmbient = new AugnitoAmbient(ambientConfig);

For the provided subscription code, accesskey and usertag, any authentication failure will be returned in onError callback for all the APIs provided below

1- Get Note Parameters

• Get Region, Note Type and Gender

  Get all possible note-parameters (applicable categories and possible values) that are expected to be passed when creating a job (when doctor-patient consultation is started). These details are used to provide consultation SOAP notes with higher accuracy.

  //Returns JSON of Region, Note Type and Gender
  const noteParamsJson = augnitoAmbient.getNoteParams();

• Get Speciality and Visit Types

  Augnito allows the speciality-type and visit-types for the doctor-patient consultation mapped at the hospital organization level. This method returns the list of speciality-type or visit-type (based on the value of ConfigTypeId parameter) mapped for the user in the hospital-organization.

  All supported specialty-types and visit-types for the hospital-organization can be specified to Augnito team at the start of integration or as and when needed.

  At the start of recording it is necessary to pass the ConfigID of applicable (user can select one or default value to be sent) Speciality and VisitType in the noteparams string.

  Typescript

  try {
    //Get list of specialities enabled for organisation
    const specialities = await augnitoAmbient.getUserConfiguration(
      SettingsConfigType.SPECIALITY
    );
  } catch (err) {
    if (err instanceof HttpCodedError) {
      console.log(err.code, err.message);
    }
  }

  Vanilla JS

  import { SettingsConfigType } from "https://cdn.jsdelivr.net/npm/augnitoambientsdk@latest/dist/augnitoambientsdk.js";
  
  try {
    //Get list of specialities enabled for organisation
    const specialities = await augnitoAmbient.getUserConfiguration(
      SettingsConfigType["SPECIALITY"]
    );
  } catch (err) {
    if (err instanceof HttpCodedError) {
      console.log(err.code, err.message);
    }
  }

  Typescript

  try {
    //Get list of visit types enabled for organisation
    const visitTypes = await augnitoAmbient.getUserConfiguration(
      SettingsConfigType.VISIT_TYPE
    );
  } catch (err) {
    if (err instanceof HttpCodedError) {
      console.log(err.code, err.message);
    }
  }

  Vanilla JS

  import { SettingsConfigType } from "https://cdn.jsdelivr.net/npm/augnitoambientsdk@latest/dist/augnitoambientsdk.js";
  
  try {
    //Get list of visit types enabled for organisation
    const visitTypes = await augnitoAmbient.getUserConfiguration(
      SettingsConfigType["VISIT_TYPE"]
    );
  } catch (err) {
    if (err instanceof HttpCodedError) {
      console.log(err.code, err.message);
    }
  }

  Response JSON for each item of speciality and visit type has the following structure

  ID: number;
  ConfigID: number;
  Value: string;
  Description: string;
  IsSelected: boolean;
  IsDefault: boolean;

2- Toggle the client

Now all you have to do is toggle the status when you want to start/stop or pause/resume recording!

/**
 * @param filetype Type of file being uploaded, wav, mp3, etc. Ex: “filetype=wav“
 * @param noteparams Qualifiers to determine the type of clinical note to be generated for that audio file. Region, NoteType and Gender values to be passed from response for getNoteParams(). Speciality and Visit Type can be set to the ConfigID returned by getUserConfiguration()
 * @param jobName, optional, a title for the note generated
 * @param jobId, optional, to be set if reconnecting to paused job id to continue recording the note
 * @param recordedDuration, optional, set recorded duration of previous paused job id if reconnecting to it
 */

// Toggles the start/stop recording
augnitoAmbient.toggleListening(
    filetype:string,
    noteparams:string,
    jobName?: string,
    jobId?: string,
    recordedDuration?: number
);
example: augnitoAmbient.toggleListening("wav",`{"Region": 1, "Speciality": 11, "NoteType": 1, "VisitType":29, "Gender": 0}`)

//Toggles the Pause/Resume recording
augnitoAmbient.togglePauseResumeListening(
    filetype: string,
    noteparams: string,
    jobName?: string,
    jobId?: string,
    recordedDuration?: number
);
example: augnitoAmbient.togglePauseResumeListening("wav",`{"Region": 1, "Speciality": 11, "NoteType": 1, "VisitType":29, "Gender": 0}`)

//#region Callbacks

//Callback to change recording button style
public onStateChanged?: (isRecording: boolean)
example: augnitoAmbient.onStateChanged = (isRecording: boolean) => {console.log(isRecording)}

//Callback to receive the Job Id
public onJobCreated?: (text: string)
example: augnitoAmbient.onJobCreated = (text: string) => {console.log(text)}

//Callback to receive when an error occurs within the SDK
public onError?: (error: ErrorInfo)
example: augnitoAmbient.onError = (errorMessage: string) => {console.log(errorMessage)}

//#endregion

Below Errors with Error Code will be returned via onError callback for toggleListening/togglePauseResumeListening

3- Explicitly stop the recording

/**
 * Stops the recording and cleans up resources
 * This function needs to be explicitly called whenever togglePauseResumeListening() function is used
 */
augnitoAmbient.stopListening();

4- List Jobs

Get all Jobs (SOAP notes and other clinical notes) created within the doctor (user’s) account with respect to the given usertag along with meta data. These notes are sorted by timestamp of creation and support pagination.

/**
 * @param PageSize a number, to fetch specified number of notes as a page for each request
 * @param PageID is optional parameter, a string value, When PageID is not given, first set of notes is retrieved according to the specified PageSize. To fetch next set of notes send the PageIDNext received as part of response from the previous getAllNotes call
 * @returns list of notes for the user on success else fail response
 */

try{
const JobList = await augnitoAmbient.getAllNotes(PageSize: number, PageID?: string);
} catch (err) {
    if (err instanceof HttpCodedError) {
      console.log(err.code, err.message);
    }
  }

Errors returned by List job API

5- Fetch Job Output

Retrieve a particular SOAP note or any other clinical note for the given JobId and with respect to the given UserTag (doctor).

/**
 * @param JobId string, to retrieve output for a specific audio file
 * @returns JSON object contains Transcript, Note, FormattedSoap, Codes, NoteParams and SystemEOS on success else fail response
 */

try{
const JobOutput = await augnitoAmbient.getSummarizedNote(JobId:string);
} catch (err) {
    if (err instanceof HttpCodedError) {
      console.log(err.code, err.message);
    }
  }

Errors returned by Fetch Job API

6- Send Final Note

Doctor might make edits to the generated SOAP note and then save it to the EMR. You can use this API to send the final edited SOAP note to help increase accuracy of output in future.

/**
 * @param JobId string, needs to pass to store the final Note for that audio file
 * @param NoteData string, This key will store the final edited Note that user wants to send.
 * @returns success response on successful submit of note else fail response
 */

try{
const response = await augnitoAmbient.sendSummarizedNote(JobId:string, NoteData:string);
} catch (err) {
    if (err instanceof HttpCodedError) {
      console.log(err.code, err.message);
    }
  }

Errors returned by Send Final Note API

7- Delete Notes

Allows you to build a capability for the user (doctor) to delete one or more notes generated under his/her UserTag.

/**
 * @param JobIds array of jobid string values, to delete one or more notes
 * @returns success response on successful delete of notes else fail response
 */
try{
const result = await augnitoAmbient.deleteNotes(JobIds: string[])
} catch (err) {
    if (err instanceof HttpCodedError) {
      console.log(err.code, err.message);
    }
  }

Errors returned by Delete Notes API

8- Rename Note Title

Allows you to build a capability for the user (doctor) to rename generated note under his/her UserTag.

/**
 * @param JobId string, to rename note title
 * @param NewJobName string, new title for the note
 * @returns success response on successful rename of note else fail response
 */

try{
const result = await augnitoAmbient.renameNoteTitle(JobId: string, NewJobName: string)
} catch (err) {
    if (err instanceof HttpCodedError) {
      console.log(err.code, err.message);
    }
  }

9- Download Note as PDF

Allows you to build a capability for the user (doctor) to download generated note as PDF.

/**
   * @param JobId to retrieve pdf for a specific note
   * @param NoteType takes a NoteTypeConfig enum value
   * @param SpecialityId a numberic value which identifies the department to populate in the PDF
   * @param Language, optional parameter, to specify the language in which to generate PDF, default value being English
   * @param PersonnelInfo, optional parameter, to give details to fill into header of PDF. Default json string is '{"PatientName":"","PatientID":"","Age":"","Gender":"","ReceivingDoctor":"","DoctorName":"","DoctorDesignation":"","DoctorEmail":""}'
   * @param RegenerateNote, optional parameter, to indicate if PDF has to be re-generated especially after an update is made to the note, default value is false
   * @returns json response with base64 string of the pdf output to be read from Data.PDF of the response
   */

try{
const result = await augnitoAmbient.getNotePDF(JobId: string, NoteType: NoteTypeConfig, SpecialityId: number, Language?: string, PersonnelInfo?: string, RegenerateNote?: boolean)
} catch (err) {
    if (err instanceof HttpCodedError) {
      console.log(err.code, err.message);
    }
  }

10- Update Speciality and Visit type config

To select/deselect or to set as default any specialty and visit type for the individual user (doctor) differentiated through UserTag.

All specialties and visit types specified by the organization to Augnito will be available (through function defined in Get Speciality and Visit Types section above) for the mapping to organization users. Out of the mapping, only the applicable specialty and visit types for the user can be configured using this API

/**
 * @param ConfigMap Config mapping json. ID to set each config can be obtained by calling the function defined in Get Speciality and Visit Types section above
 * @returns success response on successful update else fail response
 */

try{
const result = await augnitoAmbient.updateUserConfiguration(ConfigMap: UserConfigMap[])
} catch (err) {
    if (err instanceof HttpCodedError) {
      console.log(err.code, err.message);
    }
  }

11- Send EOS for abruptly ended Job

Allows the client-application to send explicit EOS for a recording which did not finish due to reasons such as mistakenly closing browser before stopping the recording.

getAllNotes method will return status of such a job as JOBPAUSED. endPausedJob method can be called to end the job successfully.

If recording was not completed before abrupt closure then reconnection to JobID can be done using toggleListening or togglePauseResumeListening with jobid and recordedDuration(previously recorded duration through getAllNotes response) to continue recording.

The reconnection needs to be done within 5-10 of the initial recording, else Augnito system will generate the note output with audio data sent to it.

/**
 * @param JobId to send EOS for a paused job
 * @returns success response on EOS sent for job else fail response
 */

try{
const result = await augnitoAmbient.endPausedJob(JobId: string)
} catch (err) {
    if (err instanceof HttpCodedError) {
      console.log(err.code, err.message);
    }
  }

12- Generate CDI suggestions

Allows you to generate CDI suggestions for the given SOAP note along with additional data sent to the method, as parameters mentioned below.

/**
   * @param JobId needs to be passed to generate output
   * @param Regenerate a bool to be set to true if CDI suggestions should be re-generated after an update is made to the note else set to false
   * @returns JSON object contains suggestion Items on success else fail response
   */

  try{
  const result = await augnitoAmbient.generateCDISuggestions(
    JobId: string,
    Regenerate: boolean
  )
  } catch (err) {
    if (err instanceof HttpCodedError) {
      console.log(err.code, err.message);
    }
  }

example input:
{
  "JobID": "23916cc6-2f9c-46bf-b95e-d68d82cae899",
  "Regenerate": false
}

example output:
{
  "Data":{
        "Items": [
            {
                "key":"suggestion-heading-1",
                "value":"suggestion-brief-1",
                "feedback":"Yes/No/Unanswered" //default is Unanswered. Use Modify/Update Generated Notes API to update Yes/No feedback for each suggestion given
            },
            {
                "key":"suggestion-heading-2",
                "value":"suggestion-brief-2",
                "feedback":"Yes/No/Unanswered"
            },
        ]
    },
  "ErrorMessage": "string",
  "Status": http-success-code
}

13- Get User Preference

Gets user preference settings.

/**
 * @returns a list of user preference
 */
try {
  const result = await augnitoAmbient.getUserPreferenceSettings();
} catch (err) {
  if (err instanceof HttpCodedError) {
    console.log(err.code, err.message);
  }
}

14- Update User Preference

Used to update user preference settings such as to update flags for automatically generating transcription for recordings, highlight of medical terms in the transcription etc.

/**
   * @param NewUserPreference a list of preference of type PreferenceConfig to be updated
   * @returns success response on successful update else fail response
   */

  try{
  const result = await augnitoAmbient.updateUserPreferenceSettings(
    NewUserPreference: PreferenceConfig
  )
  } catch (err) {
    if (err instanceof HttpCodedError) {
      console.log(err.code, err.message);
    }
  }

15- Update Patient Context

Used to add patient context. This needs to be saved once JobId for a recording is generated and before end of recording so that it gets captured in the SOAP output. It can also be used to add/update context before generating CDI suggestions for any recording

/**
   * @param JobId for which patient context needs to be updated
   * @param Context a text string which gives context/history of patient useful to generate note
   * @param Replace to be set to true if an update of context needs to be saved
   * @returns success response on update of context else fail response
   */

  try{
  const result = await augnitoAmbient.updatePatientContext(JobId: string, Context: string, Replace: boolean)
  } catch (err) {
    if (err instanceof HttpCodedError) {
      console.log(err.code, err.message);
    }
  }

16- Modify/Update Generated Notes

Used to modify the content of generated patient/referral note, update feedback for generated CDI suggestions. Response json for the note needs to be modified and stringified json should be sent as NewNote to the API. This will update the note in the backend

/**
   * @param JobId for which note such as patient/referral/CDI suggestions needs to be updated
   * @param NoteType takes a NoteTypeConfig value
   * @param NewNote to update note json with specific values modified such as to submit feedback for CDI suggestions
   * @returns success response on update of new note else fail response
   */

  try{
  const result = await augnitoAmbient.modifyGeneratedNote(JobId: string, NoteType: NoteTypeConfig, NewNote?: string)
  } catch (err) {
    if (err instanceof HttpCodedError) {
      console.log(err.code, err.message);
    }
  }

17- Fetch Transcription for Recordings

Used to fetch Transcription for any note that is recorded. It is essential to enable note type Automatic transcription at org level to generate transcription of the recorded audio.

/**
   * @param JobId to retrieve transcript for a specific audio file
   * @returns JSON object contains Time in seconds, Text spoken at that time and also array of MedicalData to highlight on success else fail response.
   */

  try{
  const result = await augnitoAmbient.fetchTranscriptionForNote(JobId: string)
  } catch (err) {
    if (err instanceof HttpCodedError) {
      console.log(err.code, err.message);
    }
  }

Note