Enhance version 10 of the SAP CRM groupware integration architecture by using the flexibility of SAP standard and non-standard offerings. Also pinpoint what can be enhanced based on the current groupware architecture.
Key Concept
Groupware integration server-side codes include an HTTP handler class to process the XMLs posted from a groupware integration client. In practical terms, enhancing the server-side code allows you to add company-specific business logic into the groupware’s standard function.
If your enterprise is considering or has completed an upgrade to SAP CRM 7.0 Support Package 9, the company will need to also use version 10 of the groupware integration. From the aspect of client-side architecture, version 10 offers useful changes in the UI and background service functions. Further details are available in this article’s companion piece, “Groupware Integration Enhancement: Decipher Version 10’s Client-side Architecture.”
Now I’d like to take the next steps by discussing version 10’s server-side architecture and the enhancement possibilities available to you. Taken in whole, my two articles allow you to understand the overall technical architecture in version 10 and review possible enhancement scenarios via a standard Business Add-In and other, non-standard ways.
Server-Side Architecture
The interaction point between the groupware integration client and the server is an HTTP service. Use transaction SICF and a filter based on CRM_ACT_GWSYNC (Figure 1). The client-side groupware integration software will post the XML to the HTTP service CRM_ACT_GWSYNC on the server.
Figure 1
SICF node for groupware integration
Double-click CRM_ACT_GWSYNC to see the class handler of the HTTP service. The class name is CL_CRM_XML_GW_SYNC (Figure 2), which is the central processing class of the groupware integration server and contains the business logic. This is also the class that handles the XML posted from the client-side groupware integration software. This is the key enhancement place that I discuss in the rest of the article.
Figure 2
Class handler for groupware integration
SAP Code on the Server Side
Use transaction SE24 and open class CL_CRM_XML_GW_SYNC. In class CL_CRM_XML_GW_SYNC, there are various processing methods (Figure 3). For example, when the groupware integration is uploading the contact person to SAP CRM, it calls method IF_CONTACTS~CREATE_CONTACT.
Figure 3
Class CL_CRM_XML_GW_SYNC
As I mentioned in my article, “Groupware Integration Enhancement: Decipher Version 10’s Client-side Architecture,” the XML files transfer the data between SAP CRM and a local machine. How would the above code in Figure 3 parse and process a XML posted by the groupware integration client? Let’s illustrate that via an example. Normally, the first XML the groupware integration client posts to the server during synchronization reads all the contact persons that belong to the user. It is sent based on the ContactReadRequestPrnTmpl.xml. Figure 4 shows a sample XML requesting a list of contact persons belonging to user ABCDEFG012345678091213231313 from SAP CRM. The content field is Raw, meaning that you only need to read a basic list, not the full detail, of the contact person.
Figure 4
Sample XML requesting a list of contact persons
To process the request:
- The HTTP service triggers standard HTTP handling method IF_HTTP_EXTENSION~HANDLE_REQUEST
- That method calls method CONVERT_XML2DOM to convert the XML posted into a tree of objects that can be processed by ABAP
- Then it calls method PROCESS_DOMTREE to process the object tree
- Method PROCESS_DOMTREE determines which XML template it is
- Method IF_CONTACTS~PROCESS_READ_REQ is called, which corresponds to ContactReadRequestPrnTmpl.xml
- The IF_CONTACTS~PROCESS_READ_REQ method reads each field on the first level and triggers corresponding method for the next level XML node
Table 1 shows the actual calling sequence to get the contact person belonging to the user.
In method IF_CONTACTS~GET_CONTACT_KEYS and some of the subordinate methods, the SAP system uses a standard function module and table to retrieve the contact person data that is called. This is how the groupware integration finally is integrated with SAP CRM data. The contact person that SAP CRM is trying to retrieve by standard is based on the BUR001 (contact person) relationship and BUR011 (responsible employee). You can override BUR011 by configuration, for example, if you changed your BUR011 relationship from one contact person to another contact person. The SAP system only retrieves the new contact person in the XML and prompts you to delete the old contact person from your local machine. This logic still works the same as the former version of the groupware integration.
At the time the SAP system gets the contact person from SAP CRM, it also posts the response back to the XML message. Figure 5 shows the actual XML SAP post back to the groupware integration client software. It contains a list of contact persons belonging to the user and the last modified data.
Figure 25
Example of code to enhance the standard application
SAP Tables on the Server Side
SAP CRM has one set of tables storing the profile information (Figure 6). The profile controls the behavior of the groupware integration client synchronization (e.g., the default server name, client, and whether each value can be overwritten by the user in the Maintain Synchronization Settings application in the start menu).
Figure 6
Profile Settings
In addition to the profile table, SAP CRM has another two important tables for CRMD_ACT_SYEXC and CRMD_ACT_SYHST. When you synchronize contact persons, you have the ability to add certain contact persons into an exception list, meaning the contact persons are not synchronized again (Figure 7). Table CRMD_ACT_SYEXC stores the exception list for each table. In case certain contact persons are not synchronized to a user, you can check this table to see whether a contact person has already been added to the exception list.
Figure 7
Add to Exception List function
As an example, if you find that one contact person in Lotus Notes is supposed to upload to SAP CRM but constantly does not show up, check Table CRMD_ACT_SYEXC. Figure 8 shows that for user DEF9435F650EC4F18E0700237D625906, the system skips contact person A92 (Lotus Notes internal key to identify the contact person record) during synchronization with groupware. GWCLNT TYPE refers to whether the client is Lotus Notes or Outlook. The ENTITY TYPE field refers to whether it is a contact person or activity.
Figure 8
Table CRMD_ACT_SYEXC
If you still need to upload contact person A92 to SAP CRM via groupware, you can still select the checkbox for Temporarily include exception list entries, which is in the Maintain Synchronization Settings application, to process the contact person in the exception list again (Figure 9).
Figure 9
Temporarily include exception list entries box is checked
CRMD_ACT_SYHST is another important table because it contains all the synchronization history between the groupware client and the server. The SAP system uses the information in this table to calculate whether SAP CRM contains a newer image of the contact person and activities or the client groupware integration contains a newer image. Based on the timestamp stored in CRMD_ACT_SYHST, groupware integration overwrites the data in SAP CRM or overwrites the data in the mail client.
Figure 10 shows that a contact person has been synchronized with SAP CRM. The contact was created in Lotus Notes on November 5, 2010, and was uploaded to SAP CRM on March 17, 2011. An interesting point: The GWCLNT ACT TIMST field is stored in the local time zone to avoid misunderstanding the meaning of the field. The timestamp in the table entry is of extreme importance. It is used to calculate whether SAP CRM or Microsoft Outlook/Lotus Notes contains the newest data. It is also used to determine whether synchronization is needed for the existing data.
Figure 10
A contact person synchronized with SAP CRM
Table 2 shows the meaning of important fields for the synchronization history table.
Synchronization Architecture
The client-side groupware integration exchanges data with the server via XML. However, what in detail will happen during synchronization? Which XML is used in what sequence? Let’s use a contact person synchronization as an example to explain the whole process.
Put a break point in class cl_crm_xml_gw_sync method IF_HTTP_EXTENSION~HANDLE_REQUEST. Monitor the variable lv_xstring, which contains the XML request from groupware client at the beginning of the method. At the end of the method, the variable contains the response send from SAP CRM back to the groupware.
During synchronization, the groupware client tries to download the latest profile based on the current user first (Figure 11). This helps in case there is an updated profile.
Figure 11
Profile XML
Then the groupware client tries to read all the contact persons belonging to the current user (Figure 12). For now, the XML response only contains the header information (i.e., the contact person GUID and the change timestamp).
Figure 12
Contact Request XML
Figure 13 shows the contact person GUID and the timestamp that SAP CRM sent back to groupware client in XML format.
Figure 13
Contact Read Response XML
Now the groupware tries to read all the synchronization records after the last time the groupware synced (Figure 14). The synchronization records are stored in table CRMD_ACT_SYHST.
Figure 14
Sync History XML
The contact person header XML and synchronization history XML are used to get the data to calculate whether synchronization is needed and whether SAP CRM contains the latest image. Based on the calculation, the groupware client will send SAP CRM the contact person it needs in detail (Figure 15).
Figure 15
Contact Detail Request XML
SAP CRM sends back the contact person detail in the same XML format (Figure 16).
Figure 16
Contact Detail Response XML
The groupware client display lets the user confirm which contact person will be synchronized after the above steps. After the user confirms (the user can also choose to not sync for specific records or change the direction of synchronization), groupware sends the final contact person detail to SAP CRM to create or change the contact person (Figure 17).
Figure 17
Contact Person Write XML
It also sends the synchronization detail to SAP CRM (Figure 18). This completes the whole synchronization process for the contact person scenario.
Figure 18
History Update XML
To check all the XMLs transferred during the synchronization, go to directory C:Documents and SettingsXXXX(user name)Local SettingsApplication DataSAP AGClient GroupwareSyncLogsSync20110316055959(synchronization time) (Figure 19).
Figure 19
Synchronization XML Log
Enhancement Options
After discussing how to synchronize Version 10 of the client-side groupware integration with SAP CRM, I now want to discuss options to enhance the framework and explain what features you can enhance.
SAP standard BADI
Let’s explore SAP note 1499833, which gives a standard option to enhance the groupware interface. The first BADI SAP provides is CRM_GWI_CONTACT_REQUEST, which contains two methods you can implement. One method (DELETE_CONTACT_REQ) prevents the deletion of a contact person in SAP CRM when the contact is deleted from a mail client. Another method (CREATE_CONTACT_FIELD_CHECK) provides the capability to do mandatory checks at the time of synchronization and issue error message (Figure 20). CREATE_CONTACT_FIELD_CHECK also allows you to change the data posting from the XML, providing a spot in which you can manipulate the data according to your business needs. You can simply change the data in parameter CS_DATA and CS_DATA_PERSON in the BADI implementation of method CREATE_CONTACT_FIELD_CHECK. The two parameters include many important fields for contact persons.
Figure 20
Performing mandatory checks
The DELETE_CONTACT_REQ method is triggered in method IF_CONTACTS~DELETE_CONTACT, class CL_CRM_XML_GW_SYNC. CREATE_CONTACT_FIELD_CHECK is triggered from method IF_CONTACTS~CHANGE_CONTACT and IF_CONTACTS~CREATE_CONTACT in class CL_CRM_XML_GW_SYNC. So the method DELETE_CONTACT_REQ covers all the create/change contact person scenarios.
There are still some limitations on this Business Add-In (BAdI). The only data you can manipulate is the fields in structure BAPIBUS1006_CENTRAL (i.e., you are not able to manipulate any address information or communication data). In addition, the only way you can send a response to the user is by issuing an error message. You cannot post data to an XML response freely. In summary, Version 10 provides several BAdIs for adding in company-specific business logic, but limitations also hinders users from enhancing the framework freely.
A PDF guide attached to SAP note 1499833 provides sample code and detailed explanation of the BAdI. If you are going to use the BAdI, the PDF guide is a good starting point.
Additional Enhancement Options
There are other ways to enhance the framework, including a custom program. As you already know, the client groupware integration software posts to transaction SICF node (Figure 21). Should you create a new Z node to replace the SAP standard SICF node?
Figure 21
SICF nodes
I don’t suggest creating a new Z SICF node because the node name (crm_act_gwsync) is not set by the groupware integration profile or any configuration, but instead set by the Windows registry entry. Figure 22 shows the URL that the groupware uses to communicate with CRM is https://[1]/sap/crm/crm_act_gwsync?sap-client=[2]. If you try to create a new Z SICF node, you need to change the local Windows registry entry on every machine using the groupware to something like https://[1]/sap/crm/ZNODE?sap-client=[2], which is not feasible in most cases.
Figure 22
Registry entry showing HTTP node
Other than creating a Z SICF node, another way to enhance the groupware integration framework is to replace the standard HTTP handler class with a new Z class (Figure 23).
Figure 23
Replace SICF handler class with Z class
The new Z class should inherit the old class and should only override the needed method (Figure 24). That way the newest code can still be adopted from SAP notes/upgrade.
Figure 24
Z class inherits the standard class
Let’s say you not only store the contact person in the SAP standard table, but you also want to push some contact persons stored in the Z table to the groupware client. The first step is to redefine the method IF_CONTACTS~GET_CONTACT_KEYS. This method can retrieve all the contact persons belonging to the current user. Review the XMLs transferred between groupware integration and SAP CRM as discussed before. The sample code in Figure 25 gives you an idea how you may enhance the standard application. It is not the full code to implement the function to push the contact person from Z table to the GWI client. You need to redefine other methods like IF_CONTACTS~GET_CONTACT_DETAILS in a similar manner.
Figure 25
Example of code to enhance the standard application
Please read the related sidebar, “Q&A: Using Enhancements and Server-side Architecture,” for further information about technical architecture and enhancement options in a questions-and-answers format.
Q&A: Using Enhancements and Server-side Architecture
Many server-side technical architecture and enhancement options are available. Let’s discuss some examples in a question-and-answer format:
Q: Suppose users upload too much junk data to SAP CRM. I want to add another staging area between SAP CRM and groupware so that when the groupware uploads contact person data to SAP CRM, it should first be uploaded to a Z table. Then I can choose which records to post from the Z table. Is that possible?
A: Yes, but there are many things to consider in this requirement. First, you need to create a Z class that inherits the standard class CL_CRM_XML_GW_SYNC. Second, override all the write and read methods in the class. Whenever it writes, it writes to the Z table. Whenever it reads, it reads from the Z table plus the SAP standard table. Third, include a timestamp in the Z table, since the timestamp is important to calculate whether groupware or SAP CRM contains the newest image. Finally, review the XML during the synchronization to make sure you provide each XML enough data. Some of the XML is easy to miss. For example, the contact person data is provided to the groupware via two XMLs. One contains only the contact person GUID and timestamp. The other contains the contact person full detail data. The whole staging scenario may take several months to develop based on the detail requirement.
Q: I want to perform more validation checks on a contact person uploaded. For example, I don’t allow a blank email in a contact person. And I want the error message to be displayed in the synchronization screen of the groupware. Is that possible?
A: Yes. Although there is no place to enhance on the groupware synchronization screen, your requirement is not to change the screen, but instead to change the data displayed in the screen. Look at the contact write XML for an error section. The error section is actually passed from SAP CRM to the groupware and then displayed in the groupware synchronization screen. So what you need to do for this requirement is basically to pass more errors in the XML. If the field you want to validate is inside the interface of BADI CRM_GWI_CONTACT_REQUEST method create_contact_field_check, use the BAdI to fulfill the requirement. If the field you want to check is something like email, you need to override the method IF_CONTACTS~CHANGE_CONTACT_HOME_ADDRESS of class CL_CRM_XML_GW_SYNC. Both methods contain a return parameter et_return. You can add your own error message to the et_return parameter. The et_return will be populated to the XML response via the groupware framework code.
Q: Suppose some enhancement has occurred in groupware, but the data did not change as expected. What are the most common steps to trouble shoot?
A: From the technical architecture you should understand the log/debug place in each framework. First, check the log as shown in Figure 19. You want to check whether the data passed to or out of SAP is the same as you expected. Second, put a breakpoint CL_CRM_XML_GW_SYNC~ IF_HTTP_EXTENSION~HANDLE_REQUEST to check the XML conforms to the XML you see in the log. Third, put a breakpoint in a lower level method that you have enhanced (e.g., IF_CONTACTS~CHANGE_CONTACT_HOME_ADDRESS) to check whether there is any problem in the code.
Q: Let’s say there are some additional fields in a local contact person address book that SAP groupware integration doesn’t support. Is there a way to transfer this to SAP CRM?
A: Even though this sounds like a valid and common requirement, it is not possible. The XML templates used by SAP are all predefined. There is no way to add more fields in the XML. Also, the retrieving logic of the contact person from the local mail client is inside the .net synchronization application and there is no way to change that aspect. The only work-around is to find some unused fields already supported by SAP, (e.g., the Notes field). Give that field a different business meaning. When synchronizing, you can get the field from XML and post it to a different field on the server.
Q: What should you do if a requirement can’t be met by the existing enhancement approach?
A: I have seen clients develop their own private groupware solution. It can take at least several months to develop a simple solution. But if the requirement is strong, that is also an achievable alternative.
Hansen Chen
Han (Hansen) Chen is a manager with PricewaterhouseCoopers’ SAP CRM practice. He has more than seven years of experience in the SAP CRM field and has finished more than 10 SAP CRM projects, on most of which he played a technical lead role. His project management experience includes managing more than 10 onsite/offshore developers and managing multiple project development teams in parallel. Han holds a PMP certification and has profound knowledge of CMMI methodology. He earned his bachelor’s degree in MIS from Tongji University, China.
You may contact the author at han.chen@us.pwc.com.
If you have comments about this article or publication, or would like to submit an article idea, please contact the editor.
