Multiple Choice Response (MCR) Matching

This page describes the MCR functionality at a high level for your understanding, and highlights the necessary configurations.

In some integrations, some adapters, such as Vocera Incoming WCTP Adapter or Vocera Incoming VMI Adapter, can be configured to handle an external system's multiple and arbitrary possible responses to an alert. These adapters, which use protocols that support multiple choice response (MCR) messages, may also be configured to allow the end user to select among multiple possible responses to an alert on their device. This functionality requires manual integration in the standard Vocera solution.

This page describes the MCR functionality at a high level for your understanding, and highlights the necessary configurations. It shows how the adapters for those protocols define the message types and rules to support responding to messages processed as events. It also shows how display values for responses received from a remote system can be displayed in events. Finally, it shows storing responses to support message forwarding where the remote message and all specified options can be forwarded to the user's device.

The standard Vocera Platform EMDAN alerting process provides Accept and Decline responses to an alert. An external system may require a different response option (such as Yes and No) or even a dynamically generated response. Furthermore, a Vocera Platform EMDAN integration may be required to provide the end user with the responses specified by the external sending system. This may occur when an existing Vocera Platform Voice Service integration is upgraded to Vocera Platform EMDAN and that customer's VMI-based user experience must be maintained, which includes responses other than Accept and Decline.

The MCR functionality in this page includes description of:

Design Overview

The following features must be created on the Vocera system if they do not exist in the customer's implementation.

A ResponseOptions dataset on the Vocera system contains each option for each message received by the MCR-capable adapters. The dataset contains the value to send for that response (stored in the response_value attribute), the display text for that value (stored in the display_value attribute), and an index for the response within the list of responses for the message (stored in the response_index attribute).

Message types are configured on the MCR-capable adapters. The message type configuration requires a path relative to the starting dataset which stores a "message key" that uniquely identifies the message. The message key is used to identify the message so that data for the response can be retrieved.

The message type configuration also allows matching responses to a regular expression. The match process takes a path to a to-one link attribute for the ResponseOptions dataset which is used to link the matching response to the record created by the message type mapping.

The standard Vocera Platform EMDAN solution design requires some additional configuration for the MCR-capable adapters to function. You will have to create a one-to-one link attribute from the Alerts dataset to the AlertMetaData dataset, and name the link meta_data. The message type will store the message key value in the meta_data.message_key path, so the alert record is linked to the adapter's message data. You will also need to create two many-to-one link attributes from the Alerts dataset to the ResponseOptions dataset, and name these links accept_response and decline_response. These link attributes are used by message types in the matching process to identify the response to use for Accept and the response to use for Decline. You can follow this pattern to create additional link attributes for other responses.

Rules are configured on a dataset to deliver event responses back to the originating external system. These rules should be conditioned on the user's response and the existence of the link for that response. When the response is Accept, the rule should send the accepted_response.response_value for the linked alert back to the external system. When the response is Decline, the rule should send the declined_response.response_value for the linked alert back to the external system.

In order to allow end user devices to use the display value specified by the external originating system for event responses, follow the same paths on the rule or workflow that sends the alert to the device to find the correct display value.

In order to support the "message forwarding" scenario functionality:

Event Handling Design

The MCR-capable functionality is based on the existing Vocera Platform EMDAN solution. It uses the standard alert processing design, including the existing rules, adapter configurations, and workflows for escalating alerts, sending alerts, and receiving responses.

The primary changes are in the processes that interface with the new MCR-capable adapters:

An exception to these primary changes occurs when the actual values requested by the originating source system are to be sent as responses to the endpoint device. See Using Requested Display Values below for details.

The examples in this event handling design assume the following scenario:

Other scenarios should work in a similar manner. However, there are a couple of special cases that need further mention:

Dataset Support

In order to support sending responses after a failover, each adapter will utilize a table in which to store critical information about received messages needed to send responses and status updates. The AlertMetaData and ResponseOptions datasets are required by the MCR-capable adapters and must be created if they do not exist in the customer implementation. The Alerts links must be manually added to the AlertMetaData and ResponseOptions datasets.

The AlertMetaData dataset is used by all MCR-capable adapters to store additional alerting options that should be persisted across a failover. The AlertMetaData dataset must have a locally unique key, a single string "message key", which is required to begin with the interface reference name followed by a ":".

The ResponseOptions dataset is used by the adapters to store response options. The ResponseOptions dataset provides the following attributes:

The Alerts dataset requires the following additional link attributes be created:

Adapter Message Type Definition

Message type definition is similar to the configurations defined on other adapters receiving alerts, with the following significant differences:

This example is effectively a copy of the standard TAP externally escalated Nurse Call message, with the additional support for the multi-response messages. Note the presence of the "Link for Responses" configuration option. In a "message forwarding" scenario, this is used to specify all of the Alert record's "responses".

Returning a Response

To return a response to the originating system, a dataset rule configured for the MCR-capable adapter is used that fires when:

The following shows an example configuration for a rule on the Responses dataset. The important values are the Message Key and Response fields; the other values shown are more specific to the adapter, in this example the Vocera Incoming WCTP Adapter.

Using Requested Display Values

The accepted_response and declined_response links (or similarly defined links) can also be used to display the values requested by the originating system, instead of the standard values (e.g., Accept and Decline) currently used in the Vocera Platform EMDAN solution. The implementation details depend on whether the display is controlled by the rule (e.g., Badges with XMPP) or by a workflow page (e.g., Cisco devices). In either case, the value to be stored if the response is selected cannot be changed (to prevent breaking other parts of the Vocera Platform EMDAN workflow for event escalations), so the rules to send the responses do not change.

Note that the current outbound Vocera VMI integration cannot display the values requested by the originating system; VMI cannot specify a value to store that is separate from the value to display. Also, using the Vocera XMPP Adapter, this will not work in the Mobile App which does not allow the display value to be overridden.

Workflow

In the standard Vocera Platform EMDAN solution, the display value for the "Accept" button is embedded in the code, in part to prevent breaking the Vocera Platform EMDAN workflow for event escalations. However, the accept response's display value can be used instead.

In this example, a link in the workflow is updated to use a display value for the "Accept" button that is specified by the originating system:

Note that there is a potential issue because the workflow does not allow much conditional display (e.g., use the display_value if set, otherwise use "Accept"). This is generally an issue if alerts of a particular type are coming from multiple systems, in which case, this is not recommended.

Rules

The following example shows how to do this, in this case using the Vocera XMPP Adapter and passing the requested value to the badges:

For rules, if there are cases where the display_value would not be available, then separate rules would be needed for the default value, probably differentiated by conditions where the value is available and where the value is not available.