Open APIs

Expand all | Collapse all

TMF-645 : geographicAddress in the request

  • 1.  TMF-645 : geographicAddress in the request

    TM Forum Member
    Posted Mar 28, 2019 13:26
    Hi All,

    I was anaylzing TMF645_Service_Qualification_Management_API_R18.0.1.pdf document vs TMF645_Service_Qualification_Management_API_REST_Specification_R18.5.0  version and I observed that in v18.0.1 there was a possibility to receive the structured address for checking technical service availability (see below json from pdf).

    fullGeographicAddress in v18.0.1
    However now in v18.5.0 this is not possible anymore (see screenshot below).

    missingFullGeographicAddress in 18.5
    Is there a reason to remove this and how is it then expected to pass structured address (the most important input) in the service qualification request?

    Kindly advice !

    ------------------------------
    BR,
    Kailash Mali
    Ericsson Inc.
    Netherlands
    ------------------------------


  • 2.  RE: TMF-645 : geographicAddress in the request

    TM Forum Member
    Posted Apr 01, 2019 05:46
    The Place resource is conceptually a base class, that could be a GeographicalAddress (or GeoLocation or GeoSite).
    As such, when passing a Place as input, you can pass the GeographicalAddress by value (structured fields), or refer to an existing address by ID. You would set the @type ​attribute to GeographicalAddress, so that the provider will understand that you are passing in such an address.

    For ServiceQualification one could argue that you would always want to check service feasibility for an existing and validated address, so as not to waste resources on dealing with an invalid address, and the example in the R18.5 spec indeed shows reference to an existing address. But the ability to pass address by value has not been removed.

    Hope it helps.

    ------------------------------
    Jonathan Goldberg
    Amdocs Management Limited
    ------------------------------



  • 3.  RE: TMF-645 : geographicAddress in the request

    TM Forum Member
    Posted Apr 11, 2019 07:13
    Thanks Jonathan for your reply.

    So indeed we would like to use fully detailed geographic address  (with PostCode, Street, House#) in input request for the Place entity (when role = "installationAddress").

    There are 2 scenarios under which other projects would also like to use fully detailed address instead of id :
    1. Combination of 1 or more elements in the address serves to identify the unique address (for ex. Countries like Netherlands where PostCode+HouseNumber serves as the unique way to identify an address . PostCode : 1121AB, Houser Number : 33)
    2. The APIs are hosted by OSS system which is a separate Network company / organization and BSS (from various OTT operators) would like to check Service Availability on a given address from this Network company and they dont share the common address master database and hence must supply the full address in the request.

    Considering above need, if we look at the documentation of v18.0, it indeed exactly solves our problem, however the element "@referredType" is missing in the v18.5 documentation, and is showing as "@type": "GeographicAddress" in the example (refer above).

    So with documentation it is not clear if we should use structure A or B below as per v18.5 documentation?
    Structure A  
    Structure A - v18.0 - with @referredType
    Structure B

    Structure B - @type in v18.5
    Appreciate your inputs and would be nice to have it also in the documentation both possibilities?



    ------------------------------
    Kailash Mali
    Ericsson Inc.
    ------------------------------



  • 4.  RE: TMF-645 : geographicAddress in the request

    TM Forum Member
    Posted Apr 11, 2019 08:51
    In R18.5 @referredType​​ was replaced in Place by the full polymorphic entity set (@type, ​@baseType, and @schemaLocation). But the presence of the role attribute is tricky (since it is not relevant to an address in isolation, only to the use of an address by another entity). So in R19.0 we are considering a refactoring - renaming Place to RelatedPlace (keeping all the attributes), for entities that use a place, and defining a new Place without the role to serve as the base address class.
    This change will not affect your ability to pass the address fields by value, and since the attributes remain the same it is not a breaking change.

    Hope it helps

    ------------------------------
    Jonathan Goldberg
    Amdocs Management Limited
    ------------------------------



  • 5.  RE: TMF-645 : geographicAddress in the request

    TM Forum Member
    Posted Apr 23, 2019 12:29
    Hi Jonathan,

    Thanks for your reply, considering above do you think (Structure B mentioned above) is a valid data structure to use to pass details of the address?
    Mainly the point that the structured fields are grouped under "geographicAddress" container in "Place" Entity to organize them based on the type mentioned.

    "place": [
              { "role": "installationAddress", 
                "@type": "geographicAddress", 
                "geographicAddress": { 
                                      "streetNr": "160", 
                                      "streetName": "de Versailles", "streetType": "Avenue", 
                                      "postcode": "75016", "city": "Paris", "country": "France" 
                                     }
                    }


    ------------------------------
    Kailash Mali
    Ericsson Inc.
    ------------------------------



  • 6.  RE: TMF-645 : geographicAddress in the request

    TM Forum Member
    Posted Apr 26, 2019 05:27
    What you have is not GeographicAddress but PostalAddress.

    "geographicAddress": { "latitude" : "48.840591",  "longitude": "2.264076" }

    I also support Johathan's question of why you need ROLE part of PLACE object schema, as that attribute likely belongs to business process context.
    Imagine same PLACE being used for installation of a fixed line product, but it may already host something else in another state (wireless, another customer).
    "Installation" is a role of a particular ORDER, SERVICE or PROJECT, not an attribute of PLACE.



    ------------------------------
    Sergey Zak
    Australia
    ------------------------------