Add new field SeverityLevel (enum, optional) to Service Alerts feed

[ibi-group-team]

The current alerts specification does not allow feed producers (agencies) to categorize alerts based on their severity. The severity of an alert often determines the channels through which an alert should be published, how an alert is displayed to customers, and the order in which alerts should be displayed (based on severity). Often, agencies use a combination of the alert attributes (such as its effect, duration, etc.) to determine its dissemination channels and display order. The SeverityLevel field encompasses all these attributes into one. Without a field to categorize the severity of the alert, feed consumers must determine severity on the fly and in an ad-hoc manner, which adds latency and reduces consistency in the alerts dissemination process.

To solve this issue we propose that a field is added called “SeverityLevel.” The SeverityLevel field would be optional and comprised of enum values. As an example, the set of enum values may be something like one of the sets below. We are not proposing these exact enum values but instead are including them as a starting point to get feedback on what the enum values should be.

“UNKNOWN_SEVERITY”
“OTHER_SEVERITY”
“INFORMATIONAL”
“ADVISORY”
“WARNING”
“CRITICAL”

Or:

“UNKNOWN_SEVERITY”
“OTHER_SEVERITY”
“INFORMATIONAL”
“DELAYS_OF_UP_TO_TEN_MINUTES”
“DELAYS_OF_UP_TO_TWENTY_MINUTES”
“DELAYS_OF_UP_TO_THIRTY_MINUTES”

Or:

“UNKNOWN_SEVERITY”
“OTHER_SEVERITY”
“LEVEL_1_SEVERITY”
“LEVEL_2_SEVERITY”
“LEVEL_3_SEVERITY”
“LEVEL_4_SEVERITY”
...

By incorporating the SeverityLevel field in the specification, feed consumers can predetermine the extent to which an alert is published based on the value of severity, and build it into their alerts management process. For example, an alert of SeverityLevel = “INFORMATIONAL” may be configured so that it is published only to Email/SMS subscribers of the particular service that is impacted, while an alert of SeverityLevel = “CRITICAL” may be configured so that it is published to all available outlets and shown prominently on the agency’s website and by other applications. Ultimately, this change would allow transit customers to receive alerts on a more timely and consistent basis.

[abyrd]

I see the advantages of having a severity enum. I don't think the enum values should have a quantitative aspect as in the DELAYS_OF_UP_TO_TEN_MINUTES and LEVEL_1_SEVERITY examples. Severity levels would then be indicated by somewhat arbitrary individual words, so we'd need a table of exactly what the levels implied, e.g. a CRITICAL alert should be distributed to all users by all means available and affects the whole transit network.

It does seem to me though that this is aiming to control the presentation layer. It might be better to include more enum-encoded factual information about the nature of the alert to enable consumers to decide who should see the alert and through what channels. The description says consumers making these choices on the fly will introduce latency and inconsistency. I would expect the added latency to be extremely small, so small as to be negligible, and arguably variation in how and when alerts are displayed is a desirable characteristic - this variety of approaches is one reason to supply open data to many different consumers instead of a single centralized trip planning system.

[paulswartz]

We use a scale of 0-10 (as an integer). While we do have internal guidelines for what the values "mean" in terms of length of delays, that's subject to change and we have changed it in the past. And it's more of an ordering tool for alerts which aren't delays and don't have an obvious time associated with them. The system which sends alert notifications breaks the severity into 5 buckets (high, extreme, severe, moderate, minor) and uses that to decide which alerts to send to subscribers.

I don't think it's great idea to have the enumeration be time-specific, as it's not clear what that means for for non-delay alerts. I'm also not a fan of OTHER_SEVERITY: how would we expect a client using this data to order that relative to the other severity levels?

[barbeau]

In my experience severity level is currently inferred by Effect. I think further clarifying severity and coming to an agreement on producer and consumer behavior related to that would be useful, but it's not clear to me the exact use case this proposal is trying to solve.

For example, if it's just ordering the alerts, then a simple integer value is probably the best solution. If it's distribution method, then an enum specifying the distribution method is probably the best solution. In it's current form it seems like this is too vague to effectively solve any of the use cases that it could potentially address.

Could we narrow down to a specific use case that this is currently being implemented for, and general agreed-upon behavior for producers and consumers for that case?

Also, “DELAYS_OF_UP_TO_TEN_MINUTES”, “DELAYS_OF_UP_TO_TWENTY_MINUTES”, “DELAYS_OF_UP_TO_THIRTY_MINUTES” seem like Effects, not severity, to me.

[LeoFrachet]

Use case:

In Transit app, the severity of the alert changes the display in the app. There are two levels commonly used: info and warning.

Warning will display a warning sign in the "nearby" view, when info won't:

In the alert view, the same distinction is provided by either a warning sign (orange triangle) or an info sign (grey circle):

Please note here that the "Warning" level has been put on an alert which is "just" a closed entrance. If MBTA was able to set the severity, they likely wouldn't have put a warning level on this one.

[paulswartz]

• The pedestrian walkway alert has severity 1
• The elevator alert has severity 3

[LeoFrachet]

@paulswartz I'm assuming that the higher the digit, the higher the severity? Aka the elevator alert has a higher severity than the pedestrian walkway alert?

If that's the case, we just found the perfect argument for an official severity field!

FWIW, I'm personally in favor of the first option, aka “UNKNOWN_SEVERITY”, “OTHER_SEVERITY”, “INFORMATIONAL”, “ADVISORY”, “WARNING”, “CRITICAL”. But with less options. I would just keep:

• UNKNOWN_SEVERITY (as default and to be backward compatible)
• INFORMATIONAL or ADVISORY (just one of them, I personaly don't see the difference)
• WARNING
• CRITICAL

This maps the usual INFO / WARNING / ERROR tryptic most of us are used to.

As guidelines (I say guidelines, not rules) I would say:

• INFO: It should just be displayed to the user in a section along the informed entity, but shouldn't have to be put in a prominent way.
• WARNING: The fact that there is a warning should be displayed along the informed entity in every single of its occurrences (e.g. trip planner result, list of lines...). Notifications should be offered to the users of the informed entity.
• CRITICAL: To use only in case of emergency (e.g. life threatening event like a bomb alert in a subway station, system wide shutdown for snowstorm or hurricane). Should be displayed prominently across the app / site / consumer service. Notification should be offered to any user of the system.

[barbeau]

@LeoFrachet's enums roughly align with how alerts are displayed in OneBusAway. OBA uses SIRI's SituationExchange model internally, but this gets mapped to three values for the UI:

• INFO
• WARNING
• SEVERE

INFO are colored coded with app theme colors (green) and require user action to reveal them (they aren't immediately visible in the main arrivals view).

WARNINGS and SEVERE get flagged in the users main view, with WARNINGs coded yellow and SEVERE red.

EDIT - As mentioned below in code SEVERE is actually referred to as ERROR.

Example:

More OBA screenshots and implementation details are here - OneBusAway/onebusaway-android#714

[ibi-group-team]

Reading through these comments, it seems that there is agreement that a severity enum field is useful.

The specific use case for IBI is that the agency we are working with relies on a severity field to determine whether an alert should be displayed prominently on top of its trip planner.

The general consensus on enum values is:
UNKNOWN_SEVERITY
INFORMATIONAL
WARNING
CRITICAL

Any other thoughts on these values?

[abyrd]

If people find it useful to explicitly declare the severity instead of inferring it from Cause/Effect, then I agree with @LeoFrachet's response. Paralleling the INFO / WARNING / ERROR log levels common in software, and reusing what is apparently already used by One Bus Away and standard in SIRI SX, a good option seems to be INFO / WARNING / SEVERE, plus UNKNOWN for backward compatibility. Subjectively, I would lean toward SEVERE rather than CRITICAL, and not add the suffix "_SEVERITY" on only one of the enum values.

However looking at your link @barbeau I don't see any mention of severity. Digging further into SIRI specs, SIRI seems to follow the TPEG Pti26 severity enumeration (https://laidig.github.io/siri-20-java/doc/schemas/siri_situationClassifiers-v1_1_xsd/simpleTypes/SeverityEnumeration.html)

These levels are: unknown / verySlight / slight / normal / severe / verySevere / noImpact / undefined

This is probably too many levels, and doesn't include "warning" or "info". @barbeau can you clarify the connection between SIRI and the OBA enum you mentioned?

Even if it doesn't exactly match SIRI, I think @barbeau's values are a good choice, plus the UNKNOWN for backward compatibility.

[barbeau]

@abyrd Yes, unfortunately the OBA docs don't currently do a good job of explaining this (hence my open issue of creating better docs :) ).

Here are the possible values that can be set in the OBA server (using a web admin console to create an alert) and returned by the OBA server API:

    String SEVERITY_UNKNOWN = "unknown";
    String SEVERITY_NO_IMPACT = "noImpact";
    String SEVERITY_VERY_SLIGHT = "verySlight";
    String SEVERITY_SLIGHT = "slight";
    String SEVERITY_NORMAL = "normal";
    String SEVERITY_SEVERE = "severe";
    String SEVERITY_VERY_SEVERE = "verySevere";

Looks like these match the values you dug up for the TPEG Pti26 severity enumeration.

In OBA Android we then collapse these down to the three buckets I mentioned for the three ways we display alerts in the UI:

            if (ObaSituation.SEVERITY_NO_IMPACT.equals(mSituation.getSeverity())) {
                return TYPE_INFO;
            } else if (ObaSituation.SEVERITY_SEVERE.equals(mSituation.getSeverity())
                    || ObaSituation.SEVERITY_VERY_SEVERE.equals(
                    mSituation.getSeverity())) {
                return TYPE_ERROR;
            } else {
                // Treat all other ObaSituation.SEVERITY_* types as a warning
                return TYPE_WARNING;
            }

As shown above we actually use ERROR instead of SEVERE as the constant in the OBA Android code, but SEVERE seems like a better enum value to me.

[abyrd]

Thanks for the clarification @barbeau. So OBA is mapping the 7 TPEG values onto 3 buckets and any other software that handles SIRI could easily perform the same mapping. So I'd agree with @ibi-group-team's comment above on the general form of the severity enum. I do think we should avoid namespacing prefixes or suffixes (SEVERITY_ or _SEVERITY) especially if they only appear on some enum values. I see this convention as a holdover from defining integer enum constants in a big C header. Most languages and data formats we're using these days will have enum types as a language feature, which provides natural scoping and context for the value names.

Combining with the approach @barbeau describes in OBA, I would therefore suggest:

• UNKNOWN
• INFO
• WARNING
• SEVERE

@ibi-group-team does this work for you? Any other comments? It seems like this one could rapidly move to a pull request.

[ibi-group-team]

We are ok with using the enum value SEVERE instead of CRITICAL. However, for alerts with unknown severity we recommend including the suffix ‘SEVERITY’ (i.e. UNKNOWN_SEVERITY) to maintain consistency with the Cause and Effect enum values (i.e. UNKNOWN_CAUSE and UNKNOWN_EFFECT).

We will open a pull request with a full proposal and call for a vote soon.

[abyrd]

That makes sense to me: UKNOWN_SEVERITY just for consistency with the rest of the spec. I think there's agreement on this proposal.

[LeoFrachet]

Yup, there is! Nice! Thanks @ibi-group-team for making those proposals move forward and for drafting the proposals!