Tutorial: How to share Business Partner into CDQ.POOL?

Overview

Use case

This tutorial explains how to share business partners and receive updates from CDQ.POOL.

Scenario

In this tutorial, you will learn how:

  1. To share Business Partners using the API or APP,
  2. To check subscriptions,
  3. To understand the linkage process,
  4. To get updates from the POOL.

Prerequisites

Authorization

Before trying CDQ APIs, user must be authenticated:

  1. Paste the API Key in the console's security bar into the X-API-KEY field.
auth7
  1. After pasting the API Key, the green padlock will appear.
auth8
Be careful

Green padlock doesn't mean that the API Key was pasted correctly.

  1. Check your API key for missing characters or extra space before trying.

No API Key?

  1. Check how to get one on authentication page.
  2. Follow the steps above.

Data Mirror

It is required that there is a data mirror available.

info

Get more information about Data Mirror Setup and Synchronization here.

Step 1: Share Business Partners

There are a few options for how to share Business Partners. Select the one that fits your needs best:

  1. Sharing is defined by:
  2. Sharing is defined in scopes:
attention

It is not possible to use two options simultaneously; therefore, if you start using sharing scopes, you should not define the disclosing option in the mapping.

Create a Mapping

To ensure that all your business partners' details are shared, you only need to add businessPartner.disclosed in the businessPartnerAttributeMappings section of the inputMapping.
Copy
Copied
{
  "inputMapping": {
    "businessPartnerAttributeMappings": [
      {
        "sourceConstant": "TRUE",
        "targetAttributes": [
          "businessPartner.disclosed"
        ]
      }
    ]
  }
}

To create a mapping, follow these steps:

  1. Go to the Data Mirror Management App,
  2. Scroll down to the Mappings section and click the Download Mapping Example button,
  3. Open the downloaded file and add the businessPartner.disclosed attribute to the inputMapping section,
  4. Use the Create Data Mapper Definition endpoint,
  • If you have no Mapping to be pasted use the Disclosed Business Partner example.
  1. Click on the Send button.
Loading...
info

To check the Disclosed Business Partner response example, exapnd the Response section below.

ResponseThe response will contain the ID of the created mapping and businessPartner.disclosed in the inputMapping section.
Copy
Copied
{
    "id": "67b847c82ea0f17b3d465214",
    "createdAt": "2025-02-21T09:30:48.022009512Z",
    "createdBy": "89bc654e-10dc-444a-8ae7-92ff1d50f511",
    "lastUpdatedAt": "2025-02-21T09:30:48.022009512Z",
    "modifiedAt": "2025-02-21T09:30:48.022009512Z",
    "modifiedBy": "89bc654e-10dc-444a-8ae7-92ff1d50f511",
    "creatorUsername": "89bc654e-10dc-444a-8ae7-92ff1d50f511",
    "creatorOrganization": "sap_bn",
    "shareWithOrganization": true,
    "name": "Test disclose mapping",
    "inputMapping": {
        "businessPartnerAttributeMappings": [
            {
                "sourceAttributes": [
                    "Name"
                ],
                "targetAttributes": [
                    "businessPartner.names[0].value"
                ],
                "targetAttributeTypes": [
                    "BUSINESS_PARTNER_NAME_TYPE_LOCAL"
                ]
            },
            {
                "sourceConstant": "True",
                "targetAttributes": [
                    "businessPartner.disclosed"
                ]
            }
        ],
        "addressesAttributeMappings": [
            [
        {
                    "sourceAttributes": [
                        "country"
                    ],
                    "targetAttributes": [
                        "address.country.shortName"
                    ],
                    "targetAttributeTypes": []
                }
            ]
        ]
    }
}
info

Full documentation of the Create Data Mapper Definition endpoint can be found here.

Upsert

Business Partners can be also disclosed by upserting. In this case, we need to declare it providing for each BP: "disclosed": "true", as in the CRUL below:

To upsert, follow these steps:

  1. Use the Upsert Business Partner endpoint,
  2. Select the Disclose Business Partners by Upsert example,
  3. Fill the required fields:
  • YOUR_DATASOURCE_ID - the datasource's ID for sharing Business Partners,
  • YOUR_EXTERNAL_ID - the external ID of the Business Partner,
  • Fullfil the record object with the Business Partner's details,
  1. Click on the Send button.
Loading...
info

To check the upsert report response, exapnd the Response section below.

Response

The response will contain the number of accepted, inserted, updated, and failed Business Partners.

Copy
Copied
{
    "numberOfAccepted": 1,
    "numberOfInserts": 1,
    "numberOfUpdates": 0,
    "numberOfFailed": 0,
    "failures": [],
    "featuresOn": [
        "ENABLE_ASYNC",
        "ENABLE_SETTINGS",
        "NOTIFY_LINKED_BUSINESS_PARTNERS",
        "UPSERT_BY_EXTERNAL_ID",
        "VALIDATE_RELATIONS"
    ]
}
info

Full documentation of the Upsert Business Partners endpoint can be found here.

Sharing scopes using API

You can declare which BPs should be shared is providing it in the sharing scopes using the API.

attention

Only batch mode.

To share the country scope, follow these steps:

  1. Use the Create Sharing Scopes endpoint,
  2. Select the Create Sharing Scope Template example,
  3. Fill the required fields:
  • YOUR_DESCRIPTION - the description of the sharing scope,
  • YOUR_DATASOURCE_ID - the datasource's ID for sharing Business Partners,
  • COUNTRY_CODE - the country code of Business Partners to be shared,
  1. Click on the Send button.
Loading...
info

To check the example Response in the section below.

Response

The response will contain the ID of the created sharing scope and job status.

Example response:

Copy
Copied
{
    "id": "67b854403921d75289365915",
    "description": "Share customers from Switzerland.",
    "dataSources": [
        {
            "id": "67b8541f0f8d900a2ce3ee1a",
            "name": "test sharing"
        }
    ],
    "countries": [
        {
            "shortName": "CH"
        }
    ],
    "applyingJob": {
        "id": "e8c0aafd-7cbd-405e-82a4-1921c402d57d",
        "status": "SCHEDULED",
        "progress": 0
    }
}
info

Full documentation of the Upsert Business Partners endpoint can be found here.

Sharing scopes using APP

To disclose Business Partners using the APP, follow these steps:

  1. Go to the Collaboration & Subscription Configuration in CDQ Cloud Apps.
share pool img001
  1. Stay on the Collaboration tab and choose you want to disclose single Business Partner or in batch mode.
attention
If sharing is enabled for a Business Partner you will see No in private column.

Single Business Partner disclosure

The application allows you to select a specific Business Partner and change the disclosure option.

To change disclosement status for a single Business Partner follow these steps:

  • Check if Yes is set in the Private column,
  • Sellect Business Partner from the list,
  • Click on the Disclosed sellected button,
share pool img002

Batch mode - Sharing scopes

In the batch mode, it's possible to share Business Partners in bulk. In the below case we will share all Business Partners from the selected data source.

To disclose all Business Partners in selected data source:

  • Click the Disclosure Management button,
share pool img003
  • Choose the data source,
  • Click the Save changes button,
share pool img004
attention

If needed you can specify the country scope for sharing Business Partners.

Step 2 Check subscriptions

Once sharing is enabled, Business Partners are put into the linkage process, which checks if they have the required identifier to be linked with the Business Partner from the POOL. The list of Business Partners linked can be checked by subscription endpoint or by generating a report.

To check subscriptions:

  1. Use the List Links endpoint,
  2. Fill the required parameters:
  • storageId - required
  • dataSourceId - optional
  • referenceDataSource - CDQ.POOL - optional
  1. Click on the Send button.
  2. Use the List Links endpoint,
  3. Fill the required parameters:
  • storageId - required
  • dataSourceId - optional
  • referenceDataSource - CDQ.POOL - optional
  1. Click on the Send button.
Loading...
For Business Partners that don't have linkage created due to a lack of required identifier or an incorrect identifier, it's worth creating an augmentation monitor with a curation profile: GOLDEN_RECORD and updating Business Partners with new, better data.
info

Full documentation of the Upsert Business Partners endpoint can be found here.

Step 3 Understanding the linkage process.

The linkage process is used to link Business Partners from different sources. The linkage process is based on the linkage strategy, a set of rules defining how the linkage process should be executed.

The linkage process is executed in the following steps:

  1. Check if BP is shareable:
  • Shared BPs (disclosed = true) are check if we have a linkage strategy for the country of BP
  • Check if BP has the required identifier (depends on linkage strategy)
  • Check if the BP is a Natural Person
  • Quality gate
    • check if the linkage identifier has a warning or error
    • check if BP has any warnings or errors
  1. Try to add BP to the POOL
  • check if BP has already linkage - if yes update BP in the POOL
  • no linkage
    • lookup BPs in the POOL with linkage matching configuration
      • no BPs = create a new record in the POOL (SHARED_WITH_NO_MATCH)
      • BP found in the POOL has a matching score over the full match threshold = BP is linked and updated in the POOL (SHARED_WITH_CONFIDENT_MATCH)
      • BP/BPs found in the POOL have matching under the maybe match threshold
In case we are unable to link a Business Partner, due to maybe match status, the Collaboration Self-Review APP provides a list of candidates for each Business Partner that can potentially be matched.
Pending decisionDescription
No linkIf we can't link the Business Partner because it could be added to the Collaboration Self-Review APP, a list of potential candidates will be provided for each Business Partner.
LinkWe are confident that the candidate is the same Business Partner, but our business partner has lower quality data, so we will link Business Partners without providing an update.
Link and UpdateWe are confident that the candidate is the same, but the mirror Business Partner has superior data quality. We will link both business partners and update POOL with the mirror's data.

Step 4 Get updates from the POOL

Your Business Partners need to be shared to get updates from the POOL. Thanks to that, the linkage is created, and it's possible to get updates each time one of the other sharing members, having linked the same BPs, makes any changes.

The following steps are in the CDQ Partner Guard - How to monitor Business Partner Updates via API? tutorial. Remember to choose CDQ.POOL for augmentation configuration and provide CDQ_POOL as a Provenance/Referece Data Source for reading updates.

Your opinion matters!

We are constantly working on providing an outstanding user experience with our products. Please share your opinion about this tutorial!

Mail our developer-portal team: developer-portal@cdq.com