Open APIs

Expand all | Collapse all

TMF 645: Synchronous and transient Service Qualification?

  • 1.  TMF 645: Synchronous and transient Service Qualification?

    TM Forum Member
    Posted Jan 08, 2019 09:11

    a typical use case in TelCo industry would be a check whether a given service - or, alternatively, which services at all - are available at a given location (e.g. address). Typically this service is a purely reading request and synchronous, so the service consumer awaits a response within the current session and within a few seconds.

    I had a look in TMF 645 (Service Qualification) and found that this is a very powerful and complex modelling:
    - a service qualification resource will be created (and persisted) - with an own lifecycle
    - it contains mechanism for asynchronous communication
    - etc.
    which implies the need for a "health care" process in order to remove such service qualification objects after some period of time etc.
    This would be fine for complex, asynchronous processes for service qualification checks.

    But isn't there also a somewhat "light version" of service qualification available, e.g. some GET method which just returns the possible services at a given place/location?  Without any persistence, house-keeping process, state notification changes and all this?

    BR Thomas

    Thomas Dupré
    Deutsche Telekom AG

  • 2.  RE: TMF 645: Synchronous and transient Service Qualification?

    TM Forum Member
    Posted Jan 09, 2019 03:44
    Hi Thomas

    To my understanding, the ServiceQualification is one example of the TASK resource paradigm that we have in the Open APIs.
    By POSTing a task resource, a business operation is invoked (e.g. address validation, prepay balance topup, and more).
    The TASK resource pattern supports synchronous and asynchronous behavior.

    • For asynch, the POST results in creation (persistence) of the task resource as well as actual execution of the task, and this resource is responsible for subsequent tracking of the task (which may take seconds, minutes, or days). The task resource would be expected to have a status attribute that would be populated with a value such as Pending, In Process, etc. Later notifications or polling would give indication as to when the task is finished (with success or failure).
    • For synch, the POST may or may not create a persistent representation of the resource, and would return a value of success or failure in the status attribute, together with any information that results from the completion of the task (e.g. the validated address, the updated amount of the prepay balance, etc.). The reason for persisting synch task requests might be for auditing, for monetization of tasks, etc.

    It's up to the implementer of the API to decide whether synch or asynch (or both) is supported.

    Hope it helps

    Jonathan Goldberg
    Amdocs Management Limited

  • 3.  RE: TMF 645: Synchronous and transient Service Qualification?

    TM Forum Member
    Posted Jan 10, 2019 06:19
    Hi Thomas, Jonathan,

    The TMF630 design guidelines have a good explanation of how task resources should be implemented.

    • If it returns 200 OK : the task has completed synchronously
    • If it returns 202 Accepted : The task will complete asynchronously

    The implementor has absolute freedom to implement this synchronously or asynchronously.
    So a synchronous implementation of TMF645 can be perfectly compliant to the specifications.


  • 4.  RE: TMF 645: Synchronous and transient Service Qualification?

    TM Forum Member
    Posted Jan 14, 2019 07:25
    Hi Koen,

    I agree that TMF645 can be implemented in a synch or asynch way.

    My primary point, however, is the need to persist Service Qualification resources if I use TMF 645 (at least how I understand it).

    • In most cases the result of a service availability check can be provided to the service consumer within a few seconds and in a purely transient manner by retrieving some sort of service data base. This is a read-only mode, no need to persist anything on the service provider side from a business point of view.
    • However, if I use TMF 645 POST for this availability check, the service provider needs to instanstiate a Service Qualification resource, generate an id for it (and for all involved Service Qualification items) and persist it in order to allow for subsequent GET operations.
      In addition, if we take into account that the number of service qualification requests can be extremely high (anyone in the Internet could submit such a service availability request) we have to take care of a clean-up job that periodically deletes old service qualification objects, and so on.
      For long-running processes (which might involve manual operations for availability check) this seems to be worth the effort - but for the >95% cases of purely reading, short running retrievals of availability information I have some doubts. 
    Therefore I wonder if there might be some more light-weight approach for service availability checks.

    Best regards

    Thomas Dupré
    Deutsche Telekom AG

  • 5.  RE: TMF 645: Synchronous and transient Service Qualification?

    TM Forum Member
    Posted Jan 14, 2019 08:30
    Hi Thomas,

    The conformance Profile indeed describes that for a fully compliant solution the GET operation is mandatory.
    However when your implementation is synchronous and not costly I do not see a reason for having it mandatory.
    You could request the OpenAPI team to make the GET operation optional.


  • 6.  RE: TMF 645: Synchronous and transient Service Qualification?

    TM Forum Member
    Posted Jan 10, 2019 06:19
    Hi Jonathan,

    thanks for your reply.

    If I understand you correctly, following your idea, for the synchronous and purely transient case a POST would then just return the available services, but without necessarily creating and persisting a service qualification object. In particular it might not return an id of this service qualification (if it is not persisted). This might look a bit strange - together with the fact that a POST (not a GET) operation would be used to retrieve some information.

    In my humble view (I am just starting to get occupied with this matter in more detail) the question is about the fundamental resource:
    • If it is about a service qualification object then it is a logical consequence that a POST should create it and return its id. This could be used for short-running and long-running service qualification processes by the same interface. (TMF645)
    • What the consumer needs from the business point of view, however, is not the qualification object (this would only be a means to an end) but information about the available services. So maybe a GET method based on the service (not the service qualification) would be more appropriate for this use case, e.g.
      GET /service?fields=...&{filtering}
      where filtering criteria could include the address. This is, however, not (yet) contained e.g. in TMF640.
    So I'm still struggling about the matter...

    BR THomas

    Thomas Dupré
    Deutsche Telekom AG

  • 7.  RE: TMF 645: Synchronous and transient Service Qualification?

    Posted Jan 09, 2019 04:50
    Hi Thomas,

    We went for a similar approach:
    - To offer this kind of serviceability information, which basically aggregates (either by locally stored projections or by invoking legacy trough adapters) based on a geographical address (there is TMF API that works well for that) an set of "flags" indicating what is available on an address. E.g. DSL/Cable/Fibre/LTE and so on, typically flags on available technologies and bandwidths. These are then used for display in agent facing UIs or further simplified in customer facing UIs/sales flows. This indeed is a simply GET call accepting the geographical address (or ID(s)).
    - This (those simple flags/keys) we consider context and we've extended the qualification APIs to accept context like this to them (other context usually are shoppingcart or customer account), we expose this context to relevant rule engines and evaluate (in our case using a declarative DSL, e.g. concepts like serviceability, compatibility, eligibility, life-cycle, promotions and so on) which products are available given the serviceability flags (and or any other context). This then you can use in conjunction with e.g. the shopping-cart API.

    We faced the same concern you do that the current model (in our opinion) doesn't fit our sales-related uses cases as well as we hoped. What we needed in qualification (a very important topic for us, being oriented at sales (support) processes) was simply information on what is available, and a way for our consumers to translate that easily to which commercial products/services customers can buy in a given context, or how he/she can change products on his/her contract. Without concerning the consumer of the services with too much complexity other then capturing address data.

    However most of this we currently do using either schemas not existing in TMF and by extending TMF schemas (as we need to achieve compatibility).

    Please let me know how you plan to tackle the challenge in your case. Always interesting to see how different parties use the APIs and how they are extended to make them work IRL.


    Pieter Pabst

  • 8.  RE: TMF 645: Synchronous and transient Service Qualification?

    TM Forum Member
    Posted Jan 16, 2019 04:54
    ​Hi Thomas
    I have looked at TMF645 and it creates and queries SQ tasks - not services themselves.
    Yes you may get/pass some attributes of the services that are available/wanted at a given location, but these is up to your implementation and interaction design.
    Services are only instantiated (UUID created are returned in responses) when using TMF640.
    If TMF645 returned a service type your customer would like as available, then next call could be creating service instance in "Feasibility Checked" state by TMF640, then progressing it (the instance) into "Reserved" or "Designed" state depending on whether there was a shortfall or intention to reserve necessary resources.
    The "health care" (housekeeping) logic might want to clean-up service/resource reservations after a period of no progress. This is down to overall interaction and business flow design.


    Sergey Zak
    Senior Domain Architect

  • 9.  RE: TMF 645: Synchronous and transient Service Qualification?

    TM Forum Member
    Posted Jan 20, 2019 14:07
    Hi all

    From my (admittedly very limited) experience in the area of service qualification, we can conceive of many use cases, such as:
    • A synchronous check that leaves no traces - this indeed has the characteristics of a query e.g. is idempotent (at least for as long as there are no changes in the network that would cause the query to be different), and in this case a GET on Service might be appropriate. But an additional consideration is that the query may be quite complex, difficult to express in a GET query string.
    • A synchronous check that does work in the network (e.g. reserves candidate resources), here even though the check is synchronous it is not idempotent and a GET on Service would be inappropriate
    • An asynchronous check (whether or not it leaves traces in the network) - here a POST is needed since the check entity (ServiceQualification) must be persisted so that it can be tracked
    Given the above, it is reasonable that a task resource with POST was chosen. We can raise the issue of whether GET on the task resource should be mandatory from conformance perspective.

    Anyway, nice to see a good healthy discussion going on here about service qualification. The team leaders for this API ( @Ludovic Robert and ​@Takayuki Nakamura ​​might want to add their views here.

    Jonathan Goldberg
    Amdocs Management Limited