Business Partner Data Management (BPDM) Integration

[matbmoser]

Caution

Will be included in this eclipse-tractusx/sig-release#654 feature of the Generic UI since its not possible to be tested for the release v24.05.

Description

Integrate the digital product pass application with the BPDM service. The functionality is the following:

• The backend retrieves information based on a BPNL and retrieves the company information.
• The backend retrieves information based on a BPNS and retrieves the address information
• The frontend then will show this information in the UI.

Acceptance Criteria

• Retrieve from BPDM a company information (name, address and contact information) based on a BPN
• Show company information (name, address and contact information) based on a BPN
• Have API that frontend can retrieve the data with a BPNL

Additional Information

BPDM Respoitory: https://github.com/eclipse-tractusx/bpdm

[matbmoser]

I will start with this ticket right now

[matbmoser]

I started to work in this branch: https://github.com/eclipse-tractusx/digital-product-pass/tree/feature/bpdm-integration

[matbmoser]

[matbmoser]

Example how sites can be found:

Response to be parsed:

[
    {
        "site": "BPNS000000000001",
        "mainAddress": {
            "version": {
                "characterSet": {
                    "technicalKey": "UNDEFINED",
                    "name": "Undefined"
                },
                "language": {
                    "technicalKey": "undefined",
                    "name": "Undefined"
                }
            },
            "careOf": null,
            "contexts": [],
            "country": {
                "technicalKey": "TH",
                "name": "Thailand"
            },
            "administrativeAreas": [],
            "postCodes": [
                {
                    "value": "83000",
                    "type": {
                        "technicalKey": "OTHER",
                        "name": "Other type",
                        "url": ""
                    }
                }
            ],
            "localities": [
                {
                    "value": "Muang Phuket",
                    "shortName": "Muang Phuket",
                    "type": {
                        "technicalKey": "CITY",
                        "name": "City",
                        "url": ""
                    },
                    "language": {
                        "technicalKey": "undefined",
                        "name": "Undefined"
                    }
                }
            ],
            "thoroughfares": [
                {
                    "value": "Ratsada 27",
                    "name": null,
                    "shortName": null,
                    "number": "27",
                    "direction": null,
                    "type": {
                        "technicalKey": "STREET",
                        "name": "Street",
                        "url": ""
                    },
                    "language": {
                        "technicalKey": "undefined",
                        "name": "Undefined"
                    }
                }
            ],
            "premises": [],
            "postalDeliveryPoints": [],
            "geographicCoordinates": null,
            "types": []
        }
    }
]

country: mainAddress.country.name
street: mainAddress.thoroughfares[type.technicalKey=="STREET"].value city: mainAddress.localities[type.technicalKey=="CITY"].value
postalCode: mainAddress.postCodes[type.technicalKey=="REGULAR"||type.technicalKey=="OTHER"].value

[matbmoser]

API to be used: {{Pool-Host}}/api/catena/legal-entities/legal-addresses/search

[
    {
        "legalEntity": "BPNL00000006M6CI",
        "legalAddress": {
            "version": {
                "characterSet": {
                    "technicalKey": "WESTERN_LATIN_STANDARD",
                    "name": "Western Latin Standard (ISO 8859-1; Latin-1)"
                },
                "language": {
                    "technicalKey": "de",
                    "name": "German"
                }
            },
            "careOf": null,
            "contexts": [],
            "country": {
                "technicalKey": "DE",
                "name": "Germany"
            },
            "administrativeAreas": [],
            "postCodes": [
                {
                    "value": "89075",
                    "type": {
                        "technicalKey": "REGULAR",
                        "name": "Regular",
                        "url": ""
                    }
                }
            ],
            "localities": [
                {
                    "value": "Ulm",
                    "shortName": null,
                    "type": {
                        "technicalKey": "CITY",
                        "name": "City",
                        "url": ""
                    },
                    "language": {
                        "technicalKey": "de",
                        "name": "German"
                    }
                }
            ],
            "thoroughfares": [
                {
                    "value": "Beim Alten Fritz 2",
                    "name": null,
                    "shortName": null,
                    "number": null,
                    "direction": null,
                    "type": {
                        "technicalKey": "STREET",
                        "name": "Street",
                        "url": ""
                    },
                    "language": {
                        "technicalKey": "de",
                        "name": "German"
                    }
                }
            ],
            "premises": [],
            "postalDeliveryPoints": [],
            "geographicCoordinates": null,
            "types": []
        }
    }
]

[matbmoser]

This API can be used to take the company name: {{Pool-Host}}/api/catena/legal-entities/BPNL000000000001

{
    "bpn": "BPNL000000000001",
    "identifiers": [
        {
            "value": "test",
            "type": {
                "technicalKey": "CX_POOL_ID",
                "name": "",
                "url": null
            },
            "issuingBody": null,
            "status": null
        },
        {
            "value": "test",
            "type": {
                "technicalKey": "EU_VAT_ID_DE",
                "name": "Umsatzsteuer-Identifikationsnummer",
                "url": "https://meta.cdq.com/European_value_added_tax_identifier_(Germany)"
            },
            "issuingBody": null,
            "status": null
        }
    ],
    "names": [
        {
            "value": "Company-X Inc.",
            "shortName": null,
            "type": {
                "technicalKey": "LOCAL",
                "name": "The business partner name identifies a business partner in a given context, e.g. a country or region.",
                "url": ""
            },
            "language": {
                "technicalKey": "undefined",
                "name": "Undefined"
            }
        }
    ],
    "legalForm": null,
    "status": null,
    "profileClassifications": [],
    "types": [],
    "bankAccounts": [],
    "roles": [],
    "relations": [],
    "currentness": "2022-06-03T11:46:03.029158Z"
}

[matbmoser]

for getting the name this key can be used:

name; names[type.technicalKey=="LOCAL"|| first element].value

[matbmoser]

So the response from the API request:

{backend-url}/api/bpn/request

{
  "legalEntities": [ 
   "BPNL000000000001"
  ],
  "site": [
       "BPNS000000000001"
    ] 
}

will be:

{
  "status": 200,
  "data": {
     "legalEntities": {
       "BPNL000000000001": {
             "name": "Company-X Inc.",
             "country": "Germany",
             "city": "Ulm",
             "street": "Beim Alten Fritz 2",
             "postalCode": 89075
        }
     },
    "sites":  {
        "BPNS000000000001": {
             "country": "Germany",
             "city": "Ulm",
             "street": "Beim Alten Fritz 2",
             "postalCode": 89075
        }
  }
}

It depends from the information that will be avaialble

[matbmoser]

Ok what have I done:

• Created BPDM Service class to communicate with the BPDM App instance.
• Created all the necessary configuration to find:
  • Which API is needed for each BPN Type
  • Which Technical Key shall be used to search
  • Which Path to the data is required
• Created all the necessary logic to parse a list of different (BPNL, BPNS and BPNA)
• Created logic to get company information from a list BPNL
• Created logic to parse the content and data based on the configuration

In this way we stay generic and if the service is changing in the future the maintenance will be really low.

[matbmoser]

This ticket is flagged 🚩... I am having a 403 from the new service and am not able to access the information.
Already contacted with @leonschand to get also some guidance which APIs need to be called and where can I get the information having a BPNL and BPNS.

Information needed:

• Name + Contact Information
• Address ( Street, City, Postal Code and Country)

I saw that also the BPDM will be accessed using the EDC, and I also wonder in the future how can I get the BPDM EDC URL? How the contracts will look like and which policies we need to accept...

[matbmoser]

What I will do is to finish the service and create the response flow so that when its ready and I know which apis to call I can do so.

[nicoprow]

@matbmoser
Please consider the BPDM Pool with the new version now only offers a restricted view on the business partner data. Namely, Catena-X members now are only allowed to view business partner data that belongs to Catena-X members.

This means the general endpoints for legal entities, sites and addresses require higher privileges than before. For your case, you would need to integrate the new endpoints: members/legal-entities, members/sites and so on. Your token would need to have the permission "read_partner_member" in the resource "Cl7-CX-BPDM".

If this permission is not in your current token, you would need to get in touch with the Portal team for support.

[matbmoser]

@matbmoser Please consider the BPDM Pool with the new version now only offers a restricted view on the business partner data. Namely, Catena-X members now are only allowed to view business partner data that belongs to Catena-X members.

This means the general endpoints for legal entities, sites and addresses require higher privileges than before. For your case, you would need to integrate the new endpoints: members/legal-entities, members/sites and so on. Your token would need to have the permission "read_partner_member" in the resource "Cl7-CX-BPDM".

If this permission is not in your current token, you would need to get in touch with the Portal team for support.

Wonderful thank you very much!

[matbmoser]

Status updated note here:

I have configured and finished to program the service that would connect to the pool (without the EDC part) since we are still not able to access it. We could be able then to do this later.

  bpdm:
    enabled: true
    endpoint: "https://partners-pool.int.demo.catena-x.net"
    companyInfo:
      apiPath: "api/catena/legal-entities"
      bpnKey: "bpn"
      name:
        path: "names"
        technicalKeys: # -- or operator active (just one will be retrieved)
          - "LOCAL"
    site:
      apiPath: "/api/catena/sites/main-addresses/search"
      bpnKey: "site"
      countryPath: "country.name"
      postalCode:
        path: "mainAddress.postalCodes"
        technicalKeys: # -- or operator active (just one will be retrieved)
          - "OTHER"
      city:
        path: "mainAddress.localities"
        technicalKeys: # -- or operator active (just one will be retrieved)
          - "CITY"
      street:
        path: "mainAddress.thoroughfares"
        technicalKeys: # -- or operator active (just one will be retrieved)
          - "STREET"
    legalEntity:
      apiPath: "/api/catena/legal-entities/legal-addresses/search"
      bpnKey: "legalEntity"
      countryPath: "legalAddress.country.name"
      postalCode:
        path: "legalAddress.postalCodes"
        technicalKeys: # -- or operator active (just one will be retrieved)
          - "REGULAR"
      city:
        path: "legalAddress.localities"
        technicalKeys: # -- or operator active (just one will be retrieved)
          - "CITY"
      street:
        path: "legalAddress.thoroughfares"
        technicalKeys: # -- or operator active (just one will be retrieved)
          - "STREET"
    address:
      apiPath: "api/catena/addresses"
      bpnKey: "address.bpn"
      countryPath: "address.country.name"
      postalCode:
        path: "address.postalCodes"
        technicalKeys: # -- or operator active (just one will be retrieved)
          - "REGULAR"
      city:
        path: "address.localities"
        technicalKeys: # -- or operator active (just one will be retrieved)
          - "CITY"
      street:
        path: "address.thoroughfares"
        technicalKeys: # -- or operator active (just one will be retrieved)
          - "STREET"
          

The API available is /api/bpn/request

The request is variable but the keys that can be used are:

{
  "legalEntity": [ "BPNL0000000000001" ],
  "site:" : [ "BPNS000000000002" ],
  "address": [ "BPNA0000000003" ]
} 

the response is the following:

{
  "legalEntity": { 
      "BPNL000000000001": {
              "company": {
                   "name": "Company-X Inc.",
              }
              "address":  {
                   "country": "Germany",
                   "city": "Ulm",
                   "street": "Austussuperstrasse 42",
                   "postalCode": "4513213",
              }
      }
   },
  "site" : {
          "BPNS000000000002": {
                   "country": "Spain",
                   "city": "Madrid",
                   "street": "Calle Serrano 3",
                   "postalCode": "494213",
              }
  },
  "address": {
          "BPNA000000000003": {
                   "country": "India",
                   "city": "Mumbai",
                   "street": "201, Alankar Indl Estate, Off Aarey Rd, Maheshwari Nagar",
                   "postalCode": "400063-HA",
           }
  }
} 

[matbmoser]

Since latest functionality is not working, I can not integrate it for this release, postponed for the next one and gets included in the Generic UI feature (which needs to display business partner data).

[matbmoser]

This functionality will not be done at all because:

• Currently since bpdm is behind the edc and no guideline is provided on how to retrieve the information
• Can not be tested

[matbmoser]

If someone wants to continue to work on this in the future they can use this branch: https://github.com/eclipse-tractusx/digital-product-pass/tree/feature/bpdm-integration