Open APIs

 View Only
  • 1.  TMF640 vs TMF638 GET/LIST API

    TM Forum Member
    Posted Jun 04, 2024 14:37

    I have a question on the relationship between the GET (LIST) services APIs for TMF640 and TMF638. 

    From the API User Guides:

    TMF640 describes the operation: GET /tmf-api-/ServiceActivationAndConfiguration/v4/service

    This operation list service entities. 

    Here's an example of a request for retrieving services from the network.

    TMF638 has a very similar operation: GET /tmf-api/serviceInventory/v4/service

    This operation list service entities. 

    Here's an example of a request for retrieving multiple services.

    The key difference seems to be that 640 is retrieving from the network. This is also explained in the discussion in TMF640 and TMF638 that TMF638 is an IT (database) component. Whereas TMF640 interacts directly with the network... However, in an actual implementation I would expect that both APIs are being served from databases, but perhaps different databases or views of the data.

    When both of these APIs coexist, is the expectation that the TMF638 response and the TMF640 response are the same? Or is the TMF638 response a superset of TMF640 such that 638 has a complete view of the inventory while 640 is limited to the live/operational network view that has either been created through TMF640 POST or is directly discoverable from the network? Or is there a better way to think about these?

    Thanks for any insights.

    - Gordon


    Gordon Bolt
    Ciena Corporation

  • 2.  RE: TMF640 vs TMF638 GET/LIST API

    TM Forum Member
    Posted Jun 05, 2024 02:00

    Hi Gordon

    At the end of the day, it's a matter of implementation decisions and network capabilities. I don't claim to be an OSS expert, but my layman's intuition would say the following:

    • TMF638 exposes the service inventory. So the scope of the data that is returned is limited to what you store in the inventory. For example, telcos may choose to bypass the service inventory completely for the mobile line-of-business, and treat the HLR/HSS as the sole master of service storage.
    • TMF640 exposes the network itself. So the scope of the data that is returned is limited by the ability of "the network" to return this data. Different service silos might have different end-points, all of which could expose TMF640. Or you could create an aggregating layer for the GET operation that orchestrates gathering the data from multiple silos.

    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: TMF640 vs TMF638 GET/LIST API

    TM Forum Member
    Posted Jun 06, 2024 09:42

    Hi Jonathan,

    Thanks for the answer. It is helpful to make the distinction of the service inventory versus the network.

    If I think of it literally as TMF640 using the network as the source-of-truth it breaks down with services with a requested state of feasabilityChecked or designed. I don't think of those as actually being in the network so a POST /service followed by a GET /service would not read its write. 

    If I think of it as a "service activation inventory", then it makes more sense to me as a separate service inventory view of services whose lifecycles are managed via 640.

    Gordon Bolt
    Ciena Corporation

  • 4.  RE: TMF640 vs TMF638 GET/LIST API

    TM Forum Member
    Posted Jun 07, 2024 17:32
    Hi Gordon,

    Our recommended way to implement TMF638 is to always have it return the 'actual' or current service. This is the service you have, refreshed from the resource layer.

    If the service was manipulated by TMF641 POST then the TMF641 serviceOrder.serviceOrderItem.service would show your intended service fragment. Similarly TMF640 POST/PATCH conveys a service intention, which either specifies or updates the expected or desired service. With TMF641 GET order the service fragment shows what you've asked for, but in service order events we like to show the service as it actually is at that moment.

    In a world where service updates are reliable and fast this distinction between expected and actual may not matter so much, but we have found that:
    • Telco operations are often complex, unreliable and/or long running, which makes them subject to further amendment of intention or change in 'delivery recipe'.
    • To use or compose a service you need to know when the work of a service is actually done, and often what you now have
    • 'Inventory' needs to contain persistent expected and actual, at least internally to a network domain
    • Service events on the actual should only be generated when work is actually done
    • If you offer TMF641/TMF638 then you don't expose TMF640 and the TMF638 GET should only ever show the service you actually have.
    • If you offer TMF640 POST/PATCH then you don't need to expose TMF638 if you expose TMF640 GET as actual service.

    • We maintain a persistent expected service view (generally this is only visible within the network domain), each order/patch is a partial update to this service
    • We difference expected and actual services to generate the outstanding or difference service, which drives the work required, as this work is done this updates actual service view which advances until there is no essential difference.
    • We are very clear how we signal when work has actually been done, this allows reliable consumption/composition

    Hope this helps. We are talking further about our expected/actual/outstanding approach at DT Ignite.

    Best Regards,



  • 5.  RE: TMF640 vs TMF638 GET/LIST API

    TM Forum Member
    Posted Jun 12, 2024 17:10

    Hi Matt - I like the focus on "intent" versus "actual" or "observed" state and that is consistent with how we think about the problem. I am just struggling a bit with how to reflect those states in the TMF aligned APIs.  Thanks for the details on how you are handling it. I'll look for your session from DT Ignite.



    Gordon Bolt
    Ciena Corporation

  • 6.  RE: TMF640 vs TMF638 GET/LIST API

    TM Forum Member
    Posted Jun 13, 2024 02:33

    Hi Matt and Gordon,

    I appreciate that you want to represent the desired and actual state of the services, and use the difference to drive the required work. 

    What is unclear is how you want to represent the actual and desired states of services in the results of TMF638 and TMF640 retrieve/list calls.

    You could have an interpretation where the TMF640 retrieve/list calls return the actual state and TMF638 returns the desired state, so that you can compare; but as I read the standards, that interpretation is not really supported by the text.

    On the other hand, you are right that the resource model of the two APIs do not appear to have sufficient information to represent both actual and desired state of a service.

    Clearly, TMF wants to ensure that an implementation MAY want to separate the representation of actual state as reported by TMF640 (e.g. by fetching information directly from a HLR/HSS), from the persisted inventory representation.

    But I don't think that TMF intends to mandate that an implementation of TMF640 MUST NOT have its own persisted representation.

    So if an underlying implementation, for whatever reason, does have its own persisted representation of both the actual and desired states of the services, and you want to support both TMF638 and TMF640 based on that single implementation, then the question arises what the difference should be between identical calls made towards one or the other API.


    • Are the TMF640 calls forbidden from returning desired states?
    • Are the TMF638 calls forbidden from returning actual states?


    • When a TMF638 call changes the desired state, is it forbidden for the underlying system to act on the difference between actual and desired that may arise from this?
    • When TMF640 call changes the state, then transiently, during the activation (or if it fails), the actual state will differ from the desired one. Is TMF640 forbidden from returning the desired state, so it is only allowed to return the actual state?

    Your suggestions are sensible:

    If you offer TMF641/TMF638 then you don't expose TMF640

    If you offer TMF640 POST/PATCH then you don't need to expose TMF638

    There are, unfortunately, operators who require that all three APIs must be exposed simultaneously for the same services, and even that TMF640 POST/PATCH can be used for external activation requests on services that are simultaneously under the control of TMF641, also making internal requests to TMF640.

    I cannot point to anything in the API definitions themselves that supports the suggestions. So this is not just a "theoretical" problem.


    Peter Bruun
    Hewlett Packard Enterprise