Open APIs

 View Only
  • 1.  instantSyncQualification attribute in TMF - 645 tasks

    TM Forum Member
    Posted Mar 02, 2021 21:07

    Hi,

     Looking for your guidance on understanding the  attribute instantSyncQualification used in  645 V4 tasks .

    As per the description for instantSyncQualification in user guide :

     

      • An indicator which when the value is "true" means that requester expects to get qualification result immediately in the response. 
      • If the indicator is true then the response code of 200 indicates the operation is successful otherwise a task is created with a response 201.

     

    Would like to get a better  clarity on the scenarios where 200 and 201 are returned. 

    Understanding is, 200 and 201 are both used in  successful  scenarios  . 

    What would be the response code when  instantSyncQualification  = false and when it's true?

     cc: @Rati Mehrotra

     Thank s & Regards,



    ------------------------------
    Uma Lakshman
    Telstra Corporation
    ------------------------------


  • 2.  RE: instantSyncQualification attribute in TMF - 645 tasks

    TM Forum Member
    Posted Mar 03, 2021 12:58
    Hi Uma
    You are probably aware, but adding brief explanation for others who may see this post.
    Task resources are used to express semantics of business operations that go beyond CRUD of entities. Examples include validation of address, prepaid balance operations, and many more, including your current example of checking service qualification. A task resource typically includes a status, input data, and output data.
    POSTing a task resource causes the business operation to be executed. Consider the following scenarios:
    • Operation was not executed immediately (e.g. address validation in some cases) - in this case a task resource will be created in some persistent storage, and its status could be polled (or, better, status change events could be raised). HTTP status for the POST would be 201 in this case, since something was created.
    • Operation was executed immediately (e.g. prepaid balance topup), still a task resource might be created due to the need to keep a permanent record of the topup transaction. So HTTP status for the POST would be 201 in this case, but the status of the task on creation would be complete or similar
    • Operation was executed immediately (e.g. qualification check with the instantSync flag set true), in this case no value to create a permanent record, so HTTP status for the POST would be 200.
    Hope it is clear.

    ------------------------------
    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: instantSyncQualification attribute in TMF - 645 tasks

    TM Forum Member
    Posted Mar 03, 2021 19:25
    Thanks for your response, @Jonathan Goldberg


    Based on your post , Scenario  1 and 2 cover cases where instantSyncQualification is false  resulting task and resource creation . 

    In case of scenario 2 (Operation was executed immediately )  task and resource are  created  and  request is fulfilled . 201 Created in this case looks valid.

    For scenario 1 (Operation was not executed immediately) it results in task and resource creation.  But the request is still not fulfilled . In this case shouldn't it be a 202 response as per below RFC standard?

     

     In case of scenario 3  where instantSyncQualification is true, understanding is no resource is created. 

    The user guide has an example where queryServiceQualification resulted in creation of resource when instantSyncQualification  was  true. Does it need to be corrected?

     

    Thanks & Regards,


    ------------------------------
    Uma Lakshman
    Telstra Corporation
    ------------------------------



  • 4.  RE: instantSyncQualification attribute in TMF - 645 tasks

    TM Forum Member
    Posted Mar 04, 2021 00:39
    Hi Uma
    Our understanding of the 202 HTTP response is that it means that the requested resource has not been created, and so a monitor resource must be returned.
    We currently use 202 explicitly in Service Activation and Resource Activation APIs, which operate directly against the network, since it is recognized that the network elements being addressed may not be able to respond immediately with fulfilment of the request.
    This is distinct from a task operation, where the API provider is typically an IT system that can respond immediately to acknowledge creation of the task, even if the task may take time to perform.
    Hope it makes sense

    ------------------------------
    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: instantSyncQualification attribute in TMF - 645 tasks

    TM Forum Member
    Posted Nov 16, 2022 18:47
    Edited by Anu Aulakh Nov 16, 2022 18:47
    Hi @Jonathan Goldberg,

    Just revisiting this thread, in particular scenario 1:
    • Operation was not executed immediately (e.g. address validation in some cases) - in this case a task resource will be created in some persistent storage, and its status could be polled (or, better, status change events could be raised). HTTP status for the POST would be 201 in this case, since something was created.
    In the TMF630 Guideline v4.0.1 - Section 8.1, the following HTTP status codes are defined for the Task resource:
    Does this mean the TMF630 should be updated to include HTTP 201 in above table?
    This is to align with TMF645v4 query and check tasks as well as TMF641v4.1 cancelServiceOrder task?

    Thanks,
    Anu

    cc: @Amita Giriya, @Radhika Desai, @Gordon Liang
    ------------------------------
    Anu Aulakh
    Telstra Corporation
    My answer is my own & doesn't necessarily represent my company or the TMF
    ------------------------------



  • 6.  RE: instantSyncQualification attribute in TMF - 645 tasks

    TM Forum Member
    Posted Nov 17, 2022 04:01
    Hi Anu
    Yes, TMF630 should be updated. Please open a JIRA for this.
    In v5 APIs, we are using better tooling which should make it easier for API designers to specify the correct response codes for Task API operations

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



  • 7.  RE: instantSyncQualification attribute in TMF - 645 tasks

    TM Forum Member
    Posted Nov 17, 2022 19:17
    Thanks @Jonathan Goldberg.

    JIRA raised: https://projects.tmforum.org/jira/browse/AP-4176
    ​​

    ------------------------------
    Anu Aulakh
    Telstra Corporation
    My answer is my own & doesn't necessarily represent my company or the TMF
    ------------------------------