Open APIs

 View Only
Expand all | Collapse all

"role" in relatedParty

  • 1.  "role" in relatedParty

    TM Forum Member
    Posted Sep 11, 2019 06:41
    Hi All,
    The role field in relatedParty is usually a String. What should be done if a person is serving more than one role?. There are three approaches I can think of. Which one of these is better?

    1. Replicate the data
    {
    	id: P1
    	name: John
    	relatedParty: [
    		{
    			role: "Primary Contact"
    			id: P2
    			name: "George"
    			@referredType: Individual
    		},
    		{
    			role: "Father"
    			id: P2
    			name: "George"
    			@referredType: Individual
    		}
    	]
    }
    


    2. Change data type of role from String to an Array
    {
    	id: P1
    	name: John
    	relatedParty: [
    		{
    			role: ["Primary Contact", "Father"]
    			id: P2
    			name: "George"
    			@referredType: Individual
    		}
    	]
    }


    3. Encode the information in the role String
    {
    	id: P1
    	name: John
    	relatedParty: [
    		{
    			role: "Primary Contact,Father"
    			id: P2
    			name: "George"
    			@referredType: Individual
    		}
    	]
    }


    ------------------------------
    Shibin CK
    Tecnotree
    ------------------------------


  • 2.  RE: "role" in relatedParty

    TM Forum Member
    Posted Sep 11, 2019 07:03

    Related Party is intended to provide a reference to either a Party (RelatedParty.role will be blank) or a PartyRole (RelatedParty.role will have the name of the role). Related Party is not in itself a managed entity.

    If a Party plays multiple roles, there will be a PartyRole (or concrete subclass) for each such role. Suppose John Doe works for H.A.L computers as the communications expert, and H.A.L. uses NXT Communications for its business wireline services. John Doe also has personal cellphone service from NXT for himself and his daughter.
    So:

    • There will be an Individual (subclass of Party) with first name John, last name Doe
    • There will be an Organization (subclass of Party) with name H.A.L.
    • There will be a Customer (subclass of PartyRole) with name John Doe, and the engagedParty for this Customer will be the Individual John Doe
    • There will be a Customer (subclass of PartyRole) with name H.A.L., and the engagedParty for this Customer will be the Organization H.A.L.
    • There will be a PartyRole with name John Doe and role Contact, and the engagedParty for this PartyRole will be the Individual John Doe
    • The Customer H.A.L. will have a RelatedParty that points to the John Doe PartyRole

    Hope this helps

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



  • 3.  RE: "role" in relatedParty

    Posted Jan 02, 2020 21:55
    Hi Jonathan

    In TMF629 Customer Management API there appears to be a mistake in the example where the RelatedParty of John Doe is using @referredType of Organisation instead of Individual and likewise for the href as follows...

    ​"relatedParty": [
        { "@referredType": "Organization",
            "href": "https://host:port/tmf-api/partyManagement/v4/organization/2777",
            "id": "2777",
            "name": "John Doe",
            "role": "bill receiver"
           }
        ]

    Also the contactMedium indicates TelephoneMedium with a preferred medium of TelephoneNumber but the telephone number has not been provided (only the address).

    There seems to be some inconsistencies within some of the other API examples relating to the @referredType.  What is the best way of raising these typos, or are these already being addressed?



    ------------------------------
    Dan d'Albuquerque
    TO BE VERIFIED
    ------------------------------



  • 4.  RE: "role" in relatedParty

    TM Forum Member
    Posted Apr 02, 2020 02:46
    Hi Dan

    I have opened a defect report on Customer Management, don't know when it will get fixed.
    Please report other specific examples - if you have access to the Open API project you can report them directly in the project JIRA at https://projects.tmforum.org/jira/ - otherwise I guess here would be the best place.
    There is a peer review process for the documents but these are mistakes that can get missed.
    Thanks for your attentiveness.

    ------------------------------
    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.
    ------------------------------



  • 5.  RE: "role" in relatedParty

    TM Forum Member
    Posted Mar 27, 2020 08:33

    Hi Jonathan,
    Regarding TMF669 and an example you gave.

    "There will be a PartyRole with name John Doe and role Contact, and the engagedParty for this PartyRole will be the Individual John Doe"


    In the previous version of TMF669, R18, I guess this example would be represented like this:

    {
    "@type": "PartyRole",
    "id": "123",
    "name": "John Doe",
    "engagedParty": {
    "@referredType": "Individual",
    "id": "42",
    "name": "John Doe"
    },
    "type": {
    "name": "Contact"
    }
    }



    When looking at the current R19 production specification of TMF669, there seem to be a few changes introduced compared to R18.
    - In R19, there is no longer a type attribute (RoleTypeRef)
    - In R19, the engagedParty is now a RelatedParty instead of a PartyRef.

    Where should the role value (Contact) be now be stored in the PartyRole resource? There is no type/role attribute anymore. Since the engagedParty type has been changed from PartyRef to RelatedParty, it could be populated there, but it does not seem quite right:

    {
    "@type": "PartyRole",
    "id": "123",
    "name": "John Doe",
    "engagedParty": {
    "@referredType": "Individual",
    "id": "42",
    "name": "John Doe",
    "role": "Contact"
    }
    }


    The TMF669 R19 specification states that name and roleType are mandatory attributes when creating a PartyRole. The roleType attribute is not mentioned anywhere else in the document, including the resource model, and it's not defined in the swagger file either nor mentioned in the conformance profile document.

    Please advise. Thank you.

     



    ------------------------------
    Paul Austdal
    Telia Company
    ------------------------------



  • 6.  RE: "role" in relatedParty

    TM Forum Member
    Posted Mar 29, 2020 19:50

    Hi Jonathan,
    Regarding TMF669 and this example you gave.

    "There will be a PartyRole with name John Doe and role Contact, and the engagedParty for this PartyRole will be the Individual John Doe"

    In the previous version of TMF669, R18, I guess the example would be represented like this:

    {
    "@type": "PartyRole",
    "id": "123",
    "name": "John Doe",
    "engagedParty": {
    "@referredType": "Individual",
    "id": "42",
    "name": "John Doe"
    },
    "type": {
    "name": "Contact"
    }
    }

    When looking at the current R19 production specification of TMF669, there seem to be a few changes introduced compared to R18.
    - In R19, there is no longer a type attribute (RoleTypeRef)
    - In R19, the engagedParty is now a RelatedParty instead of a PartyRef.

    Where should the role value (Contact) be now be placed in the PartyRole resource? There is no type/role attribute anymore. Since the engagedParty type has been changed from PartyRef to RelatedParty, it could be populated there, but is does not seem quite right:

    {
    "@type": "PartyRole",
    "id": "123",
    "name": "John Doe",
    "engagedParty": {
    "@referredType": "Individual",
    "id": "42",
    "name": "John Doe",
    "role": "Contact"
    }
    }

    The TMF669 R19 specification states that name and roleType are mandatory attributes when creating a PartyRole. The roleType attribute is not mentioned anywhere else in the document, including the resource model, and it's not defined in the swagger file nor mentioned in the TMF669 R19 Conformance Profile document.

    Please advise.



    ------------------------------
    Paul Austdal
    Telia Company
    ------------------------------



  • 7.  RE: "role" in relatedParty

    TM Forum Member
    Posted Apr 02, 2020 01:45

    Hi Paul

    First please note that all type attributes in the Open API model were renamed, since they clash with the @type attribute used for polymorphism. Here in PartyRole, it became roleType.

    But I am concerned that maybe a mistake has been made in this new published version. engagedParty is the Party playing the PartyRole, as in my examples, and hence it should be a PartyRef and not a RelatedParty.
    Additionally, it does seem that some description strings are missing in the schema, for example description for roleType.

    I plan to raise a defect report on this to the Open API team, and we'll see what happens from there.




    ------------------------------
    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.
    ------------------------------