# Tutorial: How to monitor Business Partner updates? (API Approach)

## Overview

**Use case**

Customer and vendor data quality decreases, even if the data is not touched, e.g., due to address changes, M&A, or
insolvencies. Keeping the data up to date manually is a complex and high effort on a global scale. Commercial registers
and other reference data sources have to be monitored continuously. And for countries without reliable reference data,
data has to be researched business partner by business partner. The CDQ Business Partner Update Monitoring takes over
the effort of manual update screening. Business Partner Updates are automatically collected and made available in an easy
to analyze and integrate way.

|  |
|  --- |
| ![](/assets/mbpu_overview.42c5358ca448f7d6c455c7848d17931f93d19ed7756fb32588ffcea4aa487702.b946f968.png) |
| *Use Case: Situation, Approach and Results* |


**Learning Goals**

In this tutorial, you will learn how to:

1. Create Augmentation Configuration for updates
2. Create Augmentation Monitor
3. Read Subscriptions
4. Read updates


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

For tutorial purposes, the CDQ Data Mirror is used. Use your organization's Data Mirror to recreate the *happy path*.

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

## Step 1: Create Augmentation Configuration

### List available reference Data Sources

To receive updates, define which data sources should be monitored. All data sources should be activated in the [Global settings](https://apps.cdq.com/dashboard/global-settings).

To list all available reference Data Sources:

1. Use the **List Data Sources of Update Monitors** endpoint,
2. Send the request,


Visit [List Data Sources of Update Monitors](/documentation/tutorials/partner-guard/pg-how-to-monitor-business-partner-updates-api) documentation page for more details.

1. Select the desired reference Data Source.


All available reference Data Sources will be listed in the schema below:


```json
{
    "referenceDataSources": [
        {
            "aleiPrefix": "REF_DATASOURCE_PREFIX",
            "technicalKey": "REF_DATASOURCE_TECHNICAL_KEY"
        }
    ]
}
```

### Create the configuration

1. Use the **Create augmentation configuration** endpoint,
2. Select the **Client Configuration (VIES and CH_UIDR)** example,
3. Send the request,


1. Save `id` value from the response for next step.



```json
{
    "id": "YOUR_AUGMENTATION_CONFIGURATION_ID"
}
```

Remember, the *Augmentation Configuration* must be created in the same workspace as data mirrors with Business Partners.
Use the API KEY with correct workspace assigned.

## Step2: Create an Augmentation Monitor

Selected reference Data Sources can be added to Augmentation Monitor. To activate or make changes to the Augmentation Monitor for
your data source or sources:

1. Use the **Create Update Monitors** endpoint to send the below request.


REMEMBER
The **Create Update Monitors** endpoint's request must contain all current and updated reference Data Sources. If reference
Data Source is linked to your Data Source and the request does not contain it the link will be removed.

1. Select **Create an Augmentation Monitor** example,
2. Replace values in the example:
  * `YOUR_DATA_SOURCE_ID` with proper data source `ID` or `IDs`,
  * `YOUR_AUGMENTATION_CONFIGURATION_ID` with proper configuration `ID`,
3. Send the request.


## Step 3: Browse the subscription

Browsing subscription allows seeing the list of Business Partners to be monitored for updates.

Check already subscribed Business Partners:

1. Use the **Read Links** endpoint to send the below request,
2. Replace values in the example:
  * `YOUR_STORAGE_ID` with proper Data Storage ID in a Parameters section,
3. Clean the:
  * `startAfter` filed in a Parameters section,
4. Send the request.


In response, **updateMonitoring** status can be found. Value `true` indicates that particular Business Partner is
subscribed for update monitoring.


```json
{
"id": "BUSINESS_PARTNER_ID",
"updateMonitoring": true
}
```

For every Business Partner **updateMonitoring** value is set to `true` by default.

For Business Partners, which don't have a linkage created due to lack of required identifier or identifier was incorrect,
it's worth to use augmentation with curation profile: `GOLDEN_RECORD` and update Business Partners with new, curated data.
Get back to [Step 1](#step-1-create-augmentation-configuration) and create a new configuration using the **Client Configuration
(VIES and CH_UIDR)** example.

## Step 4: Read updates

Once linkage is created, it's possible to check updates.

### Regular updates

When the update monitors are updated and all necessary Business Partners are updated, you can check Business Partners updates.

To read all updates:

1. Use the **Read Business Partner Updates** endpoint to send the below request.
2. Replace values in the example:
  * `YOUR_STORAGE_ID` with proper Data Storage ID in a Parameters section,
3. Clean below fields in the Parameters section:
  * `conceptClassification`
  * `dataTransformationDefinitionId`
  * `from`
  * `startAfter`
  * `summaryClassification`
4. Send the request.


### Filtering

A list of updated Business Partners can be filtered in various ways, with tags being the most powerful and important. Tags
combine concepts (e.g., `NAME_LOCAL`, `IDENTIFIER`, `LOCALITY`) with actions (e.g., `ADDED`, `MODIFIED`). There are two
types of classification filters:

* `summaryClassification`: This filter provides Business Partners with a summary classification, which is determined by
the highest classificationlevel among all Business Partner concepts.
* `conceptClassification`: This filter indicates the classification of a Business Partner's concept (e.g., `name`, `street`,
`legal` `form`).


Filtration by tag and conceptClassification works in pairs and identifies Business Partners where, for example, the `LOCAL_NAME`
was `MODIFIED` and this change was classified as MAJOR. When filtering by tag and summaryClassification, the endpoint returns
all Business Partners where the specified tags were added to the summary and the general summary classification is, for example,
`IDENTIFIER_ADDED`, + the highest classification for all updates `MINOR`. Additional filtering options include country,
provenance, and external IDs. Providing the data source (or your mirror) in the request can enhance response speed. It's
possible to check the total number of updates using featuresOn `NUMBER_OF_TOTAL`, but can slow down the response.

There is also an option to use updateTagsProfiles. Profiles are container for tags, grouped in: `ADDRESS_DATA`, `LEGAL_DATA`,
`RELATIONS`, `VAT_DATA`.

The list of all filtering options can be found in the [endpoint description](https://developer.cdq.com/reference-docs/data-exchange/V5/tag/Business-Partners/#tag/Business-Partners/paths/~1v5~1storages~1%7BstorageId%7D~1businesspartners~1updates/get).

### Generate seed updates

Seed updates are generated as an initial step in the update monitoring. All business partners from the mirror, for which
linkage was created, receive full BP from reference data sources with the comparison (update assessment). In case update
monitoring was turned on in the past, and some updates were not consumed, there is a possibility to generate seed updates
on demand.  It's possible to do that for a specific BP or for a big, defined group.

1. Use the **Start Seed Updates Generate Job** endpoint to send the below request,
2. Select **Seed Updates** example,


If there is no dropdown-list to choose the example, **Seed Updates** example is set by default.

1. Set the `storageId` in the Parameters section,
2. Send the request.


1. Save the `jobId` for the next step.


details
summary
Additional info about parameters

Parameters:

* `referenceDataSource` (**required**): provide a technicalKey of reference data source, for which linked Business Partners
from your mirror should get seed updates


Other parameters are optional. Seed update can be generated for specific business partner thanks to parameters `externalId`,
`businessPartnerIds`; or could be provided for a group of Business Partners from specific `dataSourceIds`, `countryShortName`.

1. Check the status of the job using the **Poll Seed Updates Generate Job** endpoint.
2. Set the `jobId` and `storageId` in the Parameters section,
3. Send the request.


### Customized response

Response from the Read Business Partner Updates endpoint can be customized to the required structure and chosen elements.
To do that, it's required to have Data Transformation Definition.

The Data Transformation Definition can be created only by **CSMs**.

A customized response is provided in the "jsonRecord" section in the response from the **Read Business Partner Updates**
endpoint:


```json
{
  "limit": "100",
  "total": "67",
  "startAfter": "5712566172571652",
  "nextStartAfter": "5712566172571652",
  "values": [
    {
      "id": "5712566172571652",
      "businessPartnerId": "63e635235c06b7396330fe40",
      "externalBusinessPartnerId": "The ID managed in the customer's SAP systems.",
      "updatedBusinessPartner": {
        "id": "63e635235c06b7396330fe40",
        "summary": {},
        "names": [],
        "legalForm": {},
        "identifiers": [],
        "categories": [],
        "status": {},
        "addresses": [],
        "externalId": "The ID managed in the customer's SAP systems.",
        "profile": {},
        "types": [],
        "relations": [],
        "jsonRecord": "{\"key\":\"value\"}"
      },
      "storageBusinessPartner": {}
    }
  ]
}
```

#### Option 1 - DTD ID provided in the request

Ask dedicated CSM to create a Data Transformation Definition based on provided needs in the workspace where the Augmentation
Monitor is created.

1. Use the **Read Business Partner Updates** endpoint to send the below request.
2. Replace values in the example:
  * `YOUR_STORAGE_ID` with proper Data Storage ID in a Parameters section,
  * `dataTransformationDefinitionId` with the Data Transformation Definition ID (Provided by CMS) in the Parameters section,
3. Clean below fields in the Parameters section:
  * `conceptClassification`
  * `from`
  * `startAfter`
  * `summaryClassification`
4. Send the request.


#### Option 2 - Configuration assigned to the API KEY

Ask CSM to create a Data Transformation Definition based on your needs in the workspace where the Augmentation Monitor is created.

1. Go to the Data Transformation Configurator APP,
2. Create a new configuration,


![](/assets/monitor-bp-updates-img001.ff828c71e45f592f710f8d13e6aca858c7d3ab9088bd211fcec3d00ee98d4bac.b946f968.png)

1. Select created Data Transformation Definition in the Business Partner Updates selector,
2. Save the configuration,


![](/assets/monitor-bp-updates-img002.dcbbae3f749822a3a16b4de09685f7f54db848a2f10f71860f621db566e8b6cc.b946f968.png)

1. Go to the API Key Management,
2. Select the existing API KEY or create a new one and click a "See Details" button,
3. Scroll down and assign a new configuration for Data Transformation Configuration,


![](/assets/monitor-bp-updates-img003.d83772d97b8070444c9a02e386f8562398d76831b05a4e9e477ce24ec7eef9e2.b946f968.png)

1. Save the changes,


Use API KEY in requests to get data in a customized way from the Read Business Partner Updates endpoint.

To read updates:

1. Use the **Read Business Partner Updates** endpoint to send the below request.
2. Replace values in the example:


* `YOUR_STORAGE_ID` with proper Data Storage ID in a Parameters section,


1. Clean below fields in the Parameters section:


* `conceptClassification`
* `dataTransformationDefinitionId`
* `from`
* `startAfter`
* `summaryClassification`


1. Send the request.


### Update Report

CDQ Cloud APPs offer the creation of update report. Report for now provides data in the old model (v4). More about creating
reports check [here](/documentation/tutorials/data-sharing-platform/dsp-generate-reports-data-clinic).

## Your opinion matters!

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