Tutorial: How to share Business Partner updates?

Overview

Use case

Sequence of activities for sharing business partner data with the CDQ Community Data Pool and monitor updates and statistics.

attention

This tutorial is based on the wiki use case and presents an integration approach using CDQ APIs.



Use Case: Situation, Approach and Results

Learning Goals



Common Process and involved APIs/Endpoints

In this tutorial, you will learn how:

Disclose data.
Manage subscriptions.
Generate the subscription report.
Get updates from the CDQ Community Data Pool.
Generate the update report based on CDQ Pool updates.

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: Disclose Data

Every Business Partner record contains disclose parameter that allows data sharing with the CDQ Community. Undisclosed Business Partners will be not visible to other community members.

Remember

Business partner's records are undisclosed by default. To share a set of data, disclose parameter value must be changed.

Mass data disclosure with Sharing Scope

To disclose range of Business Partners from selected county:

Use the Create Sharing Scope endpoint to send the below request.

Payload
curl

application/json

{"description": "Share customers from Wakanda.",
"dataSources": [{"id": "YOUR_DATASOURCE_ID"
}
],
"countries": [{"shortName": "COUNTRY_CODE"
}
]
}

Check the above example in the Try It Console now!
Set value of:
- description to YOUR_DESCRIPTION
- id to YOUR_DATASOURCE_ID
- shortName to COUNTRY_CODE
Set the YOUR_STORAGE_ID in Parameters section.
Click on the Send button.

Congratulations

Now you know how-to disclosure Business Partners data from selected county.

List Sharing Scopes

To check which countries are shared with Sharing Scopes:

Use the List Sharing Scopes endpoint to send the below request.

curl

Check the above example in the Try It Console now!
Set the YOUR_STORAGE_ID in Parameters section.
Click on the Send button.

In response, the list of shared countries will be returned.

Copy

Copied

{
    "values":[
        {
            "id": "61e58c86255bc91f4da8d42b",
            "dataSources":[
                {
                    "id": "61a5d59b470c0332d08e609c",
                    "name": "CDQ_DEMO"
                }
            ],
            "countries":[
                    {
                        "shortName": "DE"
                    }
            ]
        },
        {
            "id": "61e58c866e2f9452f3ad1148",
            "dataSources":[
                {
                    "id": "61a5d59b470c0332d08e609c",
                    "name": "CDQ_DEMO"
                }
            ],
            "countries":[
                {
                    "shortName": "FR"
                }
            ]
        }
    ]
}

Single record disclosure

attention

Before the update of the existing record the Business Partner's externalId is needed. Be sure that UPSERT_BY_EXTERNAL_ID feature is active.

To disclose existing Business Partner:

Use the Upsert Business Partners endpoint to send the below request.

info

Check the below example based on default mapping.

Payload
curl

application/json

{"dataSource": "YOUR_DATASOURCE_ID",
"featuresOn": ["UPSERT_BY_EXTERNAL_ID"
],
"businessPartners": [{"externalId": "BP_EXTERNAL_ID",
"record": "{\"Customer number:\"YOUR_EXTERNAL_ID\", \"Name\":\"COMPANY_NAME\", \"Country\":\"COUNTRY_CODE\", \"City\":\"CITY\", \"Street\":\"STREET\", \"Postal code\":\"POSTAL_CODE\"}",
"disclosed": true
}
]
}

Check the above example in the Try It Console now!
Set value of:
- dataSource to YOUR_DATASOURCE_ID
- externalId to BP_EXTERNAL_ID
Fill record of a Business Partner based on right mapping.

warning

The record must be filled with exact Business Partners details as an existing record in the Data Source. If fields contain different values or are empty, the record will be updated with the given values in the request.

Set the YOUR_STORAGE_ID in Parameters section.
Click on the Send button.

Results

Two types of results can be expected:

Existing record updated
Something went wrong
- The response includes a message about the root of the issue

Existing record updatedSomething went wrong

Copy

Copied

{
    "numberOfAccepted": 1,
    "numberOfInserts": 0,
    "numberOfUpdates": 1,
    "numberOfFailed": 0
}

Copy

Copied

{
    "numberOfInserts": 0,
    "numberOfUpdates": 0,
    "numberOfFailed": 1,
    "failures":
    [

        {
            "externalId": "BP_EXTERNAL_ID",
            "message": "Incorrect externalId value"
        }
    ]
}

Congratulations

Now you know how to disclose Business Partner data.

Step 2: Browse Subscriptions

Browsing subscriptions allows seeing the list of Business Partners to be monitored for updates and ready for sharing.

Check Business Partners

Check already subscribed Business Partners:

Use the Read Business Partners endpoint to send the below request.

curl

Check the above example in the Try It Console now!
Set value of:
- storageId to YOUR_STORAGE_ID in a Parameters section
- limit to 1000 or higher if you need more results
Click on the Send button.

In response, two important flags can be found:

disclosed flag
updateMonitoring flag

Copy

Copied

{
"id": "BUSINESS_PARTNER_ID",
"externalId": "BP_EXTERNAL_ID",
"disclosed": true,
"updateMonitoring": true

}

"updateMonitoring": true indicates that particular Business Partner is subscribed for update monitoring.
"disclosed": trueindicates that particular Business Partner data are available for sharing.

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:

Use the Toggle Update Monitoring of Business Partners endpoint to send the below request.

Payload
curl

application/json

{"enable": false,
"businessPartnerIds": ["BUSINESS_PARTNER_ID"
]
}

Check the above example in the Try It Console now:
Set the Business Partner ID.

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 CDQ_POOL reference Data Source.

Subscription report request

To generate the subscription report:

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

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

Check the above example in the Try It Console now!
Select Generate Subscription Report example.
Set value of:
- storageId to YOUR_STORAGE_ID
- dataSource to YOUR_DATASOURCE_ID
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:

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

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

Check the above example in the Try It Console now!
Set value of id to YOUR_SUBSCRIPTION_REPORT_JOB_ID in the Parameters section.
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:

Use the Request a file download endpoint to send the below request.

Payload
curl

application/json

{"url": "REPORT_FILE_LINK_PATH.zip",
"downloadLinkAge": "0"
}

Check the above example in the Try It Console now!
Set value of url to YOUR_REPORT_FILE_LINK/Subscription+Report+Collection.zip.
Click on the Send button.

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

Check the downloaded report.



List with Business Partners subscriptions and disclosure info

info

In case of lack of Disclosed column check if it's hidden.

CONGRATULATION

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

Step 4: Get updates from the CDQ Community Data Pool

To get updates from the CDQ Community Data Pool:

Use the Read Business Partner Updates endpoint to send the below request.

curl

Check the above example in the Try It Console now!
Set value of:
- storageId to YOUR_STORAGE_ID
- affectedConcepts to NAME
- affectedProperties to NAME_VALUE
- provenanceTechnicalKeys to CDQ_POOL
- from to a date not older than three months in the past. Example: yyyy-mm-ddT00:00.
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!

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": "NjIxMDIyYTM4NGY5YmQwNWE4NGMwMzFm",
        "externalBusinessPartnerId": "CH-00001",
        "changeSets": [
          {
            "propertyChanges":[
              {
                "externalIds": [],
                "property": {},
                "newContent": "ANTEIS SA",
                "provenance": {},
                "changeType": "ADDED",
                "changeClassification": "MAJOR"
              }
            ],
          "provenances":[]
          }
        ],
        "provenances":[]
    }
  ]
}

Copy

Copied

{
  "values": [
    {
        "businessPartnerId": "621022a384f9bd05a84c031f",
        "externalBusinessPartnerId": "CH-00012",
        "changeSets": [
          {
            "propertyChanges":[
              {
                "externalIds": [],
                "property": {},
                "newContent": "Mibelle AG",
                "previousContent": "Mirabelle",
                "provenance": {},
                "changeType": "MODIFIED",
                "changeClassification": "MAJOR"
              }
            ],
          "provenances":[]
          }
        ],
        "provenances":[]
    }
  ]
}

info

To limit results to specific country set country code at countryShortName field.

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:

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

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

Check the above example in the Try It Console now!
Select the Generate Update Report example.
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
Click on the Send button.

DOCUMENTATION

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

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:

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

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

Check the above example in the Try It Console now!
Set value of id to YOUR_UPDATE_REPORT_JOB_ID in the Parameters section.
Clock 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": "915df183-811e-47a6-8a7e-01fe833f4aee",
  "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:

Use the Request a file download endpoint to send the below request.

Payload
curl

application/json

{"url": "REPORT_FILE_LINK_PATH.zip",
"downloadLinkAge": "0"
}

Check the above example in the Try It Console now!
Set value of url to YOUR_REPORT_FILE_LINK/BPU+Report+Collection.zip.
Click on the Send button.

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

Check the downloaded report.



List of Business Partners' with possible changes

CONGRATULATION

You have generated the update report based on updates from CDQ Pool, 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