HOWTO: Troubleshoot Zetafax Connector for Goldmine (Outbound)
This Zetafax technical note applies to:
- Zetafax for CRM
- Zetafax Client/Server version 9 or earlier
The following document is a trouble-shooting guide that should enable users/system administrators to track down and diagnose any problems they might be experiencing with the Zetafax for CRM product when used in conjunction with GoldMine. This document specifically looks at the Outbound Message functionality.
It is intended that this document be read in parallel with technical notes that relate to the configuration and use of Zetafax for CRM.
Overview of Outbound functionality:
The Outbound functionality is installed via the Zetafax for CRM installer. To operate correctly, it requires a Zetafax CRM licence to be registered on the Zetafax Server. During install, the Zetafax CRM Windows service is registered on the system. This is an Automatic service that runs under the Local System account and can be viewed through Control Panel --> Services. It is this executable along with zfGMLib.dll that does all the processing for the Outbound messaging. In total, this service performs three major functions for the GoldMine integration:
- Generates the ZFToGM.csv file that is used by the Zetafax Client to access GoldMine contacts when addressing a fax message.
- Programmatically constructs and sends fax and SMS messages (using the Zetafax API) based upon scheduled actions created from within GoldMine.
- Monitors Zetafax user outboxes to determine whether GoldMine fax and sms messages have been sent correctly.
General troubleshooting hints and tips:
This section provides some general information that may be useful when troubleshooting the Zetafax for CRM (GoldMine) product.
Read the GoldMine log. This is called gm.log. The version of this file that pertains to the ZFToCRM service can be found in the < Windows> \System32 folder. There are four types of message that are logged to gm.log. These are:
- Error - Serious events that usually prevent the user from proceeding with their task
- Warning - Less serious events that may require attention
- Information - Informational events only, to allow users/administrators to monitor what is happening
- External Source - Events logged by an external application that is connected to the Zetafax-GoldMine integration library.
A typical log entry takes the following format:
< date> < time> < Log Entry type> < Log message> < Developer reference>
27-8-2003 15:29 ERROR Failed to log user GARY (-4) onto GoldMine GMConn.cpp 357
Furthermore, The CRM Windows Service does write limited fault information to the Windows Event Log should gm.log fail to initialise.
Resolving Specified Problems:
The remainder of this document focuses upon particular symptoms and their resolution
The GoldMine address book in the Zetafax client is not visible
- Check that you are running the correct version of the Zetafax Client. It should be version 8 or later.
- Ensure that the ZftoGM.csv file is being generated and placed in < Zetafax Install Folder> \System\Z-DB. If this file is not present, search the local hard drive for a file called ZFToGM.tmp. If this file exists, it can be renamed with a 'csv' extension and placed in the afore mentioned directory. This will get you up and running, but it is unlikely that the .csv file will be updated in the future (continue with fault diagnosis)
- Ensure that the ZFToCRM windows service is running. To do this:
- Open the Windows Control Panel
- Select Administrative Tools
- Select Services
- Locate the ZFToCRM service
- If the service is not running, then start it manually
- Wait for a couple of minutes, the CSV file should be updated/generated
- The Windows Service may not have the correct logon information with which to connect to GoldMine. If this is the case, you run the repair option on the Zetafax for CRM installer and re-enter the GoldMine logon information.
Fax/SMS messages scheduled through GoldMine are not been sent or are consistently failing
- Ensure that the ZFToCRM Windows service is running (see above for more information)
- The Windows Service may not have the correct logon information with which to connect to GoldMine (see above for more information)
- The GoldMine integration library may be unable to log onto the Zetafax API. Ensure that zfapi32.dll is present on the system and registered using regsvr32.exe. Also, ensure that the Zetafax username provided corresponds to an existing Zetafax user. To check which Zetafax username is being used, do the following:
- Open Regedit
- Browse to HKEY_LOCAL_MACHINE\\Software\\Equisys\\Zetafax\\ZfToGm
- Under this key, there will be a FAXSEND_UN entry. The value should be an existing Zetafax username.
- Under the key mentioned above, there are also two other values that it is worth checking. These are:
- ZF_SYSTEM_DIR, which should point to the Zetafax System directory
- TargetAppDir, which should point to the GoldMine install folder
- If either of these values is missing, the fax will not be sent. Gm.log will provide further information on the exact type of error that has occurred.
- If a message fails to send, it is automatically removed from the GoldMine calendar, and needs to be rescheduled by the user. The appropriate GoldMine user is sent a GoldMine email to this effect everytime the situation occurs.
The gm.log says that I provided a blank mobile number for sending an SMS message. I don't think that I did.
By default, the Outbound functionality assumes that the 'Phone3' field within a GoldMine contact record is the correct number to use for sending an SMS message. If your mobile phone numbers are stored in a different field, then this setting can be over-ridden by adding a registry setting. To do this, do the following:
- Open regedit
- Browse to HKEY_LOCAL_MACHINE\\Software\\Equisys\\Zetafax\\ZfToGM
- Create a new key called 'Mphone'
- The value of this field should be either 'Phone1' or 'Phone2' or 'Phone3' as appropriate.
Note: This is an 'all or nothing' setting, and that the field used cannot be configured on a message-by-message basis.
The documents that I attach to a fax are not being picked up by Zetafax.
This problem may occur when the folder that holds your documents is not the default templates folder created during a GoldMine install. To rectify this problem, an over-ride can be specified in the registry using the mechanism described above. The key name to create is 'GM_TEMPL' and the value should be a path that points to the location of your templates folder.
Last updated: 29 October 2003 (SV/DH)