API Endpoint for Retrieving Legal Entity Data, incl. Sites and addresses of Onboarded Legal Entities to the data space and other legal entity data of that onboarded legal entity

[maximilianong]

As a user
I want to access LSA (Legal, Site, Address) data for legal entities that are related to those onboarded to the Catena-X data space,

So that I can retrieve comprehensive information for various use cases, even if not all subsidiaries onboard independently.

Description

There is already an endpoint for getting the data that is flagged with iscatenaxmember.
How do records get this flag? Legal entities get it when they onboard to the operator. Those legal entities and their BPNL are then part of the data space.

There will be other legal entities from the same company that will never onboard to the operator.

E.g. Company with Legal entity A from Germany onboarded to the operator and is a sharing member.
Legal entity B from China belongs to the same company but will never onboard because Legal entity A did it for the company.

The data from Legal entity B from the same company that onboard to the data space should be accessible / retrievable via a pool endpoint. And also the belonging site data.

How can we identify this data?
We are using the isowncompany data flag.
So sharing members that share their other legal entities and sites can flag the data,

API Enhancement:

A new or enhanced API endpoint must be provided that allows users to access LSA data from the pool.
The API should support the following filter:

Data where the owner filed is set.

Data Retrieval:

The API should return relevant legal entities from companies that onboarded to the data space and set the owner field.

The API should return for those legal entities also the site and address data.

Security & Access Control:

The API must adhere to existing access control and security policies to ensure that only authorized users can access the data.
Technical user with separate role and permissions should be available in Keycloak and visible in the portal

Dependencies:
Keycloak + Portal

[maximilianong]

• If a site will be defined as isowncompanydata the legal entity should be flagged automatically to isowncompany.
• Across the hierarchy you own everything or nothing (you cannot own an address without owing the legal entity)
• Redundant information in confidence criteria (needs to be aligned). Shared by owner and the conflicting is owning company.

[nicoprow]

@maximilianong scheduled this feature for the 25.03. release but we will provide a pull request soon

[StWeisshaar]

@maximilianong @nicoprow @SujitMBRDI @kunyao-cofinity-x @dilipdhankecha2530 Deciding attribute should be the sharedByOwner confidence criteria on the legal entity. All child entities to that legal entity will be visible using these endpoints. Subsidiaries must claimed by the owner to be visible.

[nicoprow]

Security & Access Control:

The API must adhere to existing access control and security policies to ensure that only authorized users can access the data. Technical user with separate role and permissions should be available in Keycloak and visible in the portal

Dependencies: Keycloak + Portal

@maximilianong @StWeisshaar

Actually this is a dependency to the Portal. We would need an issue there or better yet an overall sig-release issue for adapting it.

Also, what came to my mind right now:

Who are the authorized users? Are users who can see Cx member data also the same ones who can see Cx-member data and their subsidiaries? Or is this is a separate user group?

[Sebastian-Wurm]

@maximilianong @nicoprow: This seems to be a missing puzzle tile in our C-X NEXT hierarchy / "managed by" topic, as legal entities, where only the parent company has been onboarded, shall also be returned by the new API endpoint. However, it seems that conceptually this has not been thought through. There is not even a sig-release issue assigned. The correct sig-release issue is: eclipse-tractusx/sig-release#754. Please clarify the concept for the endpoint regarding data sovereignty & interoperability with the BPDM expert group before you start the implementation! (@stephanbcbauer, @JulianStoll, @HeyHardy @zygokaktus, etc.). Our current assumption is, that the BPDM Pool does not contain any hierarchy information whatsoever, yet, or at minimum does not provide such information to the network. Also, if we agree to go into that direction and we would need a separate asset for that, this must also be in line with the BPDM purposes of the Data Exchange Governance framework agreement. The legal groundwork for returning legal entity data from the BPDM Pool other than that of C-X members has not been discussed for the BPDM Pool purpose thoroughly (cx.bpdm.pool:1): "Identifying Participants within the CX Data Space for Data Consumer's internal counterparty identification and information processes and/or for VASs. As a purpose-specific requirement, the duration of (i) contract, (ii) data provision and (iii) usage right(s) as a default are all specified as 1 year." (see https://github.com/catenax-eV/cx-odrl-profile/blob/main/profile.ttl). Even if the purpose definition might be enough, as only subsidiaries of the onboarded parent company are considered here, we should also discuss this with the lawyers, that helped us with the framework agreement.

[Sebastian-Wurm]

• If a site will be defined as isowncompanydata the legal entity should be flagged automatically to isowncompany.
• Across the hierarchy you own everything or nothing (you cannot own an address without owing the legal entity)
• Redundant information in confidence criteria (needs to be aligned). Shared by owner and the conflicting is owning company.

I don't understand the first point. Actually it should be the other way round. You can only add a site, if the legal entity has been flagged with "is own company data". Also, "is own company data" is a concept of the Gate API, in the Pool API it is called "is Catena-X member data", where only those data are returned through the Pool asset.

[nicoprow]

@maximilianong @nicoprow: This seems to be a missing puzzle tile in our C-X NEXT hierarchy / "managed by" topic, as legal entities, where only the parent company has been onboarded, shall also be returned by the new API endpoint. However, it seems that conceptually this has not been thought through. There is not even a sig-release issue assigned. The correct sig-release issue is: eclipse-tractusx/sig-release#754. Please clarify the concept for the endpoint regarding data sovereignty & interoperability with the BPDM expert group before you start the implementation! (@stephanbcbauer, @JulianStoll, @HeyHardy @zygokaktus, etc.). Our current assumption is, that the BPDM Pool does not contain any hierarchy information whatsoever, yet, or at minimum does not provide such information to the network. Also, if we agree to go into that direction and we would need a separate asset for that, this must also be in line with the BPDM purposes of the Data Exchange Governance framework agreement. The legal groundwork for returning legal entity data from the BPDM Pool other than that of C-X members has not been discussed for the BPDM Pool purpose thoroughly (cx.bpdm.pool:1): "Identifying Participants within the CX Data Space for Data Consumer's internal counterparty identification and information processes and/or for VASs. As a purpose-specific requirement, the duration of (i) contract, (ii) data provision and (iii) usage right(s) as a default are all specified as 1 year." (see https://github.com/catenax-eV/cx-odrl-profile/blob/main/profile.ttl). Even if the purpose definition might be enough, as only subsidiaries of the onboarded parent company are considered here, we should also discuss this with the lawyers, that helped us with the framework agreement.

When it comes to the implementation of this requirement I believe it is not necessary to include hierarchy information in the Pool. Next to the isCatenaXMemberDataflag there is also a flag for isSharedByOwner in the confidence criteria of the legal entity. If a legal entity is shared by the owner, the owner must be a Catena-X member. This, in turn, means that the legal entity belongs to a Catena-X member. We do not know which member but that is irrelevant for the requirement, we are just interested in the set of business partners that belong to any Catena-X member. This would include Cx member data but also business partner data of legal entities that are owned by Cx members.

I can't speak to the legal topics and framework agreement purposes.

[nicoprow]

• If a site will be defined as isowncompanydata the legal entity should be flagged automatically to isowncompany.
• Across the hierarchy you own everything or nothing (you cannot own an address without owing the legal entity)
• Redundant information in confidence criteria (needs to be aligned). Shared by owner and the conflicting is owning company.

I don't understand the first point. Actually it should be the other way round. You can only add a site, if the legal entity has been flagged with "is own company data". Also, "is own company data" is a concept of the Gate API, in the Pool API it is called "is Catena-X member data", where only those data are returned through the Pool asset.

isOwnCompanyData should instead refer to the legal entity confidence criterion of isSharedByOwner which is available in the Pool. isOwnCompanyData in the Gate basically translates to that flag in the Pool

[nicoprow]

@maximilianong As I understand there is some clarifications needed before we can start development on this issue. I removed @SujitMBRDI and myself from this issue and attached you as an assignee to drive this topic to the refined state.