Open APIs

Expand all | Collapse all

641 - Exception Management

  • 1.  641 - Exception Management

    TM Forum Member
    Posted Aug 17, 2021 12:03
    Hi All,

    In our implementation of ServiceOrderManagement, we need to handle exceptions. It was not clear on what is the recommended mechanism to handle exceptions. Our exceptions are triggered when the orchestration did not /failed to run a step and they requires "an external touch": manual handling or external Process. Exceptions could be of:
      - Missing information
      - Failed to run a task (ie. activation failure)
      - Manual process ("not yet" automated process we want a user to manually run)
      - ...

    1) To my knowledge, there is no "generic" API to carry exceptions (like a generic API to carry exceptions for ServiceOrder, ProductOrder, ResourceOrder...)

    2) We also looked into the ServiceOrderInformationRequired Event. InformationRequired seems to only cover a subset of exceptions

    3) We are planning to introduce something like ServiceOrderExceptionEvent which:
         - leverage the event entity
         - event will be the ServiceOrder
         - in the event, we'll add additional details to provide more context about the exception:
            - attributes like: exception, message, serviceOrderItem (similar to jeopardyAlert)
            - attributes that specify what could be specify the reason of the failure (like a related service/resource blocking the activation)
            - attributes to tell agent what are the available treatments for this specific exception. For example:
                   - Retry (agent fixed what cause the error, and is telling us that we can retry the step that failed)
                   - Resume (agent decided to manually activate and is telling us that we can move to the next step)
                   - Stop (agent decided to manually handle the entire ServiceDelivery manually, and is telling us that consider the service delivered and go to the end of the process)
                   - ...

         - The event could look like:
                  - event:
                        - eventType: serviceOrderException
                        - exceptionDetails:
                              - name
                              - serviceOrderItem
                              - serviceRelationship
                              - availableTreatments
                              - ...
                        - event:
                             - serviceOrder object

    Question is: How did you manage exceptions in your implementation? Is the forum planning to introduce an exceptionManagement API? Are we taking the right approach? ...

    ------------------------------
    Stephane AH-KO
    CGI Info Systems Management Consulting Inc.
    ------------------------------


  • 2.  RE: 641 - Exception Management

    TM Forum Member
    Posted Aug 18, 2021 02:10
    Hi Stephane
    The whole concept of exceptions is foreign to REST APIs, as far as I am aware. The recommended practice would be to have code that catches your exceptions and translates to the Error schema, which is present in all the TMF Open API swaggers.
    Specifically in the Service Order domain, we recently updated the schema to allow recording of errors within the Service Order entity itself. ServiceOrderErrorMessage
    Take a look at the latest Service Order swagger v4.10, accessible from the main Open API table.
    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: 641 - Exception Management

    TM Forum Member
    Posted Sep 08, 2021 06:31
    Hi @Jonathan Goldberg,

    I am looking at a similar use case. With ​ServiceOrderErrorMessage, SOM is primarily notifying the northbound that some error has occurred but what if the one of the provisioning steps fails and can be fixed with manual intervention. In this case SOM doesn't need to notify northbound about this. Is there any recommendation on how such scenarios can be addressed?

    Regards
    Kanika


    ------------------------------
    Kanika Aggarwal
    VOCUS PTY LTD
    ------------------------------



  • 4.  RE: 641 - Exception Management

    TM Forum Member
    Posted Sep 08, 2021 08:26
    Hello Kanika
    I have a different perspective on this. The SOM is not notifying northbound for me, but the SOM is raising event. After, which applications are listening to this event is another story. Based on the information within the  ​ServiceOrderErrorMessage we could assume that distinct application could 'listen' to the notification. So depending on your ​ServiceOrderErrorMessage. code (or reason) the event could be listened by the workforce management in charge of manual intervention.

    Hope it helps

    Ludovic

    ------------------------------
    Ludovic Robert
    Orange
    My answer are my own & don't represent necessarily my company or the TMF
    ------------------------------



  • 5.  RE: 641 - Exception Management

    TM Forum Member
    Posted Sep 08, 2021 08:44
    Thanks @Ludovic Robert for getting back on this. Usually BSS requests service order via TMF641 and listens to TMF641 notifications. Are we saying that a workforce management system (other than BSS) should listen to TMF641 notifications and act upon it?

    What will happen to the service order state in this case, should it then be put to held until the issue is resolved?
    What happens after issue gets resolved in workforce management system, how should service order be progressed?​​

    ------------------------------
    Kanika Aggarwal
    VOCUS PTY LTD
    ------------------------------



  • 6.  RE: 641 - Exception Management

    TM Forum Member
    Posted Sep 09, 2021 01:22
    Hi @Ludovic Robert, @Jonathan Goldberg,

    The concept of having ​​​ServiceOrderErrorMessage as a sub-resource is helpful in communicating the details of the error when it occurs. But what we also need is the trigger when this message is communicated. Currently, we only have the following events that we support on TMF641

    - ServiceOrderCreateEvent
    - ServiceOrderAttributeValueChangeEvent
    - ServiceOrderStateChangeEvent
    - ServiceOrderDeleteEvent
    - ServiceOrderInformationRequiredEvent
    - ServiceOrderMilestoneEvent
    - ServiceOrderJeopardyEvent

    Out of these, one can argue that in case of exception the state of order may change and we can use ServiceOrderStateChangeEvent. But there can be cases where we don't want to change the state of the order when exception arise.

    ServiceOrderJeopardyEvent is another one that is close, but from Order perspective, Jeopardy and Exception are different and there are cases when they need to be handled differently. In a true micro-service architecture, there can be different micro-services that are handling Jeopardies and Exceptions and there is a need to subscribe to specific events.

    The fact that SOM system is integrated to multiple downstream systems during order processing and it needs to report any error or exception coming from downstream engagements make a strong case of having a separate serviceOrderExceptionEvent. I think we should consider adding it to the next version of TMF641 Service Order API and also for TMF622 Product Order API and TMF652 Resource Order API as the similar requirement applies there as well. 



    ------------------------------
    Kinshuk Kulshreshtha
    Oracle Corporation

    My views posted on this forum are personal, and do not reflect the position of my employer or TM Forum.
    ------------------------------



  • 7.  RE: 641 - Exception Management

    TM Forum Member
    Posted Sep 09, 2021 02:56
    Hello Kinshuk, Kanika

    I should confess that I was thinking we have already an event when an error message is added to the serviceOrder. So Yes, I agreed with you that it could make sense to have this notification type. Adding @Kamal Maghsoudlou in the loop as Kamal introduced the jeopardy/errorMessage/Milestone in the 641 API.
    About alignment with TMF622 & TMF652 yes this is planned. I'm currently working on ProductOrder v5 ​and we have introduced these useful jeopardy/errorMessage/Milestone in the API.

    Kanika - regarding your last comment, for me nothing prevent several systems to subscribe to same event type. The status shift to held associated with specif error message could be both listen by the BSS and the Workforce management.

    Ludovic

    ------------------------------
    Ludovic Robert
    Orange
    My answer are my own & don't represent necessarily my company or the TMF
    ------------------------------



  • 8.  RE: 641 - Exception Management

    Posted Sep 09, 2021 09:12
    Hello All
    Been following this thread for a bit and it makes for interesting reading.

    I would agree that the publisher should not concern itself with what the subscriber wants the information for and so for exceptions, the publisher should not withhold information on the basis that it is dealing with the issue itself. After all, the subscriber might just want the information for monitoring purposes. But also, in some architectures, this notification API might be the way of handling fallout and exceptions in a single error hospital across many other components.

    Having a new notification type for this seems pragmatic to me. But it does raise the question as to how many notification types one might end up with in this specification when other concerns arise.

    In a future evolution of the specification, is there any practical mileage in looking at a different form of subscription, based on a path language to indicate which information in a resource is of interest?



    ------------------------------
    Derrick Evans
    ------------------------------



  • 9.  RE: 641 - Exception Management

    TM Forum Member
    Posted Sep 09, 2021 12:06
    Hi Ludovic,

    Thanks for acknowledging the need of new Event here. Are you planning to create a new Jira issue that we can track for this.

    ------------------------------
    Kinshuk Kulshreshtha
    Oracle Corporation

    My views posted on this forum are personal, and do not reflect the position of my employer or TM Forum.
    ------------------------------



  • 10.  RE: 641 - Exception Management

    TM Forum Member
    Posted Sep 10, 2021 05:15
    Hello Kinshuk,
    Done --> https://projects.tmforum.org/jira/browse/AP-2873

    I tagged you in the Jira, so you have probably received a notification.
    Ludovic

    ------------------------------
    Ludovic Robert
    Orange
    My answer are my own & don't represent necessarily my company or the TMF
    ------------------------------



  • 11.  RE: 641 - Exception Management

    TM Forum Member
    Posted Sep 12, 2021 22:46
    Thanks @Ludovic Robert for adding the JIRA to support new notification type. However, until this is supported, what would be the recommended way to support service order exception management considering that we don't want to complete the service delivery until issue is rectified and service is configured (even if it requires retry)?​

    ------------------------------
    Kanika Aggarwal
    VOCUS PTY LTD
    ------------------------------



  • 12.  RE: 641 - Exception Management

    TM Forum Member
    Posted Sep 13, 2021 02:18
    Edited by Kinshuk Kulshreshtha Sep 13, 2021 02:20
    Hi @Kanika Aggarwal,

    On a lighter note, I think you should also thank me for building a strong case for the new notification type  ;) . ​ Just kidding!

    Coming to your query on recommended way of adding a new notification, It is described in Chapter 10 - Notification Patterns and Chapter 12 - Event Management of TMF630 REST API Design Guidelines Part 1

    ------------------------------
    Kinshuk Kulshreshtha
    Oracle Corporation

    My views posted on this forum are personal, and do not reflect the position of my employer or TM Forum.
    ------------------------------



  • 13.  RE: 641 - Exception Management

    TM Forum Member
    Posted Sep 13, 2021 02:37
    @Kinshuk Kulshreshtha Absolutely, no doubt about that. Thank you very much :)

    I was referring to recommended way of supporting exception management for TMF641 until this new notification type (serviceOrderExceptionEvent) is supported.

    ------------------------------
    Kanika Aggarwal
    VOCUS PTY LTD
    ------------------------------



  • 14.  RE: 641 - Exception Management

    TM Forum Member
    Posted Sep 13, 2021 03:11
    Edited by Kinshuk Kulshreshtha Sep 13, 2021 04:18
    Until the proposed notification is supported in the TMF APIs, you can extend the existing APIs by building a new Event Notification similar to what is proposed above. The patterns to extend the APIs has been described in TMF633 API Design Guidelines. I was referring to the relevant chapters and parts of the documentation that can be used to extend the API to build the required notification. That way, it will be easier for you to uptake the TMF notification when it is released with minimal impact.

    ------------------------------
    Kinshuk Kulshreshtha
    Oracle Corporation

    My views posted on this forum are personal, and do not reflect the position of my employer or TM Forum.
    ------------------------------



  • 15.  RE: 641 - Exception Management

    TM Forum Member
    Posted Sep 29, 2021 05:29
    Hi @Kinshuk Kulshreshtha,

    I understood from your post here that the proposal was to add an event type to support the notification of ServiceOrderErrorMessage sub-resources being created against the order.

    i.e.  ​adding  a ServiceOrderErrorMessage --> means a ServiceOrderErrorMessageEvent is generated.

    However then your post and the linked Jira goes on to start talking about a serviceOrderException event if this is the case then i have two questions: -

    1.  are you proposing that a 'exception' sub resource is also added to the order resource model?
    2. What kind of event would relate to an errorMessage being created?





    ------------------------------
    David Whitfield
    TalkTalk Group
    ------------------------------



  • 16.  RE: 641 - Exception Management

    TM Forum Member
    Posted Sep 30, 2021 01:03
    Hi David,

    Actually the serviceOrderExceptionEvent will use ServiceOrderErrorMessage to communicate the details of the exception to external systems. Instead of calling it ServiceOrderErrorMessageEvent, which is more centred around the availability of the error message, we should call it serviceOrderExceptionEvent which implies the occurrence of a condition (Exception) and the event is triggered on that condition. There may be other conditions or events that may want to use ServiceOrderErrorMessage and it may be perfectly fine.

    The anchor for the event is the occurrence of exception and not the availability of the ServiceOrderErrorMessage sub-resource in the payload, which is the after effect of the exception and needs to be identified  before serviceOrderExceptionEvent is raised to notify other systems about the details of the exception. How we identify the occurrence of exception will depend upon the business rules and will differ from use case to use case. In some cases, we may want to see if ServiceOrderErrorMessage is populated and use it as the anchor for raising the serviceOrderExceptionEvent, but in other cases, it may be more complex condition and may not dependent on the presence of ServiceOrderErrorMessage. In such cases ServiceOrderErrorMessage needs to be built after we realize that the Exception has occurred and  populate it before raising the serviceOrderExceptionEvent


    ------------------------------
    Kinshuk Kulshreshtha
    Oracle Corporation

    My views posted on this forum are personal, and do not reflect the position of my employer or TM Forum.
    ------------------------------



  • 17.  RE: 641 - Exception Management

    TM Forum Member
    Posted Oct 01, 2021 06:15
    makes sense @Kinshuk Kulshreshtha, thanks for the clarification of your thoughts​

    ------------------------------
    David Whitfield
    TalkTalk Group
    ------------------------------