Open APIs

Expand all | Collapse all

RelatedParty reference to PartyRole (669) vs Customer (629)

  • 1.  RelatedParty reference to PartyRole (669) vs Customer (629)

    TM Forum Member
    Posted Aug 05, 2020 14:39
    Hi All,

    We are implementing ServiceOrder API (641).  We want to relate our services to a customer.
    What we understood:
    • RelatedParty: Related party defines party or party role linked to a specific entity
      • Our conclusion: RelatedParty can point to Party API (TMF632) or PartyRole API (TMF669)
    • From the PartyRoleManagement Documentation:  "This API can be seen as a generalization of Customer management API"
      • However, it is not clear if Customer ME is officially a specialization of PartyRoleManagement ME. Compared to "Individual" and "Organization" that are official Specialization of "Party" and embedded in the same 632 Document
    At the end, we are trying to understand if relatedParty can point to Party API (TMF632) or PartyRole API (TMF669), but also to Customer API (TMF629)?


    ------------------------------
    Stephane AH-KO
    CGI Info Systems Management Consulting Inc.
    ------------------------------


  • 2.  RE: RelatedParty reference to PartyRole (669) vs Customer (629)

    TM Forum Member
    Posted Aug 06, 2020 01:38
    Hi Stephane
    Conceptually, Customer is indeed a specialization of PartyRole - if you look at the fields in Customer you will see that they are a superset of PartyRole.
    Customer was broken out as a specific entity (and API) due to its ubiquity, other PartyRoles (such as Supplier, Dealer, and many more) have not been given this treatment so far in the Open API.
    I think that you can use RelatedParty to refer to a Customer entity (in Order, ShoppingCart, and many other places where we have RelatedParty).
    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: RelatedParty reference to PartyRole (669) vs Customer (629)

    TM Forum Member
    Posted Dec 04, 2020 13:01
    Hi Jonathen,

    I am currently in Physical data model development and trying to connect the sequence of APIs to populate DB. The data is coming from APIs and we are storing them in relational DB (an EDWH).
    Regarding this topic, my understanding is that PartyRole created here for Customer comes from TMF669 in relatedParty construct (@referredType + id + role). Simultaneously, the association between RartyRole and Customer is referred in TMF629 as engagedParty (@referredType + id).

    (Please correct me if the codes are allowed here or not)

    Following are the example of PartyRole and Cisutomer samples to support my question.

    -- TMF669 - PartyRole sample
    {
      "@type": "PartyRole",
      "href": "https:/host:port/tmf-api/partyRoleManagement/v4/partyRole/4079",
      "id": "4079",
      "name": "Global Pirates",
      "status": "Approved",
      "statusReason": "NDA has been signed",
      "validFor": {
        "startDateTime": "2018-06-16T00:00Z",
        "endDateTime": "2019-01-13T00:00Z"
      },
      "engagedParty": {
        "@referredType": "Organization",
        "href": "https:/host:port/tmf-api/partyManagement/v2/organization/99",
        "id": "99",
        "name": "Global Pirates",
        "role": "Provider"
      },
      "relatedParty": [
        {
          "@referredType": "Organization",
          "href": "https:/host:port/tmf-api/partyManagement/v4/organization/3658",
          "id": "3658",
          "name": "Gustave Flaubert",
          "role": "customer"
        }
      ]
    }​​


    -- TMF 629 Customer sample

    {
      "@type": "Customer",
      "href": "https://host:port/tmf-api/customerManagement/v4/customer/1140",
      "id": "1140",
      "name": "Moon Football Club",
      "status": "Approved",
      "statusReason": "Account details checked",
      "validFor": {
        "startDateTime": "2018-06-12T00:00Z",
        "endDateTime": "2019-01-11T00:00Z"
      },
      "engagedParty": [
        {
          "@referredType": "Organization",
          "href": "https://host:port/tmf-api/partyManagement/v4/organization/3658",
          "id": "3658",
          "name": "Gustave Flaubert"
        }
      ]
    }​


    Saying that:
    1) does that mean the engaged party referred in Customer API is already created first via PartRole API as relatedParty "Customer"? It is just a reference then.
    2) Or, I do not need the PartyRole API sample at all and can populate the PartyRole (as DB table consisting of PartyRole and relatedParty schema attributes) from TMF625 (Customer) sample. Does the same apply for other APIs which refer to relatedParty?

    Thanks.



    ------------------------------
    Sukhdev Singh Matharu
    Vodafone GmbH
    ------------------------------



  • 4.  RE: RelatedParty reference to PartyRole (669) vs Customer (629)

    TM Forum Member
    Posted Dec 04, 2020 13:08
    Hi Jonathen,

    I am currently in Physical data model development and trying to connect the sequence of APIs to populate DB. The data is coming from APIs and we are storing them in relational DB (an EDWH).
    Regarding this topic, my understanding is that PartyRole created here for Customer comes from TMF669 in relatedParty construct (@referredType + id + role). Simultaneously, the association between RartyRole and Customer is referred in TMF629 as engagedParty (@referredType + id).

    (Please correct me if the codes are allowed here or not)

    Following are the example of PartyRole and Cisutomer samples to support my question.

    -- TMF669 - PartyRole sample
    {
      "@type": "PartyRole",
      "href": "https:/host:port/tmf-api/partyRoleManagement/v4/partyRole/4079",
      "id": "4079",
      "name": "Global Pirates",
      "status": "Approved",
      "statusReason": "NDA has been signed",
      "validFor": {
        "startDateTime": "2018-06-16T00:00Z",
        "endDateTime": "2019-01-13T00:00Z"
      },
      "engagedParty": {
        "@referredType": "Organization",
        "href": "https:/host:port/tmf-api/partyManagement/v2/organization/99",
        "id": "99",
        "name": "Global Pirates",
        "role": "Provider"
      },
      "relatedParty": [
        {
          "@referredType": "Organization",
          "href": "https:/host:port/tmf-api/partyManagement/v4/organization/3658",
          "id": "3658",
          "name": "Gustave Flaubert",
          "role": "customer"
        }
      ]
    }​​


    -- TMF 629 Customer sample
    {
      "@type": "Customer",
      "href": "https://host:port/tmf-api/customerManagement/v4/customer/1140",
      "id": "1140",
      "name": "Moon Football Club",
      "status": "Approved",
      "statusReason": "Account details checked",
      "validFor": {
        "startDateTime": "2018-06-12T00:00Z",
        "endDateTime": "2019-01-11T00:00Z"
      },
      "engagedParty": [
        {
          "@referredType": "Organization",
          "href": "https://host:port/tmf-api/partyManagement/v4/organization/3658",
          "id": "3658",
          "name": "Gustave Flaubert"
        }
      ]
    }​​

    Saying that:
    1) does that mean the engaged party referred in Customer API is already created first via PartRole API as relatedParty "Customer"? It is just a reference then.
    2) Or, I do not need the PartyRole API sample at all and can populate the PartyRole (as DB table consisting of PartyRole and relatedParty schema attributes) from TMF625 (Customer) sample. Does the same apply for other APIs which refer to relatedParty?


    Thanks.


    ------------------------------
    Sukhdev Singh Matharu
    Vodafone GmbH
    ------------------------------



  • 5.  RE: RelatedParty reference to PartyRole (669) vs Customer (629)

    TM Forum Member
    Posted Dec 07, 2020 08:17
    Hi Sukdev
    Please note firstly that different Open APIs are authored by different people. We have a common schema that guarantees consistency between models in different APIs. But we don't have a process that verifies consistency of examples between APIs. Of course we strive to ensure that an API example set is valid for the API, and more recently we have automatic validation for the example set.

    Anyway, to get to your query:
    • A Customer is a PartyRole, as I stated earlier in this thread. You would not create a PartyRole and then a Customer, just go ahead and create a customer.
    • The engaged party, i.e. the individual or organization playing the role of the customer, must be created first, since you need to populate the engaged party reference in the Customer with the id of the engaged party
    • Of course if the Customer refers to other parties or party roles (including other customers, perhaps) via the related party reference (an array) those also need to be created first (if they don't already exist) so that you can populate the id in those references 
    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.
    ------------------------------



  • 6.  RE: RelatedParty reference to PartyRole (669) vs Customer (629)

    TM Forum Member
    Posted Dec 08, 2020 11:56
    Many thanks Jonathan for the detailed response.
    It is very helpful and obviously helped me in filling gaps in building big picture.

    Best regards,
    Sukhdev

    ------------------------------
    Sukhdev Singh Matharu
    Vodafone GmbH
    ------------------------------



  • 7.  RE: RelatedParty reference to PartyRole (669) vs Customer (629)

    TM Forum Member
    Posted Aug 06, 2020 05:14
    Hi Stephane,

    Based on my understanding regarding RelatedPartyRef -
    • We use RelatedParty when we want to indicate that an entity has parties or party roles of interest
    • This is a short-cut that is used all over the Open API model to allow a reference to be to either a Party or to a PartyRole.
    • If the Customer represented a family (for example), there might be RelatedPartyRefs pointing directly at the family members as Individuals Or the service provider might prefer to model the family members as PartyRoles of type Contact.


    ------------------------------
    Syed Javed
    Oracle Corporation
    ------------------------------