The Return of Composite Address Control in Model-driven Apps – Now with Built-in Autocomplete Functionality

Early this year, Microsoft has announced the general availability of address input control as part of geospatial features for canvas apps. But how about model-driven apps? Can we have a similar address input control for model-driven apps too?

Capturing addresses is a common business scenario and address lookup functionality is preferred to be used in most of my projects to enhance the user experience, minimise user input error and ensure data integrity. We used to implement HTML web resources or PCF controls by using third party map APIs (Google Map, AddressFinder, NZ Post, etc.) to achieve the requirement with some development effort. On top of that, in terms of the UI, the composite address columns are displayed as individual form fields on the Unified Interface and they are no longer rendered as a nice composite address control as it was before in the legacy web client.

When I set up a new trial environment of Dynamics 365 a couple of months ago, I noticed the composite address field on the Account form as Service Address. At that time, I thought it was an address field custom control which is part of the Dynamics 365 Field Service solution.

I thought a lot of people know about this control but I did not because I was not actively working on Field Service projects. But to my surprise, this is not the case and I just only realised about it when I saw a tweet from Andrew Butenko (thanks for encouraging me to put this up as a blog post).

What is this OOB custom control?

This "Address input" might be the internal custom control which is not available in the list of components built by Microsoft. However, you may use it in your custom forms by editing the FormXml and adding the control to the form.

How does the address autocomplete functionality work?

The address autocomplete (address finder, address lookup) functionality trigger the typeahead search after entering x3 characters into the textbox. If location access is allowed for the site, the suggested list shows the nearby addresses first.

Can I enter the address manually?

Yes, you can enter the address manually or amend the suggested address by clicking on the edit icon to show the address pop up dialog.

Is it available to any model-driven app?

Yes. The Microsoft.AddressInputUCI control is part of BaseCustomControlsCore solution and it can be added even to a model-driven app based on Microsoft Dataverse without any Dynamics 365 solution installed. It is not specific to the Field Service solution as I previously thought. You just need to configure the Key Provider property of the control as Organization Settings if you are using the control in the environment without Dynamics 365 Field Service app. If you have the Field Service solution installed, you can use any of the options. I believe this is to specify which Bing Maps Key to be used.

Why can't I find it under the list of custom controls?

The Address input custom control is compatible with SingleLine.Text and Multiple field types, it cannot be found in the list of custom controls when you add a custom control to the Text field. It could be because the control is probably for the internal use only, and thus not documented.

How can I use this control on my form then?

Even though you cannot find this control under the list of custom controls, you can still add it to the form by Editing FormXml in the customizations.xml file. For me, I personally use the FormXml Manager tool in the XrmToolBox to edit FormXml and publish the changes.

What changes do I need to add to FormXml?

First of all, identify the <control> tag of the form field that you want to add the custom control to. Get the uniqueid property of the control and if there is none, generate random GUID and add the uniqueid property to the <control> tag.

Before

<control id="address1_line1" classid="{F9A8A302-114E-466A-B582-6771B2AE0D92}" datafieldname="address1_line1" disabled="false" />

After

<control id="address1_line1" classid="{F9A8A302-114E-466A-B582-6771B2AE0D92}" datafieldname="address1_line1" disabled="false" uniqueid="{815D8A5B-6355-47B5-9500-EE2D658820D5}" />

In this example, I used 815D8A5B-6355-47B5-9500-EE2D658820D5 as an example of the control uniqueid and it needs to be replaced with the GUID of your control. Add the following XML between the <controlDescriptions> tag.

Sample XML

  <controlDescriptions>
  .
  .
  .
  .
  .
    <controlDescription forControl="{815D8A5B-6355-47B5-9500-EE2D658820D5}">
      <customControl id="{4273EDBD-AC1D-40D3-9FB2-095C621B552D}">
        <parameters>
          <datafieldname>address1_line1</datafieldname>
        </parameters>
      </customControl>
      <customControl name="Microsoft.AddressInputUCI" formFactor="0">
        <parameters>
          <Address>address1_line1</Address>
          <Street1>address1_line1</Street1>
          <Street2>address1_line2</Street2>
          <Street3>address1_line3</Street3>
          <City>address1_city</City>
          <StateOrProvince>address1_stateorprovince</StateOrProvince>
          <CountryOrRegion>address1_country</CountryOrRegion>
          <ZipOrPostalCode>address1_postalcode</ZipOrPostalCode>
          <WriteToPrimaryField static="true" type="Enum">True</WriteToPrimaryField>
          <AddressFormFormat static="true" type="Enum">NZ</AddressFormFormat>
          <KeyProvider static="true" type="Enum">FS</KeyProvider>
        </parameters>
      </customControl>
      <customControl name="Microsoft.AddressInputUCI" formFactor="1">
        <parameters>
          <Address>address1_line1</Address>
          <Street1>address1_line1</Street1>
          <Street2>address1_line2</Street2>
          <Street3>address1_line3</Street3>
          <City>address1_city</City>
          <StateOrProvince>address1_stateorprovince</StateOrProvince>
          <CountryOrRegion>address1_country</CountryOrRegion>
          <ZipOrPostalCode>address1_postalcode</ZipOrPostalCode>
          <WriteToPrimaryField static="true" type="Enum">True</WriteToPrimaryField>
          <AddressFormFormat static="true" type="Enum">NZ</AddressFormFormat>
          <KeyProvider static="true" type="Enum">FS</KeyProvider>
        </parameters>
      </customControl>
      <customControl name="Microsoft.AddressInputUCI" formFactor="2">
        <parameters>
          <Address>address1_line1</Address>
          <Street1>address1_line1</Street1>
          <Street2>address1_line2</Street2>
          <Street3>address1_line3</Street3>
          <City>address1_city</City>
          <StateOrProvince>address1_stateorprovince</StateOrProvince>
          <CountryOrRegion>address1_country</CountryOrRegion>
          <ZipOrPostalCode>address1_postalcode</ZipOrPostalCode>
          <WriteToPrimaryField static="true" type="Enum">True</WriteToPrimaryField>
          <AddressFormFormat static="true" type="Enum">NZ</AddressFormFormat>
          <KeyProvider static="true" type="Enum">OrgSetting</KeyProvider>
        </parameters>
      </customControl>
    </controlDescription>
  .
  .
  .
  .
  .
  </controlDescriptions>

You can either update the fields and other properties in the XML or you can update the control properties later in the form designer after publishing the FormXml changes.

What are the properties of Address Input custom control?

• Mapping to the following x7 address fields
1. Street 1
2. Street 2
3. Street 3
4. City
5. State/Province
6. Country/Region
7. Zip/Postal Code
• Write to primary field - Whether or not the select address is to be populated to the text field to which the Address Input custom control is bound.
• Address Form Format - Format the address value as a composite field based on the country specified
• Key Provider - Specify which Bing Maps Key to be used

Can I use this Address Input on the forms of a custom table?

Yes, it can be added to the form of a custom table and map to the custom address columns.

While waiting for this feature to come out of preview, what other OOB options do we have for address autocomplete functionality in Production?

If you have a Dynamics 365 Field Service installed in your environment, you can Enable Address Suggestions from Field Service as shown in this 2 Minute Tuesday video by Gus Gonzalez. (thanks for sharing about it, Rachel)

What if this Address Input does not meet the requirements for my address fields?

PCF gallery has more than a dozen of custom controls to lookup the address for various countries using different APIs. My recommendation is to check out the AB Controls Toolkit. With the Composite Address Control, you can have better control over the behaviour of the composite address control such as: 

• Control what fields should be visible and what is not.
• Use lookups instead of text fields for Countries/States.
• Reorder the fields in the popup.
• Have custom formatting of the full address.

Address Autocomplete Control in this toolkit also allows us to configure using different types of map providers (Bing Maps, Azure Maps, Google Places) for the address autocomplete functionality.

Known Issue: Why is the control only shows the address suggestions in the US?

The is a known issue with the control and to show the address from your location, change the Address Form Format property of the control to User Location.

Summary

With out-of-the-box Address input custom control, you can configure the composite address control with address lookup functionality on the forms in your model-driven apps without any development effort.