Introduction
Due to the dynamic nature of addresses, address fields in the SuperOffice CRM UI appear differently depending on the selected country for any particular company or person. Below is an example of six different country formats and how they appear in SuperOffice CRM. It is interesting to note that while the top two are similar, the middle two are also similar but different from the first two. The bottom two are uniquely different from both each other and the other four.
To support multiple address variants, SuperOffice address data structures must be generic, and an address type must be flexible enough to support all the various address formats of the world.
SuperOffice has accomplished supporting multiple country address formats by abstracting the address format from the address data and storing each separately in the database. At runtime, the address format is selected based on the company or contact county information.
FormattedAddress (NetServer Core)
In NetServer core, the datatype used to express a single address format isSuperOffice.CRM.Globalization.FormattedAddress class.
A FormattedAddress is a collection of FormattedFields data types, which contain one or more IFormattedField types. Each IFormattedField contains the actual address data, among others, three key properties: AddressType, Name, and Value.
LocalizedAddress (web services)
In the SuperOffice web service API, all address fields are in a structure calledLocalizedAddress.
This is a multi-dimensional array of LocalizedField, where the first dimension contains each address line. The second dimension contains each field in that line. Each LocalizedField contains, among others, 3 key properties: AddressType, Name, and Value.
NSLocalizedAddress (CRMScript)
All CRMScript address fields belong to a structure calledNSLocalizedAddress.
This is a multi-dimensional array of NSLocalizedField:
- The 1st dimension contains each address line.
- The 2nd contains each field in that line.
AddressType property
AddressType determines which type of address a field belongs to, of which there are 3 possibilities:
The first two types correspond to a company address, used to differentiate a company’s postal address versus its’ physical, or visiting, address. The third address type represents a contact person’s address.
Name and value properties
TheName and Value properties are just what they sound like. The name is a unique field keyname, and the value is populated with the value from the database.
Pre-defined address field names
There are two separate groups of fields, one for person and one for company (contact).Owner-id and type
TheAddress and Phone tables use two fields to determine where they belong: The owner_id field refers to a contact_id or a person_id depending on the type_idx field.
The type_idx is 1, 2, 16387, or 16388
(Result is cropped.)
Address:
type_idx
- 1 = Postal (contact)
- 2 = Street (contact)
- 16387 = Private (person)
type_idx
- 1 = Phone (contact)
- 3 = Fax (contact),
- 16385 = Phone (person)
- 16387 = Fax (person)
- 16388 = Direct (person)
- 16389 = Mobile (person)
person table, while those below are related to the contact table.
So if you wanted to pick up just the fax numbers for contact 123 then your query would be:
These are many-to-one relationships, so you can still pick up more than one phone number per owner. Phone numbers are further sorted by rank. For addresses, this is a theoretical proposition. The CRM client will not define more than one address per type for each owner.
Example
For example, the address format of Norway defines 4 lines total. The first and third lines contain just one element, while the second and fourth lines contain two elements. France, however, has 3 lines total, with the first and second lines containing just one field element and the third line containing two field elements.- NetServer Core
- Web services
- CRMScript
AddressType property that signals whether it pertains to a contact postal or street address, or a person’s address.
So how does one go about reading and writing address information using this generic construct?
For NetServer Core, use the AddressFormatter class
For web services, use the AddressHelper class