Generic Business Partner Datamodel

[nicoprow]

Proposal for a generic business partner model that can be used when the actual business partner type is unknown at creation time:

---
title: Generic Business Partner
---
classDiagram
    class Business_Partner{
        External ID
        Name Parts
        Short Name
        Legal Name
        Identifiers
        Legal Form
        States
        Classifications
        Roles
        Address
        Is Own Company Data
        Address BPN
        Legal Entity BPN
        Site BPN
    }
    class Identifier{
        Value
        Type
        Issuing Body
    }
    class State{
        Description
        Valid From
        Valid To
        Type
    }
    class Classification{
        Value
        Code
        Type
    }
    class Address{
        Physical Postal Address
        Alternative Postal Address
    }

    class PhysicalPostalAddress{
        Geo-Coordinates
        Country
        Admin Level 1
        Admin Level 2
        Admin Level 3
        City
        District
        Postal Code
        Company Postal Code 
        Industrial Zone
        Street Name
        Street Name Prefix
        Street Name Additional Prefix
        Street Name Suffix
        Street House Number
        Street Direction
        Street Milestone
        Building
        Floor
        Door
    }
    class AlternativePostalAddress{
        Geo-Coordinates
        Country
        Admin Level 1
        Delivery Service Number
        Delivery Service Type
        Delivery Service Qualifier
        City
        Postal Code
    }

 class AddressType{
   <<enumeration>>
    LegalAndSiteMainAddress
    LegalAddress
    SiteMainAddress
    AdditionalAddress

 }
    Business_Partner --> Identifier: Has Several
    Business_Partner --> State: Has Several
    Business_Partner --> Classification: Has Several
    Business_Partner --> Address: Can Have One
    Address --> AddressType: Can Have One
    Address --> PhysicalPostalAddress: Can Have One
    Address --> AlternativePostalAddress: Can Have One

Loading

Related Issues to fulfill this epic:

• Gate API: Create Input Endpoints for Generic Business Partner #384
• Gate API: Create Output Endpoint for Generic Business Partner #387
• Gate: Persist Generic Business Partner Input #428
• Gate: Connect Sharing State with One-to-One Relation to Generic Business Partners #439
• Gate: Replace LSA Typed Service Logic with Generic Service Logic #440
• Gate: Map from LSA DTOs to Generic Business Partner DTO #441
• Define ordering for generic business partner model relations #442
• Gate: Implement service logic for generic business partner #456
• Gate: Only External-ID in Generic Business Partner Input is required  #476
• Gate: Base Changelog Type on AddressType #490
• Gate: Add parent references for Generic Business Partner #489
• Doc: Update Postman Collection for Generic Endpoint #471
• Gate: Add business partner type 'Generic' to Changelog and Sharing State  #519
• Gate: Add LegalName Field for Generic Business Partner #557
• API: Rename BPN Fields #594

[Sebastian-Wurm]

A proposal for the visualization of the data model for the generic business partners, which is more comprehensive and structured like the actual OpenAPI datamodel (also of the legal entity, site and address controllers).

Note that cardinalities always refer to the entity state as required output of the sharing process. In general, cardinalities of relations and attributes are not to be enforced while uploading business partners, except for the external ID.

[Sebastian-Wurm]

@nicoprow : What would be the next steps towards implementation?

[nicoprow]

Decision: We replace the flags "legalAddress" and "siteMainAddress" inside PostalAddress with an enum field "AddressType" having values:

1. LegalAndSiteMainAddress
2. LegalAddress
3. SiteMainAddress
4. AdditionalAddress

The enum field is required in the Output version and optional in the Input version.

[Rossisep]

Dear colleagues,

Where do I find in the Generic Endpoint the LegalForm Abbreviation?
Are the GEO coordinates an alphanumeric string?

Best regards

Stephan

[nicoprow]

Dear colleagues,

Where do I find in the Generic Endpoint the LegalForm Abbreviation? Are the GEO coordinates an alphanumeric string?

Best regards

Stephan

Hi @Rossisep ,

the field "Legalform" field in the generic business partner model contains the String description of the business partner's legal Form. When the sharing member specifies in the business partner in the input they can give any String description of the legal form. For the cleaning process the service provider will try to identify the legal form and replace it with the correct technical key for the legal form from the Catena network. So the output will have the legal form technical key stored in that field.

Address information of the generic business partner will stay the same as with L/S/A typed business partners. The Geo-Coordinates are a complex object. You can refer to the Pool's OpenAPi specification or alternatively already have look into the proposed OpenApi definitions of the generic endpoints.

[Korbinian-Hutter]

@nicoprow @Sebastian-Wurm we would like to change the name from "IsOwner" to "IsOwnCompanyData" to better represent the Fields meaning.

[Sebastian-Wurm]

@Korbinian-Hutter: It makes sense to make it more specific. I actually came up with the name "SharingMemberIsOwner", when I tried to find a definition for the property: "Indicates whether the sharing member is the owner of the site." What do you think about that? It would incorporate the original idea of "IsOwner", but with slightly more information.
"IsOwnCompanyData" would also be fine for me; description would be: "Indicates whether the site belongs to the company data of the sharing member."

[Korbinian-Hutter]

@Sebastian-Wurm ja passt für mich

[Sebastian-Wurm]

@Sebastian-Wurm ja passt für mich

Which alternative of it?

[Korbinian-Hutter]

@Sebastian-Wurm I meant the first: "SharingMemberIsOwner"

[enzio-bot]

@Sebastian-Wurm I meant the first: "SharingMemberIsOwner"

For record and clarity, the members of the Regeltermin Datenmodell with a quorum, have settled on 'IsOwnCompanyData'.

[nicoprow]

I would like to propose to rename the BPNL and BPNS fields to "Parent BPNL" and "Parent BPNS" as this makes the nature of the generic business partner more obvious: It contains an address that will be mapped 1 to 1 with a golden record address partner having a BPNA. It also belongs to a legal entity and it may also belong to a site but while it may be a legal address or a main site address it is actually not a legal entity or a site itself.

@gerlitmcoding
@Sebastian-Wurm

[Sebastian-Wurm]

I would like to propose to rename the BPNL and BPNS fields to "Parent BPNL" and "Parent BPNS" as this makes the nature of the generic business partner more obvious: It contains an address that will be mapped 1 to 1 with a golden record address partner having a BPNA. It also belongs to a legal entity and it may also belong to a site but while it may be a legal address or a main site address it is actually not a legal entity or a site itself.

@gerlitmcoding @Sebastian-Wurm

I agree, that the business partner IS not a legal entity or a site. I am unsure, whether the business partner really IS an address. I see the business partner in Catena-X more as a merged view of the three L/S/A entities.

[Rossisep]

Isn't it true that a BPNA represents another physical location of a Legal Entity and/or a Site. So a BPNA is a child of either/and a Parent BPNL and a Parent BPNS. So if we define Parents we should also define Childs. The substance of a Business Partner is based on his role(s).

[kunyao-cofinity-x]

Hi Nico, I have created a data migration script for the legal entity, could you please help me review it in case something is missing to migrate? @nicoprow

/postal address/

Insert into bpdmgate.postal_addresses(
	id, created_at, updated_at, uuid, address_type, 
	phy_latitude, phy_longitude, phy_altitude, 
	phy_country, 
	phy_admin_area_l1_region, phy_admin_area_l2, phy_admin_area_l3, 
	phy_postcode, 
	phy_city,
	phy_district_l1, 
	phy_street_name, 
	phy_street_number, 
	phy_street_milestone,
	phy_street_direction, 
	phy_name_prefix, phy_additional_name_prefix, phy_name_suffix, phy_additional_name_suffix, 
	phy_company_postcode, phy_industrial_zone, 
	phy_building, phy_floor, phy_door, 
	alt_latitude, alt_longitude, alt_altitude, 
	alt_country,
	alt_admin_area_l1_region, 
	alt_postcode, alt_city, 
	alt_delivery_service_type, alt_delivery_service_qualifier, alt_delivery_service_number
)select 
	id, created_at, updated_at, uuid, 'LegalAddress',
	phy_latitude, phy_longitude, phy_altitude,
	phy_country,
	phy_admin_area_l1_region, phy_admin_area_l2, phy_admin_area_l3,
	phy_postcode, 
	phy_city, 
	phy_district_l1,
	phy_street_name,
	phy_street_number,
	phy_street_milestone,
	phy_street_direction,
	phy_name_prefix, phy_additional_name_prefix, phy_name_suffix, phy_additional_name_suffix,
	phy_company_postcode, phy_industrial_zone,
	phy_building, phy_floor, phy_door,
	alt_altitude, alt_latitude, alt_longitude,
	alt_country, 
	alt_admin_area_l1_region,
	alt_postcode, alt_city,
	alt_delivery_service_type, alt_delivery_service_qualifier, alt_delivery_service_number
	from bpdmgate.logistic_addresses;

/legal entities/

INSERT INTO 
bpdmgate.business_partners (
	id,
	created_at, 
	updated_at, 
	uuid, 
	external_id, 
	short_name,
	legal_form,
	is_own_company_data,
	bpna,
	bpnl,
	bpns,
	postal_address_id,
	stage,
	parent_id,
	parent_type)
	Select
	a.id,
	a.created_at, 
	a.updated_at, 
	a.uuid, 
	a.external_id, 
	a.name_shortname,
	a.legal_form_id,
	true,
	b.bpn as "A",
	a.bpn as "L",
	null,
	a.legal_address_id,
	a.data_type,
	null,
	null
	from bpdmgate.legal_entities a
	left join bpdmgate.logistic_addresses b
	on a.legal_address_id = b.id ;

/classifications to business_partners_classifications/

INSERT into bpdmgate.business_partners_classifications(
	value, code, type, business_partner_id)
	Select 
	value, code, type, legal_entity_id
	From bpdmgate.classifications;

/legal_entities to business_partners_identifiers/

INSERT INTO bpdmgate.business_partners_identifiers(
	value, type, issuing_body, business_partner_id)
	SELECT 
	value, type_id, issuing_body, legal_entity_id 
	FROM bpdmgate.legal_entity_identifiers;

/name_parts to business_partners_name_parts/

INSERT INTO bpdmgate.business_partners_name_parts(
	name_parts_order, name_parts, business_partner_id)
	SELECT 
	0, name_part, 
	legal_entity_id
	FROM bpdmgate.name_parts 
	Where legal_entity_id is not null;

/roles to business_partners_roles/

INSERT INTO bpdmgate.business_partners_roles(
	role_name, business_partner_id)
	SELECT
	role_name, legal_entity_id
	FROM bpdmgate.roles
	Where legal_entity_id is not null;

/legal_entity_states to business_partners_states/

INSERT INTO bpdmgate.business_partners_states(
	description, valid_from, valid_to, type, business_partner_id)
	SELECT description, valid_from, valid_to, type, legal_entity_id
	FROM bpdmgate.legal_entity_states;

`

[nicoprow]

The generic business partner data model used in the Gate and the Golden Record process has been implemented. Changes and adjustments will be dealt with in follow-up issues as necessary.