From OpenNMS

Contents 1 Overview 2 User Stories 2.1 A Simple USSD-only Sequence 2.2 An SMS Short Code Sequence 3 Strategy 3.1 Changes to sequence transaction element 3.2 Changes to transaction child elements 3.3 User-defined reason codes 4 Acceptance Criteria

Overview

A mobile sequence monitor test may fail for a variety of reasons. This specification covers the case where a sequence fails due to receiving a response message that constitutes an error based on a priori knowledge of how a sequence is expected to operate.

User Stories

A Simple USSD-only Sequence

The user wishes to test a mobile sequence that tests a USSD-only balance inquiry service as described in the following table.

Caption

Step	Direction	Message Type	Far Number	Message Content
1	TX	N/A	USSD	*225#
2	RX	N/A	USSD	Your balance is $42.00. Last payment of $45.67 received on 2009-12-05.

The user would define this mobile sequence with the following XML configuration:

        <mobile-sequence xmlns="http://xmlns.opennms.org/xsd/config/mobile-sequence">
          <transaction label="ussd-balance" gatewayId="acm4">
            <ussd-request gatewayId="acm4" label="req-balance" text="*225#" />
            <ussd-response gatewayId="acm4" label="balance-resp">
              <session-status>NO_FURTHER_ACTION_REQUIRED</session-status>
              <matches>(?s).*Your balance is \$[0-9.]+\. Last payment of \$[0-9.]+ received on [0-9-]{8,10}\..*</matches>
            </ussd-response>
          </transaction>
        </mobile-sequence>

The user knows that a response of "An error occurred processing your balance request" in step 2 indicates a problem that should cause this sequence to be considered failed. If this response is received at this stage, the sequence should be immediately marked as failed. The user wants the reason code on the outage to contain the label attributes of the transaction and action that the monitor was processing when the failure occurred, plus the expected and actual responses received at that step.

An SMS Short Code Sequence

The user wishes to test a mobile sequence that tests a stock-quote service that interacts via SMS network short codes as described in the following table. Responses indicating success have a subscript beginning with S, and failures with F.

Caption

Step	Direction	Message Type	Far Number	Message Content
1	TX	SMS	78625	RHT
2S1	RX	SMS	78625	Red Hat Inc. last traded at $30.12
2S2	RX	SMS	78625	Error: unknown ticker symbol RHT
2F1	RX	SMS	403	Error: provider forbidden for shortcode 78625
2F2	RX	SMS	404	Error: provider not found for shortcode 78625

In this case, receiving an error response from the short-code is still considered a success because the point of the sequence test is to verify the operation of the connection between the carrier network and the service provider running the stock-quote service. A failure match for this service requires matching both the source number and the content of the response received. As shown in step 2_F1 and 2_F2, the source number may vary, so the matching of the source number should be pattern-based rather than an exact match.

Strategy

The code flow for processing replies in the MobileSequenceMonitor may need to be "forked" to allow the monitor to recognize both successful and failed responses for a given sequence. I'm hesitant to specify too much since my understanding of the code flow is based more on experience troubleshooting sequences than on any comprehensive understanding of the design. The following are subject to revision.

Changes to sequence transaction element

The transaction child element of a mobile-sequence element should get a new description attribute that is meant to contain a more verbose and operator-friendly string than the existing label attribute.

Changes to transaction child elements

The ussd-request, ussd-response, sms-request, and sms-response elements should get a new description attribute that is meant to contain a more verbose and operator-friendly string than the existing label attribute.

User-defined reason codes

Regardless of the strategy used to implement failure matching, the user must be able to specify a reason code when a failure match is detected. The values of the new description attributes on the transaction element and its children must be accessible for use in reason codes. The actual message content of a response message detected as a failure match must also be accessible for use in reason codes. Prefer tokenization of the form ${transactionDescr}, ${requestDescr}, ${responseDescr}, ${failureMatchDescr}, etc.

Acceptance Criteria

1. For all types of sequences, the sequence schema must allow specification of responses that are indicative of a failure.
2. For SMS sequences, the sequence schema must allow failure responses to be specified based on source number, message content, or a combination of the two.
3. When a failure response is matched, the following dynamic variables must be made available for inclusion in the reason code returned to the poller:
   1. The value of the label and description attributes on the current transaction
   2. The value of the label and description attributes on the current sms-response or ussd-response within the current transaction
   3. The value of the description attribute on the failure match itself