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.
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:
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"
]
}
*/
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 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"
]
}
*/
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.