Spatial Location Lookup Workflow Plugin for Dynamics 365


NOTE: The following documentation applies to EasyTerritory integrated with Microsoft Dynamics 365.

The Location Lookup plugin is a workflow activity, that is, it is used as a step in a workflow process. The location lookup plugin takes latitude and longitude and does a lookup against an EasyTerritory map layer. Typically, this is used against boundary layers to identify regions containing the record location and triggered by changes to the latitude and longitude properties.

This can be used by itself but it is designed to be used in conjunction with the Geocoding Workflow Activity. The Territory Sync Plugin fires when a properly configured EasyTerritory project 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 by this plugin and update territory references on those records.

Setup Steps

To integrate the Territory (Spatial) Location Lookup plugin into your Dynamics instance following these steps:

Step 1: Install the EasyTerritory managed solution into D365. You can get the managed solution from us or Microsoft AppSource.

Step 2: In EasyTerritory, you’ll need to build your territories (from geographies such as US ZIP Codes or manually drawn shapes) and save the project using the ProjectMarkupPlugin. The ProjectMarkupPlugin is a plugin executed from EasyTerritory on project save and it writes the territory information to a structured SQL table that is used by our REST API and this plugin. Follow these steps to set up the ProjectMarkupPlugin.

Step 3: Export your territory list from EasyTerritory and import the records into Dynamics 365.

In this step, we’ll export a list of territories and their IDs (markupId) from EasyTerritory so that we can import them into our Territory entity in Dynamics. Note, you can use the out-of-the-box territory entity or use a custom entity to store your territories. Prior to importing the data in D365 you’ll need to create a field on your entity for storing the ‘markupID’. We usually name that field something like ‘new_eztkey’, which can be a text field.

Example .CSV export:

Columns (‘col1’ – ‘col8’) are your labels split out by group and/or a pipe delimiter. The markupId column is the identifier will use in D365 to match the territory record.

Import your territories into D365. For the column mappings, you’ll need at a minimum the ‘Territory Name’ (which can be col1 – col8) and the markupId (which will be the custom field you’ve created on the territory entity. e.g. ‘new_eztkey’) You can also create additional fields for storing the other column information from your EasyTerritory export, if desired.

With our territories now in D365, we can move on to configuring the project plugin.

Step 4: Create a new workflow in D365. In this example, we’ll create it on Lead entity for the purposes of lead assignment. Note: This same logic can be used to set territory on any entity related to territory such as accounts, work orders, or custom entities.

Inputs to the LocationLookup step are:

MapDotNet URL REQUIRED URI of your EasyTerritory map service endpoint.
Map ID REQUIRED EasyTerritory map ID (Use ‘EasyTerritory’)
Layer ID REQUIRED EasyTerritory layer ID. (Use ‘ProjectMarkupPolygons’)
Field Name REQUIRED Name of field to retrieve from EasyTerritory. (Use ‘markupId’)
Where OPTIONAL Where clause for filtering returned data. Example: ProjectMarkupPolygons,projectId=4a396a4b-9c70-4c16-c3a7-1a14bf3f90bb

Requires one of:

Lat String & Lon String 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.

Properties required for setting territory lookup:

The following are used if you need to update an entity reference on the record the workflow applies to.

Reference Attribute Field on the entity being updated that references the Reference Entity.
Reference Entity An entity that is referenced by the entity being updated.
Reference Entity Attribute The attribute on the Reference Entity that we look up the value of [Field Name] against.

Additional (Optional) Properties:

These additional (optional) properties are for setting lookup constraints.

Reference Entity Constraint Attribute An attribute on the Reference Entity that must match the given constraint value for the Reference Entity to be selected.
Reference Entity Constraint Value The value the Reference Entity Constraint Attribute must match.
Reference Entity Constraint Type The .Net type of Reference Entity Constraint Attribute, i.e. string for any sort of text, int, decimal, etc.
Reference Entity Constraint Attribute 2 An attribute on the Reference Entity that must match the given constraint value for the Reference Entity to be selected.
Reference Entity Constraint Value 2 The value the Reference Entity Constraint Attribute 2 must match.
Reference Entity Constraint Type The .Net type of Reference Entity Constraint Attribute 2.

Additional outputs from the LocationLookup step are:

Data Found A flag (boolean value) that indicates whether the lookup found anything. In the example shown, we check this before updating the target record.
Value The value of [FieldName] for the first record found that intersects the input location, or null if none found.

Typically, this is set up as a standalone workflow triggered by changes to longitude and latitude. You’ll want it in place prior to a bulk geocode.
If the geocode plugin workflow is the only activity that ever sets longitude and latitude then you should include this plugin in the same workflow as the geocode plugin, conditional on a successful geocode.