Custom forms - Usage

Every contact folder is assigned a standard default contact form via what's referred to as it's Message Class name. For contacts, the default message class is assigned the name of IPM.CONTACT.

You may assign a different custom form to act as the default contact for that folder. This form will be then be used whenever a new contact is added to the folder.

You can use a different custom form when adding any new contact to the contact folder provided it has been properly "published" to the folder. This form is assigned to the contact and will always be used when the contact is viewed. For more information on how to assign a new "default" custom form to a contact folder see

http://www.outlookcode.com/d/newdefaultform.htm

If you assign a new default custom form to a folder AFTER contacts have already been created, be aware that this form is NOT automatically assigned to pre-existing contacts in the folder. If you want this form to be assigned to pre-existing contacts, it will be necessary to do so manually as outlined in the information see - http://www.slipstick.com/dev/newdefaultform.htm

ContactGenie Importer will use either the contact form assigned as the default for the folder or the contact form used to create the first physical contact record in the contact folder. ContactGenie DataPorter will only use a user-defined custom form if it has been assigned as the default for the folder.

Custom Forms with User-defined fields

Custom forms can be created to present the existing internally defined Outlook contact fields in a different manner and/or to also display "user-defined fields" to which you would assign your own field names and field attributes (i.e. text, numeric, boolean etc.)

Any user-defined fields contained within a custom form are automatically appended to each contact when that contact is created.

Custom Forms and the Outlook UserProperty Collection

Every contact record has an internal "UserProperty" collection containing all the custom fields you have added to a contact item and which is programmatically accessible. This UserProperty collection is populated with field names when you add a custom field to the form and a contact item is created.

In the most basic cases, you simply create a new field, assign it a "display name" (caption) and the field name you want to use to reference it by. This reference field name is added to the UserProperty collection which is then used by ContactGenie in obtaining the user-defined fields associated with the custom form. These fields also appear in the "items used in this item list" within the Outlook folder when viewed through the Outlook interface. Once the first contact is added to a new folder using this custom form, the custom fields are also added to "Items used in this folder".

However, there are two scenarios you should be aware of that impact the fields recorded by Outlook in the UserProperty collection which results in these fields NOT appearing within any Outlook user interface option but are reported by ContactGenie as a user-defined field.

The first scenario is when you add a new field to a form by selecting it from one of the available standard Outlook fields via Outlook's field <chooser>. When this is done, Outlook automatically adds the field's "display name" as shown in the field chooser's list to the internal UserProperty collection within the custom form for later use whenever a contact item is created using this form. For international versions of Outlook, this will be the field name displayed in the language currently in use. (If you add the same field multiple times to the form, it will only appear once in the UserProperty collection).

The second scenario is when you create a new field but then assign to one of the standard available Outlook fields. In this case, TWO fields are added to the internal UserProperty collection, one being the new field name you created and the second being the standard field's "Display Name" as just described.

Under normal circumstances, when a new field is programmatically added to the UserProperty collection, it is only added if it does not already exist. For standard fields contained within this collection, if the field is programmatically added again to the collection, it will become duplicated within the contact item unlike a true user-defined field. DataPorter will bypass any duplicate field found within the collection when importing data in either add or process modes.

These additional "standard" fields are not visible to you in general operation using the Outlook user interface but will appear as an available "user-defined" field when the contacts of the custom form are reported since these form part of the UserProperty collection and there is no published programmatic way known at the current time that enables distinguishing whether an item is in fact  referencing a standard Outlook field or a true "user-defined" field. If one of these fields is used within an import map, the standard field being referenced will be updated (i.e. if you add multiple occurrences of the same standard Outlook field on the same form and use each of these fields in the import template map - the same field will be updated with different data for each reference within the import template.

With the release of CGD 2.0.161, the User Property collection is no longer used to determine valid user-defined fields associated with a custom form eliminating inclusion of any extraneous user-defined fields or the reporting of duplicates. However, it is now mandatory to have the custom form published to the contact folder in which it is being used. 

For most people, this information has no impact. However, if you programmatically manipulate contacts, you should be aware of the possible results especially if DataPorter reports duplicate fields when importing data. Duplicate fields were also being generated by DataPorter if any standard field found within the UserProperty collection and used as part of the import template. This was corrected in version 2.0.152 as soon as the cause and effect were determined so that duplicate fields are never created under any circumstances.

DataPorter does not add a new user-defined field to any contact created via a custom form. Any custom field(s) must exist in the custom form in order to be used.

Custom Forms with Data Validation

When designing/using custom forms, user-defined fields can be assigned predefined "valid" values or "validation rules". Alternatively, data validation can be performed via custom VBA program code. The purpose of this is to prevent invalid data from being added to the contact folder based on some user-defined rules. In short, Microsoft Outlook processes these rules and determines whether or not the new contact record can be added. If the data does not pass this validation - addition of the new contact is prevented by MS Outlook.

Similarly, data can be validated by looking up information on an external database via custom code which is specific to the custom form.

We refer to these kinds of custom forms as "interactive" meaning that the form itself will determine whether or not data can be added based upon some user-defined criteria.

This works fine when new contacts are being added manually since a message is typically displayed to the user. However, in an automated environment, there are no error codes returned that identify why a contact cannot be added - just that it couldn't.  Hence, if either Importer 1.3 or DataPorter 2.0 imported data to a contact folder using such an "interactive" custom form - it would have no way of knowing what the custom data validation rules were or if that was why Outlook prevented the contact from being added.

The standard Outlook import wizard to map and import data using custom forms or user-defined fields, whether or not data validation rules are in force.

Both Importer 1.3 and DataPorter 2.0 will report this attempted update as as "Outlook Update Failure" and move to the next contact record.

DataPorter 2.0 also provides an enhanced feature that enables you to optionally "bypass" a forms update process without losing the custom form assignment. However, you will not be able to make any future manual changes to such a contact record unless it passes all existing validation rules.

A quick way to determine if you have any data validation rules in force in a form is to simply add a completely blank contact record manually. If you cannot save this contact then you will also be able to add it via either of the ContactGenie versions unless the imported data is valid.

User-Defined fields without Custom Forms

With MS Outlook, it is possible to add user-defined fields to any contact either during the initial creation or after it has been added. User-defined fields added to a contact are not automatically added to contacts that already exist or that may be added later.

This is important to keep in mind when you want to use ContactGenie to "map" new incoming data to existing user-defined fields as is explained in the "Theory of Operation - ContactGenie Importer".

To get a better understanding of user-defined fields please refer to Microsoft's Knowledge Base article #290656 - OL2002: Working With User-defined Fields in Solutions

Theory of Operation - ContactGenie Importer/DataPorter

It is assumed that the reader is familiar with the basic operation of ContactGenie Importer or DataPorter in terms of how/why templates are created and used by the programs.

Importing using Custom Forms

One of the most important things to remember is how ContactGenie determines if a custom form is to be used when importing new contact data as described above under Custom Forms - Usage.

When creating a CG template, you <MUST> designate that a <default> contact folder is to be used when importing. You will then be prompted to select the contact folder to be used. Once this folder is selected, CG verifies if there is a custom form being used as described under Custom Forms - Usage.

For ContactGenie Importer, if a custom form is detected, a message is displayed advising that a contact form is being used along with all the user-defined fields contained in that form asking you if you wish to proceed. If you respond positively, then this form will be used in the creation of new contacts when data is imported and you will be able to map imported data to all fields assigned to that form.

For ContactGenie DataPorter, if a custom form is detected, the custom form tab will become activated and all fields will be listed at which point you will be able to take advantage of several other options related to custom forms.

Mapping to fields in a contact folder using a custom form MUST be done at the time the CG template is originally created since this information is recorded within the template for future use.

For ContactGenie Importer, after the template is created/saved with all fields mapped, you can then edit the template specifying that a different contact folder is to be used on import. In this case, the user-defined fields mapped will be added to every contact for the new designated folder provided it does not also have a user-defined default custom form assigned.

For ContactGenie DataPorter, you would achieve the same effect as above by checking the "Select Folder on Import" box after you selected the folder with the default custom form.

The above feature is added for those occasions where you want to enable CG to automatically add user-defined fields that you have previously defined.

If different custom forms have been used to create contacts within the folder, it is NOT possible to select WHICH of the custom forms is going to be used.

Importing using user-defined fields without a Custom Form

The process of being able to MAP incoming data to pre-defined user-defined fields is identical to the process described for Custom forms. In both cases, the default contact folder must be selected at the time the template is originally created and the user-defined fields MUST exist in the first physical contact found in the folder. User-defined fields created in any other contact other then the first cannot be used in the mapping structure.

User-defined fields used in the mapping structure on input will be added to each new contact created during the import process regardless of whether or not any data was present in a given field at the time of import.

Also, like Custom Forms, it is possible to edit the template after it has been initially to be able to select the target contact folder on import. Any user-defined fields used within the template will still be created for every contact created regardless of the contact folder. In the case of user-defined fields, the importance of initially selecting the default contact folder is purely to be able to detect all the user-defined fields contained within the first contact in the folder.

There is no simple way to determine what the "first physical contact record" is with an Outlook contact folder. However, DataPorter 2.0 does provide the ability to display information regarding the first physical contact found. This option is not available in Importer 1.3.

About the "First Contact".....

The phrase "first contact found within the contact folder" has been used several times in the previous paragraphs. The important point to remember about this phrase is that it refers to the first contact record that is returned by Outlook to ContactGenie and which may or may not be the first contact that appears in your current view. Typically, it isn't.

If you run into a situation where the first contact does not contain the information you want (custom form or user-defined fields), the simplest solution would be to create a new contact folder with one contact containing the necessary information. Use this folder as the default during the initial creation of the template and then later edit the template to reference the actual contact folder you want to use.

***NEW***

Starting with CG Exporter 1.1, user-defined fields for contacts not using a custom form will be determined from the "All user-defined fields in folder" list as opposed to "First contact" described above. The impact of this is that any user-defined fields attached to a contact that is not in this list will not be exported (or imported to in DataPorter versions later then 2.0). This can easily occur if a field is deleted from the "All user-defined fields in folder list" since these fields are not deleted from the individual contacts that may have these fields. It can also occur if contacts are copied from one folder to another.

About Data Validation & Data FORMAT validation

In short, CG does NOT provide for any "data validation" parameters on import - either via its template or thru the use of any existing rules contained in a custom form.

What CG does provide and enforce are data "format" validation rules - i.e. a date field must contain a valid date value etc.. This is done for both standard and user-defined  fields to which incoming data is being mapped.

Using an "interactive" custom form (as defined above)

ContactGenie does not perform any checks to see if there are any data validation rules present within a custom form either at the field level or associated custom code. Therefore, if a custom form is selected that performs any kind of "data validation" which could prevent contacts from being updated normally, the contact record will be recorded as an Outlook Update failure and bypassed.

Automatically created UDFs

One of the options available when creating a CG template is the ability to have it automatically create user-defined fields for each record when data is being imported and the input fields have not been pre-defined.

The limitation with using this approach is that user-defined fields created in this manner will only be created as text fields regardless of the field's content. If you want the data format to be validated, the user-defined field must pre-exist with the proper format when the template is originally created. CG does not provide any facility to specify field properties for automatically generated user-defined fields.

Field Naming Conventions

To avoid problems in the future, it is highly recommended that you only use standard characters as part of your <internal> field name avoiding any special characters such as described in question 11 on our FAQ page.

With the release of CGD 2.0.161, the restriction related to using fields containing invalid characters as described in the question 11 on our FAQ page has been eliminated and can now be mapped and updated.

In addition to the characters mentioned there, other characters such as the ampersand "&" and several others, should also be avoided to minimize any problems should you want to export your data to an XML format.

Number of fields in a form  

When an Outlook contact folder as an input data source, DataPorter creates a dynamic recordset comprised of all the fields found in the contact folder. This means that the total number of <selected> fields that can be defined for a contact (including all standard Outlook fields and user-defined fields) cannot exceed 255 in number if you plan on using it as an input data source in DataPorter.  This is the maximum number of fields that can be associated with a given record in the Microsoft Jet engine (MS Access .mdb file).  If the total number of fields in a custom form exceeds 255, DataPorter allows you to select which fields you wish to use up to a maximum of 255.

The maximum number of fields allowed represents ALL fields in the custom form and NOT just the fields used in the mapping process.