Dictation formatting

The formatting options API enables you to display and modify user-level dictation formatting options, which control how spoken words are formatted as written text. For example, you can let users configure how dates or numbers are written.

Display options

You have two ways to expose dictation formatting options to your users:

• Use the built-in Dragon Copilot UI: Display the dictation formatting page directly in an iframe using a settingsViews URL. This option requires minimal development effort and provides a ready-made, localized interface. For more information, see Display settings and library items.

• Build a custom UI: Use this API to retrieve the dictation formatting options and build your own interface. Use this approach when you need to integrate formatting options directly into your application's own UI.

The rest of this article describes the custom UI approach.

Formatting options structure

The API returns formatting options as a complex object containing one or more groups of configurable options. The following example shows a single top-level group with one parameter and one nested subgroup:

const options: FormattingOptions = {
  name: "medical",
  title: "Formatting",
  description: "",
  comment: "",
  parameters: [],
  examples: [],
  groups: [
    {
      name: "date",
      title: "Dates",
      description: "Define how the system writes dates.",
      comment: "",
      parameters: [
        {
          name: "DateFormatting",
          title: "Format dates:",
          description: "The system writes dates as you say them or converts them to standard formats.",
          key: "//medical/date/DateFormatting",
          value: "AsSpoken",
          type: 3,
          index: 1,
          lockState: "unlocked",
          comment: "",
          options: [
            {
              name: "Disabled",
              title: "Disabled",
              description: "",
              comment: "",
              examples: [],
            },
            {
              name: "AsSpoken",
              title: "As spoken",
              description: "",
              comment: "",
              examples: [],
            },
          ],
          examples: [],
        },
      ],
      examples: [
        {
          spoken: "September twelve two thousand twenty",
          written: "September 12, 2020",
        },
      ],
      groups: [
        {
          name: "date_half_numeric",
          title: "Months spoken as words",
          description: "Define how the system writes dates when you say the month by name.",
          comment: "",
          parameters: [
            {
              name: "DateHalfNumericLeadingZeros",
              title: "Write days 1-9 of the month:",
              description: "The system writes the day of the month as you say it, or with two digits.",
              key: "//medical/date/date_half_numeric/DateHalfNumericLeadingZeros",
              value: "AsSpoken",
              type: 3,
              index: 0,
              lockState: "unlocked",
              comment: "",
              options: [
                {
                  name: "AsSpoken",
                  title: "As spoken",
                  description: "",
                  comment: "",
                  examples: [],
                },
                {
                  name: "Expanded",
                  title: "With a leading zero",
                  description: "",
                  comment: "",
                  examples: [],
                },
              ],
              examples: [],
            },
          ],
          examples: [],
          groups: [],
        },
      ],
    },
  ],
};

This example has a single top-level group "date" containing a parameter with the key "//medical/date/DateFormatting". A parameter controls a specific formatting behavior. The options array of a parameter lists the possible values. In this example, the possible values are "Disabled" and "AsSpoken". The value property holds the current selection. In this example, the current selection is "AsSpoken".

The "date" group also contains a nested subgroup "date_half_numeric", which has its own parameter "//medical/date/date_half_numeric/DateHalfNumericLeadingZeros" controlling the day-of-month format.

The examples array at the group level contains sample spoken phrases and their corresponding written output, illustrating the current formatting behavior. These examples are dynamic: each time you call updateFormattingOption(), the returned object contains recalculated examples that reflect the newly selected values.

Get formatting options

Call DragonCopilotSDK.dragon.formattingOptions.getFormattingOptions() to retrieve the current formatting options:

const options = await DragonCopilotSDK.dragon.formattingOptions.getFormattingOptions();

Update a formatting option

Call DragonCopilotSDK.dragon.formattingOptions.updateFormattingOption() to modify a formatting option. The function returns the full updated formatting options object.

Use the key from a parameter and a value from that parameter's options array:

const updatedOptions = await DragonCopilotSDK.dragon.formattingOptions.updateFormattingOption({
  key: "//medical/date/DateFormatting",
  value: "AsSpoken",
});

Generate UI for formatting options

The title, description, and examples properties are designed to be displayed in your UI and are localized based on the SDK's configured language.

Each parameter has a type property that indicates how the predefined options behave. Use the DragonCopilotSDK.dragon.formattingOptions.ParameterTypes enum to check the type:

Value	ParameterType	Behavior
0	Boolean	True or False
1	Number	Numeric values
2	String	String values
3	List	A list of enum-like strings

The examples arrays are dynamic. Calling updateFormattingOption() returns a fresh FormattingOptions object in which the examples are recalculated to reflect the new selection – so the displayed samples always match the current formatting behavior. Because of this, always re-render the complete options object, including examples, after every update.

Handle concurrent updates

When updateFormattingOption is called in quick succession, calls can be pending at the same time. If the result of an earlier call is rendered after a later call has already returned, the user's most recent change appears to temporarily revert.

To prevent this problem, track the most recent operation and only re-render once the latest call completes:

let lastOperation: string = null;

// Called when the user changes a setting in the UI.
async function onOptionChange(key: string, value: string) {
  try {
    const correlationId = crypto.randomUUID();
    lastOperation = correlationId;

    const formattingOptions = await DragonCopilotSDK.dragon.formattingOptions.updateFormattingOption({
      key,
      value,
    });

    // Discard the result if a newer update has been initiated.
    if (lastOperation !== correlationId) {
      return;
    }

    // Re-render the UI with the updated formatting options.
    renderFormattingOptions(formattingOptions);
  } catch (error) {
    // Handle errors, for example by prompting the user to try again.
  } finally {
    lastOperation = null;
  }
}