Business Partner Data Management (BPDM) Integration

matbmoser commented 2 months ago

[!CAUTION]

Will be included in this https://github.com/eclipse-tractusx/sig-release/issues/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 commented 2 months ago

I will start with this ticket right now

matbmoser commented 2 months ago

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

matbmoser commented 2 months ago

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 commented 2 months ago

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 commented 2 months ago

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 commented 2 months ago

for getting the name this key can be used:

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

matbmoser commented 2 months ago

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 commented 2 months ago

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 commented 2 months ago

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 commented 2 months ago

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 commented 2 months ago

@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 commented 2 months ago

@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 commented 2 months ago

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 commented 2 months ago

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 commented 1 month ago

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 commented 1 month ago

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

eclipse-tractusx / digital-product-pass