CRM GEOCODING WORKFLOW ACTIVITY PLUGIN


OVERVIEW

Geocoding is the process of determining a latitude and longitude for a location based on an address. Having latitude and longitude set on a record in an entity such as Leads or Accounts is a requirement for territory management or advanced find mapping.

The Geocoding plugin is a workflow activity, that is, it is used as a step in a workflow process. It reads address values from a record and returns latitude and longitude values which can be used to update the record in a subsequent step. Typically you would configure such a workflow to trigger on newly created records or when a record’s address information changes.

This is designed to be used in conjunction with the Territory Sync Plugin and the Location Lookup Workflow Activity.  The Territory Sync Plugin fires when a properly configured EasyTerritory projecty is saved, pushing territory polygons from EasyTerritory to SQL Server and territory attributes to CRM. It can also intersect the territory polygons against records in other entities such as ‘Leads’ or ‘Accounts’ which have latitude and longitude set.  This plugin will update territory references on those records.

The Location Lookup Workflow Activity would typically be invoked as a later step in the same workflow where geocoding occurs, or in a separate workflow triggered by changes to latitude and longitude (if this plugin is not the only source of changes to latitude and longitude). The Location Lookup Workflow Activity looks up the new point against polygons in SQL Server. The Geocode plugin workflow can do this itself for the simplest scenarios, where the polygons refer to the actual ‘Territory’ entity.  Note that if you need to set a reference to any entity other than ‘Territory’, or if you use the column constraint feature of the Territory Sync Plugin, then the Location Lookup Workflow Activity will be a better tool for looking up the location.  The Territory Sync Plugin is not configured to use any column constraints (i.e. you do not support more than one type of Territory).

PLUGIN CONFIGURATION

  1. The Geocoding Plugin (DynamicsCRM.Plugins.Geocode) is installed when you import the EasyTerritory Components Unmanaged Solution. You can register here to get the unmanaged solution.
  2. The following example shows how to create a process that fires the geocode plugin. First, create a new workflow process.

    For the first step in the process, add the DynamicsCRM.Plugins.GeocodeProc. Set your EasyTerritory URL (version 1.1) or Bing Maps Key (version 1.0) and the form fields that contains the address information (Street Address, City, State, Zip, and Country, which defaults to ‘US’).

    If you are using EasyTerritory to manage Territory polygons and you are geocoding a record with a Territory entity reference, set PerformTerritoryLookup to true and set LookupMapDotNetURL, LookupMap, LookupLayer, and LookupLayerNameField to the MapDotNet web services location, map ID, layer ID, and field containing territory names.

    Note that if you need to set a reference to any entity other than territory, or if you use the column constraint feature of the Territory Sync Plugin, then the Location Lookup Workflow Activity will be a better tool for looking up the location.

    For the second step, set the fields that should get populated with the Bing Maps geocode response.

    LatString & LongString – Used for Latitude and Longitude fields that are ‘Single Line of Text’ data type.
    Latitude & Longitude – Used for Latitude and Longitude fields that are either ‘Floating Point’ or ‘Decimal Number ‘ data type.

    Other Response Values Include:

    Quality – How accurate the geocode is. This should be a ‘Single Line of Text’ field. The Bing Geocoding service returns the following values: High, Medium and Low. The EZT service returns Best, Good, Fair, and Poor. Bing “High” confidence values map to “Best” or “Good” based on secondary information, “Medium” maps to “Fair”, and “Low” to “Poor”.

    Match Address, Match City, Match County, Match State, Match Country, Match Full Address, Match Postal Code (Zip 5 and Zip +4), Match Zip 5 (Zip 5 Only), Match Zip 4 (Zip +4 Only). These should all be ‘Single Line of Text’ fields. These fields are the standardized (cleaned-up) values.

    If you did a territory lookup, set TerritoryEntityReference if the lookup was against a layer that corresponds to the CRM Territory entity and the entity we are geocoding has an entity reference to Territory. Otherwise set LookupName to a ‘Single Line of Text’ field.

  3. Prior to activating your geocoding process, you’ll need a way geocode all existing records.
    • If you have a low number of records, you can simply do an advanced find and run the workflow ‘on-demand’.
    • If you have thousands of records to geocode, use our awesome Bulk Geocode Utility.
    • Bulk Geocode Utility supports doing SQL boundary lookups against the geocode point and updating with queried values or entity references, but doesn’t support other scenarios such as setting an OptionSet value based on the boundary result. For such scenarios, use this ‘Bulk Workflow Execution Tool’ from zero2ten. http://www.zero2ten.com/blog/ms-dynamics-crm-2011-bulk-workflow-execution-tool/