Overview: Problems with Addresses in Dynamics 365Craig SeymourJune 6th 2018
I recently had to deal with a situation in which a customer had some requirements relating to addresses which Dynamics 365 doesn’t handle very well. In figuring out the best approach to meet their requirements, I learned a little more about addresses than I knew before, particularly about how Dynamics handles Address Types
The customer’s requirements were that:
1/ They wanted to attach ‘Offices’ to an Account – i.e. physical locations where the Account has operations, but are not a child account.
2/ They wanted Contacts’ work addresses to be linked to an Office at their associated Account, to minimise data entry when a contact works at more than one office.
3/ They wanted to tag Offices (and Contact addresses) as being one or more of Registered Address, Mailing Address, Invoicing Address and Shipping Address.
4/ On the face of it, this sounds like a job for the system Address entity, as both the Account and Contact entities in Dynamics 365 support having multiple associated addresses, and have a standard, customisable set of types including ‘Bill To’ and ‘Ship To’.
However, the implementation of Addresses has some lack of flexibility which prevents us using them to meet the requirements: in particular Addresses cannot have custom relationships added to them, so address information cannot be shared within or between entities; and a single Address cannot be tagged with multiple purposes (e.g. Billing AND Shipping).
So, a custom entity, perhaps? But Addresses are tightly integrated into Dynamics 365 and it is reasonable to assume that processes and 3rd party integrations are expecting them to be there and working ‘normally’.
But before we dive into customisation, we need to make sure we properly understand how the system Address entity works.
Or “10 things you may not have known about Addresses in Dynamics 365”.
First of all we read what’s already been written:
Building on those two articles and digging a little deeper, we arrive at the following understanding:
Embedded and Related Addresses
1/ Both the Account and Contact entities support the concept of having any number of addresses, stored as a 1: many link to the system Address entity.
2/ In both cases the Account and Contact entity also present a set of address fields embedded in the record – Accounts have 2 sets, and there are 3 for Contacts.
3/ Behind the scenes, these ‘Embedded Addresses’ (my terminology, not Dynamics 365) are stored in the system Address entity. Updates to the embedded address fields or to the corresponding Embedded Address record are automatically mirrored to the other end of the relationship.
4/ When an Account (or Contact, but I’ll just use Account from here on where there is no difference) is created, blank Address records are automatically and created and linked to the Account. Furthermore, the id of the Address records created is set in the address1_addressid and address2_addressid fields in the Account record. If you delete these system managed addresses, you will get errors when trying to update the Account address fields.
(Screengrab from Jonas Rapp’s FetchXML Builder for Tanguy Touzard’s XrmToolbox).
5/ The default views against the Address entity specifically exclude the Embedded Addresses, using the ‘addressnumber’ and ‘objecttypecode’ fields on the Address:
addressnumber: this is an Integer value with no documented significance; however empirically we observe that an Embedded Address record created to store the Address1, 2 (and 3) fields have a corresponding ‘addressnumber’ value.
Upon creation, non system Addresses have their addressnumber set to 1 more than the greatest existing value. However it can be modified after creation to any value.
objecttypecode: this field is set to match the entity object type for either Account (1) or Contact (2).
6/ By default, D365 allows an Address to be given a single type. The default Option Set labels and values are tabulated below. Although the values are the same, the Option Sets specific to each field, and are not shared.
The type is set in the ‘addresstypecode’ field, and each Embedded Address has a corresponding field (e.g. ‘Address1_AddressTypeCode’).
7/ When an Embedded Address is created, it sets the Address addresstypecode to match that in the Embedded Address, matching on the Option Set’s value. The addresstypecode on the Embedded Addresses defaults to ‘Unassigned Value’ for addressnumber 1 and 3, but to ‘Default Value’ for addressnumber 2.
8/ The Option Sets can be edited in the usual way, and so long as D365 finds matching values between the Option Sets in the Contact/Account entities and in the Address entity, it will set them in the Address record. Otherwise it will set the value to null.
Address 2 behaviour
9/ Of the Embedded Addresses, Address2 is the only one with a default value set, which is aptly (or confusingly!) labelled as ‘Default Value’. This has the Option Set value of 1, which corresponds to the Address entity’s AddressTypeCode of ‘Bill To’ – so by default, the Account’s Address2 has type ‘Default Value’ and the corresponding Address is set to ‘Bill To’.
Note that if the System Preference for Outlook Sync is set to “Synchronise all three addresses (Business, Home, Other) in Outlook Contact” then the ‘Home’ address will therefore be the ‘Bill To’ address, which may not be the desired behaviour.
Relating to Other Entities
10/ You cannot add your own relationship to or from the Address entity.
So, as discussed above, to meet the customer’s requirements we can’t customise the Address entity and we can’t replace it with a custom entity.
But we can steer a middle course: create our own custom entity ‘Site’ and ensure that it synchronises into (and duplicates) the Address records where necessary.
From the user’s point of view, they are creating and interacting with Sites instead of Addresses; but processes and 3rd party systems which are unaware of the Sites entity are able to interact with the Address entity; as are users who do an Advanced Find against the Account/Contact/Address entities.
For the specific customer which set us on this journey, we elected to setup 3 individual lookups to Sites for an Account’s Primary, Invoicing and Shipping addresses, and to sync those to Address records with the AddressTypeCode set to the default ‘Primary’, ‘Bill To’ and ‘Ship To’ values. We added some business and front-end logic to make it easy for users to set some/all of these to be the same. As our convention we chose Primary and Invoicing to be the 2 embedded addresses, and Shipping as a ‘normal’ Address.
All other Account addresses we put in a Sites sub-grid and did not sync to Addresses.
For Contacts, it was sufficient to set and sync only the ‘Primary Address’, with all other addresses simply created as sites. The ‘Primary Address’ is a lookup initially is filtered to allow the user to easily link to a Site on the Account, but they can create a new Site if they wish – but by default, any Site created from a Contact is deemed to be private to the Contact and is not linked to their Account.”
This is quite a simple solution, but as with any situation with synchronisation involved, there is some detail which we need to keep in mind: