In this blog, we highlight a lesson learned when we used a Dynamics 365 Customer Engagement online data source connector, called Instance Web API, for Power BI reports.
In order for CRM users who are not system administrators to be able to use PowerMap, they will need to be assigned one of the two PowerMap security roles. The PowerMap Administrator security role allows users access to the configuration of the mapped entities, along with all other pieces and parts of the PowerMap add-on. The PowerMap User security role gives users access to view a PowerMap, but not to change any of the configurations or settings of the PowerMap add-on.
PowerMap users will need to obtain a Bing Map license key to geocode and map records. Microsoft offers levels of licensing based on the volume of records which need to be geocoded. Please refer to Bing Maps Portal for specific information on geocoding limitations.
Users can find more information about plans and purchase Bing Map licenses through the Bing Maps Portal.
If you’re already using a Bing Map license in your CRM, you can enter the same key in PowerMap. You can locate your key in Settings > Administration > System Settings and locate the Bing Map key field.
PowerMap has some advanced settings that can be configured. Their descriptions follow the screenshot below; most people won’t need to change these values.
This is the license key PowerMap use to access Bing Maps and geocode your records. You must replace the text with your Bing Map license key.
A number between -90 and 90. This is the default of the map’s center when it first opens.
A number between -180 and 180. This is the default longitude of the map’s center when it first opens.
Here are some sample values that may be useful for the initial latitude, longitude and zoom levels:
|Region||Initial Latitude||Initial Longitude||Initial Zoom Level|
|PowerObjects headquarters in Minneapolis||44.9884||-93.27723||19|
A number between 1 (entire earth) and 19 (immediate vicinity). This is the default zoom when the map first opens.
This gives the maximum distance (in miles) from the center of the map that a pin will display. If you have a lot of data, make this value smaller so as not to show too much data at a time on the map.
This dropdown allows users to decide if they’d like to display the distance on the map in miles or kilometers.
When you are utilizing the “Directions” portion of the map, you can choose if you’d like to map based on the Fastest route (least amount of time), or the Shortest route (least number of miles/kilometers).
Once you are done with these configurations, remember to click "save".
Once you have imported PowerMap, and registered for your free 30 day trial, the next step is to provide PowerMap with information about the entity or entities you want to include in your maps.
Once you select new you will see a screen like the one below:
Once you have saved your Entity to Map record, you will be able to geocode the existing records in CRM. To geocode existing records, click on “Find Lat/Long” in the upper ribbon of the Entity to Map record. After you click on this button, a screen will pop open, letting you know how many records you need to geocode. To begin geocoding, click Geocode. If you have over 10,000 existing records to geocode, download the free Bulk Geocode Tool from the PowerMap webpage.
Repeat the steps above for each entity that you would like to include in your maps.
Custom entities work in PowerMap as long as they have latitude and longitude fields set up correctly.
The latitude and longitude fields must be Floating Point Number fields, with a precision of 5, and their IME mode should be disabled. Latitude goes from a minimum of -90 to a maximum of 90, and longitude goes from a minimum of -180 to a maximum of 180. For example, the screen shot below shows properties for the latitude field.
To begin using PowerMap, navigate to the PowerPack section and click on PowerMap. The map will appear, initially it will not show any pins. To work with the map, open the panel on the right-hand side of the map that says “Configure” If at any time you’d like to close the PowerMap control panel, simply click on the arrow in the upper right corner.
The PowerMap control panel has a number of sections: Legend, Saved Map Definitions, Saved Map Locations, Select Region/Radius, Actions and Zip Code Search.
If the Legend is empty (as shown in the next screen shot), select an entity to show on the map, thereby adding a row to the legend. The next section describes how to edit the legend to show the records you want.
The legend describes the pins showing on the map. It is editable, so you can use the legend to control what pins display. All changes to the legend appear immediately on the map. They are temporary unless you save them, as explained in the next section.
Each row in the legend represents a CRM view whose records will be shown on the map, together with the pin or heat map chosen to show these records. The view can be a system view or one of your personal views, created from an advanced find.
To change the pins for a view, click on the pin in the legend and select another option in the dropdown to use instead. To select an entity to map, click in the first dropdown and select an entity. In the next dropdown all system and personal views for that entity will be displayed. Choose the one you would like to map.
Note: Only entities set up to be mapped will be displayed in the first dropdown. If you do not see an entity you would like to map in this list, please refer to the "Setting Up Entities to Map" section, to see how to set up an entity to map.
The columns in the selected view (All Accounts in the screenshot below) determine what information displays when you click on a pin. To modify this information, modify the columns in the view (through advanced find - if a personal view - or system customizations - if a system view) and re-save the view. To open a record that is mapped, click on the name of the record. Anything that’s hyperlinked in blue can be clicked, and the related record will open in a new window.
If you see a number under the pin, that means there are multiple records at that location. To view a list of those records, click on the number.
Note: The word "Townsfolk Records" just refers to the fact that there are multiple records at this point.
To delete a row from the legend, click on the delete symbol, to the right of the view you’ve selected.
Selecting an entity in the Select Entity dropdown creates a new row in the legend. PowerMap can show any number of views from any number of entities at the same time.
With PowerMap you can create a heat map based on your mapped entities. When setting up your legend and selecting a pin to represent the mapped entity, you have the option to choose a heat map.
Note: The heat map option is not available if your browser is Version 8 (an older version) of Internet Explorer
If you select the heat map you will have additional options for the display. These can be found under “Adjust heat map options…” Once you select this link it will open a new window where you can define the color gradient, intensity and radius in miles of the heat map.
In the legend, you can choose to map based on a region, or a radius. By default, the region is selected. However, you can also choose to map points based on a radius. When you choose "define radius", you will be able to define the number of miles/kilometers from a center point you would like to map. For example, if you have "miles" set in your configuration, and you enter a radius of 500, a pin will be dropped on the map, and the radius circle will display all configured points within 500 miles of that pin.
Under the Actions area of the legend, you will see 3 options: Send Email, Assign, and Add to Marketing List. These actions can be performed in bulk, for all of the pins that are within the current radius on the map.
If you select the ‘Directions’ tab on the PowerMap Control Panel you will be able select plotted points from the map or add an address to the control panel and get driving directions. To add an address from a plotted point on the map simply select the pin of your choice and select the yellow circle with an arrow in the information box or simply right click on the pin you want to add.
After you have two points specified, users will have the ability to add additional destinations, reverse the directions or clear the directions.
Once you have the points selected to map, step-by-step driving directions will be appended in the control panel. You can print the directions, view the exact distance in miles between points, view the estimated driving time, and re-route based on current traffic. You can also choose to "Optimize the Route", and the directions will route you based on shortest distance between the points.
Note: You need at least 4 pins selected in order to have the ability to optimize the route. The first pin will, by default, be your starting point, and the last pin will, by default, be the ending point.
When looking at records plotted on the map you now have the option to add specific records straight to a CRM marketing list. In the information box select the red button. This will open up a new window where you can choose to add the contact to an existing CRM Marketing list or create a new CRM marketing list to add them to.
Users can also assign new owners to CRM records straight from the map. Simply select a record’s pin that is plotted then select the green button located in the information box. Once you select this button a new window will be opened. From this window you can select to assign the record to yourself, assign the record to another user or assign it to a team.
Users can choose to send emails out to individuals that are mapped on the PowerMap. Simply select the blue circle and a blank email will pop open with the records email already populated.
A saved map definition is a legend that is saved in CRM so you can reuse it later without reconstructing it each time you need it.
To save a new map definition, click the “Saved Current Legend as a Map Definition” link. In the dialog box that appears, provide a name for the map definition.
A saved map definition can be available only to you, or you can share it with other users, by navigating to PowerPack > Map Definitions, selecting a definition and choosing "Share".
After you have saved one or more map definitions, they will appear in the list under Saved Map Definitions. Clicking the name of a saved map definition loads it as the current legend in the legend section, and displays it on the map. An arrow on the left indicates the last map definition you have selected. The arrow is green at first; it turns red if you edit the legend. In that case the map definition has unsaved changes. You can click the Save Current Legend as a Map Definition link to save the changes.
To delete a saved map definition, first select it, then click the Delete icon that appears to the right of it. Click on the New Map Definition link to clear the legend and start fresh.
A map location tells where the map is centered and how far in or out it is zoomed. You can save map locations to return to them easily. To save a map location, first pan and zoom the map to the location you want to save. Then click the Save Current Location link. In the dialog box that appears, provide a name for the location.
All the locations you save appear as a list. Clicking a saved location pans and zooms the map to show that location. An arrow on the left shows the currently displayed location. To delete a map location, select it, then click the Delete icon that appears for it.
Just like a saved map definition, saved map locations can be available only to you, or you can share it with other users, by navigating to PowerPack > Map Locations, selecting a definition and choosing "Share".
If you'd like to view all pins within a specific zip code, type the zip code in the zip code search and hit enter on your keyboard. This will display all pins within that zip code.
Note: You can only search for and display one zip code at a time in PowerMap.
You can add the map to an entity’s form or to a dashboard. You can also view the map in its own browser window.
To add the map to the form for an entity, insert a Web resource (pomap_/Map.html). Make sure the checkbox for “Restrict cross-frame scripting” is NOT checked.
Use the other checkbox, “Pass record object-type code and unique identifier as parameters,” to specify what other records you want to see on the map.
Normally you will want to check this checkbox. This will cause the map to show a pin for the record you are viewing, and to focus the map in the area around that pin. The map will show other records from the default view for the entity.
If you do not check this checkbox, the map will behave as it does elsewhere, returning to the last map definition and last location that you used.
Note: If you would like to use the control panel to change when you’re viewing a map within a record, you will want to make the map area on the record big enough so you can see the panel and the map at the same time.
Adding the map to a dashboard is similar. Add a web resource to the dashboard and link it to the resource called pomap_/Map.html. Again, make sure the checkbox for “Restrict cross-frame scripting” is NOT checked. The map will now operate as it would if you were accessing it through the PowerPack area of your CRM.
To open the map directly in its own browser window, go to this URL:
<url for CRM>/WebResources/pomap_/map.html
The user must be a CRM user. He or she will be prompted to log in (if not already logged in). Note: If you have a CRM on premise, you will not be able to access the map outside of the office, unless you have IFD enabled and ADFS set up.
PowerMap is compatible in the Dynamics 365 online UCI. Once you have the UCI compatible version of PowerMap installed and have added PowerPack to your site map, you can add PowerMap, along with its components, to your sitemap. For PowerMap, you will need to add the following components:
To do this, open up the app designer and click on edit site map.
Then click on PowerPacks group > Click Add > Click Subarea
Then fill in the properties to create the subarea. Here's an example of the "Entities to Map" entity component:
Once you've added all 4 components as subareas, make sure to save. You should now have the PowerPack group and sub areas.
To uninstall, first delete any Entity to Map records you created. Then uninstall as usual, by deleting the solution. Deleting the ‘Entity to Map’ records removes SDK Message Processing Steps that would otherwise block the uninstall.
Uninstalling the solution does not unsubscribe the solution. If you're discontinuing use of the add-on, you must first unsubscribe in the solution.
Thank you for your interest in PowerMap, should you choose to subscribe you will be charged $1/enabled CRM user/month. If you have any questions or run into any issues with PowerMap, our friendly support team is here to help!