Docstoc

JJWDesign_Google_Maps

Document Sample
JJWDesign_Google_Maps Powered By Docstoc
					JJWDesign Google Maps
        SugarCRM Module




        Developed for use with SugarCRM.

 This project is in no way affiliated with SugarCRM.



             Written By: Jeff Walters
                   Version 1.0
           Created: October 4th, 2010
         Last Modified: October 8th, 2010



             JJWDesign.com



   OFFICE: ORLANDO | FL 32810 USA

www.jjwdesign.com | ijjwdesign@gmail.com




                                             JJW Design Google Maps   1
TABLE         OF     CONTENTS

Table of Contents........................................................................................................................................................ 2
Google Maps Project Overview................................................................................................................................... 3
Installation.................................................................................................................................................................... 3
   ModuleBuilder Installation........................................................................................................................................ 3
Geocoding................................................................................................................................................................... 3
   Geocoding Objects................................................................................................................................................... 3
   Module Geocoded Counts ....................................................................................................................................... 4
   Testing Geocoding................................................................................................................................................... 4
   Geocoding as a Scheduled Task............................................................................................................................. 4
   Geocoding Fields..................................................................................................................................................... 5




                                                                                                                     JJW Design Google Maps                        2
                            JJWDESIGN GOOGLE MAPS
GOOGLE MAPS PROJECT OVERVIEW
Like many projects on SugarForge.org, the JJWDesign Google Maps project started out during an afternoon
conversation on how great it would be if we could map all of our SugarCRM leads on a Google Map. Over the
period of about a year it has developed into an active project on SugarForge.org. It has gone through many
revisions and changes during this time. Recently it was redeveloped to be an add on Module that could be installed
using ModuleBuilder.

The current version provides Google Maps mapping for Accounts, Contacts, Leads, Opportunities, Cases and
Projects (records). Multiple records can be mapped, instead of just one record at a time. Records can be mapped
from using a module's listing view or by defining a custom map with center point and distance (radius).


INSTALLATION
MODULEBUILDER INSTALLATION
Installation is very simple using the ModuleBuilder tool and can be uninstalled (reversed) if needed. Simply
download the latest package from SugarForge.org at:

http://www.sugarforge.org/projects/jjwgooglemaps/

You must be logged in as an Administrative User to use ModuleBuilder. Please see the SugarCRM documentation
on how to use ModuleBuilder if you are new to this process.


GEOCODING
GEOCODING OBJECTS
This module takes advantage of Google Maps V3, which does not require an API Key; as the older versions have
required. Before you can create any maps, you must first geocode your objects. Geocoding is done through Google
Maps Geocoding service. This service is limited to 2,500 requests per day. Please see Google Maps Licensing
Agreement for more information on licensing costs.

The module limits the requests to 250 at one time. So, it may require several executions to reach your daily limit
and perhaps several days to geocode all of your objects. To start processing, go to the Maps module and click on
“Geocode Addresses”. Do not expect it to be done in a second or two. Geocoding may take several minutes to
execute. Don't worry as this can be setup as a Scheduled Task (See “Scheduled Task” Below). Note, this module
will cache the addresses' geocoding information during processing to reduce the overall number of requests
needed, as many common objects will have the same address, such as Accounts and Contacts.



                                                                           JJW Design Google Maps        3
MODULE GEOCODED COUNTS
After geocoding is processed, you will be redirected to the Geocoding Counts by Module page. The last geocoding
response will be shown at the top of the page. If you have exceeded your geocoding limit, you will see
“OVER_QUERY_LIMIT” at the top of the page. Otherwise, it will most likely say “OK”. The geocoding counts table
will show the number of module objects geocoded; grouped by geocoder response. The responses are from the
Google Maps Geocoder Results object.

The Google Maps Geocoder may return one of the following status values:

    •   OK indicates that the geocode was successful.
    •   ZERO_RESULTS indicates that the geocode was successful but returned no results. This may occur if the
        geocode was passed a non-existent address or a lat/lng in a remote location.
    •   OVER_QUERY_LIMIT indicates that you are over your quota.
    •   REQUEST_DENIED indicates that your request was denied for some reason.
    •   INVALID_REQUEST generally indicates that the query (address or lat/lng) is missing.
The geocoding counts table gives you a module by module count on what has yet to be geocoded (N/A – or not
applicable), what has been geocoded (OK) and what has failed geocoding (ZERO_RESULTS or
INVALID_REQUEST). You might see “ZEO_RESULTS” if the object's address is not a proper format or does not
exists. I have noticed that Google Maps does a great job of determining partial matches for addresses that are not
complete; such as a missing street.

TESTING GEOCODING
Google Maps Geocoding has worked well for many different countries, but it isn't without its issues. In case you are
having difficulties, use the “Geocode Test” page to view the response of a problem address. This will evoke a
Geocoding Request for an user input address (all on one line) and will display the resulting data as an array.

Example Data for “Orlando, FL 32810 USA”:

Array
(
  [address] => Orlando, FL 32810 USA
  [status] => OK
  [lat] => 28.6170174000000017
  [lng] => -81.4224040000000002
)


GEOCODING      AS A   SCHEDULED TASK
To process the geocoding requests it is recommended to setup a nightly Cron-Job. A custom entry point has been
created for this purpose and can be accessed without authentication. The URL shown below is meant to be used
with an Administrative Scheduled Task. Please see the SugarCRM documentation for more information on
“Scheduled Tasks”.

Example Processing URL:



                                                                            JJW Design Google Maps        4
http://www.yourdomain.com/sugarcrm/index.php?entryPoint=jjwg_Maps&cron=1

This schedules task is used to geocode various objects. This task provides geocoding for new objects as well as
objects that have had modification to their address. When a new Lead is created the geocoding data is not created
initially. The geocoding addresses process has to be executed to provide this information.

Note, the logic hook shown in the package is NOT used to geocode the object. This would slow down the CRM too
much for normal use. The logic hook is used in the case where the address has changed; in which case, the
geocoding information will be reset. Later the scheduled task will geocode the object. This may seen inconvenient
to the user creating the map, but not to the users who just want to add or edit an object.

It seem feasible to run a Scheduled Task of geocoding objects every 15 minutes, or as a nightly process. Be careful
in setting a higher limit (such as 2,500) on the number of objects geocoded during each process, as server
resources used may cause your CRM is act slow or unresponsive.

GEOCODING FIELDS
There are four custom geocoding fields that are added, during the installation process , to the Accounts, Contacts,
Leads, Opportunities, Cases and Projects modules. The field names are consistent across each module and can be
seen as custom fields using the Studio. If necessary these four custom fields can also be added to any of the views.
The following are the field names and data types used.

        jjwg_maps_lng_c - float(11,8)

        jjwg_maps_lat_c - float(10,8)

        jjwg_maps_geocode_status_c - varchar(255)

        jjwg_maps_address_c - varchar(255)




MORE    SOON ...




                                                                            JJW Design Google Maps        5

				
DOCUMENT INFO