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. 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 and provide an Instance Name. Click Next.
   
4. Use this JSON below to create the service instance.

   {
     "businessSystemId": "<businessSystemId>",
     "application": "<application>",
     "writePermissions": [
       {
         "entityType": "sap.odm.businesspartner.BusinessPartner"
       },
       {
         "entityType": "sap.odm.businesspartner.BusinessPartnerRelationship"
       }
     ],
     "xs-security": {
       "xsappname": "<Service-Clone-Name>",
       "authorities": [
         "$XSMASTERAPPNAME.BPCommonRead",
         "$XSMASTERAPPNAME.BPSensitiveDataRead"
       ]
     }
   }​

   – For businessSystemId, provide the logical system 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. You can use this link to generate a v4 UUID.

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

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 https://<<uaa.url>>/passcode with your preferred browser.

     

   •  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

    https://one-mds.cfapps.<region>.hana.ondemand.com:443/businesspartner/v0/odata/API_GENERIC_CONFIGURATIONS/GenericConfigurations​

  • 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. Username and Password for the endpoint on the client system.
8. Click on Save. The final result should look like this.
   
9. Repeat steps 3-8 and create the following destination:
   • •  <businessSystemId>_BPCONFIRM
     • <businessSystemId>_BPRELOUTBOUND
     • <businessSystemId>_BPRELCONFIRM

   Optionally you can also configure :

   • • <businessSystemId>_KEYMAPCONFIRM
     • <businessSystemId>_KMOUTBOUND
       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 “Instances and Subscriptions” on the left side. Search for the “Master Data Integration (Orchestration)” service and click Subscribe.

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. Activate the Distribution Model. You can now replicate Business Partners from SAP Master Data Integration service to client systems.

Troubleshooting

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

   https://one-mds.cfapps.<region>.hana.ondemand.com/businesspartner/v0/odata/API_BUSINESS_PARTNER/BusinessPartner(guid'<BP_GUID>')?$format=json

   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.

   https://one-mds.cfapps.<region>.hana.ondemand.com/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:

   https://one-mds.cfapps.<region>.hana.ondemand.com/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

   https://one-mds.cfapps.<region>.hana.ondemand.com:443/businesspartner/v0/soap/BusinessPartnerBulkReplicateRequestIn?tenantId=<identity_zone>
   
   https://one-mds.cfapps.<region>.hana.ondemand.com:443/businesspartner/v0/soap/BusinessPartnerRelationshipBulkReplicateRequestIn?tenantId=<identity_zone>
   
   https://one-mds.cfapps.<region>.hana.ondemand.com:443/businesspartner/v0/soap/BusinessPartnerBulkReplicateRequestConfIn?tenantId=<identity_zone>
   
   https://one-mds.cfapps.<region>.hana.ondemand.com:443/businesspartner/v0/soap/BusinessPartnerRelationshipBulkReplicateRequestConfirmIn?tenantId=<identity_zone>
   
   https://one-mds.cfapps.<region>.hana.ondemand.com:443/businesspartner/v0/soap/KeyMappingBulkReplicateRequestIn?tenantId=<identity_zone>
   
   https://one-mds.cfapps.<region>.hana.ondemand.com:443/businesspartner/v0/soap/KeyMappingBulkReplicateRequestConfirmIn?tenantId=<identity_zone>
   

   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)