Open APIs

Expand all | Collapse all

TMF642 - Alarm resource model

  • 1.  TMF642 - Alarm resource model

    TM Forum Member
    Posted Aug 02, 2021 05:00
    Hello,

    we are working with the Alarm API specification and have 3 questions about some attributes:

    1)  Attribute id

     The attribute id is commonly a string definition (in any TmForum specifications I have seen yet). Only here in the alarm resource model, the id has been defined as an integer. Any reference id (for related resources) are again defined as string. So, this is not consistent in our view and we are also having trouble to reduce the id to integer values only.
    Is this a defect or supposed to be?
    2) Attribute state

    For state attributes we are normally expecting an enumeration field to support a life-cycle model. We cannot find a clear/strikt enumeration of allowed values in the PDF v4.0.1. user guide specification in contrast to other attributes like AlarmTye.  On the other side the swagger definition v4.0.0 does show an enumeration list. So we will go with the swagger specification here, we like to see more clear description of possible values for any attribute with enum list in swagger.

    3) Attribute plannedOutageIndicator

    We cannot find any details about how to use the plannedOutageIndicator attribute. An indicator sounds more like a boolean switch, but the definition again does allow arbitrary strings. So, is it foreseen that the model user defines its custom logic for this indicator?

    Best Regards, Detlef

    ------------------------------
    Detlef Kleinfelder
    IBM Corporation
    ------------------------------


  • 2.  RE: TMF642 - Alarm resource model

    TM Forum Member
    Posted Aug 02, 2021 10:19
    Hi Detlef
    Thanks for your feedback
    1) I took a quick look at the referred standard T-REC-X.733 (here), but I didn't see any specific reference to the data type of an alarm ID. So looks like a defect to me, I plan to open a Jira issue.
    2) You are right, many APIs had their state/status attribute updated from open-ended string to string limited by enum. I guess that they didn't get to alarm yet, I can add it to the Jira.
    3) I'm afraid I don't know enough here to give a meaningful answer, sorry.
    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 resource model

    TM Forum Member
    Posted Aug 02, 2021 10:36
    Hello Jonathan,
     
    can I see and follow the Jira issues your are going to create?
     
    Thx
    Detlef Kleinfelder
    Consulting IT Architect, IBM Automation Lab Services
    Cloud Service Management and Operations & AiOps
    IBM Deutschland GmbH
    Phone: +49-171-7663336
     
    Vorsitzender des Aufsichtsrats: Sebastian Krause
    Geschäftsführung: Gregor Pillen (Vorsitzender), Agnes Heftberger, Norbert Janzen, Markus Koerner, Christian Noll, Nicole Reimer
    Sitz der Gesellschaft: Ehningen / Registergericht: Amtsgericht Stuttgart, HRB 14562 / WEEE-Reg.-Nr. DE 99369940
     
     
     
     





  • 4.  RE: TMF642 - Alarm resource model

    TM Forum Member
    Posted Aug 02, 2021 10:42

    If you are a member of the Open API collaborative project, you can see the JIRA here.

    But basically I raised the three points you mentioned in your post.



    ------------------------------
    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.
    ------------------------------



  • 5.  RE: TMF642 - Alarm resource model

    TM Forum Member
    Posted Aug 02, 2021 10:53
    @Detlef Kleinfelder wrote:
    ​> we are working with the Alarm API specification and have 3 questions about some attributes:

        I'm probably to blame so I'll answer those here.

    > The attribute id is commonly a string definition (in any TmForum specifications I have seen yet). Only here in the alarm resource model, the id has been defined as an integer.

        You may consider this an error.  The current Alarm schema uses the Entity base schema which will define the id attribute type consistently as string.

    > For state attributes we are normally expecting an enumeration field to support a life-cycle model.

    The definition of the state attribute in the User Guide includes the enumerated values in the description.

    state      A string. Defines the alarm state during its life cycle (raised | updated | cleared).

    The Alarm schema in the swagger provides an enumeration:

    "state": {
        "type": "string",
        "description": "Defines the alarm state during its life cycle (raised | updated | cleared).",
        "enum": [
            "raised",
            "updated",
            "cleared"
        ]
    },


    > We cannot find any details about how to use the plannedOutageIndicator attribute. An indicator sounds more like a boolean switch, but the definition again does allow arbitrary strings. So, is it foreseen that the model user defines its custom logic for this indicator?

         I think this really was meant to be a boolean.  We should update it as such in the next release.

    ------------------------------
    Vance Shipley
    SigScale
    ------------------------------



  • 6.  RE: TMF642 - Alarm resource model

    TM Forum Member
    Posted Aug 03, 2021 11:33
    Thx Vance, appreciate the updates you have mentioned.

    for 2) we have only access to the v4.0.0 swagger json definition on GitHub, which does NOT restrict state to the enum list. Probably this is due to the version mismatch 4.0.1 of the PDF. Can I find and access  an updated json file (v4.0.1?) with the snippet you have posted here for the state definition?
    Likely, there are some more changes in the new swagger json file.

    Beside, I was missing they typical life-cycle diagram for state (which might be quite simple as long as ackState will be left out).

    for 3) can you tell us about the planned timeline for the next release of the API?
    We would start logically with a boolean definition already to simplify the usage. So type string, but using only boolean values for this string.


    Best wished, Detlef

    ------------------------------
    Detlef Kleinfelder
    IBM Corporation
    ------------------------------



  • 7.  RE: TMF642 - Alarm resource model

    TM Forum Member
    Posted Aug 04, 2021 05:47
    Hi Detlef,
    Version 4.0.1 of the User Guide simply indicates that the published document has passed through Member Evaluation and TM Forum Approval. There have been no changes to the technical content of the document which still relates to v4.0.0 of the Swagger.
    Best regards,
    Alan

    ------------------------------
    Alan Pope
    Collaboration Manager
    TM Forum
    United Kingdom
    ------------------------------



  • 8.  RE: TMF642 - Alarm resource model

    TM Forum Member
    Posted Aug 04, 2021 09:33
    ok, got it,
    though the swagger json files v4.0.0, which I can access from GitHub or from the "release 21 reference implementations", does not include the following snippet (posted above/before by Vance).

    "state": {
        "type": "string",
        "description": "Defines the alarm state during its life cycle (raised | updated | cleared).",
        "enum": [
            "raised",
            "updated",
            "cleared"
        ]
    },​

    So it remains unclear for me, which is more current swagger file version and where can I access it.

    Regards Detlef



    ------------------------------
    Detlef Kleinfelder
    IBM Corporation
    ------------------------------