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:
- To share Business Partners using the API or APP,
- To check subscriptions,
- To understand the linkage process,
- To get updates from the POOL.
Prerequisites
Authorization
Before trying CDQ APIs, user must be authenticated:
- Paste the API Key in the console's security bar into the
X-API-KEY
field.

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

Be careful
Green padlock doesn't mean that the API Key was pasted correctly.
- Check your API key for missing characters or extra space before trying.
No API Key?
- Check how to get one on authentication page.
- 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:
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 addbusinessPartner.disclosed
in the
businessPartnerAttributeMappings
section of the inputMapping
.{
"inputMapping": {
"businessPartnerAttributeMappings": [
{
"sourceConstant": "TRUE",
"targetAttributes": [
"businessPartner.disclosed"
]
}
]
}
}
To create a mapping, follow these steps:
- Go to the Data Mirror Management App,
- Scroll down to the Mappings section and click the Download Mapping Example button,
- Open the downloaded file and add the
businessPartner.disclosed
attribute to theinputMapping
section, - Use the Create Data Mapper Definition endpoint,
- If you have no Mapping to be pasted use the Disclosed Business Partner example.
- Click on the Send button.
info
To check the Disclosed Business Partner response example, exapnd the Response section below.
Response
The response will contain the ID of the created mapping andbusinessPartner.disclosed
in the inputMapping
section.{
"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:
- Use the Upsert Business Partner endpoint,
- Select the Disclose Business Partners by Upsert example,
- 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,
- Click on the Send button.
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.
{
"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:
- Use the Create Sharing Scopes endpoint,
- Select the Create Sharing Scope Template example,
- 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,
- Click on the Send button.
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:
{
"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:
- Go to the Collaboration & Subscription Configuration in CDQ Cloud Apps.

- Stay on the Collaboration tab and choose you want to disclose single Business Partner or in batch mode.
attention
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,

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,

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:
- Use the List Links endpoint,
- Fill the required parameters:
storageId
- requireddataSourceId
- optionalreferenceDataSource
-CDQ.POOL
- optional
- Click on the Send button.
- Use the List Links endpoint,
- Fill the required parameters:
storageId
- requireddataSourceId
- optionalreferenceDataSource
-CDQ.POOL
- optional
- Click on the Send button.
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:
- 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
- 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
- lookup BPs in the POOL with linkage matching configuration
maybe match
status, the Collaboration Self-Review APP provides a list of candidates for each Business Partner that can potentially be matched.Pending decision | Description |
---|---|
No link | If 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. |
Link | We 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 Update | We 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 chooseCDQ.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