Open APIs

 View Only
Expand all | Collapse all

TMF641 - Order rejected or failed: how to notify the client of the reason/error

  • 1.  TMF641 - Order rejected or failed: how to notify the client of the reason/error

    TM Forum Member
    Posted Sep 04, 2018 12:46
    Dear TMF641 committers,

    The Service Ordering spec contains notifications about state changes ('ServiceOrderStateChangeNotification') - also in the cases a ServiceOrder switches to state 'failed' or 'rejected'.
    So a client of ServiceOrder-Mangement gets this notification and therefore can see:
    • 'ok, my service order has been rejected' or
    • 'ok, my service order has failed'.

    Now my question: Is there a standard way within the notifications to pass more specific information about the reason to the client
    like
    • rejectionCode / errorCode
    • rejectionReason / errorMesage
    Would it be possible from TMF point of view, to just add those fields in the notification, so that a client gets more detailed information?

    Is there an attribute or object within the ServiceOrder itself, which would be fitting for such information?

    Thanks and Regards
    Adrian

    ------------------------------
    Adrian Ofterdinger
    Capgemini
    ------------------------------


  • 2.  RE: TMF641 - Order rejected or failed: how to notify the client of the reason/error
    Best Answer

    TM Forum Member
    Posted Sep 05, 2018 03:32
    Hi Adrian,

    Make sense and we already suggest an improvement in the joint effort between TMF and ONAP initiative.

    The proposal is to add the following structure in the serviceOrder:

      "orderMessage": [
        {
          "code": "string",
          "field": "string",
          "messageInformation": "string",
          "severity": "information",
          "correctionRequired": true
        }
      ]
    If fulfillment fails or if specific event occurred and need to be stored this structure will be use.

    It is distinct from the HTTP message you get in the POST response.

    Now to add it in the API, we need to log a change request in TMF - As serviceOrder leader I'm fully open to do it.

    My plan is also to add it in the productOrder (requested by MEF).

    Hope it helps,



    ------------------------------
    Ludovic Robert
    Orange
    ------------------------------



  • 3.  RE: TMF641 - Order rejected or failed: how to notify the client of the reason/error

    TM Forum Member
    Posted Sep 05, 2018 09:55
    Hi Ludovic,

    This sounds great, let`s go for it!
    This would enable the SOM to add multiple order messages - which can then be handled (or just only understood) by the service client.

    Thanks a lot
    Adrian

    ------------------------------
    Adrian Ofterdinger
    Capgemini
    ------------------------------



  • 4.  RE: TMF641 - Order rejected or failed: how to notify the client of the reason/error

    TM Forum Member
    Posted Nov 27, 2018 05:21
    Hi Ludovic,

    thanks again for your answer to this topic.

    Regarding your proposed structure within the notification:

    • How can we proceed with a change request here?
    Thanks and Regards
    Adrian

    ------------------------------
    Adrian Ofterdinger
    Capgemini
    ------------------------------



  • 5.  RE: TMF641 - Order rejected or failed: how to notify the client of the reason/error

    TM Forum Member
    Posted Nov 29, 2018 03:43
    Hi Adrian,

    the Change request was presented to the APi governance team sept 19, 2018 but was not straightforwardly  approved. Members requested additional information and clarification with Note use (it's true that we have a note class that can be extended via polymorphic pattern  --> this is an interesting proposal). I've provided some UC to leverage order message Oct16th but since then the topic has not been discussed.

    One key factor for this unusual latency: the TMF API project team is working on Swagger tooling and this topic 'consumes' all our 'TMF' time.

    Best regards

    Ludovic

    ------------------------------
    Ludovic Robert
    Orange
    ------------------------------



  • 6.  RE: TMF641 - Order rejected or failed: how to notify the client of the reason/error

    TM Forum Member
    Posted Jan 21, 2019 06:19
    Edited by Adrian Ofterdinger Apr 11, 2019 22:49
    Hi @Ludovic Robert,

    thanks again for presenting this at the design board. Just to inform you: considering your input we found a solution for us:

    We would like to enhance Note model by

          "code": "string",
          "field": "string",
          "messageInformation": "string",
          "severity": "information",
          "correctionRequired": true
    we would as of now use the Note fields​
          "author": "string", => will be some value from system as the process which manages the order
          "date": "DateTime", => will be the time an error occurred
          "text": "string", => will be the summary consisting of code, field, severity and messageInformation
    
    So in fact in future Note in the API can be in future "enhanced" by those fields above (taken from ONAP).

    In consequence, the object "Note" can either be a system generated note or a Note coming from a human person / human task.

    What do you think?

    Thanks and Regards
    Adrian

    ------------------------------
    Adrian Ofterdinger
    Capgemini
    ------------------------------



  • 7.  RE: TMF641 - Order rejected or failed: how to notify the client of the reason/error

    TM Forum Member
    Posted Jan 21, 2019 06:46
    Please be aware that in release 18.5 we are enhancing the Note entity with a system attribute, so if you are planning to extend anyway I suggest you take this into account:
    "system": {
    "type": "string",
    "description": "Describes the system from which the action related to this note was done"
    },


    ------------------------------
    Jonathan Goldberg
    Amdocs Management Limited
    ------------------------------



  • 8.  RE: TMF641 - Order rejected or failed: how to notify the client of the reason/error

    TM Forum Member
    Posted Mar 01, 2019 04:34
    Hi Jonathan, thanks for the hint, so we did :-)

    ------------------------------
    Adrian Ofterdinger
    Capgemini
    ------------------------------



  • 9.  RE: TMF641 - Order rejected or failed: how to notify the client of the reason/error

    TM Forum Member
    Posted Aug 05, 2021 09:33
    @Jonathan Goldberg - what happened to the extension of the Note entity? When I look in the release 19.0 schema for 622 ProductOrder or release 21.0 for 641 ServiceOrder - I don't see the uptake as mentioned here.

    I'm wondering if the use of Note is still the best way to include more specific details about failed state changes? 

    thanks!​​​

    ------------------------------
    Lynn Dueck
    Oracle Corporation
    ------------------------------



  • 10.  RE: TMF641 - Order rejected or failed: how to notify the client of the reason/error

    TM Forum Member
    Posted Aug 06, 2021 03:11
    Hi Lynn
    I'm wondering myself the same question. I certainly updated Note way back when we first started the schemification of Open APIs. Sure enough, it's there in my local working design environment for v18, and it was definitely published, as you can see in earlier swaggers here (for example TMF640).
    All I can do is to open a defect in Open API JIRA.

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



  • 11.  RE: TMF641 - Order rejected or failed: how to notify the client of the reason/error

    TM Forum Member
    Posted Aug 09, 2021 08:27
    Super, thanks @Jonathan Goldberg. I"ll proceed assuming Note will include the extension you mentioned, and will be resolved thru the JIRA ticket.​

    ------------------------------
    Lynn Dueck
    Oracle Corporation
    ------------------------------



  • 12.  RE: TMF641 - Order rejected or failed: how to notify the client of the reason/error

    TM Forum Member
    Posted Jul 29, 2020 07:51
    Hi I am writing on behalf of my colleague Oleksandr Shykov <oleksandr.shykov@NetCracker.com>. It will great if you can help him with his queries.

    Regarding rejecting Service Order and understanding which Order Item caused this rejection: could you please clarify following scenario?

    "Create Service Order" (POST) operation was invoked. Service Order contains 3 order items: OI1, OI2, OI3. As the result, Service Order is rejected. Reason: OI2 did not pass validation. OI1 has passed the validation. OI3 was not checked since whole Service Order was rejected as soon as the first invalid Order Item failed the validation.

    Questions:
    1. What synchronous HTTP Response should be for POST call: 201 Created or 400 Bad Request?
    2. Shall synchronous HTTP Response contain detailed Service Order with indication of states of each Order Item?
    3. What notifications should be created? ServiceOrderCreateEvent(order state Rejected)? ServiceOrderStateChangeEvent(order state Rejected)?
    4. Is it expected that "List service orders" operation (GET) will return rejected Service Order?
    5. What are the states of each Order Item in this scenario (OI1, OI2, OI3)?


    ------------------------------
    Abinash Vishwakarma
    Netcracker Technology
    ------------------------------



  • 13.  RE: TMF641 - Order rejected or failed: how to notify the client of the reason/error

    TM Forum Member
    Posted Jul 29, 2020 08:15
    Hi Abinash,
    so the situation is, that the service order did not pass validation and needs to be rejeceted.

    Let me try to answer the questions
    1. What synchronous HTTP Response should be for POST call: 201 Created or 400 Bad Request?
    Answer: It should be 201, as you have really created the resource ServiceOrder.

    2. Shall synchronous HTTP Response contain detailed Service Order with indication of states of each Order Item?
    Answer: As per spec, Service Order resource is part of the http response. However in the synchronous response, it may *not yet* be rejected, because your validation process has not started yet. so it may be valid to leave it empty. Possible solution: just return the created resource, containing the real "ids" that were created (e.g. ServiceOrder.id)

    3. What notifications should be created? ServiceOrderCreateEvent(order state Rejected)? ServiceOrderStateChangeEvent(order state Rejected)?
    Answer: I guess it`s littlebit part of the freedom of the specific implementation if you need the CreatedEvent. I would say: CreatedEvent contains the freshly created resource ServiceOrder. After the process of validation is done, which may set the state to 'rejected', then a ServiceOrderStateChangeEvent should actually notify the sender, that something went wrong.

    4. Is it expected that "List service orders" operation (GET) will return rejected Service Order?
    Answer: This is possible as per spec, you can use the Finder GET with state='rejected'

    5. What are the states of each Order Item in this scenario (OI1, OI2, OI3)?
    Answer: I would say: what ever is the outcome of your validation process.

    ------------------------------
    Adrian Ofterdinger
    Capgemini
    ------------------------------



  • 14.  RE: TMF641 - Order rejected or failed: how to notify the client of the reason/error

    TM Forum Member
    Posted Jul 29, 2020 10:54
    Hi Adrian,

    Thank you for the answer.

    May I ask for additional clarification:

    >> 3. What notifications should be created? ServiceOrderCreateEvent(order state Rejected)? ServiceOrderStateChangeEvent(order state Rejected)?
    > Answer: ... CreatedEvent contains the freshly created resource ServiceOrder. After the process of validation is done, which may set the state to 'rejected', ...
    As per my understanding, CreateEvent shall contain some state of the Service Order. The first state in the lifecycle shall be either Acknowledged or Rejected (at least as per 18.5; I am not sure whether it is to be changed in 4.0.0). This means that CreatedEvent shall be submitted only after validation process has completed - either with positive result (state = Acknowledged) or with negative result (state = Rejected).

    This means that the course of action shall be as follows: 1) receive Service Order 2) complete validation 3) create two notifications: CreatedEvent, StateChangeEvent (with the same content).

    Is this logic correct?

    >> 5. What are the states of each Order Item in this scenario (OI1, OI2, OI3)?
    > Answer: I would say: what ever is the outcome of your validation process
    Suppose, OI1 passed the validation, OI2 failed the validation, for OI3 validation has not started at the moment of rejection of the Service Order. What OI states shall be in each of OI1, OI2, OI3 in the Rejected Service Order?

    This scenario would answer many questions: can OI state be empty/absent; can Acknowledged state be a terminal state for OI; can I use OI states to identify OI with mistake which caused the rejection; can I be sure that after mistake in one OI in corrected, another OI in this SO will not cause next rejection...

    I would appreciate any suggestions on this.

    Best regards
    Alex (Oleksandr Shykov)

    ------------------------------
    Oleksandr Shykov
    Netcracker Technology
    ------------------------------



  • 15.  RE: TMF641 - Order rejected or failed: how to notify the client of the reason/error

    TM Forum Member
    Posted Jul 29, 2020 10:54
    Edited by Oleksandr Shykov Jul 29, 2020 15:47
    (duplicate removed)


  • 16.  RE: TMF641 - Order rejected or failed: how to notify the client of the reason/error

    TM Forum Member
    Posted Aug 17, 2020 22:30

    Hi, 

    https://projects.tmforum.org/jira/browse/AP-2237 was raised and discussed in API development forum. Changes are WIP.



    ------------------------------
    Abdul Majid Hussain
    Telstra Corporation
    ------------------------------