Open APIs

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



  • 8.  RE: "role" in relatedParty

    TM Forum Member
    Posted May 13, 2020 03:26
    Hi All,

    i have the similar question for in TMF640, as part of the Service in TMF640, there is an array of relatedParty.
    But seem that is still under R18 whereby it don't have the roleType.
    It is correct if i extend the RelatedParty like below?
    PlantUML diagram
                    {
    			"id": "S0000201X",
    			"name": "customer fullname",
    			"role": "ServiceOwner",
    			"@baseType": null,
    			"@schemaLocation": null,
    			"@type": "Customer",
    			"@referredType": null,
    			"identificationType": "Passport",
    			"idenficationValue": "G0000201X"
    		}
    
    		{
    			"id": "19000000X",
    			"href": null,
    			"name": "Company registation name",
    			"role": "ServiceOwner",
    			"@baseType": null,
    			"@schemaLocation": null,
    			"@type": "Organization",
    			"@referredType": null,
    			"brn": "1000000X",
    			"organizationType": "NGO"
    		}​


    ------------------------------
    Chio Chuan Ooi
    SingTel Optus
    ------------------------------



  • 9.  RE: "role" in relatedParty

    TM Forum Member
    Posted May 13, 2020 08:50
    The issue was discussed in a recent Open API team and was approved for fixing. I quote:

    Governance Call:
    Agreed! Should be returned to:

    "engagedParty": { "$ref": "PartyRef.schema.json#PartyRef" }
    I cannot give a timescale for when the fix will be applied to the Party Role Management API, sorry.

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



  • 10.  RE: "role" in relatedParty

    TM Forum Member
    Posted 14 days ago
    Hi @Jonathan Goldberg,
    You mentioned above: "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."​
    Since RelatedParty itself is not an entity and nither party nor PartyRole has attribute "role" but, as you see in reference (RelatedPartyRef), it is additionally required.
    Should I create sub-classes of PartyRole for each role like Customer sub-class. Or add new field named "role" or "roleType" to the PartyRole entity.


    By the way, I see name and roleType fields in TMF669_Party_Role_Management API at "Mandatory and Non Mandatory Attributes" section. But, it is not included any where else; neither in swagger file nor in entity diagram.

    You said: "Additionally, it does seem that some description strings are missing in the schema, for example description for roleType."
    Missing part is not only description, believe me:)

    Need your help, thanks in advance :)


    ------------------------------
    Mustafa Yusufoglu
    i2i Systems
    ------------------------------