Custom Vocabulary

Introduction

nVoq's dictation service sources vocabulary from a variety of sources. And, we are constantly updating our dictionaries to keep up with the constantly changing world of medicine. Unavoidably, however, there will be words in users' daily speech that are not in our standard medical topic dictionaries. These words are typically names and other proper nouns that would not have an application to the broader base of speech recognition service consumers. nVoq provides the ability to add custom vocabulary words to both users and organizations. If a custom vocabulary word is added to a user, only that user will benefit from the additional word. However, the nVoq platform organization hierarchy functionality allows for a more efficient way to manage the specific words that are important to parts of the organization.

In order to scale an enterprise deployment, developers typically automate the creation of accounts (users) and groups. nVoq's organizational hierarchy allows for the creation of organization structures that reduce administrative overhead by allowing the application of certain operations to groups of accounts. For example, if a hospital was located on Squeezepenny Lane, the custom vocabulary word "Squeezepenny" could be added once and applied to all the accounts within the hospital's organization hierarchy. It then becomes part of those accounts' vocabularies through one administrative operation. This prevents errors from duplicated data spread across an organization and simplifies troubleshooting.

The examples below illustrate how to use the custom vocabulary functionality in the nVoq API for both organizations and accounts.

Before You Begin

Read About nVoq Orgs and Users

If you are not already familiar with nVoq's organization hierarchy functionality, please check out the Organizations page on our support site that walks you through how organizations are structured, administered, and used to organize users and administrators.

You should also take time to read through the Organization Administration How-To and the Account Administration How-To to understand how to create the organization hierarchy and accounts to which vocabulary words are assigned.

API User Account

If your organization has not already been in contact with our Sales team, please complete this short form on the Developer Registration Page and we will reach out to you regarding a user account and development with our APIs.

Once you have an account, you must change your password before the account can be used for API calls.

External Dependencies

Most platforms do not include a JSON implementation. So, you will need to download the appropriate third party implementation from one of these locations:

Java: JSON.simple
C#: Newtonsoft Json, Use Visual Studio Package Manager to install these from NuGet

Start your IDE

The nVoq API is a RESTful Web Services and WebSocket API and therefore does not constrain you to any specific platform or programming language. We provide sample code below for shell scripting (bash), C#, Java, and JavaScript. Follow along and run this code in your environment. But, if you prefer C++, Go, or some other language, that's great! Just adapt the code below to your language's web services functionality and you should be good to go.

Let's Go!

Choose your programming language...

Step 1: Get Custom Vocabulary

The code below illustrates how to get the custom vocabulary for organizations and accounts. It relies on some helper methods found in the full sample source code provided at the bottom of this page.

#!/bin/bash
#TBD

import java.io.*;
import org.json.simple.*;
//...

public class Program3 {

   //...
   
   /*
    * Get the custom vocabulary for an organization
    */
   private void getVocabularyByOrganization(Organization aOrg) {
      String url = baseUrl + "/SCVmcServices/rest/organizations/" + aOrg.myId + "/vocabulary";
      try {
         //make the web service call to retrieve the vocabulary
         StringBuffer sb = httpHelper("GET", url, null);
         JSONParser jsonParser = new JSONParser();
         //Parse the returned JSON String into objects
         Object obj = jsonParser.parse(sb.toString());
         JSONArray wordArray = (JSONArray) obj;
         //Add the vocabulary words to our Organization object,
         //using an iterator - old school
         Iterator<JSONObject> it = wordArray.iterator();
         while (it.hasNext()){
            JSONObject o = it.next();
            String s = o.toJSONString();
            //instantiate versions of our objects from the JSON
            VocabularyWord w = new VocabularyWord(s);
            aOrg.addVocabularyWord(w);
         }
      } catch (Exception e) {
         System.out.println(e.toString());
      }
      return;
   }

   /*
    * Get the custom vocabulary for acct.
    */
   private void getVocabularyByAccount(Account aAccount) {
      String url = baseUrl + "/SCVmcServices/rest/accounts/" + aAccount.myUserName + "/vocabulary";
      try {
         //make the web service call to retrieve the vocabulary
         StringBuffer sb = httpHelper("GET", url, null);
         //Parse the returned JSON String into objects
         JSONParser jsonParser = new JSONParser();
         Object obj = jsonParser.parse(sb.toString());
         JSONArray wordArray = (JSONArray) obj;
         //Add the vocabulary words to our Account object
         wordArray.forEach((word) -> aAccount.addVocabularyWord((new VocabularyWord(word.toString()))));
      } catch (Exception e) {
         System.out.println(e.toString());
      }
      return;
   }
   
   //...
}


<script>
//TBD
</script>

using Newtonsoft.Json;

//...

namespace nVoqHttpApiCSharp
{
    class Program
    {
        //...
        /*
         * Get the custom vocabulary for an organization
         */
        private static List<VocabularyWord> getVocabularyByOrganization(Organization aOrg)
        {
            String url = BaseUrl + "/SCVmcServices/rest/organizations/" + aOrg.identifier + "/vocabulary";
            //Make the web service call
            string plansJSON = httpHelper("GET", url, null);
            //convert the JSON into local Word objects
            List<VocabularyWord> words = JsonConvert.DeserializeObject<List<VocabularyWord>>(plansJSON);
            return words;
        }

        /*
         * Get the custom vocabulary for an account
         */
        private static List<VocabularyWord> getVocabularyByAccount(Account acct)
        {
            String url = BaseUrl + "/SCVmcServices/rest/accounts/" + acct.username + "/vocabulary";
            //Make the web service call
            string plansJSON = httpHelper("GET", url, null);
            //convert the JSON into local Word objects
            List<VocabularyWord> words = JsonConvert.DeserializeObject<List<VocabularyWord>>(plansJSON);
            return words;
        }
        
        //...
    }              
}

Step 2: Modify Org Vocabulary

Updates are performed through a single data structure that contains vocabulary words to add, words to update, and the IDs of the words to be removed. In this way, batches of words can be added or removed in a single operation.


#TBD

   /*
    * Update the vocabulary (add, update, remove) for an organization
    */
   private void updateVocabularyByOrganization(Organization aOrg, ArrayList<String> writtenForms){
         VocabularyUpdate vu = new VocabularyUpdate();
         Iterator<String> it = writtenForms.iterator();
         while (it.hasNext()){
            VocabularyWord w = new VocabularyWord();
            w.written = it.next();
            vu.add.add(w);
         }
          String url = baseUrl + "/SCVmcServices/rest/organizations/" + aOrg.myId + "/vocabulary";
          StringBuffer result = httpHelper("POST", url, vu.toJSON());      
   }
/* -------------------------------------------------

  The update JSON message is illustrated below...

{
    "add": 
[
    {
        "written": "nVoq",
        "soundsLike": "envoke"
    }
],
"update": 
[
    {
        "uuid": "12345",
        "written": "nVoq",
        "soundsLike": "envoke"
    }
],
"remove": 
    [
        "12345",
        "46789"
    ]
}
*/

<script>
     //TBD
   </script>

/*
 * Update the vocabulary (add, update, remove) for an organization
 */
private static void updateVocabularyByOrganization(Organization aOrg, VocabularyUpdate aUpdate)        {
    String url = BaseUrl + "/SCVmcServices/rest/organizations/" + aOrg.identifier + "/vocabulary";
    string vocabJSON = JsonConvert.SerializeObject(aUpdate,
        new JsonSerializerSettings
        {
            NullValueHandling = NullValueHandling.Ignore
        });
    httpHelper("POST", url, vocabJSON);
}

/* -------------------------------------------------

  The update JSON message is illustrated below...

{
    "add": 
[
    {
        "written": "nVoq",
        "soundsLike": "envoke"
    }
],
"update": 
[
    {
        "uuid": "12345",
        "written": "nVoq",
        "soundsLike": "envoke"
    }
],
"remove": 
    [
        "12345",
        "46789"
    ]
}
*/

Step 3: Modify Account Vocabulary


  #TBD

   /*
    * Update the vocabulary (add, update, remove) for an account.
    */
   private void updateVocabularyByAccount(Account aAcct, ArrayList<String> writtenForms){
         VocabularyUpdate vu = new VocabularyUpdate();
         Iterator<String> it = writtenForms.iterator();
         while (it.hasNext()){
            VocabularyWord w = new VocabularyWord();
            w.written = it.next();
            vu.add.add(w);
         }
          String url = baseUrl + "/SCVmcServices/rest/accounts/" + aAcct.myUserName + "/vocabulary";
          httpHelper("POST", url, vu.toJSON());
   }
/* -------------------------------------------------

  The update JSON message is illustrated below...

{
    "add": 
[
    {
        "written": "nVoq",
        "soundsLike": "envoke"
    }
],
"update": 
[
    {
        "uuid": "12345",
        "written": "nVoq",
        "soundsLike": "envoke"
    }
],
"remove": 
    [
        "12345",
        "46789"
    ]
}
*/

<script>
//TBD
</script>

/*
 * Update Account Vocabulary
 */
private static void updateVocabularyByAcct(Account aAcct, VocabularyUpdate aUpdate)
{
    String url = BaseUrl + "/SCVmcServices/rest/accounts/" + aAcct.username + "/vocabulary";
    string vocabJSON = JsonConvert.SerializeObject(aUpdate,
        new JsonSerializerSettings
        {
            NullValueHandling = NullValueHandling.Ignore
        });
    httpHelper("POST", url, vocabJSON);
}
        
/* -------------------------------------------------
   The update JSON message is illustrated below...

{
    "add": 
[
    {
        "written": "nVoq",
        "soundsLike": "envoke"
    }
],
"update": 
[
    {
        "uuid": "12345",
        "written": "nVoq",
        "soundsLike": "envoke"
    }
],
"remove": 
    [
        "12345",
        "46789"
    ]
}
*/

Full Sample Code

Below is the full sample code. Copy and paste the entire contents of the code below into your favorite editor and save locally on your machine. Modify the URL's and username/password according to your credentials and system access. Then, run the program and enjoy all the excitement of securely converting audio to text via the nVoq.API platform.

If you have any questions, please reach out to support@nvoq.com.

API How-To