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.

2. After pasting the API Key, the green padlock will appear.

3. 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.

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:
   • Mapping
   • Upsert
2. Sharing is defined in scopes:
   • API
   • APP

Create a Mapping

{
  "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.

5. Click on the Send button.

{
    "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": []
                }
            ]
        ]
    }
}

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,

4. Click on the Send button.

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

Sharing scopes using API

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

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,

4. Click on the Send button.

{
    "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
    }
}

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.

2. Stay on the Collaboration tab and choose you want to disclose single Business Partner or in batch mode.

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,

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,

• Choose the data source,
• Click the Save changes button,

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

3. Click on the Send button.
4. Use the List Links endpoint,
5. Fill the required parameters:

• storageId - required
• dataSourceId - optional
• referenceDataSource - CDQ.POOL - optional

3. Click on the Send button.

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

2. 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

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.

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