Open APIs

 View Only
Expand all | Collapse all

TMF645 - QueryServiceQualification API Generalisation

  • 1.  TMF645 - QueryServiceQualification API Generalisation

    TM Forum Member
    Posted Feb 22, 2022 15:57
      |   view attached
    Based on the API documentation of TMF645, QueryServiceQualification is to be used to check if a service is available at a particular location or not. If we have to generalise this API usage,
    1. what type of call is to be used? Should it be GET or POST? or combination of both?
    2. How to pass the search service details and address details to the GET request? as per the documentation it is not accepting any request header params other than id
    3. Can we get the examples of request and response params for both GET and POST?


    ------------------------------
    Lakshmi Mallidi
    Salesforce
    ------------------------------


  • 2.  RE: TMF645 - QueryServiceQualification API Generalisation

    TM Forum Member
    Posted Feb 23, 2022 04:30
    Hi Lakshmi
    QueryServiceQualification is what we call a TASK resource, that carries out a business operation which is not a simple create/read/update/delete (CRUD).
    To execute the task, for example to query services available at an address, you POST the task resource.
    It is possible that the implementation will persist the task resource (if the task is asynchronous then it must be persisted) - in that case GET can be used to retrieve the task resource.
    The API user guide should have examples of the inputs and outputs for each operation.

    ------------------------------
    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: TMF645 - QueryServiceQualification API Generalisation

    TM Forum Member
    Posted Feb 23, 2022 05:52
    Hi,

    I would like to add that although a QueryServiceQualification task can in some cases be automated and give near real-time responses, that is not always the case.
    Particularly for B2B scenario's this task can trigger a complex design task that can only be performed by humans. Even for B2C scenario's there are likely corner cases that require more complex evaluations, responses from partners, etc.

    Therefore it is best to assume that these tasks are always implemented as asynchronous.

    Regards

    ------------------------------
    Koen Peeters
    OryxGateway
    ------------------------------



  • 4.  RE: TMF645 - QueryServiceQualification API Generalisation

    TM Forum Member
    Posted Feb 24, 2022 09:11
    Hi Koen,

    My use case is to do a guided flow based on the serviceability results for a B2C scenario. So, I want the call to be synchronous. If queryServiceQualification API can't be synchronous is there any alternative? Can you please suggest?

    ------------------------------
    Lakshmi Mallidi
    Salesforce
    ------------------------------



  • 5.  RE: TMF645 - QueryServiceQualification API Generalisation

    TM Forum Member
    Posted Feb 28, 2022 08:31
    Hi Lakshmi,

    I agree with Koen, the same situation here in my company.

    If I understand TMF645 user guide properly, you can use "instantSyncQualification" parameter to obtain result synchronously when you POST a query request. Of course, data for qualification must by prepared (pre-calculated) in database, to be able to get instant result.

    Jan

    ------------------------------
    Ján Krištof
    T-Mobile Czech & Slovak Telekom, a.s.
    ------------------------------



  • 6.  RE: TMF645 - QueryServiceQualification API Generalisation

    Posted Feb 28, 2022 09:46
    Hello All,
    I guess, in summary, for the application at hand the implementation is a POST, to create the resource containing the relevant information for qualification, responded to synchronously with the qualified information.

    The asynch model at the heart of this API specification is then reserved for more complex scenarios requiring longer lived automation and/or surveys.

    I understand the distinction, but for my own part I think I would have preferred a model of a simple synchronous GET of information qualifying a service. Thinking back to my consumer broadband days, this is the sort of API we had (albeit a SOAP one). In addition to static information from a database, it also provided a snapshot as to whether there were any inflight orders at that time which would interfere with any order placed (like an in progress but yet to be completed cease of pre-existing blocking products on the line). In fact it was more of a pre-flight check for an order about to be placed and would check for anything which might derail the order if placed. The idea was to minimise the number of orders which were submitted only to be rejected.

    When it comes to more complex products like access Ethernet we had a similar "service availability" checker which dealt with the simple stuff. If a customer wanted to check more complex information they could ask for a "quotation" or if it was a really complex build they could place an order for a site survey to be conducted.

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



  • 7.  RE: TMF645 - QueryServiceQualification API Generalisation

    TM Forum Member
    Posted Feb 28, 2022 10:27
    Derrick

    In SOAP (as in many other API schemas, such as EJB), you have complete freedom as to the name of operations within your API.
    Unfortunately, using the REST pattern one is limited to the verbs recognized by the HTTP standard. TMF Open API has chosen to use four verbs - POST (create), PATCH (update), DELETE (delete), and GET (retrieve + search). With these CRUD-oriented verbs you are very limited in the way you can express business semantics, hence the Task resource pattern was conceived.
    If it helps, relate to the name of the task entity as if it was the name of a business operation, and look at the POST verb just as a technical part of the transport.

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



  • 8.  RE: TMF645 - QueryServiceQualification API Generalisation

    Posted Feb 28, 2022 10:46
    Hello Jonathan,

    Agree with the notion of the CRUD notion of REST.
    But I guess If I thought of a resource name such as  "ServiceAvailability"  there is no reason that this resource cannot exist in advance of me requiring the information.

    Then I can GET "ServiceAvailability" using an address as a search term or even using  the identity of a physical preinstalled line or service.

    Derrick

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



  • 9.  RE: TMF645 - QueryServiceQualification API Generalisation

    TM Forum Member
    Posted Mar 01, 2022 03:39
    Interesting take on this, Derrick. The main challenge would be constructing the query parameters that would return candidate ServiceAvailibility resources. And what do I do if there is no matching resource for my query. Additional challenge could be that GETs are supposed to be idempotent, but the network is dynamic and the answer for today might be different for the answer for tomorrow.
    For all these reasons, POST is more appropriate.

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



  • 10.  RE: TMF645 - QueryServiceQualification API Generalisation

    Posted Mar 06, 2022 13:08
    Thanks Jonathan
    Not sure I fully understand the point you are making but I suspect this is a side conversation to the original query.

    I believe the idempotency of GET is about the nature of what GET does (it does not change the state of a resource) rather than the volatile nature of the data?

    I would agree that if the information providing the list of available services has to be created in response to the API call rather than exist already then a POST is more appropriate.

    As for the query parameters. Well if they can be in the body of an entity representation in a POST then they can be passed as query parameters in a GET. But I suspect the first level attributes that you need are perhaps not available straightforwardly so you would end up using JSON Path notation?

    The point is for residential consumer use I suspect no surveys or investigations are required and the data is pre-built to be available synchronously as a resource representation.

    Derrick

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



  • 11.  RE: TMF645 - QueryServiceQualification API Generalisation

    TM Forum Member
    Posted Mar 07, 2022 02:37
    Apologies Derrick, my use of the term idempotent was not strictly accurate. Perhaps the best way forward on this discussion would be for you to propose a GET operation that you believe will meet the requirements. You'd need to define what query parameters would be supported, and explain the proposed behavior.

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



  • 12.  RE: TMF645 - QueryServiceQualification API Generalisation

    Posted Mar 07, 2022 08:51
    Thanks Jonathan
    I will give it a go.
    It might be a while before you see a response though :-) and I suspect what I come up with will be a bit rough around the edges.

    I don't particularly want to confuse Lakshmi with my musings so I might also wait for the dust to settle a bit.

    I think the approach I will take is to use TMF645 as the starting point and consider what a GET might look like if the Check or Query Service Availability resources are already existing but you wanted to GET them via something other than an  ID.  

    Let me have a think about it.

    There are only two ways I think it can work.
    One is to have URIs that have path elements related to premises locations or existing services.
    The other is to use query variables to find members of the collection which fit.

    Is there a preferred approach the TMF API team use?


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



  • 13.  RE: TMF645 - QueryServiceQualification API Generalisation

    Posted Mar 14, 2022 11:17
    Hello Jonathan,
    I have been looking at this and am beginning to form a better view as to why this API uses the task pattern.

    Not sure if other folks agree with the following but here goes.

    I agree that there is a usecase where the query or check needs to be asynchronous and that may well be the original intent here.
    But I think something else is going on as well (albeit perhaps unintentional. I am not certain).

    It is best illustrated by the discussion here (TMF 645 - query based on existing service).
    Someone asked to to use an the id of an existing service, as an alternative to place,  as a way of stating where the required service is to be installed.
    The outcome of the discussion was a snippet or two of JSON to be used in  the POST.

    When I tried to formulate URI strings or filter parameters  for these use cases  it became clear that it was easier to express this as a piece of JSON.

    Because of course GET does not accept a body in a request, there are many examples of other APIs out there where complex queries are supported using POST to in effect create a filter resource which is then either synchronously expanded with the results in response and/or is later used as a filter object in a GET.

    With OpenAPI Spec 3.0 one can have a JSON object as a query parameter but I suspect the tooling to create such a request is not common place. Also the URI sting and parameters could get very large.

    So I suspect this is another usecase (beside asynchronous behaviour) for the use of POST rather than GET in these APIs.

    I will nevertheless post my musings in another thread! :-)

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



  • 14.  RE: TMF645 - QueryServiceQualification API Generalisation

    TM Forum Member
    Posted Feb 24, 2022 09:07
    Hi Jonathan, Thank you for the response! My case is B2C and I want this to be synchronous call. I want to know whether a list of services are available at a particular address or not. Assuming that the service location is already created by a POST call, Can we use GET call to retrieve the serviceability of a service? In case of a GET call from the user guide, I do not see service name as a header param to query for service qualification. 

    Below is the request and response that I am referring.
    Request
    GET /tmf-api/serviceQualificationManagement/v4/queryServiceQualification/54
    Accept: application/json

    Response
    {
    "id": "54", "href": "http://serverlocation:port/serviceQualificationManagement/v4/queryServiceQualification/54", "description": "Query Service Qualification Illustration - 2 serviceSpec available at this place for this category", "effectiveQualificationDate": "2020-04-13T13:51:41.218Z", "estimatedResponseDate": "2020-04-13T14:00:00.218Z", "expectedQualificationDate": "2020-04-13T13:51:41.218Z", "expirationDate": "2020-04-15T13:51:41.218Z", "externalId": "QSQ-456", "instantSyncQualification": false, "queryServiceQualificationDate": "2020-04-13T13:51:41.218Z", "relatedParty": [ { "id": "456", "href": "http://serverlocation:port/partyManagement/v4/party/456", "name": "Jean Pontus", "role": "Buyer contact", "@type": "RelatedParty", "@referredType": "Individual" } ], "searchCriteria": { "id": "1", "category": {"id": "1", "href": "http://serverlocation:port/serviceCatalogManagement/v4/category/1", "name": "Fiber Access", "@type": "Category" }, "service": { "place": [ { "role": "Installation Place", "@type": "GeographicAddress", "city": "San Francisco", "postcode": "94121", "streetName": "25th", "streetType": "Avenue", "streetNr": "437", "geographicAddress": [ { "levelType": "floor", "levelNumber": "3" } ] } ] }, "@type": "SearchCriteria" }, "serviceQualificationItem": [ { "id": "1", "service": { "serviceSpecification": { "id": "78", "href": "http://serverlocation:port/serviceCatalogManagement/v4/serviceSpecification/78", "name": "X-Fiber Service", "@type": "ServiceSpecification" }, "@type": "Service" }, "@type": "ServiceQualificationItem" }, { "id": "2", "service": { "serviceSpecification": { "id": "87", "href": "http://serverlocation:port/serviceCatalogManagement/v4/serviceSpecification/87", "name": "Standard Fiber Service", "@type": "ServiceSpecification" }, "@type": "Service" }, "@type": "ServiceQualificationItem" } ], "state": "done",
    "@type": "QueryServiceQualification" }


    ------------------------------
    Lakshmi Mallidi
    Salesforce
    ------------------------------



  • 15.  RE: TMF645 - QueryServiceQualification API Generalisation

    TM Forum Member
    Posted Feb 24, 2022 10:32
    Hi Lakshmi
    I don't consider myself an expert in the service qualification domain. @Ludovic Robert might be better placed to assist here in the details.​

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



  • 16.  RE: TMF645 - QueryServiceQualification API Generalisation

    Posted Feb 25, 2022 11:46
    Hello
    Not an expert on this but I have the impression that the "queryServiceQualification" resources once available are GETable purely by their ID.

    Effectively you create a TASK style "queryServiceQualification" resource via a POST  with the relevant information in for the qualification to be executed. The ID of the resource created is in the response and the services may be qualified immediately in that resource representation, as a synchronous response, or be unqualified until a later time. If the resource indicates that the services are not qualified synchronously you have to wait for a notification with the qualified resource in or wait a while and perform a GET using the ID of the "queryServiceQualification" resource from the POST response.  


    The other way of getting the ID is to search the collection of the resource and pick up the ID based on the summary description and then perform a GET using the ID.

    What is not possible it seems is to assume that the "queryServiceQualification" resource already exists by some magic where all premises are pre-processed and get a specific resource  representation in full from the collection using PARAMs including  the service address.

    This differs somewhat from many "real world" service qualification solutions  for consumer products where in effect the services already provided and other services available for each location are pre-recorded and cached in a database,which is frequently updated with changes, to serve synchronous calls to pre-qualify an order.



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



  • 17.  RE: TMF645 - QueryServiceQualification API Generalisation

    TM Forum Member
    Posted Feb 28, 2022 03:09
    Query Service Qualification & Check Service Qualification are best to be used to perform quick synchronous qualification for e.g. can a service or a category of service can be provided on a particular location (..with certain parameters). This qualification is best to performed in an already available cache/inventory/database rather than provider performing detailed assessment.

    If a detailed feasibility is required to be performed, it is best to use TMF 640/ 641 so that the provider can perform detailed assessment and take the service into the intended state of "FeasibilityChecked" or "Reserved" state.

    ------------------------------
    Varun Nair
    Telstra Corporation
    Note: This is an opinion based on my research and not an official TMF response.
    ------------------------------



  • 18.  RE: TMF645 - QueryServiceQualification API Generalisation

    TM Forum Member
    Posted Feb 28, 2022 08:29
    Hello

    Just to add my perspective...
    The use of TMF645 is as described by @Derrick Evans with a mandatory POST operation to trigger the eligibility request. In the response you'll have a qualification id and so you 'll be able to retrieve qualification request.

    On this qualification performed, if you want to keep track of this at your service level - to reserve for example resource associated to the service​ - then you can orchestrate TMF645 and then TMF640/641 (or directly call TMF640/641 as @Varun Nair stated). In this kind of UC where the service are booked it could become complex.... if the order is never done (the service booking has to be released) or to have the service id reconciliation (how to make sure the service ordered corresponds to the service id reserved)...but that another stories...

    Thanks,
    Ludovic​​

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



  • 19.  RE: TMF645 - QueryServiceQualification API Generalisation

    TM Forum Member
    Posted Mar 01, 2022 06:13
    Collegues,

    thanks for interesting discussion. I was missing ability of TMF645 to reserve resources, now I know what are possible solutions.

    Regarding this reservation. In our current (read old) implementation, reservation is time limited, so if service order didn't come, reservation is canceled and resources are free again.

    Jan

    ------------------------------
    Ján Krištof
    T-Mobile Czech & Slovak Telekom, a.s.
    ------------------------------



  • 20.  RE: TMF645 - QueryServiceQualification API Generalisation

    TM Forum Member
    Posted Mar 02, 2022 12:52
    Hi Ludovic,

    Thank you for the explanation! I understand that POST is mandatory to get the instant response of GET and to make sure the service qualification details are present and can be retrieved. I will need your help in constructing the requests and responses of GET and POST of 'queryServiceQualification'. 

    Because, sample request of the GET in developer guide accepts only an id. In real time scenario, what if I want to query for a particular set of services serviceable at a location.

    ------------------------------
    Lakshmi Mallidi
    Salesforce
    ------------------------------



  • 21.  RE: TMF645 - QueryServiceQualification API Generalisation

    TM Forum Member
    Posted Mar 03, 2022 03:14
    Hello Lakshmi,

    I you want to query for a particular set of service (from "Internet Access" category for example) at a location (Somewhere in SF) you will do a 

    POST QueryServiceQualifcation passing following payload:

    {
      "description": "Query Service Qualification POST Illustration",
      "expectedQualificationDate": "2020-04-13T13:51:41.218Z",
      "instantSyncQualification": false,
      "relatedParty": [
        {
          "id": "456",
          "href": "http://serverlocation:port/partyManagement/v4/party/456",
          "name": "Lakshmi",
          "role": "Requester",
          "@type": "RelatedParty",
          "@referredType": "Individual"
        }
      ],
      "searchCriteria": {
        "id": "1",
        "category": {
          "id": "1",
          "href": "http://serverlocation:port/serviceCatalogManagement/v4/category/1",
          "name": "Internet Access",
          "@type": "Category"
        },
        "service": {
          "place": [
            {
              "role": "Installation Place",
              "@type": "GeographicAddress",
              "city": "San Francisco",
              "postcode": "94121",
              "streetName": "25th",
              "streetType": "Avenue",
              "streetNr": "437"
            }
          ]
        },
        "@type": "SearchCriteria"
      },
      "@type": "QueryServiceQualification"
    }
    ​

    Hope it helps,

    Ludovic

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



  • 22.  RE: TMF645 - QueryServiceQualification API Generalisation

    TM Forum Member
    Posted Mar 10, 2022 11:36
    Hi Ludovic,

    Thank you for you reply but then can you please help me to understand the below?

    • Can't I query for a list of categories/services at a time for a given address? is there a different service for this purpose?
    • Or can I query for all available services at a particular address?
    • How to identify whether a category is serviceable at an address? Is it like if a category is serviceable then only it is mentioned in the response?
    • How do I know if a POST is acknowledged? in the user guide state is mentioned as acknowledged but in the life cycle of state, this value is not avaialble.


    ------------------------------
    Lakshmi Mallidi
    Salesforce
    ------------------------------



  • 23.  RE: TMF645 - QueryServiceQualification API Generalisation

    TM Forum Member
    Posted Mar 10, 2022 12:24
    Lakshimi,
    • You can query on one category via QueryServiceQualification (with QueryServiceQualification.searchCriteria.category=<<your_category>>
    • You can query a list of service via CheckServiceQualification - one service.serviceSpecification per CheckServiceQualification.CheckServiceQualificationItem
    • You can query all service at a address QueryServiceQualification (with QueryServiceQualification.searchCriterai.service.place=<<address>>
    • You cannot make a request to check only a category - It is always service in the response (You cannot ask "is internet category eligible?" but you can ask "Which serviceSpec from internet category are eligible?)
    • As client, you can ask to have the qualification directly in the response (instantSyncQualifcation=true). If not then you have a state to follow progress for the qualification. We have an issue with the acknowledged probably (it is accepted in the swagger). when the qualification is performed the status is 'done'. You have the capability to manage event to let us know subscriber about qualification performed.
    Hope it helps
    Ludovic

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



  • 24.  RE: TMF645 - QueryServiceQualification API Generalisation

    TM Forum Member
    Posted Mar 03, 2022 09:43
    Hi Lakshmi,

    You may not need to do a GET of queryServiceQualification in this case.

    The POST operation will create a queryServiceQualification resource and since this is a task (which can also be synchronous), you can see the results in the POST response.
    Please refer the serviceQualificationItem block in the 200 response example given in TMF 645 swagger .

    If the provider system intents to persist the queryServiceQualification resource in inventory, it can be retrieved using GET of queryServiceQualification resource at later point in time subject to the the expirationDate. The example you mentioned with an id is used for this purpose.

    Hope this helps.

    Regards
    Ambily Unni
    Senior Architect
    Telstra

    ------------------------------
    Ambily Narayanan Unni
    Telstra Corporation
    ------------------------------



  • 25.  RE: TMF645 - QueryServiceQualification API Generalisation

    TM Forum Member
    Posted Mar 03, 2022 11:17
    Thanks a lot for your support. I am clear about this UC. I will go with POST+GET of queryServiceQualification by passing the parameter instantSyncQualification as true. 

    And I will follow the request and response structures as below.
    1. The request and response for the POST of 'queryServiceQualification' API is as attached
    2. The request and response for the GET of 'queryServiceQualification' API is as attached


    ------------------------------
    Lakshmi Mallidi
    Salesforce
    ------------------------------



  • 26.  RE: TMF645 - QueryServiceQualification API Generalisation

    TM Forum Member
    Posted Mar 03, 2022 11:22
    Hi Lakshmi
    If the qualification result is "instant", i.e. the task is being executed synchronously, you don't need GET. POST should return the full result of the qualification query in the response body. GET will give you nothing new (and there might not even be a persistent entity to retrieve).

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



  • 27.  RE: TMF645 - QueryServiceQualification API Generalisation

    TM Forum Member
    Posted Mar 03, 2022 11:31
    Hi Jonathan,

    Thank you for the quick reply! Isn't it semantically correct to use GET as well, so that in real time scenario,  the POST is removed and GET is replaced with an actual serviceability call?

    ------------------------------
    Lakshmi Mallidi
    Salesforce
    ------------------------------



  • 28.  RE: TMF645 - QueryServiceQualification API Generalisation

    TM Forum Member
    Posted Mar 03, 2022 12:13
    Let me try to explain the task pattern in more detai.
    First: Tasks can be executed synchronously or asynchronously. Depending on the API, the choice of synchronous or asynchronous may be:
    • Determined by the specific implementation for all invocations of a specific task - this would be expected to be documented by the implementation,
    • Determined by the API spec itself - implementations should not deviate from this (I'm not sure if we have any practical example, although prepay balance operations would seem to be good candidates for always being synchronous)
    • Determined by the consumer per task invocation, as in this example of service qualification where there is an input flag
    • Determined by the provider per task invocation (e.g. we could conceive that address validation might be immediate where the address is found in a GIS, but if it is not found there might be manual work needed to complete the validation or reject it).
    Second: Task resources may or may not be persisted:
    • If the task execution is asynchronous, the task must be persisted, since we need to track its execution (either by polling its status or by listening to status change events)
    • If the task execution is synchronous, the API implementation may decide nevertheless to persist the task, e.g. for auditing or accounting reasons, or not to persist the task.
    In your example, because you requested immediate completion, the POST of the qualification task will return the final result immediately.
    • If the implementation decided to persist, the HTTP response will be 201 Created, and the returned task resource should include ID and HREF so that a subsequent GET can be used to retrieve (BTW no guarantees on how long the resource will remain in persistence before being cleaned up.
    • If the implementation decided not to persist, the HTTP response will be 200 Success, and the returned task resource will have empty ID and HREF, there is no meaning in this case for a subsequent GET
    Hope it is now 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.
    ------------------------------