How to Configure the System-Level Voice Integration

Configure the system-level voice integration by editing the <voice> section of the evs.xml file, a structured XML document.

In most situations, the default values Vocera provides in the <voice> section of evs.xml are sufficient. However, if you want Vocera to send an escalation notification when a message send or deletion fails, you must specify a value for <voceraid> in the message escalation parameters. When <voceraid> is not specified, Vocera discards the escalation message.

In all other cases, the default values Vocera provides for the parameters in evs.xml are sufficient, unless you want to customize the voice integration.

To configure the system-level voice integration:

  1. On the Vocera Environmental Services Integration server, open the \vocera\evs\resources\evs.xml file in a text editor.
  2. Customize the behavior of the completion query by setting values for the tags in the <configuration><voice><completion-query> section of the evs.xml file.

    Specify a value within each pair of begin and end tags as follows:

    Tag Value
    <configuration>
       <voice>
          <completion-query>
             <nack-reminder-delay/>

    Use the <nack-reminder-delay/> tag to specify the amount of time (in seconds) to wait before sending a follow-up completion query when a user fails to acknowledge the previous query with either a "Yes" or a "No".

    Users must acknowledge receipt of a query by responding to it in either the affirmative or negative. A non-acknowledgement ("nack") results in a retry after a default time of 60 seconds has elapsed. The waiting time for a non-acknowledgement is much shorter than the waiting time for a response of "No", which is determined by <ack-reminder-delay/>.

    <configuration>
       <voice>
          <completion-query>
             <ack-timeout/>

    Use the <ack-timeout/> tag to specify the timeout value (in seconds) when a user has not responded to a completion query and has responded to the previous query with a "No". If the specified timeout value is reached, the room cleaning request is escalated to a manager group in the Vocera Voice Server and the task is removed. By default, the timeout value is 7200 seconds.

    <configuration>
       <voice>
          <completion-query>
             <nack-timeout/>

    Use the <nack-timeout/> tag to specify the timeout value (in seconds) when a user has not responded to a completion query and has failed to acknowledge the previous query with either a "Yes" or a "No". If the specified timeout value is reached, the room cleaning request is escalated to a manager group in the Vocera Voice Server and the task is removed. By default, the timeout value is 3600 seconds.

    <configuration>
       <voice>
          <completion-query>
             <delay/>
    Use the <delay/> tag to specify the amount of time (in seconds) to wait before sending a completion query, after a user indicates that a cleaning request is in progress. By default, this time interval is 10 seconds.
    <configuration>
       <voice>
          <completion-query>
             <ack-reminder-delay/>

    Use the <ack-reminder-delay/> tag to specify the amount of time (in seconds) to wait before sending a follow-up completion query when a user responds to the previous query with a "No". By default, the system waits 600 seconds before sending a new completion query to the user.

    Users must acknowledge receipt of a query by responding to it in either the affirmative or negative. The waiting time for a non-acknowledgement, which is determined by the <nack-reminder-delay/>, is much shorter than the waiting time for a response of "No".

    <configuration>
       <voice>
          <completion-query>
             <message/>
    Use the <message/> tag to specify a yes/no question that asks the Vocera device user if a cleaning request is complete. The Vocera device auto-enunciates this question for the user based on the <delay>, <ack-reminder-delay>, and <nack-reminder-delay> timers. By default, this query is, "Would you like to mark the request completed?".
  3. Customize the behavior of the in-progress query by setting values for the tags in the <configuration><voice><inprogress-query> section of the evs.xml file.

    Specify a value within each pair of begin and end tags as follows:

    Tag Value
    <configuration>
       <voice>
          <inprogress-query>
             <ack-timeout/>

    Use the <ack-timeout/> tag to specify the timeout value (in seconds) when a user has not responded to an in-progress query and has responded to the previous query with a "No". If the specified timeout value is reached, the room cleaning request is escalated to a manager group in the Vocera Voice Server and the task is removed. By default, the timeout value is 1000 seconds.

    <configuration>
       <voice>
          <inprogress-query>
             <message/>
    Use the <message/> tag to specify a yes/no question that asks the Vocera device user if a cleaning request is in progress. The Vocera device auto-enunciates this question for the user immediately after announcing a cleaning request. The device also enunciates reminders based on the <ack-reminder-delay> and <nack-reminder-delay> timers. By default, this query is, "Would you like to mark the request in progress?".
    <configuration>
       <voice>
          <inprogress-query>
             <nack-reminder-delay/>

    Use the <nack-reminder-delay/> tag to specify the amount of time (in seconds) to wait before sending a follow-up in-progress query when a user fails to acknowledge the previous query with either a "Yes" or a "No".

    Users must acknowledge receipt of a query by responding to it in either the affirmative or negative. A non-acknowledgement ("nack") results in a retry after a default time of 60 seconds has elapsed. The waiting time for a non-acknowledgement is much shorter than the waiting time for a response of "No", which is determined by <ack-reminder-delay/>.

    <configuration>
       <voice>
          <inprogress-query>
             <ack-reminder-delay/>

    Use the <ack-reminder-delay/> tag to specify the amount of time (in seconds) to wait before sending a follow-up in-progress query when a user responds to the previous query with a "No". By default, the system waits 600 seconds before sending a new in-progress query to the user.

    Users must acknowledge receipt of a query by responding to it in either the affirmative or negative. The waiting time for a non-acknowledgement, which is determined by the <nack-reminder-delay/>, is much shorter than the waiting time for a response of "No".

    <configuration>
       <voice>
          <inprogress-query>
             <nack-timeout/>

    Use the <nack-timeout/> tag to specify the timeout value (in seconds) when a user has not responded to an in-progress query and has failed to acknowledge the previous query with either a "Yes" or a "No". If the specified timeout value is reached, the room cleaning request is escalated to a manager group in the Vocera Voice Server and the task is removed. By default, the timeout value is 600 seconds.

  4. Specify how often Vocera retries the deletion of a message from a user's device (if the first deletion attempt fails) by setting values for the tags in the <configuration><voice><delete><retry> section of the evs.xml file.

    Specify a value within each pair of begin and end tags as follows:

    Tag Value
    <configuration>
       <voice>
          <delete>
             <retry>
                <timeout/>
    Use the <timeout/> tag to specify the total duration of time (in seconds) that may elapse during message delete retries before a timeout occurs. By default, the value is 600 seconds.
    <configuration>
       <voice>
          <delete>
             <retry>
                <interval/>
    Use the <interval/> tag to specify the total duration of time (in seconds) that Vocera will wait before attempting to delete a message, if the previous deletion attempt failed. By default, the value is 30 seconds.

    The <configuration><voice><delete> section of evs.xml specifies system-level defaults for the delete retry behavior. You can optionally override these settings in the pluginproperties.xml file for each vendor.

  5. Specify how often Vocera re-sends a message to a user's device (if the first delivery attempt fails) by setting values for the tags in the <configuration><voice><send><retry> section of the evs.xml file.

    Specify a value within each pair of begin and end tags as follows:

    Tag Value
    <configuration>
       <voice>
          <send>
             <retry>
                <timeout/>
    Use the <timeout/> tag to specify the total duration of time (in seconds) that may elapse during message send retries before a timeout occurs. By default, the value is 600 seconds.
    <configuration>
       <voice>
          <send>
             <retry>
                <interval/>
    Use the <interval/> tag to specify the amount of time (in seconds) that Vocera will wait before attempting to re-send a message, if the previous delivery has failed. By default, the value is 30 seconds.

    The <configuration><voice><send> section of evs.xml specifies system-level defaults for message send retry behavior. You can optionally override these settings in the pluginproperties.xml file for each vendor.

  6. Specify tone, priority, and recipient customizations for an escalation message in the <configuration><voice><escalation><message> section of the evs.xml file. Vocera initiates an escalation if a message send or delete attempt results in an unrecoverable failure.

    Customize the escalation routine by specifying a value within each pair of begin and end tags as follows:

    Tag Value
    <configuration>
       <voice>
          <escalation>
             <message>
                <priority/>
    Use the <priority/> tag to specify one of the following VMI message priorities:
    • 0 for normal priority
    • 1 for high priority
    • 2 for urgent priority
    <configuration>
       <voice>
          <escalation>
             <message>
                <voceraid/>

    Use the <voceraid/> tag to specify the name of a Vocera group or a Vocera User ID as the recipient of the escalation message. If you do not specify a value, Vocera EVS discards escalation messages.

    <configuration>
       <voice>
          <escalation>
             <message>
                <tone/>
    Optionally use the <tone/> tag to specify the filename of a custom audio tone to play when an escalation arrives on a Vocera device. If you do not specify a custom tone, the Vocera device plays the default message "clunk" sound. The custom tone file has the following requirements:
    • Location: \vocera\data\prompts\custom
    • Audio Format: 16 bit Monophonic WAV PCM
    • Sampling Rate: 8000 samples/second

    The <configuration><voice><escalation> section of evs.xml specifies system-level defaults for message escalations. You can optionally override these settings in the pluginproperties.xml file for each vendor.

  7. Specify tone and priority customizations for all Vocera-initiated messages (except escalations) in the <configuration><voice><message> section of the evs.xml file.

    Customize the message by specifying a value within each pair of begin and end tags as follows:

    Tag Value
    <configuration>
       <voice>
          <message>
             <priority/>
    Use the <priority/> tag to specify one of the following VMI message priorities:
    • 0 for normal priority
    • 1 for high priority
    • 2 for urgent priority
    <configuration>
       <voice>
          <message>
             <tone/>
    Optionally use the <tone/> tag to specify the filename of a custom audio tone to play when a cleaning request arrives on a Vocera device. If you do not specify a custom tone, the Vocera device plays the default message "clunk" sound. The custom tone file has the following requirements:
    • Location: \vocera\data\prompts\custom
    • Audio Format: 16 bit Monophonic WAV PCM
    • Sampling Rate: 8000 samples/second

    The <configuration><voice><message> section of evs.xml specifies system-level defaults for message priorities and tones. You can optionally override these settings in the pluginproperties.xml file for each vendor.

  8. Save the evs.xml file and continue with the system-level plugin integration.

The voice configuration is now complete. Following is an example of a typical system-level voice configuration.

<voice>
    <completion-query>
        <nack-reminder-delay>60</nack-reminder-delay>
        <ack-timeout>7200</ack-timeout>
        <nack-timeout>3600</nack-timeout>
        <delay>10</delay>
        <ack-reminder-delay>600</ack-reminder-delay>
        <message>Would you like to mark the request completed?</message>
    </completion-query>
    <inprogress-query>
        <ack-timeout>1800</ack-timeout>
        <message>Would you like to mark the request in progress?</message>
        <nack-reminder-delay>60</nack-reminder-delay>
        <ack-reminder-delay>300</ack-reminder-delay>
        <nack-timeout>600</nack-timeout>
    </inprogress-query>
    <delete>
        <retry>
            <timeout>600</timeout>
            <interval>30</interval>
        </retry>
    </delete>
    <send>
        <retry>
            <timeout>600</timeout>
            <interval>30</interval>
        </retry>
    </send>
    <escalation>
        <message>
            <priority>0</priority>
            <voceraid/>
            <tone/>
        </message>
    </escalation>
    <message>
        <priority>0</priority>
        <tone/>
    </message>
</voice>