In the Organization Administration How-To, you learned how to create
organizational hierarchies. The next step is adding accounts (users) to that hierarchy. Accounts can be assigned to groups for performing dictation
and matching operations. Administrative access can be granted at each level in the organization hierarchy as appropriate. Subscription and billing options
can be managed via the API as well.
This How-To covers the creation and management of accounts within your tenant's organizational hierarchy.
Before You Begin
Read About nVoq Orgs and Accounts
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 to understand how
to create the organization hierarchy that will support the account administration detailed on this page.
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 Dependecies
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: Create an Account
Having retrieved or created the group level organization in the Organization Administration How-To, you
can now add accounts to that organization. In addition to common account properties such as first name, last name, etc., you
must specify a usage/billing plan for the user, chosen from the list of available plans in your organization. The most common plan is an enterprise plan.
The sample code below shows how to get the plans available for an organization and then use one of those
plans to create a new account.
The helper methods and member variables referenced are available in the full sample code provided at the
bottom of this page.
Usernames must be unique across the entire system. Often, an email address is used as the username. If this is not an option for your particular application,
consider the uniqueness requirement when designing your integration. Also, usernames must be less than 45 characters and may NOT include
special characters such as " * / : < > ? \ | ' & ; # +, or spaces. They are case insensitive. For maximum portability and consistency, it is recommended that you constrain your
usernames to [a-z][0-9] - _ @ .
#!/bin/bash
#TBD
import java.io.*;
//...
public class Program {
//...
/*
* Get the plans for this organization.
*/
private void getPlansByOrganization(Organization aOrg) {
String url = baseUrl + "/SCVmcServices/rest/organizations/" + aOrg.myId + "/plans";
try {
//make the web service call
StringBuffer sb = httpHelper("GET", url, null);
//parse the returned JSON into objects
JSONParser jsonParser = new JSONParser();
Object obj = jsonParser.parse(sb.toString());
JSONArray planArray = (JSONArray) obj;
//add the plans to the local Organization object
planArray.forEach((plan) -> aOrg.addPlan(new Plan(plan.toString())));
} catch (Exception e) {
System.out.println(e.toString());
}
return;
}
// using the plan that has the charge type and
// rate category of "enterprise", you can pass
// the planID along with the orgId to create the new user
//
//[{
// "displayName": "Shortcuts and Dictation",
// "description": "Shortcuts and Dictation Enterprise",
// "rateCategory": "enterprise",
// "chargeType": "enterprise",
// "identifier": "dontusethisidentifierlookitup"
//}]
/*
* Create a new Account.
*/
private Account createAccount(String userName, String firstName, String lastName, String orgId, String planId) {
String url = baseUrl + "/SCVmcServices/rest/accounts";
//JSON representation of an Account
StringBuffer sb = new StringBuffer();
sb.append("{\"username\":\"" + userName + "\",");
sb.append("\"firstName\":\"" + firstName + "\",");
sb.append("\"lastName\":\"" + lastName + "\",");
sb.append("\"email\":\"" + userName + "@fakeemail.com\",");
sb.append("\"enabled\":true,");
sb.append("\"password\":\"myFancyPassword1\",");
sb.append("\"clientAccess\":true,");
sb.append("\"accuracyOptimizationService\":false,");
sb.append("\"clientGroup\":\"" + orgId + "\",");
sb.append("\"plan\":\"" + planId + "\",");
sb.append("\"nonBillable\":false}");
String newAccount = sb.toString();
try {
//create the account by calling the web service
StringBuffer sbAccount = httpHelper("POST", url, newAccount);
//use the last location http header to retrieve the Account JSON
Account acct = new Account(httpHelper("GET", lastLocation, null).toString());
return acct;
} catch (Exception e) {
System.out.println(e.toString());
}
return null;
}
//...
}
<script>
//TBD
</script>
using Newtonsoft.Json;
//...
namespace nVoqHttpApiCSharp
{
class Program
{
//...
/*
* Get the billing plans available for the organization
*/
private static void getPlansByOrganization(Organization aOrg)
{
String url = BaseUrl + "/SCVmcServices/rest/organizations/" + aOrg.identifier + "/plans";
string plansJSON = httpHelper("GET", url, null);
List<Plan> plans = JsonConvert.DeserializeObject<List<Plan>>(plansJSON);
aOrg.plans = plans;
}
// using the plan that has the charge type and
// rate category of "enterprise", you can pass
// the planID along with the orgId to create the new user
//
//[{
// "displayName": "Shortcuts and Dictation",
// "description": "Shortcuts and Dictation Enterprise",
// "rateCategory": "enterprise",
// "chargeType": "enterprise",
// "identifier": "dontusethisidentifierlookitup"
//}]
/*
* Create a new Account
*/
private static Account createAccount(Account aAccount)
{
String url = BaseUrl + "/SCVmcServices/rest/accounts";
string acctJSON = JsonConvert.SerializeObject(aAccount,
new JsonSerializerSettings
{
NullValueHandling = NullValueHandling.Ignore
});
string sbAccount = httpHelper("POST", url, acctJSON);
Account acct = JsonConvert.DeserializeObject < Account >( httpHelper("GET", lastLocation, null));
return acct;
}
//...
}
}
Step 2: Get All Org Accounts
You can request all the accounts in (and below) an organization in the hierarchy.
#TBD
/*
* Get all the accounts in (and below) an org in the hierarchy
*/
private void getAccountsByOrganization(Organization aOrg) {
String url = baseUrl + "/SCVmcServices/rest/organizations/" + aOrg.myId + "/accounts";
try {
StringBuffer sb = httpHelper("GET", url, null);
JSONParser jsonParser = new JSONParser();
Object obj = jsonParser.parse(sb.toString());
JSONArray acctArray = (JSONArray) obj;
acctArray.forEach((acct) -> aOrg.addAccount(new Account(acct.toString())));
} catch (Exception e) {
System.out.println(e.toString());
}
return;
}
<script>
//TBD
</script>
/*
* Get all the accounts for an organization
*/
private static List<Account> getAccountsByOrg(Organization aOrg)
{
String url = BaseUrl + "/SCVmcServices/rest/organizations/" + aOrg.identifier + "/accounts";
List<Account> acct = JsonConvert.DeserializeObject<List<Account>>(httpHelper("GET", lastLocation, null));
return acct;
}
Step 3: Update & Delete an Account
Once an Account exists, updating and deleting are the next logical operations. The methods below illustrate
how to perform these operations.
#TBD
/*
* Update an account. This method shows how to update one property
* but multiple properties can be updated simultaneously by including
* them in the JSON request.
*/
private void updateAccount(String aUsername, String aPropertyName, String aPropertyValue) {
// First disable the account (cannot delete unless disabled)
String url = baseUrl + "/SCVmcServices/rest/accounts/" + aUsername;
StringBuffer sb = new StringBuffer();
sb.append("{\""+aPropertyName+"\":\""+aPropertyValue+"\"}");
String disabledAccount = sb.toString();
httpHelper("POST", url, disabledAccount);
}
/*
* Delete an account.
*/
private void deleteAccount(Account account) {
// First disable the account (cannot delete unless disabled)
String url = baseUrl + "/SCVmcServices/rest/accounts/" + account.myUserName;
StringBuffer sb = new StringBuffer();
sb.append("{\"enabled\":false }");
String disabledAccount = sb.toString();
httpHelper("POST", url, disabledAccount);
// then delete the organization
httpHelper("DELETE", url, null);
}
<script>
//TBD
</script>
/*
* Update account. Must pass in username and whatever properties
* need to be updated.
*/
private static void updateAccount(Account aAccount)
{
String url = BaseUrl + "/SCVmcServices/rest/accounts/" + aAccount.username;
aAccount.username = null;
string accountJSON = JsonConvert.SerializeObject(aAccount,
new JsonSerializerSettings
{
NullValueHandling = NullValueHandling.Ignore
});
Console.WriteLine(accountJSON);
httpHelper("POST", url, accountJSON);
//then delete the org
httpHelper("DELETE", url, null);
}
/*
* Delete an Acct. USE WITH CAUTION
*/
private static void deleteAccount(Account aAccount)
{
String url = BaseUrl + "/SCVmcServices/rest/accounts/" + aAccount.username;
//first disable the org
Account changeAcct = new Account();
changeAcct.enabled = false;
string accountJSON = JsonConvert.SerializeObject(changeAcct,
new JsonSerializerSettings
{
NullValueHandling = NullValueHandling.Ignore
});
Console.WriteLine(accountJSON);
httpHelper("POST", url, accountJSON);
//then delete the org
httpHelper("DELETE", url, null);
}
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.
