Administration Guide. SAP CRM Groupware Connector 7.0. SAP CRM 5.0 (as of SP09) SAP CRM 5.2 SAP CRM 2007 SAP CRM 7.0 (Including Enhancement Packages)

Transcription

1

2 Administration Guide SAP CRM Groupware Connector 7.0 SAP CRM 5.0 (as of SP09) SAP CRM 5.2 SAP CRM 2007 SAP CRM 7.0 (Including Enhancement Packages) Target Audience Consultants Administrators Public Document version 1.7 March 2016

3 Copyright 2013 SAP AG or an SAP 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 AG. The information contained herein may be changed without prior notice. Some software products marketed by SAP AG and its distributors contain proprietary software components of other software vendors. National product specifications may vary. These materials are provided by SAP AG and its affiliated companies ("SAP Group") for informational purposes only, without representation or warranty of any kind, and SAP Group shall not be liable for errors or omissions with respect to the materials. The only warranties for SAP 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. AG in Germany and other countries. Please see for additional trademark information and notices. Disclaimer Some components of this product are based on Java. Any code change in these components may cause unpredictable and severe malfunctions and is therefore expressively prohibited, as is any decompilation of these components. Any Java Source Code delivered with this product is only to be used by SAP s Support Services and may not be modified or altered in any way. Documentation in the SAP Service Marketplace You can find this documentation at the following Internet address: service.sap.com/crm-inst SAP and other SAP products and services mentioned herein as well as their respective logos are trademarks or registered trademarks of SAP

4 Typographic Conventions Icons Type Style Description Icon Meaning Example Text Words or characters quoted from the screen. These include field names, screen titles, pushbuttons labels, menu names, menu paths, and menu options. Caution Example Note Recommendation Cross-references to other documentation Syntax Example text EXAMPLE TEXT Example text Example text Emphasized words or phrases in body text, graphic titles, and table titles Technical names of system objects. These include report names, program names, transaction codes, table names, and key concepts of a programming language when they are surrounded by body text, for example, SELECT and INCLUDE. Output on the screen. This includes file and directory names and their paths, messages, names of variables and parameters, source text, and names of installation, upgrade and database tools. Exact user entry. These are words or characters that you enter in the system exactly as they appear in the documentation. Additional icons are used in SAP Library documentation to help you identify different types of information at a glance. For more information, see Help on Help General Information Classes and Information Classes for Business Information Warehouse on the first page of any version of SAP Library. <Example text> Variable user entry. Angle brackets indicate that you replace these words and characters with appropriate entries to make entries in the system. EXAMPLE TEXT Keys on the keyboard, for example, F2 or ENTER.

5 Administration Guide: SAP Groupware Connector Contents 1 Introduction Architecture of Connectors Microsoft Exchange Connector Lotus Domino Connector Multi-Connector Landscape Data Exchange Using Message Queues Mapping of SAP CRM Entities and Groupware Entities Security Considerations Preparation CRM parameters SOAP Runtime Handler for RFC SOAP HTTP Handler for RFC Preparation for Microsoft Exchange Connector Preparing Administrative Account Set up Exchange Impersonation Set up Exchange Auto Discover Service Set up Exchange Public Folder Permissions Installing Microsoft Outlook Preparing a Public Folder for Storing SAP CRM Contacts Using the Contacts Folder as the Address Book in Microsoft Outlook Preparation for Lotus Domino Connector Preparing an Administrative Account Preparing the Database for Storing CRM Contacts Installing Lotus Notes Client Upgrade to 7.0 SP XX Connector from a Lower Version/SP Configuration Parameters in the Administrative Tool Groupware Configuration Configuring Groupware Server Connection Options for Microsoft Exchange Configuring Groupware Server Connection Options for Lotus Domino Groupware Adapter Connection Queue (User) Maintenance Performance Logging Proxies Configuring Proxies User Statistics March

6 Administration Guide: SAP Groupware Connector 6 Batch-Assigning Access Rights for Domino Connector Microsoft Outlook Categories Connector Logging Information Connector Log File Error Log File Trace Log File Troubleshooting the Connector Verifying Connection to the Payload Interface Resolving Payload Interface Errors Verifying the Connection to Groupware Server Connection to Microsoft Exchange Server Connection to Lotus Domino Server Error Details Diagnostics Tool Tool for Microsoft Exchange Connector Tool for Lotus Domino Connector Backup Plan March 2016

7 1 Introduction This guide describes the administrative tasks that a system administrator must perform after the installation of the SAP Groupware Connector (hereafter referred to as groupware connector ). This guide includes information about the following: Communication between the groupware connector and the groupware adapter Preparation of the groupware server and CRM settings Configuration of the groupware connector and its proxies Assignment of access rights for groupware Managing a master categories list Logging and troubleshooting Experience with typical groupware administrative tasks is required for preparing groupware servers for integration. March

8 2 Architecture of Connectors The groupware connector synchronizes messages between the SAP CRM server and the groupware server, using a messaging interface. It consists of the following components: Groupware connector Groupware connector proxy The number of installed instances of groupware connector proxies depends on the following: Geographical distribution of the organization and wide area network (WAN) landscape Desired performance of the solution Internal communication between the connector and its proxies is optimized to consume as little network traffic as possible, thus supporting distributed solutions where proxies provide a link to remote groupware servers. The overall performance of the solution greatly depends on the configured landscape, particularly for greatly distributed organizations. Performance is optimized if proxy instances do not communicate with remote groupware servers. The simplest configuration is when the groupware connector and one instance of the groupware connector proxy per organization are installed on the same server in the same local area network (LAN) as SAP CRM. This configuration is easiest to maintain, but has the lowest performance. In a distributed organization, SAP recommends that you set up a separate proxy instance within each remote LAN. This will provide much better performance and will dramatically reduce wide area network (WAN) usage, since calls between connectors and proxies are optimized to use as few network resources as possible. Proxy instances can be installed or removed after the initial setup is performed. For more information about the required environment (software and hardware requirements) for the groupware connector, see the SAP CRM Groupware Connector Installation Guide. 8 March 2016

9 2.1 Microsoft Exchange Connector The groupware connector for Microsoft Exchange Server is a.net VC++ application, usually running as a Windows service under an administrative account. For data synchronization, another administrative account, SAP Groupware Admin is required, which must be assigned with permissions to read and write into other users' mailboxes and public folders on the Microsoft Exchange Server. The groupware connector for Microsoft Exchange Server uses Exchange Web Services (EWS) Managed API 2.0 to connect to the Microsoft Exchange Server. The figure below shows the communication between the components: The groupware connector communicates with SAP CRM via the groupware adapter. The connector uses Simple Object Access Protocol (SOAP) over HTTP or.net 4 over HTTPS (depending on the connector version) to communicate with the adapter. The groupware connector uses Exchange Web Services (EWS) for communication with the Microsoft Exchange Server. You must install the groupware connector and the Microsoft Exchange Server in the same domain. March

10 2.2 Lotus Domino Connector The groupware connector for Lotus Domino is a Java application that uses Lotus Notes libraries during the processing. The connector usually runs as a Windows NT service, supported by a small application called CustomService.exe. This application starts Java as a child process with proper parameters set. The groupware connector for Lotus Domino uses the Lotus Domino toolkit for Java/CORBA to connect to the Lotus Domino Server. The figure below shows the communication between the components: The groupware connector communicates with SAP CRM via the groupware adapter. The groupware connector uses RMI for communication with the Lotus Domino server. You must install the groupware connector and the Lotus Domino server in the same domain. Installation of the groupware connector and proxy requires the Lotus Notes client to be on same machine. In case of remote proxy, each proxy must have a Lotus Notes client on the same machine. 10 March 2016

11 2.3 Multi-Connector Landscape In the lower versions of groupware connector, it was restricted to have only one groupware connector connected to a single CRM system in the production scenario. Typically most of the organizations have a significant number of mail servers distributed in different geographic locations. To cover all of the mail servers and to reduce the latency during data exchange, we now have more than one groupware connector connecting to a single CRM groupware adapter in close proximity to the exchange/domino servers. In groupware connector 7.0, data exchange from a single CRM system with multiple connectors, which are in turn mapped to separate groupware servers, is enabled via a Multi-Connector scenario. CRM side corrections, CRM side settings and AdminTool configuration are necessary to enable a multi-connector scenario. For more information, refer to SAP Note Multi-Connector scenario works with Connectors of version 7.0 and not between a 5.0 Connector and a 7.0 Connector. Filter criteria: any field in the ADRC table can be provided in the GWAFILTAB table under the column FIELD and provide a relevant entry for SIGN, OPT and LOW columns. The following figure shows the communication between the components in a multi-connector landscape: March

12 Replication from SAP CRM to Groupware The groupware adapter gets a set of changed messages from the user s storage, distributes the users among the installed groupware connectors and puts them into respective data queues. The groupware connector periodically reads the active queue list and starts the Inbound Messages Processor if there are messages available. The groupware connector accepts the list of the active queues appended with the corresponding connector instance name as configured in the AdminTool. Inbound Messages Processor goes through all queues sequentially and reads the messages one-by-one, posting them to the groupware server. The IDs of the newly created messages are posted into the CMW_PIF_ID_QUEUE queue. In case of processing errors, the queue for the user is locked for a predefined interval and an error notification is posted into the CMW_PIF_PROTOCOL queue. Replication from Groupware to SAP CRM The groupware adapter provides a list of users whose data is intended for replication from groupware to SAP CRM via the UserList.xml file. In multiple connector scenarios, the groupware adapter distributes the user list among the connector instances based on ADRC filter criteria maintained in the GWAFILTAB database table for each connector instance. For example, if there are 1000 users (300 users for IN country and 700 users for DE country) in the CRM user storage, and there are 2 connector instances with the instance names AIN and ADE. The groupware adapter distributes the data of IN country users to the connector instance AIN, and the data of DE country users to the connector instance ADE. Thus, users are load balanced between the connector instances. The groupware connector goes through all storages sequentially of the users provided in the list and replicates changes to SAP CRM one-by-one, by posting the messages into the user s data queue in the groupware adapter. Limitations The GWAFILTAB table should be maintained appropriately to enable the Multi-Connector scenario, failing which the connector will behave as a single connector. In order to prevent the overloading of groupware connector systems, a request for UserList.xml, AppList.xml and CatsList.xml will not be placed from the groupware connector system to the CRM system. The automatic download of these xml files will be replaced by the report REQUEST_USERLIST in the CRM system which fills the outbound queues for each connector with appropriate data. For loading the Public Contacts, during the initial load of the BUPA_MAIN object from CRM to groupware, maintain the block size of the object BUPA_MAIN to 1 in transaction R3AC3. Data filtering must be done on each business partner in case of multi-connector scenarios and as a result this setting is required. The SITE_ID maintained in table GWAFILTAB should be the same as the value maintained for the Connector ID (CRM Adapter connection Advanced) field in the AdminTool. No two groupware users should have the same ID. If there are 2 groupware connectors in a landscape (one with a country filter value = DE, and another one with a country value not equal to DE), a user with country DE will be present in the user list of groupware connector1. If the address of the user changes to a value not equal to DE, then the user will be present in the UserList.xml of connector2 also. The change in address will not delete the user from the UserList.xml of connector1. This is currently a limitation as there is no delete BDOCs created in the CRM system. You can overcome this in one of the following ways: 12 March 2016

13 1. Remove the role (maintained in SPRO for GWEMPL) for the user before changing the address and assign the role GWEMPL after the address change. 2. Rename UserList.xml in the connector system and run the report REQUEST_USERLIST in the CRM system after the address is changed. This will populate the UserList.xml in all the connector systems. March

14 2.4 Data Exchange Using Message Queues Data exchange is organized using a data-queue pattern: The groupware adapter provides the message queues, and the groupware connector fetches messages from the queues to get the operations to be performed and to exchange data items from SAP CRM to groupware. The groupware connector puts the messages into queues to exchange data items from groupware to SAP CRM. The groupware adapter provides a predefined set of system queues and a variable number of data queues (separate queue for each user). The system queues are as follows: System Queues _ISP_QFILLED CMW_PIF_ID_QUEUE CMW_PIF_PROTOCOL USER_LIST* CATS_LIST Description (Read Only) Groupware adapter provides a list of currently filled queues from SAP CRM. (Write Only) Groupware connector posts the IDs of the newly created messages in groupware server storage. This updates the mapping between SAP CRM and groupware items on the groupware adapter side. (Write Only) Groupware connector posts error notifications into this queue. (Read Only) Groupware adapter provides a list of users whose data is intended for replication from groupware to SAP CRM. Usually the queue name will be USER_LIST if the landscape is not a multi-connector one. In a multi-connector scenario the queue name will be appended with the connector ID. For example, if a Connector ID AIN for the users in India exists, then the queue name would be USER_LIST_AIN. (Read Only) Groupware adapter provides a list of categories that are used to distinguish the items/messages in the groupware server storage to be replicated via the groupware connector. 14 March 2016

15 Data flow for two-way replication is shown in the following figure: Replication from SAP CRM to Groupware The groupware adapter gets a set of changed messages from the user s storage and puts them into data queue. The groupware connector periodically reads the list of the active queue and starts the Inbound Messages Processor if there are messages available. Inbound Messages Processor goes through all queues sequentially and reads the messages one-by-one, posting them to the groupware server. The IDs of the newly created messages are posted into the CMW_PIF_ID_QUEUE queue. In case of processing errors, the queue for the user is locked for a predefined interval and an error notification is posted into the CMW_PIF_PROTOCOL queue. Replication from Groupware to SAP CRM The groupware adapter provides a list of users whose data is intended for replication from groupware to SAP CRM via the UserList.xml file. The groupware connector sequentially goes through all storages of the users provided in the list and replicates changes to SAP CRM one-by-one, by posting the messages into the user s data queue in the groupware adapter. For both replication directions, each successful replication operation is listed in a log file. Short descriptions of any errors are written into an error log file. Error details and information about the groupware connector s operations are provided in a trace log file. March

16 2.5 Mapping of SAP CRM Entities and Groupware Entities For every mailbox user on groupware whose entities should be synced from SAP CRM to groupware and vice versa, the groupware user should have a valid Business Partner with the Groupware Employee role in the CRM system. The standard communication address of this Business Partner should be the Primary SMTP address of the user. Only if the address and the groupware employee role are maintained correctly, will the user have an entry in the UserList.xml which provides the list of users for data replication. The following table shows the equivalency between entities in SAP CRM and a Microsoft Exchange server: SAP CRM Business partner Activities or tasks from resource planning Activities or appointments from resource planning Microsoft Exchange Contact: Contacts folder in user s mailbox (private contacts) Public folder (public contacts) Task: Tasks folder in user s mailbox Appointment, meeting: Calendar folder in user s mailbox The following table shows the equivalency between entities in SAP CRM and a Lotus Domino server: SAP CRM Business partner Activities or tasks from resource planning Activities or appointments from resource planning Lotus Domino Contact (person): User s private contact database (private contacts) Public contacts database (public contacts) To do entry: User s mail database: to-do frameset Calendar entry (appointment): User s mail database: calendar frameset 16 March 2016

17 3 Security Considerations Like all other server applications, the groupware connector should be well-protected against external access in order to maintain corporate security on an acceptable level. The security configuration recommendations for the groupware connectors are similar to recommendations for other server-side software. The groupware connector requires comprehensive authorizations for the special administrative account in the groupware server, allowing read/write/delete access to user mailboxes. Due to requirements for the server software to be run as a service, the administrative account name and password must be stored on the connector host in a file. To protect user/password information on the host computer, the host should be located in a locked room with monitored access. Keep the rights for login to the system to a minimum. The administrator can change the attributes of config.xml, and mwpayload.wsdl files to Hidden, for better file protection (Microsoft Exchange connector only). Do not use the word "admin" as the administrator account name. Use a name that does not imply authorizations. The administrator password must satisfy a stringent password policy, with regard to length and content. It should be changed regularly. Replace the Everyone group with a restricted number of users on the server's file shares. Never assign the Everyone group access to a file share on the connector host. Shutdown services are not necessary. Make sure that terminal services, Internet information services, and remote access services are disabled on the server. It is often convenient to enable terminal services to allow remote control functions for the help desk or administering servers, but you must make sure that it is properly configured. Enable auditing. The most basic form of intrusion detection for Windows is to enable auditing. This will alert you in case of changes to the account policies, attempted password attacks and unauthorized file access March

18 4 Preparation Groupware server should be prepared before configuring the Connector and Proxies. Details of the CRM system is necessary, these parameters should be kept ready before configuring the Connector and Proxies. Installation of Connector and Proxies should be complete. Refer to the SAP Groupware Connector 7.0 Installation Guide in the SAP Service Marketplace under service.sap.com/crm-inst. SAP Notes that are relevant for the SAP groupware 7.0 release are as follows. Implement these Notes to work with groupware connector 7.0: SAP Groupware Connector 7.0 SP02 - Release Information Note Groupware connector fixes Groupware multiple connector support For information about CRM customizing, see the SAP Library for SAP Customer Relationship Management in the SAP Help Portal at <choose a release> Application Help <choose a language> Data Exchange and Mobile Technologies Groupware Integration Server-Based Groupware Integration. 18 March 2016

19 4.1 CRM parameters This section describes how to find the parameters required for configuring the connection to the groupware adapter. The connection between the groupware connector and the SAP CRM system is established via Web services in SOAP protocol. The connector supports the following options: SOAP Runtime Handler for RFC (available for Lotus Domino and Microsoft Exchange). This is the recommended connection method and is available as of connector version 5.0 and supported for SAP CRM 2007 and above. SOAP HTTP Handler for RFC (available only for Microsoft Exchange) SOAP Runtime Handler for RFC To activate and configure the necessary Web services, do the following (see SAP Note ): 1. In SAP CRM, call transaction SE Select the package CMW_MAPBOX_FW. 3. Expand the folder Enterprise Services Service Provider. 4. Double click on the service provider INTSYNC_PAYLOAD_IF. 5. Click Edit and add the short description Webservices for Groupware Integration. 6. Save and activate your changes. 7. In SAP CRM, call transaction SOAMANAGER. 8. SAP CRM 7.0 and lower releases: Click the Single Service Administration link. From SAP enhancement package 1 for CRM 7.0 onwards: Click the Web Service Configuration link. March

20 9. Search for the service INTSYNC_PAYLOAD_IF. 10. Create the end points S_LEVEL_1, S_LEVEL _2 and S_LEVEL_3 for the service INTSYNC_PAYLOAD_IF. The service name is case-sensitive and should be created as shown below: Once you have created the end points, they are displayed as follows: 20 March 2016

21 11. Make settings for S_LEVEL_1 as shown below: 12. Make settings for S_LEVEL_2 as shown below: March

22 13. Make settings for S_LEVEL_3 as shown below: 22 March 2016

23 14. Go to the Overview tab page and select the required end point in the Select Binding field. 15. Select the link Open WSDL document for selected binding or service to generate the wsdl file. 16. Go to last section of this file and, as the required end point/binding, use the value of the CRM URL from the tag soap:address location. For the Lotus Domino connector, you also need to save this wsdl file. After installation, copy this file to the Connector folder of the installation directory and rename it to GWNewWebService.wsdl. An empty file with the same name exists in the Connector folder and can be replaced by this file SOAP HTTP Handler for RFC Determine the HTTP/HTTPS URL of the SOAP Listener Find the host name and port for the HTTP/HTTPS server as follows: 1. In SAP CRM, call transaction SMICM and choose Goto Services. 2. Note the values for Host Name and Service Name/Port for the HTTP/HTTPS protocol, as shown below. This forms part of the URL as follows (depending on the protocol that you want to use): Name]:[Service Name/Port] Or Name]:[Service Name/Port] Determine the Relative Path of the SOAP Listener 1. In SAP CRM, call transaction SICF and choose Execute. 2. Expand the tree to locate the SOAP node (usually found under default_host sap bc soap rfc). The path below the default_host node (sap/bc/soap/rfc) forms the rest of the URL address, resulting in a URL with the following format (depending on the protocol that you want to use): Name]:[Service Name/Port]/sap/bc/soap/rfc or Name]:[Service Name/Port]/sap/bc/soap/rfc March

24 You obtain the user name, password, client and language of the SAP CRM system from the system administrator. 24 March 2016

25 Optional: Select SSL for HTTPS Protocol 1. Access transaction SICF (Maintain Services), ensure that SERVICE is entered in the Hierarchy Type field, and click Execute. 2. Expand the node default_hostsap bc soaprfc. 3. Double-click on rfc. The Create/Change a Service screen appears. 4. Go to the tab page Logon Data and click Change. 5. In the section Security Requirements, select SSL. 6. Save and click Back. March

26 4.2 Preparation for Microsoft Exchange Connector Preparing Administrative Account The groupware connector for Microsoft Exchange Server requires an administrative account, SAP Groupware Admin, with following access permissions: Groupware Administrator account must be assigned Exchange Impersonation rights. Each user (mailbox) to be synchronized must be assigned to the role Groupware Employee in the CRM system. Read/write access for the public folder that stores the public contacts. The administrative account which is used as the logon information for the groupware connector s Windows service (see the Log On tab in service properties) need not be SAP Groupware Admin account. You must run the installation routine using the administrative user account that will be used for running the groupware connector service. For the installation, the user account must belong to the local administrators group. The mailbox alias used in the installation settings must correspond to the same user. To create a new account to be used as the administrative account for the groupware connector, follow the steps below. If you want to use an existing account, use the steps below as a reference to ensure that the correct settings are made. 26 March 2016

27 Microsoft Exchange In Active Directory Users and Computers, create a user without a mailbox. 2. Enter details for the user: 3. In the Exchange Management Console, create mailboxes and connect users to them. Note that mailboxes created in the Exchange Management Console have a proper SMTP address. Mailboxes created in Active Directory Users and Computers, however, have a blank primary e- mail address (the account cannot send and receive ). March

28 a. Expand Recipient Configuration. b. Right-click on the Mailbox container, and choose Enable Mailbox. c. In the Exchange Mailbox wizard, choose Select, select a user, and choose Finish. 28 March 2016

29 Microsoft Exchange In Active Directory Users and Computers, create a user without a mailbox. 2. Enter details for the user: 3. Open Exchange Admin Center 2013 via the web console and logon with the administrator user. March

30 4. Create new mailboxes: 5. Enter the correct details of the new user mailbox. Note that the created mailboxes have a proper SMTP address. 30 March 2016

31 March

32 Microsoft Exchange Online (Office 365) 1. Logon to Microsoft online portal. In the admin dashboard, click on Add users, reset passwords and more under users & groups. 2. Click on the + sign to add a new user. 3. Enter the user details and click on Next. 32 March 2016

33 4. Click on Yes to provide Administrator permissions and assign appropriate roles for the user. March

34 4.2.2 Set up Exchange Impersonation Exchange Impersonation enables a caller to impersonate a given user account. This enables the caller to perform operations by using the permissions that are associated with the impersonated account, instead of the permissions that are associated with the caller's account. It is inherently designed for one-to-many mailbox access, which means that there is less configuration complexity and overhead for managing new users that need to be added to the application scope. An administrator is able to configure impersonation on behalf of a service account, and grant that service account impersonation rights over many mailboxes. Individual users cannot manage who does or does not have impersonation rights over their mailboxes. For the Office 365 landscape, impersonation rights should be provided as mentioned in the Microsoft documentation at Microsoft Exchange 2010 and 2013 You can use the New-ManagementRoleAssignment Exchange Management Shell cmdlet to assign the ApplicationImpersonation role to users in the organization. When you assign the ApplicationImpersonation role, use the following parameters of the New- ManagementRoleAssignment cmdlet: Name The friendly name of the role assignment. Each time you assign a role, an entry is made in the RBAC roles list. You can verify role assignments by using the Get- ManagementRoleAssignment cmdlet. Role The RBAC role to assign. When you set up Exchange Impersonation, you assign the ApplicationImpersonation role. User The impersonating identity. CustomRecipientScope The scope of users that the impersonating user can impersonate. The impersonating user will only be allowed to impersonate other users within a specified scope. If no scope is specified, the user is granted the ApplicationImpersonation role over all users in an organization. You can create custom management scopes using the New- ManagementScope cmdlet. The following prerequisites are required to configure Exchange Impersonation: Administrative credentials for the computer that is running Exchange 2010 that has the Client Access server role installed. Domain Administrator credentials, or other credentials with the permission to create and assign roles and scopes. Remote PowerShell installed on the computer from which you will run the commands. To configure Exchange Impersonation for all users in an organization: 1. Open the Exchange Management Shell. 2. Run the New-ManagementRoleAssignment cmdlet to add the permission to impersonate to the specified user. The following example shows how to configure Exchange Impersonation to enable a service account to impersonate all other users in an organization: New-ManagementRoleAssignment Name:impersonationAssignmentName Role:ApplicationImpersonation User:serviceAccount To configure Exchange Impersonation for specific users or groups of users: 1. Open the Exchange Management Shell. 2. Run the New-ManagementScope cmdlet to create a scope to which the impersonation role 34 March 2016

35 can be assigned. If an existing scope is available, you can skip this step. The following example shows how to create a management scope for a specific group: New-ManagementScope Name:scopeName RecipientRestrictionFilter:recipientFilter 3. Run the New-ManagementRoleAssignment cmdlet to add the permission to impersonate the members of the specified scope. The following example shows how to configure Exchange Impersonation to enable a service account to impersonate all users in a scope: New-ManagementRoleAssignment Name:impersonationAssignmentName Role:ApplicationImpersonation User:serviceAccount CustomRecipientWriteScope:scopeName This feature offers access to groupware user mailboxes with minimal configuration by the Exchange administrator. For more information about configuring Exchange Impersonation, see March

36 4.2.3 Set up Exchange Auto Discover Service This section is not applicable in an Office 365 landscape. The Auto Discover Service (SOAP) provides a mechanism that allows you to automatically configure Exchange 2010 client applications to access the Client Access server by using SOAP as the messaging framework for messages sent between the client application and the Exchange server. If you do not configure the external URL values, the Autodiscover service information provided to the Microsoft Office Outlook 2007 or Outlook 2010 clients may be incorrect for users who are connecting from outside your network. They may be able to connect to their Exchange mailbox. However, they won't be able to use Exchange features such as Automatic Replies, the Availability service, Unified Messaging, or offline address book downloads. Generally, the internal URL is configured by Exchange Setup. However, the external URLs must be configured by using the virtual directory cmdlet for each component. In the following cmdlet, CASServerFullName should be replaced with the Client access server instance fully qualified name. Get-AutodiscoverVirtualDirectory -server CASServerFullName Set- AutodiscoverVirtualDirectory -ExternalUrl ' -InternalUrl ' /Autodiscover/Autodiscover.xml' Test the Auto Discover Connectivity This example tests that the Outlook provider settings for the Autodiscover service are configured correctly on the Client Access server CASServer01. Test-OutlookWebServices -ClientAccessServer "CASServer01" For more information about the Autodiscover Service, see 36 March 2016

37 4.2.4 Set up Exchange Public Folder Permissions This section is optional but required if your organization wants to synchronize the public contacts from Exchange. You can configure public folder permissions for administrators or for users of client programs such as Microsoft Outlook. Public folder permissions consist of various access rights that specify the level of control that a client user or administrator has over a public folder or public folder hierarchy Microsoft Exchange 2010 and 2013 There are two methods by which a user is granted the permissions to administer public folders: Public Folder Management role group: Adding the user to the Public Folder Management role group is similar to assigning the Public Folder Administrator role in Exchange It grants the user all of the permissions necessary for managing public folders. Run the following cmdlet using the Exchange management shell. This example adds TestUser to the Public Folder Management role group: Add-RoleGroupMember -Identity "Public Folder Management" -Member TestUser PublicFolderAdminstrativePermission cmdlet set: Using these cmdlets is more granular and gives you the ability to specify the scope for the user in the organization by modifying the database's access control lists (ACLs). Adding permissions to a specific folder also requires that the user has the correct Role Based Access Control (RBAC) permissions assigned so that they can access the public folder cmdlets. This example adds AllExtendedRights permissions for TestUser to access the public folder Marketing and all of the public folders under it. Add-PublicFolderAdministrativePermission -Identity "\Marketing" -User "TestUser" -AccessRights AllExtendedRights -InheritanceType SelfAndChildren For more information on public folders, see Microsoft Exchange Online (Office 365) The Public folder can be configured via the Outlook client. The Public folder should be of type Contact. You can use Exchange Control Panel (ECP) to provide permissions for an administrative user on this Public folder Installing Microsoft Outlook Microsoft Exchange 2010 and 2013 Microsoft Exchange 2010 and 2013 can be configured to work with Microsoft Outlook 2007, 2010, and Outlook can be installed on the machine where groupware connector is installed. March

38 4.2.6 Preparing a Public Folder for Storing SAP CRM Contacts This section is optional if you do not want to synchronize contacts. This section describes how to configure the public folder for storing public contacts. Any public folder that conforms to the following requirements can be used to store public contacts: The folder is for Contact Items. Read/write permissions are granted to the groupware connector administrative account Microsoft Exchange 2010 and 2013 During installation of Microsoft Exchange 2010, select the option Yes under Client Settings. This ensures that Microsoft Exchange 2010 creates a public folder, which is required by the connector. For information about creating public folders in Microsoft Exchange 2010 and 2013, refer to the documentation in the Microsoft Developer Network Using the Contacts Folder as the Address Book in Microsoft Outlook You can use the Contacts folder on the Microsoft Exchange Server as a part of the address book in Microsoft Outlook. For more information, see the Microsoft Outlook Help. The Microsoft Outlook address book is a configuration on the client. You must configure it on every client computer. You register a public folder in the Microsoft Outlook address book as follows: 1. To enable the service, add a Microsoft Outlook address book to the user profile: a. In the Tools menu, select accounts. b. Select View or change existing directories and address books and click Next. c. Ensure that Outlook Address Book is listed. If is not, click Add and select Addition Address Books. Click Next and select Outlook Address Book. d. Restart Microsoft Outlook. 2. Set up the Contacts folder to be displayed in the Address Book dialog box: a. If the Folder List is not visible, choose Go and then Folder List. b. In the Folder List, right-click on the contacts folder that you want to display in the Address Book dialog box and select Properties. c. Go to the Outlook Address Book tab. d. Select the Show this folder as an Address Book checkbox. e. Enter the name for the contacts folder that you want to appear under Show names in the Address Book dialog box. A contact item must have an entry in the field or the fax phone number field to appear in the Outlook Address Book. 38 March 2016

39 4.3 Preparation for Lotus Domino Connector Preparing an Administrative Account Before starting the groupware connector Installation Wizard, you must set up an administrative account. To create a new account as the administrative account for the groupware connector, follow the steps below. If you want to use an existing account, use the steps below as a reference to ensure that the correct settings are made. Refer to the Help documentation for Lotus Domino Administrator for more information on setting up Lotus Notes users. 1. Start Lotus Domino Administrator and navigate to the People & Groups tab. 2. Expand the public address book, right-click on People, and select Register Person Select the Advanced checkbox. 4. Enter the user information and click Password Options to set the password as an Internet password. 5. Click Done and then click Register. 6. Grant access permission to the administrative account in all relevant mailboxes. To do so all Lotus Notes users need to add the account for the groupware connector into the access control list (ACL) of their database, as follows: a. Start the Lotus Notes client. b. Right-click on the database and select Database Access Control. c. In the Access drop-down list, select Editor access level as a minimum. Make sure that the Delete documents checkbox is selected. March

40 In Lotus Domino it is possible for the administrator to grant access permissions for multiple databases simultaneously. Refer to the Help documentation for Lotus Domino Administrator for more information on editing entries in multiple ACLs. This operation requires the following access privileges: Full access administrators, Administrator, Database administrator. Refer to the Help documentation for Lotus Domino Administrator for more information on restricting administrator access. The installation of the groupware connector for Lotus Domino includes the custom ACLRights utility for batch assignment of database access permissions. For more information, see the SAP Groupware Connector Administration Guide (section Batch-Assigning Access Rights for Lotus Domino Connector) at service.sap.com/crminst Preparing the Database for Storing CRM Contacts The groupware connector for Lotus Domino replicates public contacts into a dedicated database. You must perform the following steps to prepare the database: 1. Create the database using the personal address book template. 2. Register the database in the public address book. 3. Determine the SMTP address of the database to be used when configuring the target for public contacts during the setup routine. Create a New Database and Grant Access for the Administrative Account 1. Start Lotus Domino Administrator. 2. Choose File Database New 3. Provide the necessary information in the pop-up. 40 March 2016

41 Do not use file names that are not longer than the 8.3 filename convention unless the operating system on which the Lotus Domino server runs supports longer file names. Do not select the option Inherit future design changes. 4. Grant access permission to the database for the administrative account for the groupware connector, as follows: a. Go to the Files tab. b. Right-click on the newly-created database and choose Access Control Manage c. Add the administrative account of the groupware connector to the Access Control List, select Person as the User type and choose Designer as the Access authorization. Make sure the Delete documents option is checked. d. Assign Reader access for the Default user and all other users of the type Person that are displayed in the Access Control List. Check that Read public documents is the only option enabled for the users. March

42 The groupware connector must have rights to add, change, and delete contacts in the contacts database. The connector must have the permission to change some elements of the design, such as the prefix and the suffix of the contact name. Designer access rights permit these actions. 42 March 2016

43 Register the Database in the Public Address Book 1. Start the Lotus Domino Administrator. 2. Go to the People & Groups tab, expand the address book and select Mail-In Database & Resources. 3. Click Add Mail-In Database in the right-hand pane. 4. On the Basics tab enter the Mail-in name, Domain, Server, File name, and Internet Address. Determine the SMTP Address of the Database To obtain the SMTP address of the database you must form a string from the name and domain as follows: <name>@<domain>. By default, the name part of the SMTP address is the value that you entered in the Mail-in name field when registering the database in the public address book. To obtain the domain part, refer to the global domain document. To create and register the global domain document, do the following: 1. Select the Configuration tab. 2. Expand the Messaging group. 3. Select Domains. 4. Click on Add Domain and specify the details (select the domain type Global Domain). March

44 The newly-created global domain is displayed as follows: 5. For the replication of private contacts, enable synchronization of personal contacts into the mail file of the users Installing Lotus Notes Client The groupware connector for Lotus Domino uses an API provided by the Lotus Notes client to access the Lotus Domino server. When installing the Lotus Notes client, make sure that it uses the administrative account of the groupware connector. 44 March 2016

45 4.4 Upgrade to 7.0 SP XX Connector from a Lower Version/SP The upgrade option is not available in the groupware connector installer, you will have to uninstall the previous version/sp of groupware connector and install the latest SP of 7.0 groupware connector. If groupware server is migrated from Domino to Exchange, make sure that the users mailbox is migrated correctly and the custom properties and values of the appointments, tasks, and contacts are retained after migration. Every synced activity or contact will have a unique BDoc ID representing the object in CRM and will have an UID representing the object in the groupware server. These IDs are required to determine whether the object is new or already synced. Steps to be followed when you are upgrading to 7.0 Connector from a lower version: Refer to the SAP Groupware Connector 7.0 Installation Guide in the SAP Service Marketplace under service.sap.com/crm-inst.to install the latest SP of Connector 7.0. Configure the connector and proxy instances using the AdminTool as described in 5 Configuration Parameters in Administrative Tool. In the AdminTool, follow the steps below to configure the proxies such that the replication is done for the objects of any age: o AdminTool.exe o In Proxies/General select a proxy o Click on Edit Proxy Configuration o Under Replication/Groupware CRM, choose the of any age option from the dropdown lists for all of the fields under Replicate Changes. This setting can be changed to any desired level at a later date. Keeping this setting at a lower value and changing it later will cause inconsistencies. Then start the connector and proxy services for data synchronization: o In the groupware server migration from Domino to Exchange Server scenario, previously synced items will have a BDoc ID mapped to the UID of the corresponding item in Domino server. On synchronization, this item is fetched using the BDoc ID and maps it with a new UID corresponding to that item in the Exchange server. In the groupware server migration from Domino to Exchange scenario, if there were any items deleted which were still not synced, those entries will not be deleted when the services are started. Such items should be deleted again. March

46 5 Configuration Parameters in the Administrative Tool The configuration of the groupware connector and its proxies is predefined by SAP and can be changed in the SAP groupware connector AdminTool. This tool updates configuration files with new options and the groupware connector tracks the changes in these configuration files and updates the behavior as required, during processing. You access the tool by logging on to the groupware connector system using the administrative account and starting the AdminTool.exe file, which can be found in the installation folder under Connector. You must right click on AdminTool.exe and select Run as Administrator to start it. Depending on whether you use Microsoft Exchange or Lotus Domino, the tool offers slightly different settings. The following graphic shows the start page for the Microsoft Exchange connector: The following graphic shows the start page for the Lotus Domino connector: 46 March 2016

47 Power User Mode Some expert settings can only be accessed if power user mode is switched on. Select the Power User Mode checkbox in the bottom left area of the window and choose Yes in the Confirm window. March

48 5.1 Groupware Configuration Configuring Groupware Server Connection Options for Microsoft Exchange Groupware Configuration/General You can change the server name, domain, user name, password and either the address of the administrative account or the Exchange web service end point URL. Page Area/Field Groupware Server Explanation Specifies the name or IP address of the groupware server. This option is not available for an Office 365 landscape. Groupware Domain Mail server Version Use Windows Default Credentials Name Password Enable Auto Discover Specifies the domain of the groupware server. Specifies the version of the Exchange server. Select this option if the access to the Exchange Server is to be made via the Windows Default Credentials of the local administrative account where the connector is installed. To use this option, the local administrator account credentials must be the same as the exchange web services administrative account. SAP recommends that you use this option to avoid the DPAPI encryption issues for remote proxies. This option is not available for an Office 365 landscape. Specifies the name of the Exchange service administrative account. Specifies the password of the Exchange administrative account. Select this option if you do not know the Exchange Web service End Point URL. This option is set as the default for an Office 365 landscape. Provide the address of the administrative account. This address will be used to determine the Exchange web service end point URL. 48 March 2016

49 Service End Point URL Auto Discover Domain (available from Connector 7.0 SP 03 Patch 01) Specifies the Exchange Web Service End Point URL. This option is not available for an Office 365 landscape. Specifies the Auto Discover Domain. Microsoft recommends certain ways for load balancing and one of it is to install the auto discover service on a domain other than the Exchange. For example: if the exchange domain is outlook.company.org, the autodiscover domain may be autodiscover.company.org, in this case you will have to enter in this field. For more details, refer the following link Leave this field blank if the Exchange domain and the Autodiscover domain are same. You can use Test Connection button to check the connection to Microsoft Exchange Server with the parameters you entered. If the connection succeeds, then the connection status will be displayed as Connection OK, otherwise it will be displayed as Connection Failed Groupware Configuration/MS Exchange Specific This page provides the same functionality that is available on the Log On tab of Windows service properties. Page Area/Field Additional Internet Domains Explanation You can provide the list of additional organization domains in addition to the domain account of the administrative account. March

50 Folder for public contacts Service Authentication Enable Check on End Date Specify the name of the public folder which is to be used for public contact synchronization and this can be any folder under public folder root directory. To synchronize public contacts, the Exchange Service administrative account must be assigned to the public folder management role group. You can find this information in the Windows service properties: Start Run services.msc right click on service Properties Log On tab. If you want to change the Microsoft Exchange logon information, you can make changes to the account credentials here. This option is available from Patch5. Upon selecting this and choosing the end date only those appointments which are later than the end date will be synchronized. This feature is not available for Lotus Connector. Note that the same value has to be selected both at the Connector and Proxy for the end date Configuring Groupware Server Connection Options for Lotus Domino Groupware Configuration/General You can change the global domain, the administrative account s password, and the address of public contacts for groupware. Page Area/Field Groupware Server Lotus Domino Global Domain Explanation Specifies the name or IP address of the groupware server. The name of the global domain document in the Lotus Domino public address book. 50 March 2016

51 Administrative Account Default Recipient Mail-ID (SMTP) Specifies an administrative account used by the connector to access the groupware storage. Specifies the default mail ID of the target for data messages. This should be the mail-in database for storing public contacts. March

52 Groupware Configuration/Lotus Domino Specific Page Area/Field Occurrences Per Endless Recurrence All-Day Events Use Broadcast for Sending Requests Create New Instead Of Update Explanation Default number of occurrences for a recurring appointment without a specified end date. This setting is only supported if you are using SAP Workforce Management. Specifies the start and end time for all-day events replicated from SAP CRM. SAP recommends that you set the start time and end time to 00:00. If you select this option you do not get responses from attendees upon sending meeting requests or updates. If you do not select this option you get responses. Determines how the groupware behaves when an update for a meeting comes from SAP CRM. If you do not select this option, existing items are updated. Only the meeting time and location can be updated this way. SAP recommends that you do not select this option. If you select this option previous instances are deleted and new ones are created in their place. Attendees receive a cancellation and new invitation. All properties are regenerated. Priority of Miscellaneous Fields Gives the order of using miscellaneous fields available in the contact form since Lotus Notes 8.0. By default, a meeting request will be sent to invitees. Invitees have to accept it before the meeting is entered in their calendar. To enable direct calendar entry in the attendee's calendar, use the autoprocessing settings provided in Lotus Notes client or Domino server. 52 March 2016

53 5.2 Groupware Adapter Connection CRM Adapter Connection/General The connection between the groupware connector and the SAP CRM system is established via web services in the SOAP protocol. You can modify the groupware adapter connection here. You can use the Test button to validate your new parameters by attempting to connect to the selected CRM server. The result of the connection attempt will be shown next to the Test button as Connection OK or Connection Failed. The connector supports the following options: SOAP Runtime Handler for RFC (available for Lotus Domino and Microsoft Exchange) This is the recommended connection method and is available as of connector version 5.0 and supported for SAP CRM 2007 and above. For more information, see SAP Note SOAP HTTP Handler for RFC (available only for Microsoft Exchange). CRM SOAP Processor: SOAP HTTP Handler for RFC Not available for Lotus Domino connector 7.0 Page Area/Field URL User, Password Client, Language SSL / HTTPS Explanation Specifies the HTTP URL to the SOAP processor of the groupware adapter. Contact your SAP CRM administrator for this information. Specifies the user name and password for connection to the groupware adapter. Contact your SAP CRM administrator for this information. Specifies client options for connection to the groupware adapter. Contact your SAP CRM administrator for this information. Use SSL If this option is selected, the connection takes place by login/password using SSL. Use Client Certificate If this option is selected, the connection takes place using SSL and client certificate created by your system administrator (browse to locate the file in your local file system). March

54 CRM SOAP Processor: SOAP Runtime Handler for RFC (Recommended) For Microsoft Exchange connector, the window looks as follows: For Lotus Domino connector, the window looks as follows: Page Area/Field URL User, Password SSL / HTTPS Explanation Specifies the HTTP URL to the SOAP processor of the groupware adapter. Contact your SAP CRM administrator for this information. See SAP Note Specifies the user name and password for connection to the groupware adapter. Contact your SAP CRM administrator for this information. Use SSL If this option is selected, the connection takes place by login/password using SSL. You also must provide a certificate, as described below in Further Steps to Set Up SSL. Use Client Certificate If this option is selected, the connection takes place using SSL and the client certificate created by your system administrator (browse to locate the file in your local file system). 54 March 2016

55 You can use Test button to check the connection to CRM Server with the parameters you entered. If the connection succeeds, then the connection status is displayed as Connection OK, otherwise it will be displayed as Connection Failed. Further Steps to Set Up SSL Export the SAP CRM server certificate and import it into the groupware connector system as follows: Export Certificate from SAP CRM 1. Log on to the SAP CRM WebClient UI. 2. In the Web browser, click Security Report (to the right of the URL field) and choose View certificates. 3. On the Details tab, click Copy to File 4. In the Certificate Export Wizard select DER encoded binary X.509 (.CER). 5. Browse to a location in the groupware connector system where you want to save the certificate and click Next, then Finish. Import Certificate into Groupware Connector System 1. Right-click on the certificate file and choose Install Certificate. 2. Select Place all certificates in the following store and select Trusted Root Certification Authorities. For the Lotus Domino connector, you need an additional certificate, which you provide as follows: Export Certificate from SAP CRM 1. Log on to the SAP CRM WebClient UI. 2. In the Web browser, click Security Report (to the right of the URL field) and choose View certificates. 3. On the Certification Path tab, select the root node (certificate) in the Certificate path section. 4. Click View Certificate and go to the Details tab. 5. Click Copy to File 6. In the Certificate Export Wizard select DER encoded binary X.509 (.CER). 7. Browse to a location in the groupware connector system where you want to save the certificate and click Next, then Finish. Import Certificate into Groupware Connector System 1. Right-click on the certificate file and choose Install Certificate. 2. Select Place all certificates in the following store and select Trusted Root Certification Authorities. Import Certificate into Java Runtime Environment Import the certificate into the certificates file named cacerts which resides in the security properties directory java.home/lib/security (java.home is the directory of the Java runtime environment. You do this as follows: 1. Use the command prompt to browse to the bin folder of the Java runtime environment directory. 2. Enter the following command: C:\Program Files\Java\jre6\bin>keytool -importcert -trustcacerts - keystore "C:\Program Files\Java\jre6\lib\security\cacerts" -file "<certificate file with path>" -alias "<alias>" 3. Copy the wsdl file generated after applying the SAP Note to the Connector folder and rename it as GWNewWebService.wsdl. An empty file with the same name exists in the Connector folder and can be replaced by this file. March

56 CRM Adapter Configuration/Advanced For Microsoft Exchange Connector, the window looks as follows: Page Area/Field Connector ID Explanation If the connector is in a multi-connector landscape (many connectors mapped to a single CRM system), specify a connector name that is available in the table GWAFILTAB. Connector names (SITE_ID) and their filter conditions (FIELD, SIGN, OPT, LOW) are maintained in the GWAFILTAB table. Connectors can be different from each other based on any field from address table ADRC. Data is replicated to each connector based on the filter conditions maintained in the table GWAFILTAB, where the filter conditions are applied by organizer of task/appointment or on the business partner in case of public contacts. Maintaining the table GWAFILTAB with appropriate filter conditions and specifying the Connector ID (value for SITE_ID in GWAFILTAB) here in the AdminTool will enable the multi connector behavior. If there are no entries in the table GWAFILTAB and no connector name is specified here in the AdminTool then it is a single connector scenario (only one connector is mapped to one CRM system). Do not remove Users from User list upon Network Failure In a multi connector scenario the request for Userlist.xml, Applist.xml will not be triggered from groupware connector but will be done via the REQUEST_USERLIST report, which will extract the users to the appropriate connectors (based on a filter in GWAFILTAB). For the report, refer to SAP Note While performing an initial load of BUPA_MAIN from CRM to the GWA_01 site, set the block size to 1 in transaction R3AC1. In multiple connector scenarios the data has to be distributed by applying the filter condition for each record. Select this option if you do not want to remove a user from the user list when the network fails to connect to the user s mailbox. 56 March 2016

57 Never Delete Users from user list Update Groupware users master category list Select this option if you do not want the invalid user entries to be automatically removed from the user list file. Select this option if you want to update the master category list of the users present in the user list with the categories present in the Catslist.xml file. For Lotus Domino Connector, the window looks as follows: Page Area/Field Connector ID Explanation If the connector is in a multi-connector landscape (many connectors mapped to a single CRM system), specify a connector name that is available in the table GWAFILTAB. Connector names (SITE_ID) and their filter conditions (FIELD, SIGN, OPT, LOW) are maintained in the GWAFILTAB table. Connectors can be different from each other based on any field from address table ADRC. Data is replicated to each connector based on the filter conditions maintained in the table GWAFILTAB, where the filter conditions are applied by organizer of task/appointment or by the business partner in case of public contacts. Maintaining the table GWAFILTAB with appropriate filter conditions and specifying the Connector ID (value for SITE_ID in GWAFILTAB) here in the AdminTool, will enable the multi connector behavior. If there are no entries in the table GWAFILTAB and no connector name is specified in the AdminTool, then it is a single connector scenario (only one connector is mapped to one CRM system). In a multi connector scenario, the request for Userlist.xml, and Applist.xml will not be triggered from groupware connector but will be done via the REQUEST_USERLIST report which will extract the users to the appropriate connectors (based on a filter in GWAFILTAB). For the report, refer to SAP Note While performing an initial load of BUPA_MAIN from CRM to the GWA_01 site, set the block size to 1 in transaction R3AC1. In multiple connector scenarios the data must be distributed by applying the filter condition for each record. March

58 Dump Xmls To (only available in power user mode) Select this option if you want all incoming and outgoing queues from and to the CRM Middleware to be logged in XML files. One XML file is created per item. Specify the folder name where the XML files will be saved. The standard folder is XmlDump which is located in the installation folder under Connector. Huge number of XMLs is generated during data synchronization; SAP recommends that you do not select this option. 58 March 2016

59 5.3 Queue (User) Maintenance Queue (User) Maintenance/Lock Options You can only change the settings if power user mode is enabled. Page Area/Field Lock Timings For Failed Queues Queue Errors Processing Explanation Messages must be processed in strict order as they come into the queue for a user (the second message cannot be processed until the first one has been processed). If processing errors occur, the queue is locked for the time intervals, in seconds that are specified here. If you enter 60, 1200, 3600, or the first attempt to process messages again after an error takes place after 60 seconds. If the error still occurs, the next attempt is taken after 1200 seconds, and so on. When the last attempt has taken place, the queue will be locked. Some errors can be ignored when processing data messages. Error information can be logged without the queue being locked. Regardless of which options you choose, error messages are written to the error and trace logs that are available in the logs folder under the installation folder under Connector. Ignore Required Fields If you select this option, incorrect XML messages coming from SAP CRM are skipped automatically and the user queue is not locked. Incorrect messages (for example, where required fields are not filled) are lost. Ignore All Errors If you select this option, any kind of error during processing of messages in the direction SAP CRM to groupware is ignored. SAP recommends that you do not select this option. Ignore Internal Errors If you select this option, any kind of error during generation of messages for sending from groupware to SAP CRM will be ignored. March

60 Queue (User) Maintenance/Current Locks The groupware connector locks the users data queues in case an error occurs during processing. You can check for currently locked queues here. Select a queue and click Explain to get an explanation of the error case by its code and get short problem resolution guidelines. Double -click the entry to get extended information about the error condition: 60 March 2016

61 To unlock a queue (or multiple queues) select the queue(s) and do one of the following: If the queue-lock error is resolved, click Unlock to unlock the queue If the queue-lock problem cannot be resolved and you want to skip the first erroneous message, click Unlock & Accept. The queue is unlocked and the first message in the queue is forcibly accepted. Information about queue locks is automatically reset when the connector is restarted. March

62 5.4 Performance Performance/General In power user mode, you have the option to make settings related to the performance of the groupware connector; however, SAP recommends that you do not change the default settings. Page Area/Field Notify Queue Interval (sec) Notify Queue Retry Interval (sec) Maximal Number Of Messages Per Cycle Number Of Inbound Workers Maximum memory usage value (in MB) (available from Connector 7.0 SP 03 Patch 02) Explanation The groupware connector queries the groupware adapter for the list of queues filled with data. This option specifies the interval, in seconds, between recurrent calls when there are no filled queues. A notify queue call to pick up messages from the queue can fail, for example, due to network problems, or if the groupware adapter is not available. You can specify the interval before the next notify queue call in case of failure. Specifies the maximum number of messages to be processed for a queue for each complete logon session between SAP CRM and groupware. Specifies the number of simultaneous inbound worker threads in the groupware connector. Each worker thread can process one user queue at any time. More threads provide better performance but put more load on the groupware connector system, network, and groupware adapter. If you want to increase the number of threads, make sure your hardware supports this. Specifies the maximum memory allocated (in MB) for the connector service. Groupware Connector service will be restarted once this threshold is reached. Default value is 500 MB. You can configure this value as per your requirements. 62 March 2016

63 5.5 Logging Logging/General For Microsoft Exchange Connector, the window looks as follows: Page Area/Field Enable Groupware Connector Logs Log Directory Basic Log Enable Settings Visible Messages Severity Dump Middleware Failure Messages Explanation Select this option if you want information with respect to the synchronization to be logged into the log files. If you enable the Connector Logs, you can choose the directory where the Log files will be generated. The groupware connector supports the following types of log files: Error file This file will have information about errors that have occurred. EWS Trace file This file will have information about communication between the Connector and the Exchange web service. Crash Trace file If there are any crash errors, the same will be logged into this file. Connector Trace file This will have information with respect to the working of the Connector service (communication with CRM and with the proxy services). Information is logged to the trace file depending on the severity level that you specify. Lower severity values can be used to reduce the size of the trace file, higher severity values are used to get very detailed information about the errors. This option is available for Trace log and EWS trace log. The groupware connector sends information about errors to the groupware adapter. Such failure messages can be logged to the local disk before being sent to the groupware adapter. March

64 Dump Middleware Xmls Dump EWS Soap Xmls Select this option if you want all the incoming and outgoing queues from and to the CRM Middleware to be logged in XML files. One XML file is created per item. Huge number of XMLs is generated during data synchronization; SAP recommends that you do not select this option. Select this option if you want all the requests being sent via Exchange web services to the Exchange server and the corresponding responses from the Exchange server to be logged in XML files. Huge number of XMLs is generated during data synchronization; SAP recommends that you do not select this option. For Lotus Domino Connector, the window looks as follows: Page Area/Field Log files Visible Messages Severity Dump Failure Messages To Explanation The groupware connector supports the following types of log files: Log file Error file Trace file If you enable any of these files, you can choose a location for the files to be stored. Information is logged to the trace file depending on the severity level that you specify. Lower severity values can be used to reduce the size of the trace file, higher severity values are used to get very detailed information about the errors. The groupware connector sends information about errors to the groupware adapter. Such failure messages can be logged to the local disk before being sent to the groupware adapter. 64 March 2016

65 Logging / Limits For Microsoft Exchange Connector, the window looks as follows: Page Area/Field Connector Log History Limits Explanation If the Delete Connector Logs checkbox is checked then the groupware connector will automatically delete old log files according to the specified number of days in the Delete Log Folders after setting. For Lotus Domino Connector, the window looks as follows: March

66 Page Area/Field History Limits Split Trace File By Fragments Of Explanation The groupware connector can automatically delete obsolete log files according to the specified maximum age for each type of log file: Log file Error file Error dumps Trace file The trace file can become very large, depending on the severity level set in the General settings. You can limit the maximum size of the trace file to the specified number of Megabytes. 66 March 2016

67 5.6 Proxies Proxies/General For Microsoft Exchange, the window looks as follows: For Lotus Domino, the window looks as follows: Page Area/Field Proxy ID Host Servers Explanation ID of the proxy as provided by the administrator. The name of the system on which the proxy instance is running. For Microsoft Exchange: The server to which the proxy is connected. For Lotus Domino: Nothing is displayed. March

68 You can do the following in this window: Task Register new proxy instance View or modify custom options of the proxy instance Unregister a proxy View or modify default options for all proxy instances Mark the proxy instance as default Action Click the Add New Proxy button on the toolbar and provide its property in the popup. See the section below for details on proxy configuration. Double-click the proxy or select the row and click the Edit Proxy Configuration button on the toolbar. Select the proxy and click the Delete Selected Proxy button on the toolbar. Click the Edit Default Configuration button on the toolbar. Select the proxy and click the Set Proxy as Default button on the toolbar. Proxies/Monitoring This window provides current state information and gives information about performance of all proxies, such as memory consumption and CPU usage, of all the proxies. You can do the following in this window: Task View or modify options of the proxy instance Change the period that the average performance values are collected for Action Double-click the proxy or select the row and click the Edit Proxy Configuration button on the toolbar. Select the requested period from the drop-down list. 68 March 2016

69 Page Area/Field Status Icon %CPU Memory Mhp-In Mhp-Out Scan Explanation Green means proxy is running; red means proxy is not running. Load taken by the proxy process on the host computer. Memory usage in kilobytes taken by the proxy process on the host computer. Average inbound (SAP CRM groupware) processing performance, measured in messages per hour. Average outbound (groupware SAP CRM) processing performance, measured in messages per hour. Time in seconds taken by a logon session to scan all mailboxes listed in the UserList.xml file. March

70 5.7 Configuring Proxies The following windows appear when double-clicking on a proxy instance in the Proxy / General or Proxy / Monitoring windows described in section 5.6 Proxies. Proxy/Groupware Configuration/General This window provides information about proxy registration options. The same information is listed on the Proxy / General window. Microsoft Exchange Page Area/Field Proxy ID Proxy Host Use Proxy System Credentials Name Password Primary Groupware Server / Additional Groupware Servers Mail server Version Explanation ID of the proxy as provided by the administrator. The name of the system on which the proxy instance is running. Select this option if the access to the Exchange Server is to be made via the Windows Default Credentials of the local administrative account where the proxy is installed. To use this option, the local administrator account credentials must be same as exchange web services administrative account. SAP recommends that you use this option to avoid the DPAPI encryption issues for remote proxies. This option is not available for an Office 365 landscape. Specify the name of the Exchange service administrative account. Specifies the password of the Exchange administrative account. The server(s) to which the proxy is connected. A Groupware Server can be maintained as a Primary / Additional Groupware Server only in one Proxy instance. This option is not available for an Office 365 landscape. Specifies the version of the Exchange server. Lotus Domino 70 March 2016

71 Page Area/Field Proxy ID Proxy Host Name Password Primary Groupware Server Lotus Domino Global Domain Explanation ID of the proxy as provided by the administrator. The name of the system on which the proxy instance is running. This option is disabled in Lotus landscape. The password of the Lotus Notes client that is installed on the same machine as the groupware proxy. The server to which the proxy is connected. The name of the global domain of the Lotus Domino server. March

72 Proxy/Groupware Configuration/Advanced This window is available only for Microsoft Exchange proxy. You can use the Test Connection button to validate your new parameters by attempting to connect to the selected server. The result of the connection attempt will be shown next to the Test Connection button as Connection OK or Connection Failed. Page Area/Field Groupware Domain Enable Auto Discover Explanation Specifies the domain of the groupware server. Select this option if you do not know the Exchange Web service End Point URL. This option is set as the default for an Office 365 landscape. Service End Point URL Provide the address of the administrative account. This address will be used to determine the Exchange web service end point URL. Specifies the Exchange Web Service End Point URL. This option is not available for an Office 365 landscape. Auto Discover Domain (available from Connector 7.0 SP 03 Patch 02) Specifies the Auto Discover Domain. Microsoft recommends certain ways for load balancing and one of it is to install the auto discover service on a domain other than the Exchange. For example: if the exchange domain is outlook.company.org, the autodiscover domain may be autodiscover.company.org, in this case you will have to enter in this field. For more details, refer the following link Leave this field blank if the Exchange domain and the Autodiscover domain are same. Enable Check on End Date This option is available from Patch5. Upon selecting this and choosing the end date only those appointments which are later 72 March 2016

73 than the end date will be synchronized. This feature is not available for Lotus Connector. Note that the same value has to be selected both at the Connector and Proxy for the end date. March

74 Instance Configuration/Performance/General You can only change the settings if power user mode is enabled. You can then select the Custom checkbox to edit the settings. Page Area/Field BDOC Map Maximal Size Count of Active Workers Maximum memory usage value (in MB) (available from Connector 7.0 SP 03 Patch 02) Explanation The groupware connector caches the mapping between SAP CRM message ID (BDOC-ID) and the corresponding groupware messages ID (GW-ID). This cache is required in case of performance issues when the SAP groupware adapter is not able to provide the GW-ID. SAP recommends a setting of about entries. Outbound The number of simultaneous threads scanning for changes in users mailboxes/databases. Each worker thread can process one user queue at any time. More threads provide better performance but put more load on the groupware connector system, network, and groupware adapter. Outbound worker threads run all the time unless scheduled outbound replication is selected (see the section Replication/Schedule below). Auto-acceptor (Microsoft Exchange connector only) The number of simultaneous threads that accept self-generated meeting requests. Auto-acceptor threads are activated when meeting requests with invitees are replicated from SAP CRM to Microsoft Exchange. More auto-acceptor threads result in lower latency of processing. Auto-acceptor functionality can be disabled. See the section Replication / CRM Groupware for details. SAP recommends the setting 0 which would disable this functionality. Specifies the maximum memory allocated (in MB) for the proxy service. Groupware Proxy service will be restarted once this threshold is reached. Default value is 500 MB. You can configure this value as per your requirements. 74 March 2016

75 Instance Configuration/Performance/Outbound Replication You can only change the settings if power user mode is enabled. You can then select the Custom checkbox to edit the settings SAP recommends that you do not change the default settings. Page Area/Field Scanner Threads Sleep Factor Maximal Number Of Messages Per Cycle Minimal Interval Between Cycles Deadlock Timeout (in mins) Explanation Specifies the interval at which the outbound scanner thread sleeps between switching to another user. This parameter allows you to increase the total number of simultaneous outbound threads with the same CPU load. The greater the number of threads the lower the change-detection latency in a situation where many users generate changes in their databases. Specifies a maximal number of messages to be processed for a queue per groupware to SAP CRM session. Specifies the minimum interval between sessions for each user at which the proxy scans the user s database for changes. This option prevents the proxy from scanning the database too frequently. It indicates the maximum timeout interval in minutes for the proxy outbound threads while scanning the mailbox folders. If the thread crosses the timeout interval, dead lock will be detected and proxy will be restarted. SAP recommends that you to set this value to 30 minutes for bulk data synchronization from exchange to CRM and during the initial stages after installing groupware connector 7.0. March

76 Instance Configuration/Tracing This window allows you to configure tracing options for the proxy instance. Trace files for the proxy can be created as follows: On the same system where the proxy is running This approach does not consume network resources. Via replication of data to the groupware connector system (stored in a single file for all proxies) This approach gives all the information in one place (in the groupware connector system). You can only change the settings if power user mode is enabled. You can then select the Custom checkbox to edit the settings Microsoft Exchange Page Area/Field Log Directory Enable Proxy Trace Enable EWS Trace Enable Proxy Dumps Enable Proxy Error Dump EWS Soap Xmls Delete Proxy logs Explanation You can specify the folder where Proxy log files get saved. This option enables tracing for the proxy instance. You choose a severity level for errors from the list of possible entries. This option enables tracing for all communication between Proxy and the Exchange Web Services for data synchronization to and from Exchange Server. You choose a severity level for errors from the list of possible entries. This option enables generation of log files that have error information if the proxy stops or restarts due to an error. This option enables generation of log files with the error information occurred in proxy. Select this option if you want all requests being sent via Exchange web services to the Exchange server and the corresponding responses from the Exchange server to be logged in XML files. Huge number of XMLs is generated during data synchronization; SAP recommends that you do not select this option. Select this option to automatically delete old Proxy log files based on the number of days specified in the drop list. 76 March 2016

77 Lotus Domino Page Area/Field Enable Tracing Trace Locally Explanation This option enables tracing for the proxy instance. You choose a severity level for errors from the list of possible entries. This option specifies whether the trace messages will be written to a local file on the proxy host or transferred to a trace file of the groupware connector system (via the network). SAP recommends local tracing to minimize consumption of network resources. Trace File Limits Split Trace File By Fragments Of Location of the trace file (relative to ProxySvc.exe). Time period before files are overwritten. Maximum size of a trace file fragment in megabytes. Instance Configuration/Replication/CRM -> Groupware This window provides various message replication options. You can only change the settings if power user mode is enabled. You can then select the Custom checkbox to edit the settings. March

78 Microsoft Exchange Page Area/Field Default Reminder Interval Auto-accept Meeting Requests Send New Task Notifications FileAs Format (Contacts) Always consider CRM categories as Master Explanation Specifies the default reminder interval for appointments and tasks in case the value is not explicitly provided by SAP CRM. For more information, see the GW Customizing Guide. If this option is selected the groupware connector reproduces the behavior of Microsoft Outlook when creating meetings. To invite users to the meeting, it sends invitations to recipients. The attendee has to accept the meeting so that the corresponding entry appears in their calendar. The groupware connector can handle this automatically. SAP recommends that you do not select this option. This option enables additional notification to be sent to the target user when a new task or an updated task is replicated from SAP CRM to groupware. Specifies the format of a contact in the contact message (vcard) in the groupware server. By enabling this, the groupware categories will be always overwritten by the CRM categories. 78 March 2016

79 Lotus Domino Page Area/Field Default Reminder Interval Send New Task Notifications Explanation Specifies the default reminder interval for appointments and tasks in case the value is not explicitly provided by SAP CRM. This option enables additional notification to be sent to the target user when a new task or an updated task is replicated from SAP CRM to groupware. Instance Configuration/Replication/Groupware -> CRM You can only change the settings if power user mode is enabled. You can then select the Custom checkbox to edit the settings. March

80 Page Area/Field Do Not Replicate Changes In... Replicate Changes... Explanation Disables the replication of selected objects from groupware to SAP CRM. Specifies the age of changed items to be replicated from groupware to SAP CRM. The option is designed to avoid replication of outdated items during initial user synchronization (it makes no sense, for example, to replicate appointments to SAP CRM that were created more than a year ago). SAP recommends that you to set this value to of any age in the beginning. This setting can be changed to any desired value at a later date. Instance Configuration / Replication / Schedule You can only change the settings if power user mode is enabled. You can then select the Custom checkbox to edit the settings. Page Area/Field Replicate From Groupware Only By Schedule Explanation To avoid unnecessary load on the Microsoft Exchange Server while scanning mailboxes for changes, you can specify the start time for the scan cycles. The time specified is the local time of the computer on which the proxy instance is running. 80 March 2016

81 Instance Configuration / Debugging You can only change the settings if power user mode is enabled. You can then select the Custom checkbox to edit the settings. Page Area/Field Dump Configuration Files Post User Last Scanned Time to Connector Explanation Select this option if the proxy in-memory configuration should be written to a local file in the proxy installation folder. This option replicates the last scanned information from the proxy to the groupware connector and provides it in the user statistics. Due to increased network traffic, this option should be used for debugging purposes only. Once the configuration of Proxy and Connector are complete, click Apply or Save & Close in the AdminTool. The settings corresponding to the Connector are stored in Config.xml and the settings corresponding to Proxy are stored in Proxies.xml in the Connector folder. After configuring the connector and proxy, you can start the proxy and connector services. To do this, choose the Microsoft Windows Start menu and navigate to Control Panel Administrative Tools Services. Select the relevant service and click Start. March

82 5.8 User Statistics This window can be launched by clicking the Statistics button in the AdminTool. This window gives an overview of the users, the last time that their mailboxes were scanned for both directions, and the frequency of scanning. Error codes are also displayed if relevant. 82 March 2016

83 6 Batch-Assigning Access Rights for Domino Connector You can use the ACLRights utility to grant the groupware connector s administrative account the necessary access permissions for the databases of groupware users. The utility uses the UserList.xml file to get the list of databases to operate on. The groupware connector automatically downloads this file from SAP CRM at startup and at run time, if the file has been updated. It also grants the following rights to the groupware connector s administrative account. Editor rights to mail databases of all users provided in UserList.xml Designer rights to private address book databases of all users provided in UserList.xml Designer rights to the public address book database. To assign access permissions using the ACLRights utility, do the following: 1. Copy the following files to the Lotus Domino directory on the Lotus Domino server (for example, C:\Lotus\Domino): LotusConnector.jar Config.xml UserList.xml Private-contact-map.xml 2. Stop the Lotus Domino server. 3. Launch the following command from the console: java -classpath LotusConnector.jar com.sap.gcn.aclrights.main <user name> (where <user name> is the name of the groupware connector s administrative account) 4. Check the report.txt file in the SysInfo sub-folder and the trace*.txt file in the Logs sub-folder if necessary. 5. Start the Lotus Domino server again. The ACLRights utility only works with databases located on a local Lotus Domino server. In case of multiple Lotus Domino servers, you must start the utility on each server separately. March

84 7 Microsoft Outlook Categories The groupware connector uses filtering by categories for tasks and appointments in users mailboxes. An item is replicated to SAP CRM only if it is assigned a certain category from a predefined category list. Therefore, you must make these categories available in Microsoft Outlook. Microsoft Outlook stores category names in the Master Categories list. The default set is specified during the Microsoft Outlook installation process. In the AdminTool, CRM Adapter Connection / General window, if the option Update Groupware users master category list is enabled, then connector updates the master category list of the groupware users present in the userlist with the categories present in the Catslist.xml file. Whenever there is a new category added to the Catslist.xml file, the master category list will be updated in the users mailboxes. The Support Center tool can also be used to update the groupware users master category lists with predefined categories available in the Catslist.xml offline mode. Select the users and the categories, click on Add to Master Category List to add the selected categories to the master category list in the selected user s mailbox. Select the users and the categories, click on Remove to remove the selected categories from the master category list in the selected user s mailbox. SAP recommends using either of the above options to update the groupware users master category list. 84 March 2016

85 8 Connector Logging Information To effectively manage a groupware connector, you need information about the processing and performance of the connector as well as any problems that may occur. The groupware connector provides comprehensive and flexible logging capabilities. This section describes how to configure the logging capabilities of the connector and how to interpret the contents of the logs. SAP recommends that you do not to enable logs unless required. Log files are generated while the connector software is running. They require hard disk space to store logged information. If the Log deletion option is set in the AdminTool, Logging Limits, then the log files are removed automatically after the specified number of days. If the Log deletion option is not set, then it is an administrative task to remove and back up obsolete files. 8.1 Connector Log File This section is not relevant for Microsoft Exchange Connector. The connector log file records all messages processed by the connector. The format of the log file is strictly defined and is similar to the standard HTTP log file format. Therefore, it is possible to create a tool for analyzing log information and producing useful statistics. The following is an example of a connector log file entry and is described below: [25/May/2002:13:08: ] MIDDLEWARE jonh_doo@sap.com INSERT APPOINTMENT 66ED4A099D1F274AAC4B37EB9EB0AE14 18DFD51F9FF1CD5EC2256BC Format of Connector Log File [25/May/2002:13:08: ] The time when the connector finished message processing. This part of the entry has the format [day/month/year:hour:minute:second zone] MIDDLEWARE The source of the message. Supported values are GROUPWARE and MIDDLEWARE. jonh_doo@sap.com address representing the destination user or public folder (for Microsoft Exchange) or the mail-in database (for Lotus Domino). INSERT The operation type of the message. Supported operation types are INSERT, UPDATE, and DELETE. APPOINTMENT The type of the processed message. Supported types of messages are: APPOINTMENT, TASK, and CONTACT. 66ED4A099D1F274AAC4B37EB9EB0AE14 BDoc ID of the message as defined in the SAP CRM system. 18DFD51F9FF1CD5EC2256BC Groupware UID of the message. The length of the UID for the Lotus Domino Server is always 32 characters; the length of the UID for Microsoft Exchange can vary up to a length of 256 characters. March

86 8.2 Error Log File The error log file contains information about messages that were processed with an error. The connector also writes diagnostic information to this file. The following is an example of an error log file entry: [20/Jul/2002:12:14: ] ERROR MIDDLEWARE UPDATE TASK [ERR:1002] Global address book not available The log file format is similar to the connector log file format, with two additional fields defined: ERROR The severity of the error. Valid values are as follows: - WARNING: Typically indicates that an operation cannot be completed, but the problem is not an error. For example, in carrying out a DELETE task, the corresponding item in the groupware server cannot be found. - ERROR: Indicates that a single user has a permanent error while delivering a message that does not exist in the groupware server. - CRITICAL: Indicates that no messages can be delivered, since no connection can be established to the groupware server or the groupware adapter. [ERR:1002] Global address book not available The error message produced by the connector, including the error code and a short error description. The table below describes possible error messages: Code Short Description 9 Unspecified error Description: An unknown error has occurred. Resolution: See trace log for details %s Description: Not an error - reserved for system messages like service started or service stopped. Resolution: None Administrative logon failed. %s Description: Initial logon to the groupware server using the provided administrative account failed. %s denotes additional comments that may be generated by the connector. Resolution: Make sure that the options specified in config.xml correspond to a valid groupware server name and administrative account name. Make sure that valid logon credentials are provided for the groupware connector service. For more information, see the section 9.3 Verifying the Connection to Groupware Server 1002 Global address book not available Description: Global address book is not available for the administrative account. Resolution: Verify the setting of the administrative account on the groupware Msxml2.DOMDocument not available Description: Msxml2.DOMDocument COM object is not installed on the computer with the groupware connector service. Resolution: Verify the installation. 86 March 2016

87 1006 XSLT transformation not available for '%s' Description: XSLT files are missing or invalid. Resolution: Verify if the required set of valid XSLT files is available in the xslt/ folder (as specified in config.xml) Internal error occurred. Description: An internal connector error has occurred. Resolution: See trace log for details Public folders store not available to administrative account. Description: (Microsoft Exchange only). Connector failed to locate the Exchange information store with public folders. Resolution: Verify the installation. Check administrative account settings Invalid default target folder for contacts. Description: The option specified in config.xml for gw. .default is either invalid or does not correspond to the public folder. Resolution: Verify the installation. Microsoft Exchange Connector: make sure that the checkbox Hide from Address Book is not selected on the Exchange Advanced property page of the public folder XSD schema validation failed. Description: Validation of outgoing XML message against XSD schema failed. Resolution: Contact SAP CRM technical support CDO (Collaboration Data Objects) library not available. Description: CDO (Collaboration Data Objects) library not available. Resolution: Verify the pre-installation requirements Local user list is not available. Description: The local user list is not available. A request for a new users list will be sent to the groupware adapter. Resolution: none Error while reading user list from CRM. Description: Error while reading user list from CRM. Resolution: Contact SAP CRM technical support Mailbox not available: '%s' Description: Groupware connector fails to open given mailbox. Resolution: Make sure the administrative account has enough rights on the target mailbox and servers holding a given mailbox are available over the network. March

88 2002 Logon failed for: %s Description: Logon to mailbox failed using administrative account. Resolution: Make sure the administrative account has enough rights on the target server User not found in groupware domain. %s Description: The address specified in the message header belongs to the groupware domain; however, the corresponding mailbox does not exist. Resolution: Either ensure the given mailid is available in the groupware or fix mailid on the SAP CRM middleware side Q-Unlock XML is not well formed Description: An invalid XML is provided in the administrative queue unlock XML file. Resolution: Provide the valid XML Transport error Description: SOAP transport error. Resolution: Verify the network connection and check if the SAP CRM middleware SOAP server is working properly. For more information, see the section 9.1 Verifying Connection to the Payload Interface Payload interface error. %d Description: An error was returned by the payload interface. Resolution: For more information, see the section 9.2 Resolving Payload Interface Errors CMW_PIF_Qlogon failed. %s Description: Logon into queue failed. Possible reason SOAP transport error or payload interface error. Resolution: For more information, see the section 9.2 Resolving Payload Interface Errors CMW_PIF_Qlogoff failed. % Description: Queue logoff failed. Possible reason SOAP transport error or payload interface error. Resolution: For more information, see the section 9.2 Resolving Payload Interface Errors 3005 CMW_PIF_getMsg failed. %s Description: Failed to get message from the logical queue. Possible reason SOAP transport error or payload interface error. Resolution: For more information, see the section 9.2 Resolving Payload Interface Errors 3006 CMW_PIF_getMsg returned empty message Description: SAP CRM middleware has returned a NULL message. Resolution: None, this is a warning. CMW_PIF_getMsg failed. %s 3007 CMW_PIF_getMsgCount failed. %s Description: Failed to get message count in data queue. Possible reason SOAP transport error or payload interface error. Resolution: For more information, see the section 9.2 Resolving Payload Interface Errors CMW_PIF_postMsg failed Description: Failed to post message. Possible reason SOAP transport error or payload interface error. Resolution: For more information, see the section 9.2 Resolving Payload Interface Errors XML message is not well formed Description: SAP CRM middleware has returned a not well formed XML. Resolution: Verify the functionality of the SAP CRM middleware side; see the trace log for details Required field(s) missing or invalid. %s 88 March 2016

89 Description: One or more required fields are missing in the XML message. Resolution: Verify the functionality of the SAP CRM middleware side; see the trace log for details CRM Message is invalid. %s Description: XML message provided by SAP CRM is invalid: The structure is incorrect, required blocks are missing, for example. Resolution: Verify the functionality of the SAP CRM middleware side; see the trace log for details XSLT transformation failed Description: Failed to invoke XSLT transformation on a given message part. Resolution: Verify the functionality of the SAP CRM middleware side; see the trace log for details CDO folder lookup failed: mailid = %s Description: Target public folder not found for a given mailid. Resolution: Ensure that the folder corresponding to the given mailid is available in the groupware or fix mailid on the SAP CRM middleware side CDO folder not available: mailid = %s. Description: Folder exists in the groupware server but is not available to the administrative account. Possible reasons not enough rights granted over the user or the folder was removed since last address-book cache operation. Resolution: Verify folder access rights CDO default folder not available: %s. Description: Default CDO folder is not available in the given mailbox. Resolution: Logon to the mailbox using Microsoft Outlook for creation of all required folders or else not enough access rights are assigned to the user CDO message not found Description: CDO message is not found in the groupware for INSERT or UPDATE operations. Resolution: None, this is a warning Unsupported field: name = %s. Description: Unsupported field name is listed in translated XML. Resolution: Verify available XSLT files for corresponding document type Unsupported field-type: %s. Description: Unsupported field type is listed in translated XML. Resolution: Verify available XSLT files for corresponding document type Invalid field value: field id = %s. Description: The SAP CRM middleware side provides invalid field value. Resolution: Verify the functionality of the SAP CRM middleware side; see the trace log for details Update CDO message failed Description: Failed to save changes to the CDO message into the groupware. Possible reasons one or more fields are not accepted by the groupware, insufficient access permissions for the administrative account. Resolution: Verify the functionality of the SAP CRM middleware side; see the trace log for details Delete CDO message failed March

90 Description: Failed to delete message from the groupware server. Possible reasons not enough access permissions for the administrative account. Resolution: Make sure the administrative account has enough rights on the target recipient server Send CDO message failed Description: Failed to invoke sending of a message to the target recipients. Resolution: Should never happen IDMAP notification failed, ERR:%d. Description: Failed to post UID of the groupware message to the SAP CRM middleware side. Can occur due to SOAP transport errors or due to failure on the SAP CRM middleware side. Resolution: Verify the ready state of the SAP CRM middleware side ERROR notification failed, ERR:%d. Description: Failed to post ERROR information to the SAP CRM middleware side. Can occur due to SOAP transport errors or due to a failure on the SAP CRM middleware side. Resolution: Verify ready state of middleware side Message failed Description: Processing of the message failed due to one or more errors. Resolution: See the trace log for details Auto-accept initiation failed Description: Failed to initiate auto-accept for meeting request. Resolution: See the trace log for details Searching by BDOC-ID Description: Message from the CRM side does not provide groupware message UID for UPDATE and DELETE operations. Connector tries to find the message by raw scan of messages in the target folder (performance consuming operation). Resolution: Verify functionality of the SAP CRM middleware side; see the trace log for details List of recipients is invalid Description: List of attendees or recipients provided in message has one or more invalid recipient SMTP address specification. Resolution: Verify functionality of the SAP CRM middleware side; see the trace log for details Failed to initialize middleware Description: Failed to initialize middleware. Resolution: See the trace log for details Failed to uninitialize middleware Description: Failed to uninitialize middleware. Resolution: See the trace log for details Failed to get list of active queues Description: Failed to get the list of active queues. Resolution: See the trace log for details Failed to get count of messages in data queue Description: Failed to get the count of messages in the data queue. Resolution: See the trace log for details. 90 March 2016

91 6005 Failed to get message from data queue Description: Failed to get the message from the data queue. Resolution: See the trace log for details Failed to accept message Description: Failed to accept message. Resolution: See the trace log for details Failed to send failed message notification Description: Failed to send failed message notification to the CRM side. Resolution: See the trace log for details Failed to post message into data queue Description: Failed to post message into data queue. Resolution: See the trace log for details Failed to get list of users Description: Failed to get list of users. Resolution: See the trace log for details Failed to get list of categories Description: Failed to get list of categories. Resolution: See the trace log for details Unsupported field-type: %s Description: (Lotus Domino only) translated XML contains an unsupported field type. Resolution: Verify available XSLT files for the corresponding document type Invalid field value: field id = %s Description: (Lotus Domino only) the SAP CRM middleware side provides an invalid field value. Resolution: Verify the functionality of the SAP CRM middleware side; see the trace log for details Update Lotus document failed Description: (Lotus Domino only) failed to save changes in the Lotus document into the groupware. Possible reasons insufficient access permissions for the administrative account. Resolution: Verify the functionality of the SAP CRM middleware side; see the trace log for details Delete Lotus document failed Description: (Lotus Domino only) failed to delete a Lotus document from the groupware server. Possible reasons not enough access permissions for the administrative account. Resolution: Make sure the administrative account has enough rights on the target recipient server Insert Lotus document failed Description: (Lotus Domino only) failed to create/save a Lotus document to the target recipients. Resolution: Should never happen. March

92 7013 Message failed Description: (Lotus Domino only) processing of the message failed due to one or more errors. Resolution: See the trace log for details Searching by BDOC-ID Description: (Lotus Domino only) message from CRM side does not provide groupware message UID for UPDATE and DELETE operations. Connector tries to find the message by raw scan of messages in the target folder (performance consuming operation) and has a search error. Resolution: Verify functionality of the SAP CRM middleware side; see the trace log for details SMTP. Send message failed Description: (Lotus Domino only) failed to invoke sending a message to the target recipients. Resolution: Should never happen Failed to generate XML representation for message Description: Failed to generate XML representation for a message in groupware. Resolution: Contact SAP technical support. 8.3 Trace Log File The connector writes debugging information to the trace log file, which helps you to investigate possible problems with the connector. The format of the trace log file is not specified. The connector can write any messages, with no strict format defined. These messages can be useful when contacting SAP technical support. An error message reported to the error log will always appear in the trace log, provided that tracing is enabled. The trace log file can grow very large and can also affect overall application performance. SAP recommends that you have the trace log disabled during normal operation. You should only enable it during the deployment phase or if problems are discovered. An error message reported to the error log will always appear in the trace log, provided that tracing is enabled. 92 March 2016

93 9 Troubleshooting the Connector This section provides explanations and possible solutions to problems that may arise while using Groupware Connector. 9.1 Verifying Connection to the Payload Interface You can check the connection to CRM groupware adapter via the Test button in the CRM Adapter Connection\General window of the AdminTool. If the status is displayed as Connection Failed or if the error [ERR:3001] SOAP Transport error is logged in the log files, verify the connection to the payload interface. Use your Internet browser to connect to the groupware adapter. To find the URL of the adapter, choose Administrative Tool CRM Adapter Connection General. Your browser may return a response like Unable to locate server XXX or Page cannot be displayed. The following are possible causes: The payload interface server is down. Make sure the payload interface server is running on the specified server and is configured according to the port provided in the URL. The standard HTTP port 80 is used by default. The specified URL is invalid. If a different URL is configured for the payload interface on the server, you receive the error message HTTP Error 404 Not Found. Check the configuration of the payload server. March

94 9.2 Resolving Payload Interface Errors If you receive errors relating to the payload interface (error codes 3001 to 3009), refer to this section. The errors can occur while processing different operations and their resolution depends on the error code returned by the payload Interface. You can find the corresponding error code in the text of the error messages. Code Short Description 0 Success 1 Success - queue created on the fly 2 Error access denied. Most probable reason: Wrong parameters are specified for the groupware adapter connection in the AdminTool. 3 Queue does not exist Most probable reason: There is a problem on the groupware connector or groupware adapter side. Contact the support team for details. This error should not happen. 4 Another session already established Most probable reason: Two or more groupware connectors are connected to the same groupware adapter. Verify the groupware adapter connection setting for all running instances of groupware connectors. 5 Session ID not known Most probable reason: Connection session with groupware adapter has expired due to a timeout. Connector will automatically restore the connection as needed. This error can be ignored. 6 Wrong parameter Most probable reason: There is a problem on the groupware connector or groupware adapter side. Contact the support team for details. This error should not happen. 7 Property not known Most probable reason: There is a problem on the groupware connector or groupware adapter side. Contact the support team for details. This error should not happen. 8 Feature not implemented Most probable reason: There is a problem on the groupware connector or groupware adapter side. Contact the support team for details. This error should not happen. 9 Unspecific error Most probable reason: There is a problem on groupware connector or groupware adapter side. Contact support team for details. 10 No more messages available Most probable reason: All messages are already fetched from the groupware adapter s data queue. This error can be ignored. 11 Operation not allowed Most probable reason: There is a problem on the groupware connector or groupware adapter side. Contact the support team for details. 101 SOAP transport error Most probable reason: The groupware adapter is experiencing problems with the network connection. For more information, see the section 9.1 Verifying Connection to the Payload Interface. 94 March 2016

95 9.3 Verifying the Connection to Groupware Server Connection to Microsoft Exchange Server You can verify the connection to Exchange server via the AdminTool\Groupware Configuration\General window. Click on the Test Connection button and check if the Connection Status is shown as Connection OK. Similarly, for checking the connection of the Proxy to Exchange server, you can go to Proxy configuration in the AdminTool and then go to the Proxy\Groupware Configuration \ Advanced window and click on Test Connection. If the connection status is displayed as Connection Failed, check the following: 1. Ensure that the ID specified on this window is correct and that you have checked the Enable Auto Discover checkbox. It should be the primary SMTP address of the connector administrator user account. 2. If you have specified the service end point URL, then try to ping this URL to check if this URL is correct Connection to Lotus Domino Server To verify the connection to Domino Server or to the CRM system, run the self-test using SelfTest.cmd present in the Groupware Installation directory. While you run the self-test, services should be stopped. Selftest.cmd will start the services to check the connection and to resolve the users. Once the connection is successful, you can start the Connector and Proxy services. March

96 9.4 Error Details In case of a connector failure, detailed error information is available in the following places: Error log file Trace log file ErrDumps subfolder queue-locks.xml Provides one line per error with a short description. Provides detailed error information if available. You can use the contents from the error log to search in the trace file for details. Contains detailed information about errors sent to SAP CRM. A copy of the sent message is stored on the local drive. Use the Current Locks page in the AdminTool (section Queue (User) Maintenance) to view the contents of this file. Each of the mentioned items is available by default. However, each of them can be disabled using the AdminTool. Detailed system information may be required to provide support for the solution. The information can be partially obtained using the diagnostics tool. For more information, see the following sections about using the diagnostics tool. 96 March 2016

97 9.5 Diagnostics Tool Tool for Microsoft Exchange Connector The Support Center tool gathers system diagnostics using the groupware connector configuration. You access the tool by logging on to the groupware connector system using the administrative account and starting the EWSSupportCenter.exe file, which can be found in the installation folder under Support Center. You must right click on EWSSupportCenter.exe and select Run as Administrator. User list validation and Global Address list validation is done via the tool and is displayed in the Groupware Diagnostics panel of the Support Center. March

98 98 March 2016