How to Map Complex Type Properties to Standard Properties in Outlook

Mapping complex types in an OData service to standard properties in your Microsoft Outlook add-in.

Prerequisites

Make sure that you have a GWM Outlook add-in project for Contacts that calls the OData service with the complex type you want to use.

Context

You can edit the generated code on completing and building the GWM Outlook add-in template to map a complex type to a standard Outlook property.

Note The example used in this section is based on the a generated application in Visual Studio 2010, however, you can also use Visual Studio 2013 and run the add-in on Outlook 2013.

A complex type is a structured type that contains a list of properties without a key. Complex types can only exist as properties on entity types, or other complex types.

To map a complex type to a standard Outlook property, open the generated class for the service and add your custom code.

Example

In this guide, we used an example based on the service, GWDEMO, which is shipped with SAP Gateway system for demo purposes. In the example, the template name used in the generated project is EPMAccounts.

For our example, the address property in the service is a complex type, which contains properties, such as, street, country, postal code, and many more.

Metadata

Note The name of the complex property can vary depending on the service selected for GWM Outlook Add-in Contacts application.

The following is an overview of the steps:

We will map the complex type, Address, to the Contacts item in Microsoft Outlook using the method, MapEntityToStandardFields.
We will map the properties of the complex type to the Outlook user properties using the method, MapEntityToUserProperties.
We will map the standard Outlook properties to the complex type using the method, MapStandardFieldsToEntity.
We will map the standard Outlook user properties to the properties of the complex type, using the method MapUserPropertiesToEntity.
We will load the data grid for the fields using the method, LoadCustomFieldsDataGrid.

Map the Complex Type to the Standard Outlook Item

Context

The first step in our example is to map the complex type, Address, to the item, Contacts. This ensures that the data from the SAP system is available in the Microsoft Outlook Contacts standard UI.

Procedure

From the Solution Explorer window, choose the class, <Your project folder> Outlook Contacts EPMAccounts EPMAccountsBusinessApplication.cs to open it.
Search for the method, MapEntityToStandardFields.
Note The names EPMAccounts and EPMAccountsBusinessApplication may vary depending on the template name.
Copy and paste the following code to the method, MapEntityToStandardFields, to map the properties from the complex type, Address to Contacts standard properties.
```
if (entity.Address != null)
            {
                outlookItem.BusinessAddressStreet = entity.Address.Street;
                outlookItem.BusinessAddressCity = entity.Address.City;
                outlookItem.BusinessAddressPostalCode = entity.Address.PostalCode;
                outlookItem.BusinessAddressCountry = entity.Address.CountryCode;
            }
```
The mappings that we will exhibit from the given service are as follows:
- The service property, Address.Street, is mapped to, BusinessAddressStreet.
- The service property, Address.City, is mapped to, BusinessAddressCity.
- The service property, Address.PostalCode, is mapped to, BusinessAddressPostalCode.
- The service property, Address.CountryCode, is mapped to, BusinessAddressCountry.
Note The mappings can vary in case a different service has been selected to create the GWM Outlook application.

Map the Properties of the Complex Type to Outlook User Properties

Context

The second step is to map the properties of the complex type that you want, such as, street, city, postal code, country, to the user property types in Outlook.

Procedure

Open the class, EPMAccountsBusinessApplication, and search for the method, MapEntityToUserProperties, to map the complex property to the Outlook Contacts Custom fields.
The method, MapEntityToUserProperties reads the value from the service, and maps it to the Outlook Contacts user properties.
When the project is generated, for every custom property selected in the GWM Outlook Add-in wizard, a user property will be created for the Contacts item.

The MapEntityToUserProperties first checks if the user property exists. If the user property does not exist, then a new user property will be created using standard Outlook APIs, and then sets the value by converting it to string value.
Note Outlook does not allow certain characters in the user property. So the method Outlook.GetUserPropertyName removes the characters that are not allowed and also appends the name with an SAP namespace to avoid probable naming conflicts.

Copy and paste the following code to the method, MapEntityToUserProperties:

userProperty = userProperties[OutlookUtilities.GetUserPropertyName("Address.CountryText")];
            if (userProperty == null)
            {
                userProperty = userProperties.Add(OutlookUtilities.GetUserPropertyName("Address.CountryText"),  
                OlUserPropertyType.olText, false, 1);
            }
            if (entity.Address.CountryText != null)
            {
                userProperty.Value = entity.Address.CountryText.ToString();
            }
            else
            {
                userProperty.Value = null;
            }
            OutlookUtilities.CleanUpResources(userProperty);
			
			userProperty = userProperties[OutlookUtilities.GetUserPropertyName("Address.AddressTypeCode")];
            if (userProperty == null)
            {
                userProperty = userProperties.Add(OutlookUtilities.GetUserPropertyName("Address.AddressTypeCode"),  
                OlUserPropertyType.olText, false, 1);
            }
            if (entity.Address.AddressTypeCode != null)
            {
                userProperty.Value = entity.Address.AddressTypeCode.ToString();
            }
            else
            {
                userProperty.Value = null;
            }
            OutlookUtilities.CleanUpResources(userProperty);

Note Repeat step 7 for other user properties if required.

Map Standard Outlook Properties to the Complex Type

Context

The third step is to map the standard properties to the Contacts item to the appropriate properties of the service.

Procedure

Search for the method MapStandardFieldsToEntity in class the EPMAccountsBusinessApplication to map the complex property from Outlook Contacts standard properties to the appropriate properties of the service.
Note Skip this step if the service does not support create, or update calls. This step is required only to read the values from the Outlook fields and update them in the service during create, or update calls.
The MapStandardFieldsToEntity method reads the value from the Outlook Contacts standard fields and updates it back to the appropriate service property.

Copy and paste the following code to the method to map values to the complex property Address.

if (entity.Address == null)
{
   entity.Address = new GWDEMO.Address();
}
entity.Address.Street = outlookItem.BusinessAddressStreet;
entity.Address.City = outlookItem.BusinessAddressCity;
entity.Address.PostalCode = outlookItem.BusinessAddressPostalCode;
entity.Address.CountryCode = outlookItem.BusinessAddressCountry;

Note The mapping can vary in case a different service has been selected to create the GWM Outlook application.

Map Outlook User Properties to Properties of the Complex Type

Context

The fourth step is to map the user property types in Outlook to the properties of the complex type such as, street, city, postal code, country.

Procedure

Search for the method MapUserPropertiesToEntity in the class EPMAccountsBusinessApplication to map Complex Property from Outlook Contact Custom fields to the appropriate service fields.

Note This step is required only to read the values from the Outlook fields and update it in the service during create or update calls. If the service does not support create or update calls, skip this step.

The method MapUserPropertiesToEntity reads the value from the Outlook Contact user properties, and maps them to the appropriate service properties.

Add the following code to the MapUserPropertiesToEntity method to map the values to the Complex property Address.

userProperty = userProperties[OutlookUtilities.GetUserPropertyName("Address.CountryText")];
if (userProperty != null)
{
  if (!string.IsNullOrEmpty(userProperty.Value))
  {
     entity.Address.CountryText = userProperty.Value;
  }
  OutlookUtilities.CleanUpResources(userProperty);
}

userProperty = userProperties[OutlookUtilities.GetUserPropertyName("Address.AddressTypeCode")];
if (userProperty != null)
{
  if (!string.IsNullOrEmpty(userProperty.Value))
  {
     entity.Address.AddressTypeCode = userProperty.Value;
  }
  OutlookUtilities.CleanUpResources(userProperty);
}

Repeat the steps above for other custom properties if required.
The Outlook “Contact” UI by default has a field for showing only the standard or General properties like Address, Telephone no, etc. The custom properties are not shown in any standard UI. The GWM provides the flexibility to add custom tabs to the Outlook item, where the custom properties are displayed.

Load the Outlook Data Grid for Custom Fields

Context

The steps listed below details how you can use GWM to add the new custom properties to the custom properties tab.

Note You can skip these steps if you do not want to show the custom properties in the UI.

Procedure

From the Solution Explorer window navigate to Outlook Contact EPMAccounts UserPropertiesTab.cs .
Double click on UserPropertiesTab.cs to open it.
Search for the method LoadCustomFieldsDataGrid in the UserPropertiesTab.cs.

Add the following code to the method:

this.AddPropertyToDataGrid("Address.CountryText", userProperties, itemCreate);
this.AddPropertyToDataGrid("Address.AddressTypeCode", userProperties, itemCreate);

Verifying in Outlook

Prerequisites

Verify the filter condition on a system where Microsoft Outlook professional edition is installed
Clear up any previous projects with the same name from the Outlook test system before testing this functionality

Procedure

Run the project.
In Outlook, double click on the EPM_Accounts menu, or the name of a project that you used.
Click on Get All to get the filtered list of records from the SAP system.
The contacts from the SAP system are retrieved and displayed in the details region.
Open any EPM account, and check if the address field maintained in the SAP system displays as shown in the Outlook standard fields.
Navigate to the EPMAccountProperties tab to check if the mapped complex properties are displayed. By default, it is called CustomProperties.