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.0Based 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
------------------------------
Original Message:
Sent: Jun 14, 2021 18:31
From: Karen Aiken
Subject: TMF642 Alarm Management: Perceived Severity
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
Original Message:
Sent: Jun 14, 2021 15:01
From: Jonathan Goldberg
Subject: TMF642 Alarm Management: Perceived Severity
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.
Original Message:
Sent: Jun 14, 2021 12:27
From: Karen Aiken
Subject: TMF642 Alarm Management: Perceived Severity
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
------------------------------
Karen Aiken
TELUS
------------------------------