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.

MBPU Overview
Use Case: Situation, Approach and Results
info

This Use Case Enabler is based on Monitor Business Partner Updates use case but present API approach.

Scenario and Learning Goals

MBPU Process API
Common Process and involved APIs/Endpoints

In this tutorial, you will learn how to:

  1. Activate update monitoring for the Data Mirror.
  2. Browse subscriptions.
  3. Generate the subscription report.
  4. Read updates.
  5. Generate the update report
attention

The following tutorial describes a happy path based on a common use case. Depending on your particular business requirements, the steps may be different and/or need to be customized.

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

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

info

Get more information about Data Mirror Setup and Synchronization here.


Step 1: Activate update monitoring

Update monitoring helps organizations to stay aligned with the latest Business Partners details. Update Monitoring can be activated for one or multiple reference Data Sources.

List reference Data Sources

To list all available reference Data Sources:

  1. Use the List Data Sources of Update Monitors endpoint to send the below request.
  1. Check the above example in the Try It Console now!
Loading...
  1. All available reference Data Sources will be listed in the schema below:
Copy
Copied
{
    "referenceDataSources": [
        {
            "aleiPrefix": "REF_DATASOURCE_PREFIX",
            "technicalKey": "REF_DATASOURCE_TECHNICAL_KEY"
        }
    ]
}
info
Use received REF_DATASOURCE_TECHNICAL_KEY in the update step.

Create Update Monitor

Selected reference Data Sources can be added to Update Monitor. To activate or make changes to the Update 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.

Cannot find specified operation in definition: data-exchange-v4

attention

Presented payload example contains only three reference Data Sources. Before sending the request, please check that the list of reference data sources you want to use is complete.

  1. Check the above example in the Try It Console now!
  2. Select Update multiple Update Monitors example.
  3. Set value of:
    • id to YOUR_DATA_MONITOR_ID
    • referenceDataSource to REF_DATASOURCE_TECHNICAL_KEY
    • affectedDataSourceIds to YOUR_DATASOURCE_ID
    • storageId to YOUR_STORAGE_ID in a Parameters section
  4. Click on the Send button.

Cannot find specified operation in definition: data-exchange-v4

If the affectedProperties is empty it will check for all updates. It can be reduced to specific parameters.
Copy
Copied
{
  "affectedProperties": ["NAME_VALUE", "IDENTIFIER_VALUE"]
}
DOCUMENTATION

Check the full list of available affectedProperties values to be used.

Congratulations

Your Update Monitors have been successfully updated!

Step 2: Browse the subscription

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

Check Business Partners

Check already subscribed Business Partners:

  1. Use the Read Business Partners endpoint to send the below request.
  1. Check the above example in the Try It Console now!
  2. Set value of:
    • storageId to YOUR_STORAGE_ID in a Parameters section
    • limit to 1000 or higher if you need more results
  3. Click on the Send button.
Loading...
In response, updateMonitoring status can be found. Value true indicates that particular Business Partner is subscribed for update monitoring.
Copy
Copied
{
"id": "BUSINESS_PARTNER_ID",
"updateMonitoring": true
}
info
For every Business Partner updateMonitoring value is set to true by default. To disable update monitoring, go to the next subchapter.

Enable/disable update monitoring

The updateMonitoring status can be changed if the update monitoring is no longer needed:

  1. Use the Toggle Update Monitoring of Business Partners endpoint to send the below request.
application/json
{
  • "enable": false,
  • "businessPartnerIds": [
    ]
}
  1. Check the above example in the Try It Console now!
  2. Set the Business Partner ID.
  3. Click on the Send button.
Loading...
attention

The Toggle Update Monitoring of Business Partners endpoint will show no response body. To check the results use Read Business Partners endpoint.

Step 3: Generate the subscription report

Subscription report allows checking which Business Partners are subscribed for update monitoring in the xlsx report. In the below example, you will generate the subscription report for Swiss Business Partners in VIES reference Data Source.

Subscription report request

To generate the subscription report:

  1. Use the Build Business Partner Reports endpoint to send the below request.

Cannot find specified operation in definition: data-exchange-v4

  1. Check the above example in the Try It Console now!
  2. Select Generate Subscription Report example.
  3. Set value of:
    • storageId to YOUR_STORAGE_ID
    • dataSource to YOUR_DATASOURCE_ID
  4. Click on the Send button.

Cannot find specified operation in definition: data-exchange-v4

The response will give the YOUR_SUBSCRIPTION_REPORT_JOB_ID and the job progress status.
Copy
Copied
{
    "id": "YOUR_SUBSCRIPTION_REPORT_JOB_ID",
    "status": "SCHEDULED",
    "progress": 0
}

Poll the report status

To poll the report job status:

  1. Use the Poll Business Partner Reports endpoint to send the below request.

Cannot find specified operation in definition: data-exchange-v4

  1. Check the above example in the Try It Console now!
  2. Set value of id to YOUR_SUBSCRIPTION_REPORT_JOB_ID in the Parameters section.
  3. Click on the Send button.

Cannot find specified operation in definition: data-exchange-v4

When the job is finished set of attachments will be displayed. Look for the link containing Subscription+Report+Collection.zip and copy whole value of the url.
Full ResponseReport link example
Copy
Copied
{
    "summary": { },
    "id": "YOUR_SUBSCRIPTION_REPORT_JOB_ID",
    "status": "FINISHED",
    "progress": 100,
    "attachments":[
      {"url": "FILE_LINK/Review+Process+Business+Partner+Record+Statistics.html"},
      {"url": "FILE_LINK/Overlap+Rate+and+Record+Distribution.html"},
      {"url": "FILE_LINK/Subscription+Dashboard.zip"},
      {
          "url": "YOUR_REPORT_FILE_LINK/Subscription+Report+Collection.zip"
      },
      {"url": "FILE_LINK/Record+Distribution.html"    }
    ]
}
Copy
Copied
{
  "url": "job-files/4a1af653988a3bfc9e04854ebe5e630b/326704a3-4225-44ef-8c92-69718a0c884d/Subscription+Report+Collection.zip"
}

Download the report files

To download the report files:

  1. Use the Request a file download endpoint to send the below request.
application/json
{
  • "url": "REPORT_FILE_LINK_PATH.zip",
  • "downloadLinkAge": "0"
}
  1. Check the above example in the Try It Console now:
  2. Set value of url to YOUR_REPORT_FILE_LINK/Subscription+Report+Collection.zip.
  3. Click on the Send button.
Loading...
In the response you will get the downloadLink. Use it to download a desired report.
Copy
Copied
{
    "url": "YOUR_REPORT_FILE_LINK/Subscription+Report+Collection.zip",
    "downloadLink": "YOUR_DOWNLOAD_LINK",
    "downloadMethod": "GET"
}
  1. Check the downloaded report.
MBPU S2 P7
List with Business Partners with possible changes
CONGRATULATION

You have generated the subscription report, and you are able to download it.

Step 4: Read 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.
  1. Check the above example in the Try It Console now!
  2. Set value of:
    • storageId to YOUR_STORAGE_ID
    • affectedConcepts to NAME
    • affectedProperties to NAME_VALUE
    • countryShortName to CH
    • from to a date not older than three months in the past
  3. Click on the Send button.
DOCUMENTATION

Check the full list of available affectedConcepts and affectedProperties values to be used.

Remember

Select an affectedConcepts and corresponding affectedProperties. Mixing not related values returns an empty list of updates in the response!

Loading...
In the response check the changeSets for potential changes. If the change had placed, compare newContent and previousContent.
Change type: ADDEDChange type: MODIFIED
Copy
Copied
{
  "values": [
    {
        "businessPartnerId": "BUSINESS_PARTNER_ID1",
        "externalBusinessPartnerId": "CH-00001",
        "changeSets": [
          {
            "propertyChanges":[
              {
                "externalIds": [],
                "property": {},
                "newContent": "ANTEIS SA",
                "provenance": {},
                "changeType": "ADDED",
                "changeClassification": "MAJOR"
              }
            ],
          "provenances":[]
          }
        ],
        "provenances":[]
    }
  ]
}
Copy
Copied
{
  "values": [
    {
        "businessPartnerId": "BUSINESS_PARTNER_ID2",
        "externalBusinessPartnerId": "CH-00012",
        "changeSets": [
          {
            "propertyChanges":[
              {
                "externalIds": [],
                "property": {},
                "newContent": "Mibelle AG",
                "previousContent": "Mirabelle",
                "provenance": {},
                "changeType": "MODIFIED",
                "changeClassification": "MAJOR"
              }
            ],
          "provenances":[]
          }
        ],
        "provenances":[]
    }
  ]
}
info
With presented settings the endpoint returns a list with all types of changes. The results can be limited by two filters: changeClassification and changeType in the request Body section. For details explore documentation.

Step 5: Generate the update report

All updates can be gathered and generated as a xlsx report.

Update report request

To generate the update report:

  1. Use the Build Business Partner Reports endpoint to send the below request.

Cannot find specified operation in definition: data-exchange-v4

  1. Check the above example in the Try It Console now!
  2. Select Generate Update Report example.
  3. Set value of:
    • storageId to YOUR_STORAGE_ID
    • dataSource to YOUR_DATASOURCE_ID
    • from to a date not older than three months in the past
    • to a date with time stamp. Example: yyyy-mm-ddT00:00
  4. Click on the Send button.
DOCUMENTATION

Check the full list of available affectedConceptTechnicalKeys values to be used. The values are described in the Read Business Partner Updates documentation page, but can be used in the request.

Cannot find specified operation in definition: data-exchange-v4

The response will give the YOUR_UPDATE_REPORT_JOB_ID and the job progress status.
Copy
Copied
{
    "id": "YOUR_UPDATE_REPORT_JOB_ID",
    "status": "SCHEDULED",
    "progress": 0
}

Poll the report status

To poll the report job status:

  1. Use the Poll Business Partner Reports endpoint to send the below request.

Cannot find specified operation in definition: data-exchange-v4

  1. Check the above example in the Try It Console now!
  2. Set value of id to YOUR_UPDATE_REPORT_JOB_ID in the Parameters section.
  3. Click on the Send button.

Cannot find specified operation in definition: data-exchange-v4

When the job is finished set of attachments will be displayed. Look for the link containing BPU+Report+Collection.zip and copy whole value of the url.
Response with attachmentsReport link example
Copy
Copied
{
  "id": "YOUR_UPDATE_REPORT_JOB_ID",
  "status": "FINISHED",
  "progress": 100,
  "attachments": [
    {"url": "FILE_LINK/Count+of+Updates+per+Country.html"},
    {"url": "FILE_LINK/Count+of+Updates+per+Concept.html"},
    {"url": "FILE_LINK/Business+Partner+Updates+Dashboard.zip"},
    {
      "url": "YOUR_REPORT_FILE_LINK/BPU+Report+Collection.zip"
    }
  ]
}
Copy
Copied
{
      "url": "job-files/4a1af653988a3bfc9e04854ebw5e630b/915df183-811e-47a6-8a7e-01fe833f4aee/BPU+Report+Collection.zip"
}

Download the report files

To download the report files:

  1. Use the Request a file download endpoint to send the below request.
application/json
{
  • "url": "REPORT_FILE_LINK_PATH.zip",
  • "downloadLinkAge": "0"
}
  1. Check the above example in the Try It Console now!
  2. Set value of url to YOUR_REPORT_FILE_LINK/BPU+Report+Collection.zip.
  3. Click on the Send button.
Loading...
In the response you will get the downloadLink. Use it to download a desired report.
Copy
Copied
{
    "url": "YOUR_REPORT_FILE_LINK/BPU+Report+Collection.zip",
    "downloadLink": "YOUR_DOWNLOAD_LINK",
    "downloadMethod": "GET"
}
  1. Check the downloaded report.
MBPU UPDATEREPORT
List with Business Partners with possible changes
CONGRATULATION

You have generated the update report, and you are able to download it.


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