# 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](https://meta.cdq.com/Feature/CDQ_Community_Data_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.


![](/assets/auth7.0d4fb05fa55bc16d828c76e9976f979930ffadb949cfc149a6617cc6518ab57d.6fde6558.png)

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


![](/assets/auth8.28e02515b78db57ec32c07fd6bd7d296484e64f65ef6a3bc5296520cb1da8d65.6fde6558.png)

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](/documentation/instructions/authentication).
2. Follow the steps above.


### Data Mirror

It is required that there is a data mirror available.

Get more information about Data Mirror Setup and Synchronization [here](https://developer.cdq.com/documentation/instructions/synchronize-a-data-monitor/).

## 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](#create-a-mapping)
  - [Upsert](#upsert)
2. Sharing is defined in scopes:
  - [API](#sharing-scopes-using-api)
  - [APP](#sharing-scopes-using-app)


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


```json
{
  "inputMapping": {
    "businessPartnerAttributeMappings": [
      {
        "sourceConstant": "TRUE",
        "targetAttributes": [
          "businessPartner.disclosed"
        ]
      }
    ]
  }
}
```

To create a mapping, follow these steps:

1. Go to the [Data Mirror Management](https://apps.cdq.com/dashboard/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.


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

details
summary
Response
The response will contain the ID of the created mapping and `businessPartner.disclosed` in the `inputMapping` section.


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

Full documentation of the **Create Data Mapper Definition** endpoint can be found [here](https://developer.cdq.com/reference-docs/data-exchange/V5/tag/Data-Mapping/paths/~1datamapperdefinitions/post/).

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


To check the **upsert report** response, expand the **Response** section below.

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


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

Full documentation of the **Upsert Business Partners** endpoint can be found [here](https://developer.cdq.com/reference-docs/data-exchange/V5/tag/Business-Partners/paths/~1v4~1storages~1%7BstorageId%7D~1businesspartners/put/).

### Sharing scopes using API

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

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.


To check the example **Response** in the section below.

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

Example response:


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

Full documentation of the **Upsert Business Partners** endpoint can be found [here](https://developer.cdq.com/reference-docs/data-exchange/V4/tag/Business-Partner-Storages/paths/~1v4~1storages~1%7BstorageId%7D~1sharingscopes/post/).

### Sharing scopes using APP

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

1. Go to the [Collaboration & Subscription Configuration](https://apps.cdq.com/dashboard/collaboration)
in CDQ Cloud Apps.


![](/assets/share-pool-img001.536c5cb470f6f98ec9ed2114eb559d8034a904fbe17db8be11e94db49b356edf.4b2643bd.png)

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


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,


![](/assets/share-pool-img002.19ce0174f4eddef20900ec2478d57e43f3322163fe07629dc5ce56bdda431fdf.4b2643bd.png)

#### 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,


![](/assets/share-pool-img003.b178f990010f04738f2eacb9cee206fd7d8da31fa3179286004ef6ab2952bdad.4b2643bd.png)

- Choose the data source,
- Click the **Save changes** button,


![](/assets/share-pool-img004.b4fe865a59cdf5166af8d8d774948a6e43d35dfa72739f41b102bf6536ca91b1.4b2643bd.png)

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.


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.

Full documentation of the **Upsert Business Partners** endpoint can be found [here](https://developer.cdq.com/reference-docs/data-exchange/V5/tag/Subscriptions/paths/~1v4~1businesspartners~1identitylinks/get/).

## 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 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?](https://developer.cdq.com/documentation/tutorials/partner-guard/pg-how-to-monitor-business-partner-updates-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!