SAP Groupware Connector Administration

Administration GuideAdministration GuideAdministration GuideAdministration Guide

SAP CRM Groupware Connector SAP CRM Groupware Connector SAP CRM Groupware Connector SAP CRM Groupware Connector

Release 4.0Release 4.0Release 4.0Release 4.0

Document Version 2.1.7 – Aug 08, 2007

© Copyright 2003 SAP AG. 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.

Microsoft®, WINDOWS®, NT®, EXCEL®, Word®, PowerPoint® and

SQL Server® are registered trademarks of Microsoft Corporation.

IBM ®, DB2®, DB2 Universal Database, OS/2®, Parallel Sysplex®,

MVS/ESA, AIX®, S/390®, AS/400®, OS/390®, OS/400®, iSeries,

pSeries, xSeries, zSeries, z/OS, AFP, Intelligent Miner, WebSphere®,

Netfinity®, Tivoli®, Informix and Informix® Dynamic ServerTM

are

trademarks of IBM Corp. in USA and/or other countries.

ORACLE® is a registered trademark of ORACLE Corporation.

UNIX ®, X/Open®, OSF/1®, and Motif® are registered trademarks of

the Open Group.

LINUX is a registered trademark of Linus Torvalds and others.

Citrix®, the Citrix logo, ICA®, Program Neighborhood®, MetaFrame®,

WinFrame®, VideoFrame®, MultiWin® and other Citrix product names

referenced herein are trademarks of Citrix Systems, Inc.

HTML, DHTML, XML, XHTML are trademarks or registered

trademarks of W3C®, World Wide Web Consortium, Massachusetts

Institute of Technology.

JAVA® is a registered trademark of Sun Microsystems, Inc.

J2EE™ is a registered trademark of Sun Microsystems, Inc.

JAVASCRIPT® is a registered trademark of Sun Microsystems, Inc.,

used under license for technology invented and implemented by

Netscape.

MarketSet and Enterprise Buyer are jointly owned trademarks of SAP

AG and Commerce One.

SAP, SAP Logo, R/2, R/3, mySAP, mySAP.com, xApps, mySAP

Business Suite, and other SAP products and services mentioned herein

as well as their respective logos are trademarks or registered

trademarks of SAP AG in Germany and in several other countries all

over the world. All other product and service names mentioned are the

trademarks of their respective companies.

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/instguidesservice.sap.com/instguidesservice.sap.com/instguidesservice.sap.com/instguides

0

SAP AGSAP AGSAP AGSAP AG Neurottstraße 16 69190 Walldorf Germany T +49/18 05/34 34 24 F +49/18 05/34 34 20 www.sap.comwww.sap.comwww.sap.comwww.sap.com

Typographic Conventions

Type Style Represents

Example Text Words or characters that appear on the screen. These include field names, screen titles, pushbuttons as well as menu names, paths and options.

Cross-references to other documentation

Example text Emphasized words or phrases in body text, titles of graphics and tables

EXAMPLE TEXT Names of elements in the system. These include report names, program names, transaction codes, table names, and individual key words of a programming language, when surrounded by body text, for example, SELECT and INCLUDE.

Example text Screen output. This includes file and directory names and their paths, messages, names of variables and parameters, source code as well as names of installation, upgrade and database tools.

Example text Exact user entry. These are words or characters that you enter exactly in the system as they appear in the documentation.

<Example text> Variable user entry. Pointed brackets indicate that you replace these words and characters with appropriate entries.

EXAMPLE TEXT Keys on the keyboard, for example, function keys (such as F2) or the ENTER key.

Icons

Icon Meaning

Caution

Example

Note

Recommendation

Syntax

Administration Guide: SAP CRM Groupware Connector

Aug 2007 4/57

Contents Introduction....................................... .....................................................................5

Architecture of Connectors ......................... .........................................................6 Architecture of the Lotus Domino Connector......... ................................................... 7 Architecture of the MS Exchange Connector.......... ................................................... 8

Security Considerations ............................ ...........................................................9 Performance Guidelines ............................. ........................................................10

Integration Landscape .............................. ................................................................. 10 Performance Estimates.............................. ................................................................ 11

Typical Administrative Tasks ....................... ......................................................14 Changing Groupware Server Connection Options ....... ........................................... 14 Changing CRM Adapter Connection Options ............ .............................................. 14 Resetting Locked User Queues....................... .......................................................... 15 Managing Proxies................................... .................................................................... 18 Batch-Assigning Access Rights for Lotus Domino Conn ector .............................. 19 Batch-Assigning Access Rights for MS Exchange Conne ctor............................... 19

Setting Configuration Parameters ................... ..................................................21 Groupware configuration............................ ............................................................... 22 CRM Adapter Connection ............................. ............................................................. 25 Queue (User) Maintenance ........................... ............................................................. 27 Performance........................................ ........................................................................ 29 Logging ............................................ ........................................................................... 30 Managing Proxies................................... .................................................................... 31 Configuring Proxies ................................ ................................................................... 34

Debugging .......................................... ..................................................................40

SLD Server Configuration........................... ........................................................41

General ............................................ .....................................................................41

Setting Master Categories List in Microsoft Outlook (till 2003 version) ........42

Using Connector Logging Information................ ..............................................44 Connector Log File ................................. .................................................................... 45 Error Log File ..................................... ......................................................................... 45 Trace Log File ..................................... ........................................................................ 52

Troubleshooting the Connector ...................... ...................................................53 Verifying Connection to the Payload Interface ...... .................................................. 53 Resolving Payload Interface errors................. .......................................................... 53 Verifying Connection to the MS Exchange Server..... .............................................. 55 Obtaining Error Details ............................ .................................................................. 55 Using Diagnostics Tool (Exchange Connector)........ ............................................... 56 Using Diagnostics Tool (Lotus Connector) ........... ................................................... 56

Backup plan ........................................ .................................................................56


Aug 2007 5/57

Introduction In today’s world, most world companies have a complex software environment, which helps them to organize their employees, create and maintain business processes and communicate with customers. Many customers in the world rely on SAP CRM - a system, which provides the customer-centric solutions that you need to plan, build, retain and enhance profitable customer relationships.

SAP CRM provides a unique level of integration within all parts of the business cycle, from market analysis and telemarketing to business transactions and order processing.

SAP CRM Groupware Connectors add a new level of integration to the enterprise environment. They provide access to important business information created in SAP CRM in the most widely used Groupware systems: Microsoft Exchange Server and Lotus Domino.

This version of SAP CRM Groupware Connectors allows a server based, two-way replication of CRM business partners, contact persons and activities with the groupware contacts, appointments and tasks. Once, an item is created, changed or deleted in the SAP CRM system, the changes are sent to the Groupware Connector that forwards them to the users' mailboxes. Users can immediately see changes in their mailboxes, using their favorite Groupware Client application, like Microsoft Outlook or Lotus Notes. This is an important step for increasing the productivity of employees, because now it is possible to see calendar entries received from colleagues via the Groupware server, and business meetings with a customer, created in the SAP CRM system. Users can view contacts, mapped from CRM business partners in their groupware client, or can quickly find a customer telephone number without starting the CRM client.

The replication is based on the SAP CRM middleware approach, i.e. changes in the CRM are sent to the Groupware Connector via sync BDoc messages, as in a mobile application. Connectors are able to support large site configurations with up to several thousand CRM users.

Groupware Connectors can help reduce the entire CRM site deployment cost by using MS Outlook and Lotus Notes as a simplified CRM client.


Aug 2007 6/57

Architecture of Connectors The Lotus Domino Connector architecture and the MS Exchange Connector architecture are very similar. A special effort was made in order to unify Groupware Connectors. The only reason the architectures may be different is to reflect specific Groupware interface differences.

Groupware connector consists of two types of components:

• Groupware Connector (GWC) - deals with CRM side.

• Groupware Connector Proxy (GWP) - deals with Groupware side.

GroupwareServer

GroupwareServer

CRMCRM

GroupwareAdapter

GroupwareConnector

GroupwareConnector

Proxy

GroupwareConnector

Proxy

GroupwareServer(s)

GroupwareServer

GroupwareServer

GroupwareServer(s)

SOAPover

HTTPDCOM / RMI

GroupwareNative

API

GroupwareNative

API

GroupwareServer (as

AddressBookprovider)

GroupwareNative

API

Groupware Adapter (GWA) is the entry point from CRM side for external connectors. It is provided by SAP CRM installation.

There is exactly one instance of Groupware Connector component in integration environment. Connection to groupware servers can be organized via one or more Groupware Connector Proxy components.

It is recommended to set up separate Proxy instance within each remote local area network (LAN) node in distributed organization. This will provide much better performance and will dramatically reduce wide area network (WAN) usage because calls between Connectors and Proxies are optimized to use as less network resources as possible.

The connector uses Simple Object Access Protocol (SOAP) over HTTP for collaboration with Groupware Adapter. Data exchange is organized using data-queue paradigm: GWA provides the message queues, GWC fetches messages from queues to get the operations to be performed and to exchange data items from CRM to Groupware. GWC put the messages into queues to exchange data items from Groupware to CRM.

GWA provides predefined set of system queues and variable number of data queues (separate queue for each user). There are following system queues:

• _ISP_QFILLED (ReadOnly) GWA provides list of currently filled queues from CRM side.

• CMW_PIF_ID_QUEUE (WriteOnly) GWC posts IDs of the newly created messages in Groupware server storage. This will update mapping between CRM and Groupware items on GWA side.

• CMW_PIF_PROTOCOL. (WriteOnly) GWC posts error notifications into this queue.

• USER_LIST (ReadOnly) GWA provides list of users whose data is intended for replication Groupware to CRM.

• CATS_LIST (ReadOnly) GWA provides list categories used to mark intended for reapplication messages in Groupware server storage.

Data flow for two-way replication is provided on the below diagram:


Aug 2007 7/57

CRM Groupware Adapter

Data Queue([email protected])

read

write

_ISP_QFILLEDread

write

CMW_PIF_ID_QUEUEread

write

CMW_PIF_PROTOCOLread

write

USER_LISTread

write

CATS_LISTread

write

Data Queue([email protected])

read

write

…

Groupware Connector for CRM

Inbound Queue Dispatcher

Inbound Messages Processor

GroupwareServer DB

Outbound Queue Dispatcher

Outbound Messages Processor

Categories Reader

For replication from CRM to Groupware

• GWA gets set of changed messages from user’s storages and puts them into data queue

• GWC periodically reads list of active queue and starts Inbound Messages Processor if there some available

• Inbound Messages Processor will sequentially go through all queues and will read the messages one by one posting them to Groupware server. IDs of the newly created messages will be posted into CMW_PIF_ID_QUEUE queue. In case of processing error occurres, the queue for that user fill be locked for configured interval and error notification will be posted into CMW_PIF_PROTOCOL queue.

For replication from Groupware to CRM

• GWA provides list of users whose data is intended for replication Groupware to CRM via USER_LIST

• GWC sequentially goes though all storages of the users provided in the list and replicates changes to CRM one by one by posting the messages into user’s data queue in GWA.

For both directions each successful replication operation is listed in log file.

Short description for all error cases is written into error log file.

Details for errors and various information about connector’s operations are provided in the trace log file.

Architecture of the Lotus Domino Connector The Lotus Domino Connector is a Java application that uses Lotus Notes libraries during the processing. The Sun Java Runtime Engine (JRE) 1.4 .2 and Lotus Notes must be installed before starting the connector installation on a Windows platform.

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.


Aug 2007 8/57

The table below provides mapping for documents types in CRM and corresponding item in Lotus Notes groupware:

SAP CRM Lotus Domino Groupware Server

Business partner Contact (Person)

• User’s private contact database (private contacts) • Public contacts database (public contacts)

Activity Management or Resource Planning

To Do (Task)

• User’s mail database: to-do frameset, calendar frameset


Calendar Entry (Appointment)

• User’s mail database: calendar frameset

Architecture of the MS Exchange Connector The MS Exchange Connector is a C++ application, usually running as a Windows NT service under a special administrative account, which must be assigned with permissions to read and write into other users' mailboxes and public folders on the MS Exchange server.

The table below provides mapping for documents types in CRM and corresponding item in MS Exchange groupware:

SAP CRM MS Exchange Groupware Server

Business partner 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


Aug 2007 9/57

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 have to be stored on the connector host, either in the Windows registry or 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.

• Administrator may change attributes of config.xml, and mwpaylaod.wsdl files to Hidden, for better file protection (MS 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, as regards 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 for 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 2000 is to enable auditing. This will alert you in case of changes to the account policies, attempted password attacks and unauthorized file access.


Aug 2007 10/57

Performance Guidelines

Integration Landscape Overall performance of entire solution greatly depends on configured landscape. This is particularly important for largely distributed organizations. The performance will be optimized if Proxy instances never talk to remote Groupware servers.

Next diagram describes right and wrong approaches for build Groupware Connector’s landscape.

LAN B

LAN C

LAN 1

CRM

CRMGroupware

Adapter

GroupwareConnector

GroupwareConnector

Proxy

‘Default’Proxy

GW Server 2

GW Server 1

LocalGroupware

Server

GW Server 1

GW Server 2

LAN A

GW Server 1 GW Server 2

OK

Wrongway

Wrong way

Following options can be considered to select the best solution

• Minimum required bandwidth between Groupware Connector and Remote Proxy instance is 128kbps.

• Minimum required bandwidth between Groupware Connector Proxy and remove Groupware Server is 1Mbps. (This is the case for the simplest configuration).

• When using Remote Proxy in comparison to setting up the Proxy to deal with remote Groupware Servers …

o Network utilization is about 5 times less during CRM � Groupware replication.

o Performance of Groupware � CRM replication can be up to 100 times faster (depending on WAN bandwidth) because Remote Proxy will not utilize the network while detecting the changes.


Aug 2007 11/57

Performance Estimates The tables below provide estimate groupware connector’s performance in provided environment. One can consider provided results to estimate performance in its own landscape.

Environment 1 Simple configuration for small organizations.

Groupware Connector and Groupware Connector Proxy are installed on the same box. There is only one groupware server. All servers are located in the same LAN.

• Box with GW Server - Intel P4 2 GHz, bla, bla, bla

• Box with GW Connector & Proxy - Intel P4 2 GHz, bla, bla, bla

• Number of Users in UserList - 500

CRM �� GW, messages/hour

GW �� CRM, messages/hour Operation

MSX LN MSX LN

INSERT APPOINTMENT 18700 11800

UPDATE APPOINTMENT 17500 16200 43902 18800

DELETE APPOINTMENT 27700 63700 54900 18000

INSERT TASK 20300 13400

UPDATE TASK 14800 17600 32400 20400

DELETE TASK 28100 63700 51400 18400

INSERT CONTACT 17700 6800

UPDATE CONTACT 12000 9700 29600 19500

DELETE CONTACT 28700 64300 48600 20700

Latency of Change Detection (min) 1 --- --- 50 sec 20 sec

Latency of Change Detection (typical) 2 --- --- 100 sec 180 sec 1 Average interval between the message gets changed in the Groupware system and Connector detects the change under minimal load (almost no changes). 2 The same under heavy load (the time taken to detect and replicate 2000 of changes).

Change Detection greatly depends on number of outbound synchronization threads. Increasing the number outbound synchronization threads will proportinaly increase CPU usage on the Proxy host.

Environment 2 Typical configuration for synchronizing the remote groupware servers.

Groupware Connector is installed in the same LAN with CRM system. Groupware Connector Proxy is installed on the separate box in remote LAN with the Groupware server(s).

This environment gives the estimate performance for synchronizing the data to one remote LAN via one Proxy instance. Having multiple Proxy instances for each remote LAN, the rought estimate of combined performance will be the sum of performance provided by each Proxy.


• Box with GW Connector - Intel P4 2 GHz, bla, bla, bla


Aug 2007 12/57

• Box with GW Proxy - Intel P4 2 GHz, bla, bla, bla


• WAN link bandwidth - 512 Kbps



MSX LN MSX LN

INSERT APPOINTMENT 13700 16200



INSERT TASK 14900 14800

UPDATE TASK 13800 20700 20200 17900

DELETE TASK 21200 64300 35300 17300

INSERT CONTACT 8800 10000

UPDATE CONTACT 8500 12100 10900 22800

DELETE CONTACT 13200 70500 36500 23000

Latency of Change Detection (min) --- --- 50 sec 20 sec

Latency of Change Detection (typical) --- --- 180 sec 180 sec

Environment 3 Non-optimized configuration for synchronizing the remote groupware server.

Groupware Connector and Groupware Connector Proxy are installed on the same box. There is one (or more) Groupware server(s) in different remote LANs.

This environment gives the estimate performance degradation in comparison to previous environment.


• Box with GW Connector - Intel P4 2 GHz, bla, bla, bla


• WAN link bandwidth - 512 Kbps



MSX LN MSX LN

INSERT APPOINTMENT 2900 1030 7000



INSERT TASK 3300 1030 4800

UPDATE TASK 3200 1000 5400 4300

DELETE TASK 16200 8600 11800 5000

INSERT CONTACT 1540 500 2300


Aug 2007 13/57

UPDATE CONTACT 1260 480 2300 5600

DELETE CONTACT 9000 8200 6700 7300

Latency of Change Detection (min) --- --- 250 sec 50 sec

Latency of Change Detection (typical) --- --- 800 sec 600 sec


Aug 2007 14/57

Typical Administrative Tasks This chapter covers typical administrative tasks. All options can be configured using Administrative Tool.

Changing Groupware Server Connection Options Groupware Server connection options can be modified on the Groupware Connection → General page of Administrative Tool.

1. Type in new option values.

2. Click Apply button. Administrative Tool will try to validate new option values in connecting to the selected server. A warning will be issued to indicate failure.

When changing administrative account for MS Exchange Groupware Connector one may will be required to update LogOn information of the corresponding Windows NT service.

Changing CRM Adapter Connection Options CRM Adapter connection options can be modified on the CRM Adapter Connection → General page of Administrative Tool.


Aug 2007 15/57

1. Type in new option values.

2. Click Apply button.

Resetting Locked User Queues Groupware Connectors locks the user’s data queue in case of processing error. Administrator can use Queue Maintenance → Current Locks page in Admin Tool to check for currently locked queues.


Aug 2007 16/57

One may select the listed errorneous queue and press Explain to get exmplanation of error case by its code and get short problem resolution guidelines. Double click the entry to get extended information about error condition.

To unlock the queue ..

• Select queues to be unlocked, and do one of the following:

• Press Unlock to unlock the queue. This action is intended for the cases when locking problem is fixed. The problem can be identified by queue-lock error code.

• Press Unlock & Accept to unlock the queue and force accept the first data message in the queue. This action is intended for the cases when queue-locking reason cannot be resolved and we want to skip first erroneous message.

Information about queue locks is automatically reset when connector is restarted.


Aug 2007 17/57

Connector can automatically skip some kind of errors. These options are available for configuration on the Queue Maintenance → Lock Options page


Aug 2007 18/57

Managing Proxies Admin Tool provides service of managing options of remote Groupware Connector Proxy instance and checking their active state.

One can get list of registered Proxy instance and associated Groupware server on Proxies � General page.

The Proxies � Monitoring page provides alive-state information and gives some Proxy’s performance counters. It allows starting and stopping the Proxies on remote hosts.

See the dedicated chapter below for details.


Aug 2007 19/57

Batch-Assigning Access Rights for Lotus Domino Connector ACLRights utility provides the easy way to grant required access permissions to the Groupware Connector’s administrative account to databases of users intended for Groupware Integration between CRM and Lotus Domino.

Utility uses UserList.xml file to get the list of databases to operate on. Groupware Connector automatically downloads that file from CRM at startup and at run time if updated. Utility grants to 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 public adress book database.

To assign access permissions using ACLRights utiity:

1. Copy LotusConnector.jar, Config.xml, UserList.xml and private-contact-map.xml files to Lotus Domino directory on Domino server (e.g. C:\Lotus\Domino)

2. Stop Lotus Domino server

3. Launch following command from console:

java -classpath LotusConnector.jar com.sap.gcn.aclr ights.Main <user name>

where:

<user name> Name of Groupware Connector’s administrative account

4. Check report.txt file in Sysinfo sub-folder and trace*.txt file in Logs sub-folder if necessary

5. Start Lotus Domino server

ACLRights utiity will work only with databases located on local Domino Server. In case with multiple Domino Servers utility should be started on each server separately.

Batch-Assigning Access Rights for MS Exchange Connector ExAclSet utility provides the easy way to grant required access permissions to the Groupware Connector’s administrative account to required folders of users intended for Groupware Integration between CRM and MS Exchange.

To assign access permissions using ExAclSet tool:

ExAclSet tool operates using permissions of currently logged on user. Please verify that currently logged on user has permissions to assign access rights in all target mailboxes.

ExAclSet tool may not work with MS Outlook 2003 configured to work in Cached Mode. Switching Cached Mode ‘off’ and reverting to ‘on’ may resolve the problem.


Aug 2007 20/57

1. Start the ExAclSet tool.

2. Click Get Address Book button to open connection to MS Exchange server using MAPI profile and get list of users from Exchange Global Address Book.

3. Select the Groupware Connector’s administrative account in User combo box.

4. Add users to operate on into Operate On Mailboxes list by selecting them in Address Book list and

clicking button. List of users can be loaded from UserList.xml file (Groupware Connector automatically downloads that file from CRM at startup and at run time if updated). Click Load button to load list of users.

5. Select desired folder access rights in Role combobox. Editor role is required for replication of

• Appointments and Meetings in Inbox, Outbox, Calendar folders

• Private Contacts in Contacts folder

• Tasks in Tasks folder

Select Current (No Change) role if you do not want to change access permissions for selected folder.

Select Remove role if you want to remove selected user from folder’s Access Control List.

6. Click Apply Permissions to batch update folder Access Control Lists.

7. Check the log window for success of operation. Double click user in Operate On Mailboxes list to view current Access Control Lists of selected user.


Aug 2007 21/57

Setting Configuration Parameters Groupware

Сonnector stores configuration options in two files that are placed in the same folder with

Groupware С

onnector itself:

• Config.xml - contains configuration options for groupware connector.

• Proxies.xml - provides list of registered Proxy instances and their configuration options.

Admin Tool is used to view and modify configuration options for both Connector and Proxies. Admin Tool updates configuration files with new options and Groupware Connector tracks the changes in this config files and updates the behaviour ‘on the fly’.

The same Admin Tool executable is used for both Lotus and MS Exchange Groupware Connector. It switches to different modes depending on the set of files residing in the same folder. One can check the mode of Admin Tool and location of configuration file on the Home page.

To get current users statistics, press Statistics button.

The chapters below will provide the description of options configurable in Admin Tool and their mapping into config.xml.


Aug 2007 22/57

Groupware configuration

General (Connection configuration) Groupware Connection options for MS Exchange Connector.

Groupware Connection options for Lotus Domino Connector.

Groupware server (gw.connection.server, MS Exchange Connector only)

Specifies the name or IP address of the Groupware Server.


Aug 2007 23/57

Lotus Domino: Lotus Notes client installed on the same computer configures Groupware server name and user account. Configuration of the Groupware Connector stores only password for that account.

Lotus Domino Global Domain (gw.lotus.global-domain, Lotus Domino Connector only)

The name of the Global Domain document in Lotus Domino Public Address Book.

Administrative Account (gw.connection.admin-account)

Specifies an administrative account used by the connector to access the groupware storage.

MS Exchange: only name of the administrative account is specified. Authentication information used to access storage of MS Exchange Server should be provided on Log On property page of Groupware Connector service properties. Use Services applet in Control Panel to configure service options. The same can be specified on Groupware Connection → MS Exchange Specific page of Administrative Tool.

Lotus Domino: only pasword for the administrative account is specified. Lotus Notes client installed on the same computer configures Groupware server name and user account. Configuration of the Groupware Connector stores only password for that account.

Default Recipient Mail-ID (SMTP) (gw.default.mail-id, Optional parameter)

Specifies default mail ID of the target for data messages. In current implementation this should be e-mail address of the public folder for Contacts (MS Exchange Groupware Connector) or the Mail-in database for storing public contacts (Lotus Domino Groupware Connector).

MS Exchange Specific This page provides exactly the same functionality that is available on Log On tab of Windows NT service properties. One can change the account Windows NT service is running under.

Additional Internet Domains (gw.connection.domains)

Provide the list of additional organization domains in addition to domain account of administrative account (e.g.: [email protected]). The list is used to identify external users.


Aug 2007 24/57

Lotus Domino Specific This page provides additional Lotus Domino Connector specific configuration options.

Occurrences Per Endless Recurrence (gw.lotus.appointment.default-ocurrences)

Default number of occurrences per endless recurrent appointment.

All-Day Events (gw.lotus.allday.time-start & gw.lotus.allday.time-end)

Specifies start and end time for All-Day events replicated from CRM side.

Use Broadcast for Sending Requests (gw.lotus.broadcast-enable)

Do not expect responses from attendees upon sending meeting requests or updates.

Create New Instead Of Update (gw.update.as.delete.and.insert)

When update for a meeting comes from CRM, there are two options

- Update the already existing item. Only metting 'time' and 'location' properties can be updated this way.

- Delete previous instance and create a new one instead. This is default option. Attendees receive 'cancel' and new 'invitation' in this case. All properties are regenerated.

Replicate Meetings to Invitees as ... (gw.domino.meeting.request)

Specifies if meetings should be delivered to attendees as Meeting Requests (to be automatically or manually accepted later) or directly to user's Calendar.

Note: Recurrent meetings will be delivered to attendees as Meeting Requests only!

Priority of Miscellaneous Contact Fields (gw.lotus.contact.misc-fields-priority)

Gives the order of using miscellaneous fields appeared on Contact form since Lotus Notes 6.x.

Default Suffix For Database (gw.lotus.private-addressbook.file-suffix)

Default suffix for private address book database.

Address Book Mapping (gw.lotus.private-addressbook.mapping-file)

Private address book databases mapping file.


Aug 2007 25/57

CRM Adapter Connection

General

URL (mw.connection.url)

Specifies HTTP URL of the CRM Adapter. Please contact your CRM administrator for details.

User, Password (mw.connection.crm-auth)

Specifies user name and password for connection to CRM Adapter. Please contact your CRM administrator for details.

Client, Language (mw.connection.crm-auth)

Specifies client options for connection to CRM Adapter. Please contact your CRM administrator for details.

WSDL, WSML (mw.connection.msx.wsdl, mw.connection.msx.wsml, MS Exchange Connector only available for developers)

Specifies the path to the SOAP WEB Service definition files. Typically should not be modified.


Aug 2007 26/57

Advanced

Dump Xmls To (mw.advanced.xml-dump., available only in Power User mode)

This is a Check box which determines whether all incoming and outgoing xmls from CRM Middleware need to be dumped or not.

Dump Xmls To ( mw.advanced.xml-dumpto, available only for in Power User mode)

This determines the folder name specified in the above edit box for dumping xml’s

( i.e., Standard folder is XmlDump and which will be available in the Connector installation folder).


Aug 2007 27/57

Queue (User) Maintenance

Lock Options

Lock Timings For Failed Queues (queue.lock.timings)

Messages in each queue for a user should be processed in strict order - as they come in queue. This means that second message can no be processed if the first one is not done.

When error occurs queue is locked for the interval specified in this option. E.g.:

60, 1200, 3600, 86400

means that next try to process first messages again will be taken after 60 seconds, and in case of recurrent failure next retry will be taken after 1200 seconds and so on. When the last specified timing is reached - queue will be locked on the last listed period. The option is available only in “Power User Mode”.

Queue Errors Processing

Some errors can be ignored when processing data messages. Error information will be dumped to error log but queue will no be locked. Following options available:

• Ignore Required Fields (queue.lock.ignore.required-fields) - incorrect XML messages posted form missing some required fields will be skipped automatically and user queue will not be locked. Corrupt messages will be lost

• Ignore All Errors (queue.lock.ignore.all) - any kind of error during processing of messages in direction from CRM to Groupware will be ignored.

• Ignore Internal Errors (queue.lock.ignore.internal-errors) - any kind of error during generation of messages for sending from Groupware to CRM will be ignored.

In all cases error message will be written into error and trace logs.

The option is available only in “Power User Mode”.


Aug 2007 28/57

Current Locks This page gives the list of currently locked user data queues and allows administrative unlock of such queues.

To get explanation of error case by its code and get short problem resolution guidelines

• Select the listed errorneous,

• press Explain.

To get detailed error information

• Double click the entry.

To unlock the queues

• Select required queues (press Select All to select all queues) and do one of the following:

• Press Unlock to unlock the queue. This action is intended for the cases when locking problem is fixed. The problem can be identified by queue-lock error code.

• Press Unlock & Accept to unlock the queue and force accept the first data message in the queue. This action is intended for the cases when queue-locking reason cannot be resolved and we want to skip first erroneous message.


Aug 2007 29/57

Performance

General

BDOC Map Maximal Size (perf.cache-size.bdoc)

Groupware Connector stores cache of the mapping between CRM message ID (BDOC-ID) and Groupware messages ID (GW-ID). This cache is required for performance issues for the cases when Groupware Adapter is not able to provide GW-ID. Recommended value is about 10000 entries. The option is available only in “Power User Mode”.

Notify Queue Interval (sec) (perf.interval.nqueue)

Groupware Connector queries Groupware Adapter for the list of queues filled with data. This option specifies interval in seconds between recurrent calls when there is no filled queues. The option is available only in “Power User Mode”.

Notify Queue Retry Interval (sec) (perf.interval.nqueue-retry)

Specifies interval before next call to notify queue in case of failure (Network problems, CRM Adapter is not available and so on). The option is available only in “Power User Mode”.

Maximal Number Of Messages Per Cycle (perf.limit.msg-per-in-cycle)

Specifies maximal number of messages to be processed for a queue per one CRM � Groupware cycle. The option is available only in “Power User Mode”.

Number Inbound Workers (perf.job-count.in)

Specifies number of simultaneous inbound worker threads in Groupware Connector. Each worker thread can process one user queue at the moment. More threads provide better performance and make more load on Groupware Connector computer, network and Groupware Adapter and should have suitable hardware to support it.


Aug 2007 30/57

Logging

General

Logging files

Connector supports three types of logging files - log, error and trace. Each of them can be enabled/disabled and directed into specified file.

Log File (log.file.log.enable, log.file.log.fname)

Error File (log.file.err.enable, log.file.err.fname)

Trace File (log.file.trace.enable, log.file.trace.fname)

Visible messages severity

Information dumped to the trace file is ranged by severity. Lower severity values can used to reduce size of trace files, higher severity values can used to identify possible problems (log.file.trace.file-severity).

For debugging purposes Connector can be launched as console application. Message severity can be filtered for console output or console output can be disabled at all. It is recommended to disable console output in production environment (log.file.trace.console-enable, log.file.trace.console-severity).

Dump Failure Messages

Connector sends information about errors to CRM Adapter. Failure messages can be dumped to local disk before sent to CRM Adapter (log.dump.enable, log.dump.folder).


Aug 2007 31/57

Limits

History Limits

Connector can automatically delete obsolete log files. Specify maximal age for each type of log file.

Log File (log.limits.log-history)

Error File (log.limits.err-history)

Trace File (log.limits.trace-history)

Split Trace File By Fragments Of (log.limits.daily-size.truncate, log.limits.daily-size.max)

Trace file can grow up for a very huge size during one day when greater severity level is set up. Maximum size of trace file can be limited to the specified number of Megabytes. This makes viewing trace files much easier using any text editing tool like Notepad.

Managing Proxies

General This page allows to shortly review list and assignment of Groupware Proxies, specify default configuration options and custom configuration options for each Proxy instance.

The list provides following information

• Proxy ID – free-form ID of the proxy as provided by Administrator

• Host – the name of server on which Proxy instance is running

• Servers – the list associated Groupware servers. Data for the users whose mailboxes are located on given servers will be routed through that proxy. If some groupware server is not excplicitly assigned to a Proxy, default proxy will handle it. Default proxy does not require list of associated Groupware servers.

Following actions can be performed on given page:

• To register new Proxy instance – click Add New Proxy button on toolbar, and provide its option in the popup dialog. See the chapter below for details on Proxy configuration options.


Aug 2007 32/57

• To view or modify custom options of the Proxy instance – dbl-click the line of Proxy instance or select the line and press Edit Proxy Configuraton button on toolbar.

• To unregister proxy – click Delete Selected Proxy on toolbar.

• To view or modify default options for all Proxy instances – click Edit Default Configuration button on toolbar.

• To mark the Proxy instance as default – select the line and click Set Proxy as Default button on toolbar.

Monitoring This provides alive-state information and gives some Proxiy’s performance counters. It allows starting and stopping the Proxies on remote hosts.


Aug 2007 33/57

Following actions can be performed on given page:

• To start Proxy instance – click Start Proxy button on toolbar.

• To stop Proxy instance – click Stop Proxy button on toolbar.

• To view or modify custom options of the Proxy instance – dbl-click the line of Proxy instance or select the line and press Edit Proxy Configuraton button on toolbar.

• To change the period the average values are collected for – select the on from dropdown combo box.

Following information can be monitored on the given page for each proxy instance:

• Alive-state is color-highlighted.

• %CPU load on taken by the process of the Proxy on the host computer.

• Memory usage in kilobytes taken by the process of the Proxy on the host computer.

• Mhp-In (Messages Per Hour – Inbound – CRM � MSX) average inbound processing performance.

• Mhp-Out (Messages Per Hour – Outbound – MSX � CRM) average outbound processing performance.

• Scan – time taken by cycle to scan all mailboxes listed in User List.


Aug 2007 34/57

Configuring Proxies

General This page provides Proxy registration options and Groupware Connection options. First ones are listed on Proxies � General page of the Admin Tool.

• Proxy ID – free-form ID of the proxy as provided by Administrator

• Host – the name of server on which Proxy instance is running

• Servers – the list associated Groupware servers. Data for the users whose mailboxes are located on given servers will be routed through that proxy. If some groupware server is not excplicitly assigned to a Proxy, default proxy will handle it. Default proxy does not require list of associated Groupware servers.

Groupware Connection options for the Proxy instance has the same meaning as for Groupware Connector itself.


Aug 2007 35/57

Performance �� General

BDOC Map Maximal Size (perf.cache-size.bdoc)

Groupware Connector stores cache of the mapping between CRM message ID (BDOC-ID) and Groupware messages ID (GW-ID). This cache is required for performance issues for the cases when Groupware Adapter is not able to provide GW-ID. Recommended value is about 10000 entries. The option is available only in “Power User Mode”.

Count of Active Workers (perf.job-count.in, perf.job-count.out, perf.job-count.aac)

Inbound - the number simultenous PutMessage requests from Groupware Connector this proxy can handle simulteneously. Provide the value lower then same provided for Groupware Connector to limit the load on given Proxy instance computer.

Outbound - the number of simultenous threads scanning for changes in user’s mailboxes/databases. Each worker thread can process one user queue at the moment. More threads provide better performance and make more load on Groupware Connector computer, network and Groupware Adapter. Outbound worker threads are running all the time unless scheduled outbound replication is selected (see chapter Replication – Schedule below).

Auto-acceptor - (MS Exchange Connector only) the number of simultenous threads that accept self-generated meeting requiests. Auto-acceptor threads are activated when some meeting requests with invitees are posted from CRM to Exchange. More auto-acceptor threads provide smaller latency of processing. Auto-acceptor functionality can be disabled. See chapter Replication - CRM � Groupware for details.


Aug 2007 36/57

Performance �� Outbound Replication

Scanner Threads Sleep Factor (perf.job-out.sleep-factor)

Specifies the interval outbound scanner thread sleeps between switching to another user. This parameter allows increasing total number of simultenous outbound thread with the same CPU load. The greater number of threads the lower level of change-detection latency under condition when many users generate changes in their databases. The option is available only in “Power User Mode”.

Maximal Number Of Messages Per Cycle (perf.limit.msg-per-out-cycle)

Specifies maximal number of messages to be processed for a queue per one Groupware � CRM cycle. The option is available only in “Power User Mode”.

Manimal Interval Between Cycles (perf.interval.out-scan)

Specifies minimal interval between cycles for each individual user when Proxy will scan the user’s database for changes. This option prevents the Proxy from scanning the database too frequently.


Aug 2007 37/57

Tracing This page configures tracing options for the proxy instance. Trace files for the Proxy can be created on the same host where the proxy is running, or the data can be replicated to the computer with Connector and stored in the same file for all proxies. The first approach does not consume network resources, the second one gives all the information in one place – on the host with Connector.

Enable Tracing (log.file.trace.enable)

Enables tracing for the Proxy instance.

Trace Locally (log.file.trace.locally)

Specifies if trace messages will be written to local file on the Proxy host or will be transferred into trace file of the connector (over network). Localy tracing greatelly reduces network resources usage.

Trace File (log.file.trace.fname)

Filepath to the local trace file (relative to ProxySvc.exe).

Limit (log.limits.trace-history)

Upto how many days do you want to keep the files.

Split Trace File By Fragments of (log.limits.trace.fragment-size)

Specifies maximim size of the single local trace file fragment.


Aug 2007 38/57

Replication – CRM �� Groupware This page provides varios message replication options.

Default Reminder Interval (replica.default.reminder)

Provides default reminder interval for appointments and task when the value is not explicitly provided by CRM.

Auto-accept Meeting Requiest (replica.meetings.auto-accept)

Connector reproduces the behaviour of MS Outlook when creating meetings. To invite users into the meeting it sends invitations to recipients. Next, attendee has to accept the meeting so that corresponding entry appears in his Calendar. Groupware Connector can handle this automatically.

Send “New Task” Notifications (replica.tasks.notifications)

Check the option if your organization requires additional e-mail notification to be sent to the target user when task insertion or updation is being replicated from CRM to Groupware .

Format for Contact’s FileAs Field (replica.contacts.msx.file-as)

Specifies format for FileAs autogenerated field in Contact messages in Exchange store.


Aug 2007 39/57

Replication – Groupware ��CRM

Don’t replicate changes in … (replica.disable….)

Disables Groupware � CRM replication of given data message types.

Replicate changes … (replica.since….)

Specifies the age of changed items to be replicated from Groupware to CRM. The option is designed to avoid replication of outdated items duting initial user synchronization. E.g. typically there is no sence to replicate appointments created on year old.

In Groupware -> CRM replication the list of attachments supported are:

• Text files ( .txt extensions )

• Word documents ( .doc, .rtf and other similar extensions )

• Excel files ( .xls and other similar extensions )

• PowerPoint presentations ( .ppt and other similar extensions )

• Microsoft Mail documents ( .msg extensions )

• Image files ( .jpg, .bmp and other similar extensions )


Aug 2007 40/57

Replication – Schedule

To avoid unnessary load onto Exchange server while scanning mailboxes for changes, one may specify the scan cycles to start at given periods of time withing each day. The time is local time of the computer the Proxy instance is running on.

Debugging

Dump configuration files (dbg.dump-config)


Aug 2007 41/57

Checks if proxy in-memory configuration options should be dumped to local drive in the Proxy installation folder. Following files will be generated: DbgAppList.xml, DbgLastConfig.xml, DbgUserList.xml

Post “User Last Scanned” Time to Connector (dbg.dump-config)

Replication of “Last Scanned” information from Proxy to Connector consumes some network traffic. This information if provided in user statistics. Enable this option for debugging only.

SLD Server Configuration

System Landscape Directory (SLD) is a central repository of system landscape information that is relevant

for the management of the software lifecycle. It contains a description of the system landscape, that is, the

systems and software components that are currently installed. SLD data suppliers register the systems on the

SLD server and keep the information up-to-date.

General

SLD Authorisation details ( sld.reg.auth )


Aug 2007 42/57

Administrative Username and Password details required for SLD registration are stored as

Encoded encrypted format (using basic encryption algorithm).

SLD Server host name ( sld.reg.host )

SLD server host name is stored.

SLD Port number ( sld.reg.port )

SLD port number is stored.

SLD Registration enable/disable ( sld.reg.enable )

To enable or disable SLD registration of GW Connector is controlled by this attribute.

Setting Master Categories List in Microsoft Outlook (till 2003 version) SAP CRM Groupware Connectors use filtering by Categories for Tasks and Appointments in users’ mailboxes. An item is replicated to SAP CRM only if it is assigned with a category from predefined category list; therefore it is important to make these categories available in the groupware clients (such as Microsoft Outlook and Lotus Notes).

The Microsoft Outlook stores category names in Master Categories List; the default set is specified during Outlook installation process. When user changes Master Categories List, the Outlook updates user’s registry. Since the setting is stored on the client computer (under HKEY_CURRENT_USER\Software\Microsoft\Office\... registry key), in many cases it is impossible for system administrator to change Master Categories List without accessing user’s computer directly, under specific user’s account.

Different companies may have different practices for using Categories, including using of third party solutions, which provides its own custom list of categories. The solution, provided with SAP CRM Exchange Connector is designed with the specific goal of coexisting with other products and extending, not overwriting, the existing Master Categories List. The utility (regCategories.exe) provides a safe way to update the Windows registry, without the risk of damaging it. The utility only accesses specific keys in the registry, and does not require administrative rights for users (HKEY_CURRENT_USER key is always accessible).

A SAP CRM specific categories list could be configured by SAP CRM administrator. SAP Groupware Connector receives updated Master Categories List and writes it to the hard drive. Then, the Connector notifies administrator about changes in categories list by sending a notification to him. The administrator is responsible for distributing this information in a way that is most appropriate to the company.

The subsequent scenario could be the following:

• Administrator receives a notification letter about changes in categories list.

• Administrator copies regCategories.exe and CatsList.xml from Exchange Connector directory to some network resource(s), which could be accessed by all SAP CRM users.

• Administrator sends a letter to the users, containing a link to the regCategories.exe utility and short instruction how to run it and what is the purpose and importance of this activity.

• After receiving the instruction, the user runs regCategories.exe, and the following dialog appears:


Aug 2007 43/57

• The dialog contains a list of SAP CRM categories to be mandatory added to the Master Categories List. These categories are located on top of the list and are shaded grey. User can’t uncheck them. The categories listed in an existing Master Category list are located on bottom and are checked by default. User may review the list and uncheck any of them. Unchecked categories will be deleted from updated Master Category List. The resulting Master Category List will contain exactly those categories that are checked in the list. The user chooses the categories required and presses OK.

User may review the result choosing Edit → Categories menu items of Microsoft Outlook.

For Silent mode operation of RegCategories.exe kindly refer SAP Note :1043481

Setting Categories List in Microsoft Outlook 2007 Unlike described in the “Setting Master Categories list in Microsoft Ou0tlook (till Outlook 2003)” in outlook 2007 or so called Outlook 12 version does not use user’s registry (HKEY_CURRENT_USER) for storing categories. Outlook 2007 has changed the way categories where being stored and from this version it is storing the categories in a hidden object (0x7C08) of Calender folder of each individual mailbox.

So in order to upload CRM Categories from catlist.xml into Outloook 2007 following steps need to be followed:

• Administrator receives a notification letter about changes in categories list.

• Administrator copies regCategories.exe and CatsList.xml from Exchange Connector directory to some network resource(s), which could be accessed by all SAP CRM users.

• Administrator sends a letter to the users, containing a link to the regCategories.exe utility and short instruction how to run it and what is the purpose and importance of this activity.

• Start Outlook for the mailbox for which categories need to be updated.

• After receiving the instruction, the user runs regCategories.exe, and the following dialog appears


Aug 2007 44/57

• Unlike displaying Outlook default categories in the list (like old behavior) it displays only SAP CRM categories and user can’t uncheck these options. The behavior has just been retained even though user can’t uncheck the options in the list in order to avoid confusions among the old behavior and new behavior of this tool.

• Press OK if you want to update Outlook Categories list.

• Immediately you get Choose Profile dialog asking the user to give the profile name to which SAP CRM categories will be updated i.e., Each profile is associated to an exhange mailbox, so inturn it will be updating the mailbox itself.

o If User does not have any profile then create a new outlook profile for the desired user mailbox to which user wanted to update outlook categories list.

(Use Windows Control Panel -> Mail -> Show Profiles -> Add option to create new outlook profile)

• Wait for the regCategories.exe to close automatically.

• Close the Outlook.

User may review the result choosing Edit -> Categories menu item of Microsoft Outlook.

Using Connector Logging Information In order to effectively manage a Groupware Connector, it is necessary to get feedback about the activity and performance of the connector as well as any problems that may occur. The Groupware Connector provides comprehensive and flexible logging capabilities. This chapter describes how to configure the logging capabilities of the Connector, and how to interpret the contents of the logs.

The log files are generated as the connector software is running. They require hard disk space to store logged information. Obsolete log files are not removed automatically and it is an administrative task to remove and backup obsolete files.


Aug 2007 45/57

Connector Log File 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.

Example of a Connector Log File Here is an example of the connector log file entries: [25/May/2002:13:08:57 -0500] MIDDLEWARE jonh_doo@sa p.com INSERT APPOINTMENT 66ED4A099D1F274AAC4B37EB9EB0AE14 18DFD51F9FF1CD5EC2256BC400379134 Each part of this log entry is described below:

1. [25/May/2002:13:08:57 -0500]

The time when the Connector finished message processing. This part of entry has the following format: [day/month/year:hour:minute:second zone]

2. MIDDLEWARE

The source of the message. Supported values are GROUPWARE, MIDDLEWARE.

3. [email protected]

This e-mail address represents the destination user or public folder (for MS Exchange) or the mail-in database (for Lotus Domino).

4. INSERT

The operation type of the message. Supported operation types are INSERT, UPDATE or DELETE.

5. APPOINTMENT

The type of the processed message. The release 3.1 of SAP CRM supports the following types of messages: APPOINTMENT, TASK, and CONTACT.

6. 66ED4A099D1F274AAC4B37EB9EB0AE14

BdocID of the message as defined in the SAP CRM System.

7. 18DFD51F9FF1CD5EC2256BC400379134

The Groupware UID of the message. The length of the UID for the Lotus Domino Server equals strictly 32 characters; the length of the UID in the MS Exchange can vary up to a length of 256 characters.

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.

Format The format of the log file is as follows: [20/Jul/2002:12:14:23 +0300] ERROR MIDDLEWARE Jonh_ [email protected] UPDATE TASK 8478753987534287 33985834893454394342342 “[ERR:1002 ] Global address book not available” The log file format is similar to the Connector log file format, with two additional fields defined:

1. ERROR The severity of the error. Valid values are WARNING, ERROR or CRITICAL.

WARNING typically informs that some 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 severity means that a single user has a permanent error while delivering a message that does not exist in the Groupware server.


Aug 2007 46/57

CRITICAL severity means that no messages can be delivered, since no connection to the Groupware Server or the Groupware Adapter can be established. 2. “[ERR:1002] Global address book not available”

The error message produced by the Connector includes the error code and a short error description.

List of Error Messages The table below describes possible error messages:

SAP Connector Error Messages

Code Short Description

9 Unspecified error

Description : An unknown error has occurred.

Resolution : See trace log for details.

1000 %s

Description : Not an error - reserved for system messages like ‘service started’ or ‘service stopped’.

Resolution: None.

1001 Administrative logon failed. %s

Description : Initial logon to the Groupware server using 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. See the chapter “

Verifying Connection to the MS Exchange Server” for details.

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

1003 Msxml2.DOMDocument not available

Description : Msxml2.DOMDocument COM object is not installed on the computer with the Groupware connector service.

Resolution : Verify the installation.

1004 MSSOAP.Client not available

Description: MSSOAP.Client COM object is not installed on the computer with the Groupware connector service.

Resolution : Verify the installation.

1005 SOAP initialization failed

Description : Initialization of SOAP transport failed. A typical problem is an invalid content of mwpayload.wsdl or mwpayload.wsml.

Resolution: Verify the contents of mwpayload.wsdl, the value of ‘<soap:address location>’ should point to the URL of the SAP CRM SOAP server.

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 “xslt/” folder (as specified in “config.xml”).


Aug 2007 47/57


1008 Internal error occurred.

Description : An internal connector error has occurred.

Resolution: See trace log for details.

1009 Public folders store not available to administ rative account.

Description : (MSX only). Connector failed to locate the Exchange information store with public folders.

Resolution: Verify the installation. Check administrative account settings.

1010 Invalid default target folder for contacts.

Description : The option specified in config.xml for “gw.email.default” is either invalid or does not correspond to the public folder.

Resolution: Verify the installation.

MS Exchange Connector: make sure that Hide from Address Book is unchecked on Exchange Advanced property page of the public folder.

1012 XSD schema validation failed.

Description : Validation of outgoing XML message against XSD schema failed.

Resolution: Contact SAP CRM technical support.

1013 CDO (Collaboration Data Objects) library not availa ble.

Description : CDO (Collaboration Data Objects) library not available.

Resolution: Verify the pre-installation requirements.

1014 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 CRM adapter.

Resolution: none.

1015 Error while reading user list from CRM.

Description : Error while reading user list from CRM.

Resolution: Contact SAP CRM technical support.

2001 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 given mailbox is available over network.

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.

2003 User not found in groupware domain. %s

Description : The e-mail 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.

2020 Q-Unlock XML is not well formed


Aug 2007 48/57


Description: An invalid XML is provided in the administrative queue unlock XML file.

Resolution : Provide the valid XML.

3001 Transport error

Description : SOAP Transport error.

Resolution : Verify the network connection and check if the SAP CRM middleware SOAP server is working properly. See the chapter “Verifying Connection to the Payload Interface” for details.

3002 Payload interface error. %d

Description : An error was returned by payload interface.

Resolution : See the chapter “Resolving Payload Interface errors" for details.

3003 CMW_PIF_Qlogon failed. %s

Description: Logon into queue failed. Possible reason – SOAP Transport error or Payload interface error.

Resolution: See the chapter “Resolving Payload Interface errors" for details.

3004 CMW_PIF_Qlogoff failed. %s

Description: Queue logoff failed. Possible reason – SOAP Transport error or Payload interface error.


3005 CMW_PIF_getMsg failed. %s

Description: Failed to get message from the logical queue. Possible reason – SOAP Transport error or Payload interface error.


3006 CMW_PIF_getMsg returned empty message

Description: SAP CRM Middleware has returned NULL message.

Resolution: None, this is a warning.

3007 CMW_PIF_getMsgCount failed. %s

Description : Failed to get message count in data queue. Possible reason – SOAP Transport error or Payload interface error.


3008 CMW_PIF_postMsg failed.

Description : Failed to post message. Possible reason – SOAP Transport error or Payload interface error.


4001 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 trace log for details.

4002 Required field(s) missing or invalid. %s

Description : One or more required fields are missing in the XML message.


4003 CRM Message is invalid. %s


Aug 2007 49/57


Description : XML message provided by CRM side is invalid: the structure is wrong, required blocks are missing, etc.


4004 XSLT transformation failed.

Description : Failed to invoke XSLT transformation on a given message part.


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

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

5003 CDO default folder not available: %s.

Description : Default CDO folder is not available in the given mailbox.

Resolution : Login to the mailbox using MS Outlook for creation of all required folders or else not enough access rights assigned to the user.

5004 CDO message not found.

Description: CDO message is not found in the Groupware for INSERT or UPDATE operations.

Resolution: None, this is a warning.

5005 Unsupported field: name = %s

Description: Unsupported field name is listed in translated XML.

Resolution: Verify available XSLT files for corresponding document type.

5006 Unsupported field-type: %s.

Description: Unsupported field type is listed in translated XML.


5007 Invalid field value: field id = %s

Description: The SAP CRM middleware side provides invalid field value.


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


5009 Delete CDO message failed.

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.


Aug 2007 50/57


5010 Send CDO message failed.

Description: Failed to invoke sending of a message to the target recipients.

Resolution: Should never happen.

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

5012 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 failure on the SAP CRM middleware side.

Resolution: Verify ready state of middleware side.

5013 Message failed

Description: Processing of the message failed due to one ore more errors.


5014 Auto-accept initiation failed

Description: Failed to initiate auto-accept for meeting request.


5015 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 target folder (performance consuming operation).

Resolution : Verify functionality of the SAP CRM middleware side, see trace log for details.

5016 List of recipients is invalid

Description: List of attendees or recipients provided in message has one or more invalid recipient SMTP address specification.


6001 Failed to initialize middleware

Description: Failed to initialize middleware.


6002 Failed to uninitialize middleware

Description: Failed to uninitialize middleware.


6003 Failed to get list of active queues.

Description: Failed to get list of active queues.


6004 Failed to get count of messages in data queue.

Description: Failed to get count of messages in data queue.


6005 Failed to get message from data queue.


Aug 2007 51/57


Description: Failed to get message from data queue.


6006 Failed to accept message.

Description: Failed to accept message.


6007 Failed to send failed message notification.

Description: Failed to send failed message notification to CRM side.


6008 Failed to post message into data queue.

Description: Failed to post message into data queue.


6009 Failed to get list of users.

Description: Failed to get list of users.


6010 Failed to get list of categories.

Description: Failed to get list of categories.


7006 Unsupported field-type: %s.

Description: (Domino only) translated XML contains an unsupported field type.


7007 Invalid field value: field id = %s

Description: (Domino only) the SAP CRM middleware side provides invalid field value.


7008 Update Lotus document failed.

Description: (Domino only) Failed to save changes in the Lotus document into the Groupware. Possible reasons – insufficient access permissions for the administrative account.


7009 Delete Lotus document failed.

Description : (Domino only) Failed to delete 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.

7010 Insert Lotus document failed.

Description: (Domino only) Failed to create/save a Lotus document to the target recipients.


7013 Message failed

Description: (Domino only) Processing of the message failed due to one ore more errors.


7015 Searching by BDOC-ID


Aug 2007 52/57


Description: (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 target folder (performance consuming operation) and has search error.


8010 SMTP. Send message failed.

Description: (Domino only) Failed to invoke sending a message to the target recipients.


9001 Failed to generate XML representation for mess age

Description: Failed to generate XML representation for message in Groupware.

Resolution: Please contact SAP technical support.

Trace Log File The connector writes debugging information to the trace log file, which should help you to investigate possible problems with the connector.

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

The trace log file may grow very large and may also affect overall application performance. It is recommended to have the trace log disabled during normal operation. You should only enable it during the deployment phase or when some problems are discovered.

An error message reported to the error log will always appear in the trace log, provided tracing is enabled.


Aug 2007 53/57

Troubleshooting the Connector

Verifying Connection to the Payload Interface Review this chapter if the following error occurs: “[ERR:3001] SOAP Transport error “

Use MS Internet Explorer or Netscape Navigator to connect to the CRM Adapter. To find the CRM Adapter URL 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 two possible reasons for the responese are:

• 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 will get the error message “HTTP Error 404 - Not Found “. Check the configuration of the payload server.

Resolving Payload Interface errors Review this chapter if you are getting errors concerned with the Payload Interface (error codes 3001 through 3009 ). These errors can be raised while processing different operations and their resolution depends on their error code returned by the Payload Interface. You can find the corresponding error code in the text of error messages.


0 Success

1 Success - queue created on the fly

2 Error – access denied. Most probable reasons:

• Wrong parameters are specified for CRM Adapter connection in Admin Tool.

3 Queue does not exist Most probable reasons:

• There is a problem on groupware connector or groupware adapter side. Contact support team for details. This error should not happen normally.

4 Another session already established

Most probable reasons:

• Two or more groupware connectors are conected to the same groupware adapter. Verify the CRM Adapter Connection setting for all running instances of groupware connectors.


Aug 2007 54/57


5 Session ID not known


• Connection session with groupware adapter has expired due to timeout. Connector will automatically restore connection as needed. This error can be ignored normally.

6 Wrong parameter



7 Property not known



8 Feature not implemented



9 Unspecific error


• There is a problem on groupware connector or groupware adapter side. Contact support team for details.

10 No more messages available


• All messages are already fetched from groupware adapter’s data queue. This error can be ignored typically.

11 Operation not allowed


• There is a problem on groupware connector or groupware adapter side. Contact support team for details.

101 SOAP transport error


• The Groupware adapter is experiencing problems with the network connection. See the chapter "Verifying Connection to the Payload Interface" for details.


Aug 2007 55/57

Verifying Connection to the MS Exchange Server Read this chapter if one of the following errors occurres:

[ERR:1001] Administrative logon failed “

[ERR:2002] Logon failed for:<mailid>“ occurs.

You will require an MS Outlook to be installed.

Proceed as follows:

Log off from MS Outlook (if started).

Choose Start�Setting�Control Panel �Mail applet and configure the Administrative Log-on profile as follows.

1. Display profiles.

2. Add a new “Microsoft Exchange Server” profile.

3. Type in the name of your account.

4. Specify the Exchange server and Account provided in config.xml (gw.server and gw.admin.account properties).

5. Select the newly created account in “When starting MS Outlook, use this profile” combo-box.

Launch MS Outlook. If MS Outlook is unable to log on either the Exchange Server name or the provided Account is invalid.

If you receive the message ERR:#2002 , the provided administrative account may have no permissions to log on to the mailbox corresponding to the provided mail ID.

The Connector (as well as MS Outlook) uses Windows NT authentication for providing authorization in the Exchange Server. That means you have to locally log on to the computer running MS Outlook using the administrative account when connecting to the MS Exchange Server. When running the Connector as a service, authentication information provided on the Logon tab of the service properties is used.

Obtaining Error Details In case of any connector failure detailed error information is available in the following places:

1. Error log file provides one line per error with short info.

2. Trace log file provides detailed error information if available. You may use the contents from the error log to search in the trace file for details.

3. ErrDumps subfolder contains detailed information about errors sent to CRM. A copy of the sent messages is stored on the local drive.

4. queue-locks.xml use Current Locks page in the Admin Tool to view contents of this file

Each of the mentioned items is available by default. However each of them can be disabled from Admin Tool.

Detailed system information may be required to provide support for the solution. The information can be partially obtained using the diagnostics tool. Refer to chapter Using Diagnostics Tool for more details.


Aug 2007 56/57

Using Diagnostics Tool (Exchange Connector) Exchange connector includes GwcDiag.exe diagnostics tool. It will gather system diagnoistics using Groupware Connector configuration and generate reports into SysInfo subfolder.

One must logon locally using Groupware Connector administrative account to start the tool. The tool does not require additional paramters to start.

Generated files are:

• AddrBook.txt - contains complete dump of the Global Address book with names of the Exchange Servers holding user’s mailboxes.

• Summary.txt - contains short summary of solution: administartive account, size of UserList.xml, size of Exchange Global Address Book and list of known Exchange servers (identified by references from Global Address Book).

• SysInfo.txt - contains the computer configuration with list of used DLLs.

• UserList.txt - contains details of mailbox access verification for each user listed in UserList.xml

• UserList Access.txt - contains list of mailboxes and folders the connector is not able to get access to.

• UserList External.txt - contains list of external users listed in UserList.xml

• UserList Invalid.txt - contains list of users having no mailbox in the organization

Using Diagnostics Tool (Lotus Connector) Lotus connector includes GwcDiag.bat diagnostics tool. It will gather system diagnoistics using Groupware Connector configuration and generate reports into SysInfo subfolder.

One must logon locally using Groupware Connector administrative account to start the tool. The tool does not require additional paramters to start.

Generated files are:

• AddrBook.txt - contains complete dump of the Public Address Book.

• Summary.txt - contains short summary of solution: size of UserList.xml, size of Public Address Book and list of known Domino servers (identified by references from Public Address Book).

• SysInfo.txt - contains complete dump of java environment.

• UserList.txt - contains details of mail databases access verification for each user listed in UserList.xml

• UserList Access.txt - contains list of users from UserList.xml whose permissions prevent accessing required databases.

• UserList External.txt - contains list of external users from UserList.xml

• UserList Invalid.txt - contains list of users from UserList.xml that are not available in Public Address Book.

Backup plan MS Exchange and Lotus Domino Connectors store all sensitive information in file system. There is no sensitive information stored with the Proxy instances.

The following items are subject to backup:

Config.xml Stores all the configuration settings for connector.

Proxies.xml Stores all the configuration settings for proxy instances.


Aug 2007 57/57

UserList.xml Holds the list of CRM Users

AppList.xml Holds the list of CRM Application

Storage subfolder Holds internal connector’s data.

In case of a server crash follow the next steps to recover configuration:

• Reinstall the Groupware connector.

• Extract Config.xml from backup storage.

• Extract outbound replication state data from backup storage.

SAP Groupware Connector Administration

Documents

require additional

global address

gather system

messageshour

public address

click apply

modify custom

power user