(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": [
               "$XSMASTERAPPNAME.BPCommonRead",
               "$XSMASTERAPPNAME.BPSensitiveDataRead"
           ]
       }
   }

   – 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.

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.

    <base_url>/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. 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.

Troubleshooting

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 

   <base_url>/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.

   <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

   <base_url>/businesspartner/v0/soap/BusinessPartnerBulkReplicateRequestIn?tenantId=<identity_zone>
   <base_url>/businesspartner/v0/soap/BusinessPartnerRelationshipBulkReplicateRequestIn?tenantId=<identity_zone>
   <base_url>/businesspartner/v0/soap/BusinessPartnerBulkReplicateRequestConfIn?tenantId=<identity_zone>
   <base_url>/businesspartner/v0/soap/BusinessPartnerRelationshipBulkReplicateRequestConfirmIn?tenantId=<identity_zone>
   <base_url>/businesspartner/v0/soap/KeyMappingBulkReplicateRequestIn?tenantId=<identity_zone>
   <base_url>/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)