Open APIs

Expand all | Collapse all

TMF642 Alarm Management: Perceived Severity

Jump to Best Answer
  • 1.  TMF642 Alarm Management: Perceived Severity

    TM Forum Member
    Posted Jun 14, 2021 13:21
    Good morning -

    Just looking for confirmation as to which of the provided definitions for perceivedSeverity is the preferred - and an ask as to how to handle a value outside the proscribed vocabulary.

    The perceivedSeverity property in GitHub is defined as a string, with guidance to comply with ITU-T: tmforum-apis/TMF642_AlarmManagement
    "perceivedSeverity": {
       "type": "string",
       "description": "Lists the possible severities that can be allocated to an Alarm. The values are consistent with ITU-T Recommendation X.733.\nOnce an alarm has been cleared, its perceived severity is set to 'cleared' and can no longer be set."
    },​

    The user guide defines it as an enum, and sets out the values per the standard: TMF642 Alarm Management API User Guide v4.0.1 - TM Forum

    from page 20 of the alarm management user guide
    We have a system which, in addition to returning alarms which line up (semantically) with the provided enum - but additionally also can return "not set", which doesn't map to X.733. Is it preferred in that case to extend the model?

    Appreciate your insights,
    Take care,
    Karen


    ------------------------------
    Karen Aiken
    TELUS
    ------------------------------


  • 2.  RE: TMF642 Alarm Management: Perceived Severity
    Best Answer

    TM Forum Member
    Posted Jun 14, 2021 15:01
    Hi Karen
    It does appear that the Alarm resource was changed to use closed enum lists, but for some reason the updated swagger (which I see correctly in our development area) was not republished.
    I can only apologize on behalf of the Open API team, and I'll be opening a defect report to see if we can get this fixed.
    Hope it helps

    ------------------------------
    Jonathan Goldberg
    Amdocs Management Limited
    Any opinions and statements made by me on this forum are purely personal, and do not necessarily reflect the position of the TM Forum or my employer.
    ------------------------------



  • 3.  RE: TMF642 Alarm Management: Perceived Severity

    TM Forum Member
    Posted Jun 14, 2021 18:31
    No worries, and thanks very much for the prompt reply Jonathan. Understand there are many moving parts, and at least I know I'm looking in the right place for them

    I am wrestling with the best way to manage one additional value to this enum, since it is based on a standard, and our implementation has a single exception to it: the value of "Not Set". I'm getting clarity on what that value is intended to mean. I've managed extensions to include new properties to a model, but never new values in an enum.

    If it is a needed extra value, would the correct pattern be to simply add the value to the existing enum? I'm not sure how to create extensions of the models and retain the link back to the original models for this case.

    And, if it is a needed extra value, I imagine we should be investigating getting it included in X.733.

    Take care,
    Karen

    ------------------------------
    Karen Aiken
    TELUS
    ------------------------------



  • 4.  RE: TMF642 Alarm Management: Perceived Severity

    TM Forum Member
    Posted Jun 22, 2021 09:40
    We landed on a compromise for the extension of the PerceivedSecurity enum, with an eye towards future alignment with the OOB specification.

    We referenced section 2.3 of TMF630 Part 2 - "State Extension Pattern":
    https://projects.tmforum.org/wiki/display/API/TMF630+API+Design+Guidelines+4.0.1+R20.0

    Based on that pattern, we provided the following guidance to the dev team:
    Enumerations are generally considered "normative" but not comprehensive. They must not be removed from the specification, or semantically redefined by the implementation, but they can be added to - both in breadth (additional states) and depth (additional sub-states).
    The provided values should not be renamed - if the system supplying these values uses different words, your implementation should translate those to the TMF vocabulary, so that consumers can expect a standard response set for a given meaning. APIs generally should be insulating the consumers from system-specific information.

    The dev team is encouraged to use the OOB PerceivedSecurity enum as configured. If there is a business need to persist the system vocabulary to the interface, that should be done as a separate property; API providers and consumers however should be expecting the standard OOB property and value naming.

    Take care,
    Karen

    ------------------------------
    Karen Aiken
    TELUS
    ------------------------------