--- title: "Admin: Substitution Types" slug: "administrator-help-substitution-types" updated: 2024-07-30T20:10:03Z published: 2024-07-30T20:10:03Z canonical: "support.nvoq.com/administrator-help-substitution-types" --- > ## Documentation Index > Fetch the complete documentation index at: https://support.nvoq.com/llms.txt > Use this file to discover all available pages before exploring further. # Admin: Substitution Types nVoq dictation includes support for literal substitutions as well as *"regular expression"* substitutions. Regular expressions (Regex) search for patterns in a transcription and standardize how text is returned, for example, to format dates, telephone numbers, or monetary amounts. **The examples on this page are only examples. They are not guaranteed to work. Always TEST your substitutions to make sure they work for you.** [nVoq Administrator: Substitutions](https://player.vimeo.com/video/990715161?h=7456cca236&badge=0&autopause=0&player_id=0&app_id=58479) ## Literal Substitutions A literal substitution replaces a literal sequence of text characters (or "string") with another literal text character string. **Example:** A literal substitution to replace "Denver health" with "Denver Health Medical Center"![LITERAL EXAMPLE GIF](https://cdn.us.document360.io/03b5534a-5f9a-42ce-852d-08bf09105da4/Images/Documentation/LITERAL%20EXAMPLE%20GIF.gif)Click on this image to see it larger. - Literal substitutions are full word matches. This allows the word  "cat’" to be substituted with "FELINE" while preventing the word "catalog" from being substituted with "FELINEalog". - A literal substitution is applied exactly as it appears in the Spoken Form and Written Form fields. - The spoken form is the word or phrase as it IS CURRENTLY RETURNED by the dictation engine. This is not case sensitive. - The written form is how you WANT IT TO RETURN in your transcript. This IS case sensitive. - Use literal substitutions to replace words in a transcript with an abbreviation, an acronym, a capitalized version of the word, a carriage return, an entire sentence, or to correct words in a dictation that consistently return incorrectly. **Some substitutions may not work in Direct Text mode. See** [**Substitution Behavior with STABLETEXT**](/v1/docs/administrator-help-substitutions-direct-text) **for more information.** ### Examples of Literal Substitutions **Example:** A substitution to replace "mobile voice" with "nVoq Mobile Voice™" **Type:** Literal **Spoken Form:** `mobile voice` **Written Form:** `nVoq Mobile Voice™` **Before Substitution:** I just started using mobile voice **After Substitution:** I just started using nVoq Mobile Voice™ **Example:** A substitution to replace "payment" with "pymt" **Type:** Literal **Spoken Form:** `payment ` **Written Form:** `pymt` **Before Substitution:** Customer called to ask when payment is due **After Substitution:** Customer called to ask when pymt is due **Example:** A substitution to replace "Denver health" with "Denver Health Medical Center" **Type:** Literal **Spoken Form:** `Denver health` **Written Form:** `Denver Health` **Before Substitution:** Patient was referred to Denver health for treatment **After Substitution:** Patient was referred to Denver Health for treatment **Example:** A substitution to correct when a dictation of "two thousand eleven" is misrecognized as "2000 Lavon" **Type:** Literal **Spoken Form:** `2000 Lavon` **Written Form:** `2011` **Before Substitution:** This occurred in May 2000 Lavon **After Substitution:** This occurred in May 2011 **Example:** A substitution to replace "next line" with a carriage return key press. **Type:** Literal **Spoken Form:** `next line` **Written Form:** `{ENTER}` **Before Substitution:** Customer submitted payment next line payment approved **After Substitution:** Customer submitted payment Payment approved If you want a substitution that clicks the Tab key, use a Regex Plus substitution See [**Regex Plus Substitution Examples**](/docs/administrator-help-substitution-types#examples-regexplus). **Example:** A substitution to replace "insert prognosis statement" with the actual prognosis statement. **Type:** Literal **Spoken Form:** `insert prognosis statement` **Written Form:** `All medications reviewed during IDG meeting. Patient continues to be hospice appropriate with a life expectancy of 6 month or less if terminal illness runs its normal course.` **Before Substitution:** Patient is DNR period insert prognosis statement **After Substitution:** Patient is DNR. All medications reviewed during IDG meeting. Patient continues to be hospice appropriate with a life expectancy of 6 month or less if terminal illness runs its normal course. ## Regex Substitutions A Regex substitution defines text matching a particular sequence of characters (or "string") and replaces it with a Regex "backreference", a literal text string, or both. **Example:** A substitution to change the formatting on phone numbers to add parenthesis and dash in the appropriate places![REGEX EXAMPLE GIF](https://cdn.us.document360.io/03b5534a-5f9a-42ce-852d-08bf09105da4/Images/Documentation/REGEX%20EXAMPLE%20GIF.gif)Click on this image to see it larger. - Regex substitutions are NOT full word matches unless the expressions are explicitly defined with boundary markers. - A Regex is a search pattern that is used to identify character patterns in a transcript and modify how they are returned, such as how telephone numbers or dates display. - The spoken form of a regular expression substitution is a search pattern which, by default, is **case insensitive**. (Additional rules must be specified for the spoken form to be case sensitive.) - The written form could be literal text or Regex backreferences. - Regex substitutions are implemented with the `java.util.regex.Pattern `class. - The JavaDoc for this class can be accessed at **[http://docs.oracle.com/javase/6/docs/api/java/util/regex/Pattern.html](http://docs.oracle.com/javase/6/docs/api/java/util/regex/Pattern.html)**. See the section titled Summary of regular-expression constructs. - nVoq Administrator performs minimal error checking for Regex syntax. - It is strongly recommended that you test your substitutions *extensively* to ensure they perform the expected substitution. **Regex substitutions *may not work* as expected in STABLETEXT mode.See [**Substitution Behavior with STABLETEXT**](/v1/docs/administrator-help-substitutions-direct-text) for more information.** ### Examples of Regex Substitutions **Example:** A Regex substitution to convert the phrase "next line" to a single carriage return **Spoken Form:** `(\A|\n|[.:?!]|[ ])((next|necks) line)[ ](k)` **Written Form:** `$1K` **Before Substitution:** Customer submitted payment next line payment approved **After Substitution:** Customer submitted payment Payment approved **Example:** A substitution to change the formatting on phone numbers to add parenthesis and dash in the appropriate places **Type:** Regex **Spoken Form:** `(\d{3})(\d{3})(\d{4})` **Written Form:**   `($1) $2-$3` **Before Substitution:** 1232312332 **After Substitution:** (123) 231-2332 **Example:** A substitution to correct numbers spoken as "one to zero" and replaces it with "120" **Type:** Regex **Spoken Form:**   `(d)stoszeros` **Written Form:**   `$120` **Before Substitution:** Number of days is one to zero **After Substitution:** Number of days is 120 **Example:** A substitution to correct the years 2012 - 2014 returning incorrectly, such as "200012" instead of "2012" **Type:** Regex **Spoken Form:**   `20001(2|3|4)b` **Written Form:**   `201$1` **Before Substitution:** 200012 200013 200014 **After Substitution:** 2012 2013 2014 ## Regex Plus Substitutions A Regex Plus substitution uses JavaScript to reference variables. ****Example:**** This substitution removes the previously spoken dictation within the same dictation back to the most recent punctuation mark when a person dictates "scratch that"![REGEX PLUS EXAMPLE GIF](https://cdn.us.document360.io/03b5534a-5f9a-42ce-852d-08bf09105da4/Images/Documentation/REGEX%20PLUS%20EXAMPLE%20GIF.gif)Click on this image to see it larger. - Regex Plus substitutions are NOT full word matches unless the expressions are explicitly defined with boundary markers. - This type of substitution uses a Regex search pattern for the spoken form. When a match is found, the JavaScript programmatically determines the text to substitute. - The spoken form of a Regex Plus substitution is a regular expression. - The written form is a JavaScript. - **Regex Plus substitutions *may not work as expected* in Direct Text mode. See [**Substitution Behavior with STABLETEXT**](/v1/docs/administrator-help-substitutions-direct-text) for more information.** - In the context of Regex Plus substitutions, browser elements and functions (e.g., window.* variables) and web page elements (e.g., document.* variables) are undefined. In other words, you cannot use a Regex Plus substitution to launch a web page. - The JavaScript written form can reference the variables [defined below](/v1/docs/administrator-help-substitution-types#supported-variables-for-realtime-and-batch-processing). ### Supported Variables for Real-time and Batch Processing **User-defined variables are supported for dictations submitted with API batch processing. They are not available in real-time clients.** **Variable: nvoq.fullText** Definition: The entire transcript. JavaScript Type: String **Variable: nvoq.profile** Definition: The profile used to generate the transcript JavaScript Type: String **Variable: match.group(N)** Definition: The contents of the Nth capturing group in the Regex (if any) JavaScript Type: String **Variable: match.start(N)** Definition: The start index into the Nth capturing group in the Regex (if any) JavaScript Type: Number **Variable: match.end(N)** Definition: The end index into the Nth capturing group in the Regex (if any) JavaScript Type: Number **Variable: match.groupCount()** Definition: The number of capturing groups declared in the Regex JavaScript Type: Number ### Examples of Regex Plus Substitutions **Example:** A Regex Plus substitution to replace "dot", "full stop", "PD", "pleaded", etc. with a period ( . ) instead of those words. **Spoken Form:** `(( dot| PD| pleaded| PD it| PD and| PD an(?!d)| PD on| full stop)($|\n)([a-z]|[0-9]*))` **Written Form:** `"\. " + match.group(3) + match.group(4).toUpperCase()` **Before Substitution:** Patient was seen at the clinic today full stop **After Substitution:** Patient was seen at the clinic today. **Example - Insert a Tab:** This substitution inserts a tab without leading or trailing spaces when the user says "tab key" within the dictation. **Type:** Regex Plus **Spoken Form:**   `(\s?tab key\s?)` **Written Form:**   `"\t"` **Before Substitution:** Medications tab key the patient is on the following medications... **After Substitution:** Medications the patient is on the following medications... **Example - Transcribe Current** **Date****:** This substitution includes a user-defined function to replace the phrase "current date" with today's date in MM/DD/YYYY format. It can be used in real-time clients and with API batch processing. **Type:** Regex Plus **Spoken Form:**   `current date|Current date` **Written Form:** `cur_date();` `function cur_date(){` ` var today = new Date();` ` today = today.getUTCMonth() + 1 + "/" + today.getUTCDate() + "/" + today.getUTCFullYear();` ` return today;` `}` **Before Substitution:** On current date she says she... **After Substitution:** On 1/12/2021 she says she... **A similar function can be written for time, or date *and* time. However, note that time stamps will be server time and not necessarily the *user's* time zone.** **Example - Delete Last Sentence Spoken****:** This substitution removes the previously spoken dictation within the same dictation back to the most recent punctuation mark. ****A similar substitution written with a different Spoken Form (**`\A[\s\S]*\z`**) DOES NOT WORK with Direct Text *and* causes capitalization substitutions not to work as expected. Using the Spoken form listed below should not cause these problems.**** **Type:** Regex Plus **Spoken Form:**   `\A[\s\S]*[Ss]cratch that[\s\S]*\z` **Written Form:** `var counter = 0; var func = function (text) { log("func" + counter++);` `var regex = / ?scratch that ?/ig;``var match = regex.exec(text);``if (match == null) {``return [false, text];``}``//log("**\n"+ JSON.stringify(match));`` ``log("match.index " + match.index);`` ``var preText = text.substring(0, match.index);``var phrase = text.substring(match.index, regex.lastIndex);``var postText = text.substring(regex.lastIndex, text.length);`` ``log("preText=" + preText);``log("phrase=" + phrase);``log("postText=" + postText);`` ``var phraseStartIdx = match.index;`` ``var sentenceIdx = -1;``var newline = false;``var startOfString = true;``var stringBetweenScratchAndStop = [];``for (var i = phraseStartIdx; i >= 0; i--) {``var c = text.charAt(i);``if (c == "." || c == "!" || c == "?" || c == "\n") {``if (c == "\n") {``newline = true;``}``sentenceIdx = i;``startOfString = false;``break;``} else {``stringBetweenScratchAndStop.push(c);``}``}`` ``log("sentenceIdx=" + sentenceIdx + " newline=" + newline + " startOfString=" + startOfString + "");`` ``stringBetweenScratchAndStop = stringBetweenScratchAndStop.reverse().join('');``log("stringBetweenScratchAndStop = [" + stringBetweenScratchAndStop + "]");`` ``if (/^\s+$/.test(stringBetweenScratchAndStop)) {``log("All whitespace between phrase and stop.");``if (sentenceIdx > -1) {``text = setCharAt(text, sentenceIdx, " ");``//text = text.substring(0, sentenceIdx);``return [true, text];``}``}`` ``if (sentenceIdx > -1 || startOfString) {``var newPreText = "";``if (!startOfString) {``newPreText = text.substring(0, sentenceIdx + 1);``}``log("newPreText[" + newPreText + "]");``var newPostText = "";``if (postText && postText != null) {``newPostText = postText.charAt(0).toUpperCase() + postText.substring(1, postText.length);``}``log("newPostText[" + newPostText + "]");``var newText = newPreText;``if (!(newline || startOfString)) {``newText += " ";``}``newText += newPostText;``log("newText[" + newText + "]");``return [true, newText];``}`` ``// fallback``return [false, nvoq.fullText]``}`` ``function indexOfGroup(match, n) {``var ix = match.index;``for (var i = 1; i < n; i++)``ix += match[i].length;``return ix;``}``function setCharAt(str, index, chr) {``if (index > str.length - 1)``return str;``return str.substr(0, index) + chr + str.substr(index + 1);``}`` ``function log(m) { if (nvoq.log){nvoq.log(m)} else {} }`` ``var result = func(nvoq.fullText);``while (result[0]) {``result = func(result[1]);``}`` ``var finalResult = result[1];``log("final[" + finalResult + "]");``finalResult;` **Before Substitution:** Medical history COLON scratch that risks and benefits COLON I went over the risks and benefits with the patient **After Substitution:** Risks and benefits: I went over the risks and benefits with the patient **Example** **-** **Prepend Voice Client Username to Transcript:** This substitution prepends the speaker's username to the transcript when the transcript includes the phrase "end of dictation". It uses the nvoq.profile and nvoq.fullText variables. This substitution can be used in real-time clients and with batch processing. **Type:** Regex Plus **Spoken Form:** `(?s).*end of dictation.*` **Written Form:**   `nvoq.profile + ":\n" + nvoq.fullText;` **Before Substitution:** Suggest follow up in six weeks. End of dictation **After Substitution:** user@ouroffice.com: Suggest follow up in six weeks. End of dictation **Example** **-** **Append Text to Transcript:** This substitution looks for mention of an older model iPhone and appends the entire transcript with an upgrade offer. It uses the nvoq.fullText variable. This substitution can be used in real-time clients and with API batch processing. **Type:** Regex Plus **Spoken Form:** `(?s).*iPhone ?5.*` **Written Form:**   `nvoq.fullText + "\n***We are currently offering a \$50 discount on new iPhones.***\n";` **Before Substitution:** How often are you having the problem with your iPhone 5? **After Substitution:** How often are you having this problem with your iPhone 5? ***We are currently offering a $50 discount on new iPhones.*** **Example** **-** **Prepend Text to Transcript:** This substitution is invoked when a transcript includes an age phrase. It prepends the transcript with instructions when the age is less than 3 years or given in months. This substitution can be used in real-time clients and with batch processing. **Type:** Regex Plus **Spoken Form:**   `.*(d{1,3}[- ])((year|month)s?[- ]?)old.*` **Written Form:**   `sub(); function sub() { var x; var y; x = match.group(2).charAt(0); y = match.group(1); if (x =="m") {   return "***Schedule vaccines***\n" + nvoq.fullText;   } else if (y <=3) {   return "***Schedule vaccines***\n" + nvoq.fullText;   } else {   nvoq.fullText;   }` **Before Substitution:** Patient is a healthy 36 month old male... **After Substitution:** **Schedule vaccines** Patient is a healthy 36 month old male... **Example** **-** **Time-sensitive Append Text to Transcript:** This substitution compares the current date to a deadline. If the deadline has not passed, it appends a time-sensitive message. This substitution can be used in real-time clients and with batch processing. **Type:** Regex Plus **Spoken Form:** `(?s).*sold.*subscription.*` **Written Form:**   `sub();` `function sub(){` ` var deadline=new Date();` ` deadline.setFullYear(2013,11,31);` ` var today = new Date();` ` if (deadline>today){` ` return nvoq.fullText + "\n" + "Member Drive on now: CONGRATS on your SALE!";` ` }` `}` **Before Substitution:** Sold 6 month subscription. **After Substitution:** Sold 6 month subscription. ***Member Drive on now: CONGRATS on your SALE!*** **Example** **-** **Change Case:** This substitution looks for a 4-20 character word followed by "exam:". It uses the match.group(1) variable and the JavaScript String toUpperCase() method to capitalize the match, and then adds a carriage return after the colon. This substitution can be used in real-time clients and with API batch processing. **Type:** Regex Plus **Spoken Form:**   `(?m)([a-zA-Z]{4,20} exam: )` **Written Form:**   `sub();` `function sub() {` ` return match.group(1).toUpperCase() + "\n";` `}` **Before Substitution:** physical exam colon the patient is a pleasant... **After Substitution:** PHYSICAL EXAM: The patient is a pleasant... **Example** **-** **Case Sensitive:** This substitution looks for a word that matches the case in the spoken form and returns the result defined in the written form. This substitution can be used in real-time clients and with batch processing. **Type:** Regex Plus **Spoken Form:** `((?-i)ICE)` **Written Form:**   `ICE Unit` **Before Substitution:** The patient was treated at the ICE period **After Substitution:** The patient was treated at the ICE Unit. **Example** **-** **Display Character Count:** This example displays the cumulative character count at the end of each line. A line is defined by the phrase "new line" or "new paragraph". This substitution can be used in real-time clients and with API batch processing. **Type:** Regex Plus **Spoken Form:** `((n)|(z))` **Written Form:**   `match.start(1) + match.group(1);` **Before Substitution:** Mary had a little lamb new line whose fleece was white as snow new line new paragraph and everywhere that Mary went new line he lamb was sure to go new line **After Substitution:** Mary had a little lamb23 whose fleece was white as snow55 56 And everywhere that Mary went87 the lamb was sure to go112 **Example** **-** **Create a Lettered List:** This example allows a dictator to say "letter next" in order to dictate a lettered list that automatically adds a carriage return before each list item. Each new list item is also capitalized. **Type:** Regex Plus **Spoken Form:** `((letter next)(\.*)(\s*)([\S\s]*))` **Written Form:**   `var mainText = match.group(5);` `var sections = mainText.split(/letter next\.?/i);` `var newText = "";` `var letters = ["A","B","C","D","E","F","G","H","I","J","K","L","M","N","O","P","Q","R","S","T","U","V","W","X","Y","Z"];` `for(var i = 0; i < sections.length; i++) {` `                var ordinal = i < letters.length ? letters[i] : i+1;` `                var sectionText = capitalize(trimLeadingWhitespace(sections[i]));` `                newText += "\n" + ordinal + ". " + sectionText;` `}` `function capitalize(str) {` `    return str.charAt(0).toUpperCase() + str.slice(1);` `}` `function trimLeadingWhitespace(str) {` `                return str.replace(/^\s+/, "");` `}` **Before Substitution:** Admission diagnosis colon letter next cerebrovascular accident with left arm weakness letter next hyperlipidemia **After Substitution:** Admission diagnosis: A. Cerebrovascular accident with left arm weakness B. Hyperlipidemia ## Order that Substitutions are Applied to a Transcript - Literal substitutions are applied *first*, in matching longest to shortest string order. (If the same length, they are compared based on the Unicode value of each character in the strings.) - Then Regex and Regex Plus substitutions are applied next, but in an indeterminate order. - A *given string in a transcript* can only be replaced once by any single substitution. However, the *substituted result* in the transcript is subject to subsequent substitutions. - Substitutions may behave differently in Direct Text mode. **See** [**Substitution Behavior with STABLETEXT**](https://support.nvoq.com/v1/docs/administrator-help-substitutions-direct-text) **for more information.** ## Related - [Admin: Substitution Settings](/administrator-help-substitution-settings.md)