Skip to Content
Technical Articles
Author's profile photo Manasi Sridhar

Configuring SAP Master Data Integration service for Business Partner replication using SOAP API’s – 2022

(Note: Some features mentioned here might not be available in your environment. Please get in touch with SAP support if you face any such discrepancy.)

SAP Master Data Integration service serves as a central integration point for master data within the Intelligent Suite. There are many articles such as this one that explain how the service can help our customers achieve true integration for various Domain models in the cloud.

In this blog, I will go through the steps required to enable the SAP Master Data Integration service and replicate Business Partners using SOAP API’s. This blog is a latest version of this post. I have linked each section title to respective official help pages, please refer them for detailed and up to date information.

I. Service Instance creation for Business Partner Read and Replicate

  1. Go to the SAP BTP subaccount where you want the SAP MDI instance to be created. On the left-hand side, under Services, click on Instances and Subscriptions.
  2. Click on Create on the top right side.
  3. Select the service name as Master Data Integration and provide an Instance Name of your choice.For service plan, choose sap-integration for connecting SAP-branded cloud applications. s4hana-onpremise for connecting S/4HANA on-premise systems.The s4hana-onpremise is visible as a service plan option, if and only if the service instance is created in an CPEA-enabled account or has an explicit entitlement in the BTP Control Center. For more information, see Entitlements and Quotas.
  4. Click Next.
  5. Use this JSON below to create the service instance.
        "businessSystemId": "<businessSystemId>",
        "application": "<application>",
        "writePermissions": [
                "entityType": "sap.odm.businesspartner.BusinessPartner"
                "entityType": "sap.odm.businesspartner.BusinessPartnerRelationship"

    or If you want to use Odata API to read business partner master data from MDI, you can use the json below. ( The xs-security section with the “$XSMASTERAPPNAME.BPCommonRead”, “$XSMASTERAPPNAME.BPSensitiveDataRead” authorities are added. )

        "businessSystemId": "<businessSystemId>",
        "application": "<application>",
        "writePermissions": [
                "entityType": "sap.odm.businesspartner.BusinessPartner"
                "entityType": "sap.odm.businesspartner.BusinessPartnerRelationship"
        "xs-security": {
            "xsappname": "<Service-Clone-Name>",
            "authorities": [

    – For businessSystemId, provide the businessSystem identifier of the client system that you will connect to the MDI instance.
    In SAP S/4HANA Cloud system this value is can be found under Communication systems tile and then filter by Own System.
    In SAP S/4HANA On-premise system, open transaction se37 and execute Function Module LCR_GET_OWN_BUSINESS_SYSTEM.
    – For application type, provide one value from “ariba”, “c4c”, “cdc”, “commerceCloud”, “concur”, “cpq”, “mdg”, “s4”, “sfsf”, “hrc”(SAP Subscription Billing) depending upon the type of your client system. In case your system type is not listed above, please contact SAP MDI development team.
    – For xsappname, a unique v4 UUID can be used.

  6. Select the service instance created and click on Create under Service Key. Click Next and then Finish.

Note that for every new client that you want to connect to MDI, a separate instance has to be created. More information can be found here

II. Setting up BusinessSystem using Generic Configuration API

In this step we provide a unique identifier to the MDI tenant. This identifier is referenced in MDI Key Mapping.
Note that this is a one time activity per subaccount as opposed to service instance creation which should be done for every connecting client.

  1. Under the Security dropdown on the left side, click on Role Collections. (You should have a Security Administrator authorisation to perform this step)
  2. Click on sign and create a new Role collection with the name BusinessConfigurationAdmin. Search for the role BusinessConfigurationAdmin to the role collection. Finally, add your user to the role collection.
  3. This endpoint uses Business User Authorization. To get the the token using Business User Authorization by Passcode, create a POST request in Postman and do the following:

    • Select a service key from any valid service instance.

    • Create a POST request as below. Replace xsuaa_url with uaa.url from your service key.

    • In the Authorization tab, replace client_id and client_secret with uaa.clientid and uaa.clientsecret from your service key.

    • In the Body tab, replace passcode value by visiting <<uaa.url>>/passcode with your preferred browser.

    •  In the Headers tab, make sure the value of accept header is application/json.
    •  Execute the POST request, you should receive 200 OK response with access_token in   the response payload.

  4.  Create another POST Request
    • Set Request URL as below, <base_url> has to be replaced with uri from service key.
    • In the Authorization tab, select Bearer Token as type and put the value of access_token generated in step 3 above,
    • In the Headers tab, set Content-Type as application/json
    • In the Body tab, use the following payload.
        "ConfigurationName": "Business System",
        "ConfigurationValue": "<mdi_business_system>"

The value of ConfigurationValue parameter can be set as “identityzone” from service key. This value should match with RecipientBusinessSystemID in the SOAP payload sent from client to MDI.

III. Create SOAP Outbound Destinations to the client

The Business partner implementation in MDI utilises the BTP subaccount destinations for SOAP outbound communication that are defined in a specific format.

  1. Navigate to your subaccount and click on the Destinations tab on the right side. (Your user should have relevant security authorisations)
  2. Click on “New Destination”.
  3. In the Name placeholder provide value <Business_System_Name>_BPOUTBOUND. Make sure “Business_System_Name” value is the same as “businessSystemId” used in section I of this blog.
  4. Type: HTTP
  5. The URL is an endpoint on client system capable of receiving SOAP payload for BusinessPartner.
    Ex : For S/4HANA OnPremise system login to your ERP system and create BP SOAP endpoint as mentioned in section VIII of this blog here. Use the final URL created in this field.
    For S/4HANA Cloud system, open a communication arrangement of type SAP_COM_0008 and copy the inbound Services URL.
  6. Proxy Type: OnPremise for S/4HANA on-premise system / Internet for S/4HANA Cloud system or any other client reachable on internet. Additionally, a cloud connector setup would be required for OnPremise systems.
  7. If client system uses BasicAuthentication, set it’s Username and Password. Else if client system uses oAuth2, maintain the client system’s clientid,clientsecret and TokenServiceUrl.
  8. Click on Save. The final result should look like this.
  9. Repeat steps 3-8 and create the following destination:
      •  <businessSystemId>_BPCONFIRM (Confirmation Destination for BP)
      • <businessSystemId>_BPRELOUTBOUND (Outbound Destination for Relationship)
      • <businessSystemId>_BPRELCONFIRM (Confirmation Destination for Relationship)

    Optionally you can also configure :

      • <businessSystemId>_KMOUTBOUND (Outbound Destination for KeyMapping)
      • <businessSystemId>_KEYMAPCONFIRM (Confirmation Destination for KeyMapping)
        These interfaces are part of the Communication Arrangement SAP_COM_0539 and SAP_COM_0540 in S/4HANA Cloud.

IV. Subscription to Master Data Orchestration service

In the sub-account, click on “Service Marketplace” on the left side. Navigate to the tile Master Data Integration (Orchestration), select it, and click on Create. Inside the dialog, choose the standard plan, and click on Create once more.

V. Configuring access for Master Data Orchestration Fiori application

To view the Master Data Orchestration tiles, your user should have the necessary roles assigned.

  1. Under the Security dropdown on the left side, click on Role Collections. (You should have a Security Administrator authorisation to perform this step).
  2. Click on sign and create a new Role collection with the name MDOAdmin. Search for the role MasterDataOrchestrationAdmin & MasterDataOrchestrationDisplay to the role collection. Finally, add your user to the role collection.
  3. Once your user is assigned, go back to Instances and Subscriptions and click on “Go to Application”.
  4. You should now have access to all the Master Data Orchestration tiles.

VI. Creating Distribution Model for Business Partner Replication using SOAP Outbound

  1. Open the “Manage Distribution Model”.
  2. Provide a name for the model and select “ (sap.odm.businesspartner.BusinessPartner)” in the Business Object Type dropdown and mode as “PUSH”.
  3. Set the continuous distribution checkbox if you want the business partners to be replicated as soon as they are created/updated.
  4. Select the latest stable API : MDI_SOAP_BUSINESS_PARTNER as the provider interface.
  5. To create a Provider and Consumer, click the create button and select the provider: MDI
    Similarly for the consumer, select the relevant businessSystemId passed in the service instance. You can select the appropriate “Application Category” if required.
  6. Set Data filters if required.
  7. Select Key Mapping Distribution checkbox if key mapping replication is required from MDI to client using SOAP.
  8. Save and Activate the distribution model. You can now replicate Business Partners from SAP Master Data Integration service to client systems using SOAP.


Note :

<base_url> has to be replaced with uri from your service key.

<identity_zone> has to be replaced with uaa.identityzone from your service key.

  1. Checking if the Business Partner is replicated
    SAP MDI adopts the BP UUID of the sender system. If UUID is known


    SAP MDI also adopts the BP Number of the sender system. So, you can use the BP Number of the sender system for the GET request.

    <base_url>/businesspartner/v0/odata/API_BUSINESS_PARTNER/BusinessPartner?$format=json&$filter=BusinessPartner eq '<BP_Number>'

    Additionally, you can expand on an entity to see the details. For Ex:

    <base_url>/businesspartner/v0/odata/API_BUSINESS_PARTNER/BusinessPartner?$format=json&$filter=BusinessPartner eq '<BP_Number>'&$expand=to_Person

    This endpoint is OAuth2.0 protected. See step3 below to generate token.

  2. Accessing MDI Business Partner SOAP Endpoints using HTTP POST

    If using Basic Authentication. clientid is the username and clientsecret is the password. Both of the values are available in the service keys of the MDI Instance.
    If using OAuth2.0, tenantId query param is not needed. See step 3 below to generate token.

  3. To generate token using Postman Client with OAuth2.0 authenticated endpoints (using service key from section I above)

Assigned Tags

      You must be Logged on to comment or reply to a post.
      Author's profile photo Syambabu Allu
      Syambabu Allu

      Hi Manasi,

      It’s really informative blog..Thanks for sharing in detail.

      Thank you,


      Author's profile photo Ward Persyn
      Ward Persyn

      Hi Manasi Sridhar 

      Thank you for the useful blog!

      I have some questions regarding the API calls in Troubleshooting > 1. Checking if the Business Partner is replicated.

      When I do a GET call to the first API URL, with the correct region and BP guid, I get a 403 forbidden, with the error "Bearer error="insufficient_scope", error_description="The request requires higher privileges than provided by the access token.", error_uri="".

      I am not sure what causes this error, I used a new bearer token which is correct (a wrong one gives a 401). I recieved the token by used the client ID & secret of the S4-MDI instance, and the passcode retrieved with my SAP S-user account which has access to the subaccount where the MDI instance runs.

      If you have any idea, please reach out to me.

      Thanks in advance!


      Author's profile photo Manasi Sridhar
      Manasi Sridhar
      Blog Post Author

      The instance created should have authorities “$XSMASTERAPPNAME.BPCommonRead”, “$XSMASTERAPPNAME.BPSensitiveDataRead”. Use the service key from this service instance to access Odata endpoints. Please refer to point 3 in Troubleshooting section on how to generate token.

      Author's profile photo Rashmi Joshi
      Rashmi Joshi

      Hi Manasi,


      how to send master data from MDI to Ariba solution?

      can you please share configuration guide for this?

      also in s4h SpRO, I see MASTER DATA NATIVE INTEGRATION, here connection url should be CIG, then how will data move to MDI?


      thank you!


      Author's profile photo Manasi Sridhar
      Manasi Sridhar
      Blog Post Author

      Hi Rashmi,

      I do not have expertise in CIG/Ariba solution.

      This blog has information on MDI-side configurations related to SOAP integration for BP irrespective of connecting client/system.


      Manasi Sridhar

      Author's profile photo Syambabu Allu
      Syambabu Allu

      Hi Rashmi,

      If you are looking for supplier/BP data replication from S/4HANA CE to Ariba/CIG via MDI. Hope this guide will help you .

      Integrating Supplier Data from SAP S/4HANA Cloud with SAP Ariba Solutions Using SAP Master Data Integration | SAP Help Portal

      Thank you,


      Author's profile photo Rashmi Joshi
      Rashmi Joshi

      Thanks Syam, this is helpful!

      We will to push master data for Sourcing and Procurement as well from S4H to MDI to Ariba.

      please share relevant documents for the same if you have.


      also how to check master records in MDI?
      i know how to create instance in BTP for MDI. However Im not getting how to see posted records in MdI.

      please shed some light of knowledge here 🙂


      Thanks in advance!

      - RJ

      Author's profile photo Gregor Wolf
      Gregor Wolf

      Hi Manasi,

      do you know why SAP Master Data Integration is provided in the BTP Trial but SAP Master Data Orchestration isn't available? As I understood from your blog post SAP Master Data Orchestration provides the UI for administration. The service instances I can create for SAP Master Data Integration give me the connectivity for the different systems. Is that correct?

      Best Regards