Using OData to read territory information from C4C

[h_duengelhoef]

Summary

This document explains how one can read territory information via a remote interface from C4C.

The concrete customer use case is as follows: The customer uses C4C territory management to assign sales reps to customers. This information needs to be updated in the ERP customer master as well. Customers are replicated from ERP, so the ERP ids are known in C4C. Employees are not replicated from ERP. The E-Mail address is used as the identifying attribute to find the corresponding employees in ERP.

This document explains how to create an OData service in C4C that provides

• territories,
• the assigned customers together with their ERP ids,
• the assigned employee responsible together with his/her E-Mail address.

This document does not cover how to do the ERP updates. It was written based on a C4C 1605 release.

Author(s): Hermann Düngelhoef

Company: SAP AG

Author Bio

Hermann Düngelhoef works in SAP Cloud for Customer Product Management on Integration of Cloud for Customer with other SAP solutions like ERP, CRM or S/4HANA.

Definition of the OData service

C4C 1605 does not contain a standard remote interface to read territory information. But using the OData Service Explorer customers can define an OData service providing this information.

The OData service explorer is part of the administrator UI.

I created a new custom OData service  z_territory_customers_employees

I chose the work territory work center COD_TERRITORY_WCVIEW and selected the territory root object.

First I added some basic attributes from the root object which adds the root node to the right side.

Next step is to add the employee responsible of the territory to the OData service. Selecting the EmployeeResponsible in the left column brings up a pop-up. Simply click “Yes” here - and do this every time this pop-up comes up in the following steps.

Add the EmployeeID as an additional attribute, select the Employee sub node

and select the following nodes and fields to get the E-Mail address in:

Now the employee responsible part is covered.

Next step is to add the accounts for the territory. We just restrict to the C4C customer id and the ERP id. To do that you have to select the top node SalesTerritory in the right column and scroll down to the “Account” node.

Select it, then it gets added to the right column as “SalesTerritoryAccount”. In the left column select the CustomerID and the Customer node.

Scroll down to the ObjectIdentifierMapping node.

Select it and it gets added to the right column. Rename it to “CustomerIdMapping” in the lower right and select the basic attributes in the left column.

Now save and activate your service. With the activation, the service URL gets visible.

Now the OData service is created and ready to be used.

Sample C4C territory with accounts and employee responsible

Here is a sample data record, the sales territory with id 30

These are the details of the employee responsible Gerald Weber. Most relevant for this use case is the E-Mail address.

This is the list of the accounts that are assigned to this territory.

This is the detailed data for the first account 1001302. The external id is 755557

Call the OData service to get the data for the above territory.

Let’s use the OData service to read the data for the above territory. The URL to get the data for the territory with id 30 is

<YourServer>/sap/c4c/odata/cust/v1/z_territory_customers_employees/SalesTerritoryCollection?$filter=ID%20eq%20%2730%27&$expand=SalesTerritoryAccount/CustomerIdMapping

This URL has two parameters.

1. The first parameter “filter=ID%20eq%20%2730%27” is the URL encoded version of “filter=ID eq ‘30’”. This is to select the sales territory with id 30.
2. The second parameter “expand=SalesTerritoryAccount/CustomerIdMapping” takes care that the sales territory accounts and the ERP ids get expanded into the call result. Otherwise you would only see the basic data of the territory.

See below the result of launching the above URL in the browser. I used the XML flavor of OData (you can get the data in JSON format by adding “&$format=json” to the URL).

I highlighted the areas which are relevant.

• The “SalesTerritoryAccount section (first box) contains all the accounts assigned to the territory. We have a detailed look at the first customer record shown here.
• First subsection is the Customer ID mapping (second box)
• where you see the remote ID for the customer (third box).
• After that the basic data for the SalesTerritoryAccount follows where you see the customer id (fourth red box).

On the second screenshot I collapsed the SalesTerritoryAccount section (first box) to show the basic data for the territory that comes after that section. There you see the id (second box), name (third box) and the employee data, id and E-Mail address (fourth box).

Select updated territories

To update the ERP master data based on territory changes in C4C, it may make sense to select the C4C territories that were recently updated. This e.g. is the URL to get all territories that were updated after 2016-03-01 00:00:00:

<YourServer>/sap/c4c/odata/cust/v1/z_territory_customers_employees/SalesTerritoryCollection?$filter=LastChangeDateTime%20gt%20datetimeoffset%272016-03-01T00:00:00Z%27&$expand=SalesTerritoryAccount/CustomerIdMapping

The first filter is the URL encoded form of “filter=LastChangeDateTime gt datetimeoffset‘2016-03-01T00:00:00Z’”.

I didn’t check which updates exactly touch the LastChangeDateTime attribute of a territory, e.g. if a reassignment of accounts to a territory does this. Please test your specific use cases if they are covered by a selection on the LastChangeDateTime attribute.

Copyright

© 2016 SAP SE or an SAP SE affiliate company. All rights reserved.

No part of this publication may be reproduced or transmitted in any

form or for any purpose without the express permission of SAP SE.

The information contained herein may be changed without prior notice.

Some software products marketed by SAP SE and its distributors contain proprietary software components of other software vendors. National product specifications may vary.

These materials are provided by SAP SE and its affiliated companies (“SAP SE Group”) for informational purposes only, without representation or warranty of any kind, and SAP SE Group shall not be liable for errors or omissions with respect to the materials. The only warranties for SAP SE Group products and services are those that are set forth in the express warranty statements accompanying such products and services, if any. Nothing herein should be construed as constituting an additional warranty.

SAP SE and other SAP SE products and services mentioned herein as well as their respective logos are trademarks or registered trademarks of SAP SE in Germany and other countries.

Please see https://www.sap.com/corporate-en/legal/copyright/index.epx#trademark

for additional trademark information and notices.