Define application commands (Browser)

Each application command is associated with one command set.

Prerequisites

Procedure

To define application commands, do the following:

Create a command set:
```
var cmdSetId = NUSA_createCommandSet("My Test CommandSet ", " Description of my test command set ");
```
My Test CommandSet - a human-readable title for your command set; displayed in the personalization & help window.

Description of my test command set - a human-readable description; displayed in the personalization & help window.

Note

The command set created is enabled by default; call NUSA_enableCommandSet(cmdSetId, enabled) to enable/disable it.
Create application commands in the command set:
```
NUSA_createCommand(cmdSetId, "myTestCommandId", "this is a test", "THIS IS A TEST", "My test command description.");
```
myTestCommandId - the unique identifier of the application command; this is the identifier that your app will receive in the application command event callback when it's recognized.

Important

Make sure the application command ID doesn't contain spaces and doesn't start with a number.

this is a test - the application command phrase (that's said to initiate the application command); displayed in the personalization & help window if no display string is set.

THIS IS A TEST - the application command display string; displayed in the personalization & help window. If you don't want to set a display string, pass a null value or empty string.

My test command description - a human-readable description; displayed in the personalization & help window.

Note

The command created is enabled by default; call NUSA_enableCommand(myTestCommandId, enabled) to enable/disable it.

Standard placeholders

Standard placeholders are delivered with Dragon Medical SpeechKit. To add a standard placeholder to an application command, add its identifier to the phrase of the command:

NUSA_createCommand("myScrollCommand", "scroll down <standard:cardinal0-100> pages", "scroll down <standard:cardinal0-100> pages","Scrolls down the specified number of pages.");

For a list of standard placeholders, see: Standard placeholders.

Important

If you use a display string, the placeholder in the display string and in the phrase must be the same (see: Recommendations for phrases).

App-defined placeholders

When designing the VUI for your app, you can provide one or more commands. For example, you can define voice commands that refer to a patient name: show allergies for mister Pink or create new note for mister Orange. To do this, you can create an app-defined placeholder and add it to application commands as needed. Proceed as follows:

Create an application command with a placeholder defined in angled brackets for the phrase parameter:
```
NUSA_createCommand(cmdSetId ,"myShowPatientCommand", "show me <patientId>", "show me <patientId>", "Shows data for the corresponding patient.");
```
<patientId> is the unique identifier of the placeholder.

Tip

The same placeholder can be used in different commands.
Create the placeholder:
```
NUSA_createCommandPlaceholder("patientId", "Name of the patient");
```
patientId - the unique identifier of the placeholder that is used in application command phrases; must not contain spaces and/or numbers.

Name of the patient - a human-readable description; displayed in the personalization & help window.
Set its phrases and values.
Make sure that values[index] corresponds to spokenForms[index]:
```
var values = new Array();
var spokenForms = new Array();
values.push("PTN.48389488");
spokenForms.push("Mr. Pink");
values.push("PTN.48389488");
spokenForms.push("Mr. Orange");
NUSA_setCommandPlaceholderValues("patientId", values, spokenForms);
```
"PTN.48389488", "PTN.48323466" - an array of strings containing the values of the placeholder.

"Mr. Pink", "Mr. Orange" - an array of strings containing the corresponding spoken forms.

The number of elements in the two arrays must be the same. In this example, the "patient" placeholder can have two values, PTN.48389488 if the user says mister Pink or PTN.48323466 if the user says mister Orange.

Note

If you use a display string, the placeholder in the display string and in the phrase must be the same. The value of a placeholder can be changed. The new value will become active after the next NUSA_reinitializeVuiForm() call.

Recognizing application commands

Dragon Medical SpeechKit notifies your app about recognized application commands; the NUSA_onCommandRecognized() function is called. For more information, see: VuiController events. For your app to receive this notification, do the following:

Implement the NUSA_onCommandRecognized() function. This will be called back when an application command is recognized.
```
function NUSA_onCommandRecognized(cmdId, spokenText, content, placeholderIds, placeholderValues)
```
In SpeechMagic-based systems, the spokenText parameter is empty in command mode.
In NUSA_onCommandRecognized(), check for the ID of the recognized application command.
```
if (cmdId =="myShowPatientCommand") {
```

Process the recognized placeholder values.

if (placeholderIds[0] == "patientId") { // the unique identifier of the placeholder
    var patientName = placeholderValues[0];
}

If you're using more placeholder values or several placeholders in one command, step through as follows:

for (var i = 0; i < placeholderIds.length; ++i) {
    if (placeholderIds[i] == "patientId") { // the unique identifier of the placeholder
        var patientName = placeholderValues[i];
    }
    else if (placeholderIds[i] == "anotherId") {
        var data = placeholderValues[i];
    }
}

Note

The procedure above also applies for commands with standard placeholders. Standard placeholders delivered with Dragon Medical SpeechKit have predefined keys, for more information, see: Standard placeholders.

Considerations when defining application commands

Commands can have multiple phrases; call the NUSA_createCommand() method multiple times for the same ID, passing the phrases you want defined for the application command.
Your app is notified when an application command is recognized via a VuiController event callback.
To enable/disable a command set, call the NUSA_enableCommandSet(id, enabled) method.
To enable/disable individual commands in a command set, call the NUSA_enableCommand(id, enabled) method with the corresponding command ID.
If your application wants to modify attributes of application commands or command sets, (for example, add new application commands, enable/disable application commands or change placeholder values after the end user has already used speech recognition); apply the changes to the attributes by calling NUSA_reinitializeVuiForm(). It's best practice to do all changes before applying them via NUSA_reinitializeVuiForm().
You can speech-enable your app UI even if no speech-enabled controls are active.
To change the placeholder in an application command, use the NUSA_clearCommandPlaceholderValues() method. Once the placeholder is empty, you can add new phrases and values to the placeholder.
If you need commands active immediately on creation of a form, the NUSA_createCommand() method must be called while handling the NUSA_configure() function. In this case NUSA_reinitializeVuiForm() must not be called.

Feedback

Was this page helpful?

Last updated on 2025-03-07