Open APIs

Expand all | Collapse all

TMF674 Geographic Site Management API

  • 1.  TMF674 Geographic Site Management API

    TM Forum Member
    Posted Jun 10, 2020 09:21
    Hi!

    I've been looking into use cases for Customer Site management in the Customer and Product domain. In TMF637 Product Inventory API there is a relation to a "place" RelatedPlaceRefOrValue. Place is in SID Common domain: Location ABE, but is not really defined much. The use cases I'm looking at are not specific to Product Installation Address, but more to logical and physical Customer Sites like Head office, Side office, Stores etc. In some real life use cases the Site can be considered logical (organisation unit, lobby services, maybe some place-of-work where the actual geographical location is not important) Or moving, as in vehicles and animals. They are not really users and most cannot be modeled as Parties anyway. They are not Resources either as they represent Customer information and are not part of the functionality of the "Network".

    TMF674 seems like a good API candidate for this, but there is a problem (for me at least) in the API Resource model and API Conformance Profile. It assumes every Site has a known and relatively fixed location as either "address" or "geographicLocation" is mandatory. In real life use cases it can be currently unknown, not applicable or not fixed.

    Long story short, is there a possibility to change the relationship between GeographicSite and GeographicAddress from
    0..* - 1 to 0..* - 0..1 in the TMF674 Geographic Site Management API Resource model? Then it would be usable for all use cases of Party Site Management as well.

    P.S. Having a dummy address for this is not a good workaround.

    ------------------------------
    Niko Kolari
    Enterprise Information Architect
    DNA Plc
    Finland
    ------------------------------


  • 2.  RE: TMF674 Geographic Site Management API

    TM Forum Member
    Posted Jun 12, 2020 11:17
    Helo Niko

    Agree that TMF674 is the right API to have a look on.
    I checked the latest version of TMF674 and the cardinality to a place is 0..*. This is what you're looking for?

    Hope it helps
    Ludovic

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



  • 3.  RE: TMF674 Geographic Site Management API

    TM Forum Member
    Posted Jun 12, 2020 14:11
    Hello Niko,

    If I understand correctly, you want to model the case in which a product is installed on a moving vehicle or an animal (alongside others). I personally believe TMF674 is not appropriate for this case, since it is oriented towards geographic placement.

    So I would rather suggest making use of polymorphism and developing a totally new model of the moving "thing" where the product is installed. Then you could point product.place to that thing (and set @referredType accordingly).

    Regards,

    ------------------------------
    Şanver Narin
    PiA-TEAM INC.
    ------------------------------



  • 4.  RE: TMF674 Geographic Site Management API

    TM Forum Member
    Posted Jun 15, 2020 03:32
    Hi Şanver,

    What you are describing is not what I'm trying to model per se, but it is a corner case. My main case is Site Management and most "sites" do have an "address". To me "site" is a synonym for a "place". In TMF674 it is only when it has a known address/location.

    Problem with modeling a "thing" without "address/location" as a subclass of a "place", where a "site" with an "address/location" another subclass of "place",  is that it is not logical and thus becomes a entity management problem. If the classes are mutually exclusive there is a need for housekeeping where we need to move a single conceptual entity from one class (and API) to another depending on if we know the address or not. If they are modeled as not mutually exclusive and would be like roles, we would have one conceptual entity existing as two entities "site" and "thing", but without a clear distinction of why.  Logical law of identity does imply that a Sales office is a Sales office even if there are other definitions for it. Maybe Aristotle used a bit different terminology :)

    So using the above terminology where "site" and "thing" are subclasses of "place", I have a need to handle a "place" as a managed entity in TMForum Open API model. I could do that if that one hard coded mandatory relation would be relaxed in TMF674. If that was relaxed, nothing would prevent anyone from implementing that as a business rule, if needed.


    ------------------------------
    Niko Kolari
    Enterprise Information Architect
    DNA Plc
    Finland
    ------------------------------



  • 5.  RE: TMF674 Geographic Site Management API

    TM Forum Member
    Posted Jun 15, 2020 02:52
    Hi Ludovic,

    it's the right relation but the wrong direction. So one address can be related  to 0 to many "places", but a "place" must be related to one "address" or "location". As stated in the documentation about address being mandatory: "Yes, if geographicLocation not included".

    What I argue is that we have use cases where we need to manage "places" also when we don't know the "address/location". Sometimes "address/location" comes after the managed relationships of the "place" entity,  sometimes never.


    ------------------------------
    Niko Kolari
    Enterprise Information Architect
    DNA Plc
    Finland
    ------------------------------



  • 6.  RE: TMF674 Geographic Site Management API

    TM Forum Member
    Posted Jun 16, 2020 03:44
    Hi Niko

    Which version are you looking at ? Seems that Conformance profile latest version has not be uploaded :(

    About following sentence: "one address can be related to 0 to many "places", but a "place" must be related to one "address" "
    Are we aligned that a place is only a abstract class that must be specialized in the API payload as a geographic address, geographic location, or geographicSite?

    Hope it helps
    Ludovic

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



  • 7.  RE: TMF674 Geographic Site Management API

    TM Forum Member
    Posted Jun 16, 2020 04:21
    Hi Ludovic

    API
    TMF674
    Release 17.5.0
    January 2018

    Conformance Profile
    TMF674B
    Release 17.5.0
    January 2018

    I use the Open API table to navigate the documents https://projects.tmforum.org/wiki/display/API/Open+API+Table

    > Are we aligned that a place is only a abstract class that must be specialized in the API payload as a geographic address, geographic location, or geographicSite?
    Yes. I would like to use "geographicSite" in the payload and use the TMF674 API for that. But here when we are talking about the payload for a "place" we are talking about TMF637 Product Inventory API though? The quoted sentence of mine concerns TMF674, where the geographicSite (as a specialized place) has a mandatory address or location. And I argue that we need the managed entity for a geographicSite in some cases when we don't know the address/location. As those geographicSite entities are Party specific unlike address and location which are global.

    If there are unpublished documents/versions where an address or a location is no longer mandatory for a geographicSite, then everything should be fine for me and I can proceed with my plans for using TMF674. But as I am unaware of those I cannot comment. I still have the feeling that we are not talking about exactly the  same thing. Which for me is:
    "a possibility to change the relationship between GeographicSite and GeographicAddress from
    0..* - 1 to 0..* - 0..1 in the TMF674 Geographic Site Management API Resource model"

    ------------------------------
    Niko Kolari
    Enterprise Information Architect
    DNA Plc
    Finland
    ------------------------------



  • 8.  RE: TMF674 Geographic Site Management API

    TM Forum Member
    Posted Jun 16, 2020 04:53
    Niko,
    Yes ...We crafted the release v4.0 since then but probably not yet released. I check internally with @Alan Pope to have release situation update.

    The API model has been changed and relatedPlace is now 0..*.

    Ludovic


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



  • 9.  RE: TMF674 Geographic Site Management API

    TM Forum Member
    Posted Jun 17, 2020 04:22
    Hi Ludovic

    I now found the v4.0 document here:  https://projects.tmforum.org/wiki/pages/viewpage.action?pageId=128855518

    I now understand what you are referring to with "relatedPlace is now 0..*".  You have changed the site model to refer to a place instead of address or location. Where place is either an address, a  location or a site. This works for my use cases just fine.

    Thanks! So it looks like what I was asking was already in the pipeline. :)


    ------------------------------
    Niko Kolari
    Enterprise Information Architect
    DNA Plc
    Finland
    ------------------------------