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.

[maximilianong]

1. Sharing member is sharing his own data, legal entities and also the sites

2. The new endpoint is just giving the information that this data was shared by an owner, not by which owner
   and its not showing the relationship between two companies that are maybe owned by the same owner.

I don’t want to make my hierarchy fully transparent; I only want to make the legal entities and sites visible. For now, it doesn’t matter who they belong to.

[HeyHardy]

Hello,
thanks for the helpful diagram. I've got some questions, maybe we can answer these with devs

• Is the red dashed line in the diagram representing a Relationship Object?
• Where does the mapping of Legal Entities occur in this context?
• For the second question, how can it be ensured, for example, that Volkswagen (VW) cannot arbitrarily assign itself to a Legal Entity belonging to Mercedes?

[Sebastian-Wurm]

Hello, thanks for the helpful diagram. I've got some questions, maybe we can answer these with devs

• Is the red dashed line in the diagram representing a Relationship Object?
• Where does the mapping of Legal Entities occur in this context?
• For the second question, how can it be ensured, for example, that Volkswagen (VW) cannot arbitrarily assign itself to a Legal Entity belonging to Mercedes?

I guess the last question is the most interesting one. So, I'm also interested in an answer.

I think that an explicit relationship in the internal data model of the BPDM Pool (not necessarily in the data model of the BPDM Pool API) better allows the operating company to detect and resolve error cases in the entity assignment, for example, if two legal entities claim the same legal entity (subsidiary). If the information, that a legal entity is a subsidiary of a Catena-X member shall not even be accessible by the operating company, the operating company cannot resolve such issues. Alternatively, such knowledge could also be stored decentrally as verifiable credentials in the wallets of the operating companies, which should then be accessible by the operating company for such checks.

Another question, that came to my mind, is regarding the usage of one EDC / the BPNL of the corporate group for signing data exchange contracts of the subsidiaries. First of all, it needs to be juristically clarified for all use cases, if this is possible. Second, the EDC must implement a way of signing data exchange contracts for subsidiaries. For the latter it is probably better, if the network explicitly "knows" the relationship between the subsidiary and the corporate group, whether centrally in the BPDM Pool or decentrally in wallets, remains to be seen...

[maximilianong]

Differentiation between "is shared by owner" and "managed by"

[Sebastian-Wurm]

We discussed this in the Expert Group and prefer the "managed by" solution as the set of business partners shared by the owner might be bigger than the set of "managed by" business partners, that actually shall participate in the data space.

[maximilianong]

Clarification on "Managed By"

The "Managed By" attribute, as I understand it, indicates that one company is managed by another within the portal's use cases. However, I feel we might be misusing this attribute. There could be companies that we don’t want to manage but still want to make visible in the pool via this endpoint.

The same concern applies to "IsOwnCompanyData".

I understand that some company data should not be visible in the pool, yet we still want to set "IsOwnCompanyData" to true. This suggests that both attributes serve distinct purposes.

Should we consider defining a new attribute/property to better address these cases?

Timeline:
'The managed by solution' needs at least the next PI.
At the moment its just available in the gate, not it pool.

[maximilianong]

Meeting: 17.02.2025

More specific requirements:

• I as a sharing member want to creating the sites under the correct legal entity
  Reason: Preventing that companies create wrong relationships

• I as a manager of a corporate group want to mark multiple legal entities that are not onboarded to the operator but participate in the data space

Possible way:
DataSpaceParticipant identification

WIP (more clarification needed):

I as a sharing member can define which of my 'IsOwnCompanyData' flagged data is data I want to share in the data space, to make this data available for other data space participants

I as a BPDM data manager can create other legal entities via the portal and flag this data that I want to share in the data space, to make this data available for other data space participants

[JulianStoll]

Meeting: 17.02.2025 decision:
We, the expert group BPDM, agreed that we need a long term solution for the requirements that Max mentioned.
In the long term it should be displayed via relations.
As a short term solution we think the members are responsible to only share data they want to share. These data records will be flagged with the "is Catena-X Member Data" flag.
This can be consumed via the members endpoint, that is already available. We do not need a new endpoint.
It is conform with CX-0012.
https://catenax-ev.github.io/docs/standards/CX-0012-BusinessPartnerDataPoolAPI

For non sharing members this data should be added by a portal UI.
Sharing Partners can either use their gate or the portal UI.

[nicoprow]

Alright, based on that decision there will be no new endpoint needed. Someone from the expert group should create a sig-release issue for the follow-up long-term plan. Then we can close this issue.