Craig Seymour – cloudThing, Dynamics Practice Lead
I recently had to deal with a situation in which a customer had some requirements relating to addresses in Microsoft Dynamics 365, which wasn’t handling them very well.
In figuring out the best approach to meet their requirements, I learned a little more about addresses than I knew before, particularly around how Microsoft Dynamics 365 handles Address Types that I thought I’d share with you all…
A Bit Of Background First
The customer’s requirements were that:
- They wanted to attach ‘Offices’ to an Account i.e. physical locations where the Account has operations but are not a child account.
- 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.
- They wanted to tag Offices (and Contact addresses) as being one or more of Registered Address, Mailing Address, Invoicing Address and Shipping Address.
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 a lack of flexibility which prevents us using them to meet the above 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 Microsoft Dynamics 365 and it’s 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.
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
- 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.
- 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.
- 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.
- 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.
- 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).
- By default, Microsoft Dynamics 365 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’).
- 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.
- 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
- 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
- You cannot add your own relationship to or from the Address entity.
Addressing the Limitations
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 enough 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:
- To give the best chance of a flawless integration with 3rd party systems, we need to make sure we set the ‘Type’ correctly on our Addresses.
So if I set my Site as the ‘Invoicing Address’ or the ‘Billing Address’ or whatever other convention the requirements specify, then the Address I create off that should be given the type ‘Bill To’.
- When a Site is linked to multiple Contacts, they will each get a copy of the Site’s address data into their own individual Address records – we need to remember to update all of those records if the Site data is changed.
- If a Site is deleted, we can normally delete all the Address records created from it. However, if the data was synchronised into the Address1/2/3 entities, then we need to clear the data rather than delete the record.
- It’s tempting to think we can treat Addresses as a target only, as they are a copy of the Site data; but we need to remember that if some process we don’t know about updates an Address, it needs to get reflected up to the originating Site.
cloudThing are experts in solving complex business problems with Microsoft Dynamics 365. If you’re ready for a Cloud-based migration or looking to make the most out of Dynamics 365 then get in touch today for a chat…