Using the IPropertyFormatter Interface

This section explains how to develop custom formatters to convert properties, and make them compatible with the properties of an OData service in the SAP Gateway system.

Prerequisites

You have a GWM Outlook add-in project.

Context

In some cases, you may need to develop a custom formatter that can map custom properties in Microsoft Outlook to the properties in an OData service.

The formatter then converts the Microsoft Outlook custom property to the property as known by the OData service, so that the expected data can be retrieved from the SAP system for end users.

To create a custom formatter, create a new class for the formatter and implement the IPropertyFormatter interface, which is provided in the GWM Outlook add-in project.

Example For example, you can develop a formatter to convert the property, Country Value in Microsoft Outlook to the property,Country Code as required by an OData service.

The example is based on the OData service, GWDEMO, and the Check Address dialog box in Microsoft Outlook.

Note The code used in the example below was generated in Visual Studio 2010.

To open the Check Address dialog, from the menu choose Start of the navigation path Home Next navigation step New Item Contact End of the navigation path , enter some text in the box beside Business and then select Map It in the Addresses pane.

For instance, to map the property, Country/Region (for example, Germany) in the Check Address dialog box, to the OData property, Country code (for example, DE) as required by the service, follow the steps below.

Procedure

In the Solution Explorer region, right click the folder, <Your Project Name> Outlook Formatter .
Choose Add Class .
The Add New Item window displays.

A new Class item is created.

Enter the name, CountryFormatter.cs, for the class in the Name field.
An empty class named CountryFormatter.cs is created.
Do the following to retrieve the Country Code list from the SAP Gateway system:
1. From the project, open the class, ConfigurationReaderHandler, and go to the method, GetServiceDetails.
  The SAP.IW.GWPAM.Common.dll has the ConfigurationReaderHandler class that contains the method GetServiceDetails. This method can be used to read the OData service details using the name of the service (proxy name) in the App.config file under the folder SAP Service Reference.
  To get the list of CountryCode, we call the method, GetServiceDetails in the ConfigurationReaderHandler class to retrieve the details of the service “GWDEMO”.
  
  Note The service name GWDEMO can differ depending on the service proxy name used during the GWM project generation.
2. Copy and paste the code snippet below into the CountryFormatter class
```
using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using SAP.IW.GWM.Common.Configuration;

namespace GWPAM_Outlook_Addin1.Outlook.Formatter
{
    class CountryFormatter 
    {
        static List<GWDEMO.Country> CountryCodeList = null;

        static CountryFormatter()
        {
            CountryCodeList = new List<GWDEMO.Country>();
            ServiceDetails serviceDetail = ConfigurationReaderHandler.Instance.GetServiceDetails("GWDEMO");
            GWDEMO.GWDEMO context = new GWDEMO.GWDEMO(new Uri(serviceDetail.Url));
            foreach(var country in context.CountryCollection)
            {
                CountryCodeList.Add(country);
            }
        }

        
    }
}
```

Implementing IPropertyFormatter Interface

Context

The GWM Outlook add-in comes with the IPropertyFormatter interface, which can be used to format the values received from the SAP system to the values required by Microsoft Outlook and vice versa.

Below are the methods of the IPropertyFormatter interface:

Table 1: Details of the IPropertyFormatter interface
Interface Methods	Description
ConvertValue	This method will convert the value received from the SAP system into the value as required by Microsoft Outlook. This method takes in the values and returns the formatted value. Example In case of CountryFormatter it will take in the country code and return the country description
ConvertValueBack	This method will convert the value received from Microsoft Outlook into the value as required by the SAP system. This method takes in the value and the target data type of the value (such as, int, string…) and returns the formatted value. Example In case of `CountryFormatter` it will take in the country description and return the country code

Below is the code snippet showing the class CountryFormatter with the IPropertyFormatter interface:

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using SAP.IW.GWM.Common.Configuration
;

namespace GWPAM_Outlook_Addin1.Outlook.Formatter
{
    class CountryFormatter : IPropertyFormatter
    {
        static List<GWDEMO.Country> CountryCodeList = null;

        static CountryFormatter()
        {
            CountryCodeList = new List<GWDEMO.Country>();
            ServiceDetails serviceDetail = ConfigurationReaderHandler.Instance.GetServiceDetails("GWDEMO");
            GWDEMO.GWDEMO context = new GWDEMO.GWDEMO(new Uri(serviceDetail.Url));
            foreach(var country in context.CountryCollection)
            {
                CountryCodeList.Add(country);
            }
        }

        /// <summary>
        /// This method will convert the value from the country code as received in the service to the country Description as present in the country description drop down of outlook contact
        /// </summary>
        /// <param name="value">country code</param>
        /// <returns>country description</returns>
        public object ConvertValue(object value)
        {
            var  country = CountryCodeList.FirstOrDefault(j => j.CountryCode == value.ToString());
            string result = country == null ? value.ToString() : country.CountryText;
            return result; 
        }

        /// <summary>
        /// This method will convert the value country description as received from outlook into the country code as required by the service
        /// </summary>
        /// <param name="value"></param>
        /// <param name="targetType"></param>
        /// <returns></returns>
        public object ConvertValueBack(object value, Type targetType)
        {
            var country = CountryCodeList.FirstOrDefault(j => j.CountryText == value.ToString());
            string result = country == null ? value.ToString() : country.CountryCode;
            return result; 
        }
    }
}

Invoking the CountryFormatter Class

Context

We will initialize IPropertyFormatter interface with CountryFormatter class, and then invoke the method ConvertValue to convert the country code received from the OData service to the country description value in Microsoft Outlook contacts.

Procedure

Open the method, MapEntityToStandardFields from Start of the navigation path

Solution Explorer Next navigation step

Project

Outlook

Contact

EPMAccounts Next navigation step

EPMAccountsBusinessApplication.cs End of the navigation path

private static void MapEntityToStandardFields(FormatterApplication.GWDEMO.BusinessPartner entity, ContactItem outlookItem)
        {
 
          Logger.Log(Severity.Verbose, Categories.Outlook_StarterKit, "EPMAccountsBusinessApplication::MapEntityToStandardFields()");
          IPropertyFormatter propertyFormatter = null;
          outlookItem.WebPage = entity.WebAddress;
          outlookItem.JobTitle = entity.BusinessPartnerRoleCode;
          outlookItem.JobTitle = entity.BusinessPartnerRoleText;
          outlookItem.Email1Address = entity.EmailAddress;
          outlookItem.CompanyName = entity.Company;
          outlookItem.BusinessTelephoneNumber = entity.TelephoneNumber;
		
		propertyFormatter = new CountryFormatter();
          outlookItem.BusinessAddressCountry = propertyFormatter.ConvertValue(entity.Address.CountryCode).ToString();
        }

Initialize IPropertyFormatter interface, with CountryFormatter class, and invoke the method ConvertValueBack to convert the Country Description received from the Outlook Contact to Country Code value as required by the service. Here is a sample code:

private static void MapStandardFieldsToEntity(GWDEMO.BusinessPartner entity, ContactItem outlookItem)
        {
			Logger.Log(Severity.Verbose, Categories.Outlook_StarterKit, "Contacts01BusinessApplication::MapStandardFieldsToEntity()");
			entity.Company=outlookItem.CompanyName;
			entity.WebAddress=outlookItem.WebPage;
			entity.FaxNumber=outlookItem.BusinessFaxNumber;
			entity.EmailAddress=outlookItem.Email1Address;
			entity.TelephoneNumber=outlookItem.BusinessTelephoneNumber;

            IPropertyFormatter propertyFormatter = null;
            propertyFormatter = new CountryFormatter();
            entity.Address.CountryCode = propertyFormatter.ConvertValueBack(outlookItem.BusinessAddressCountry, typeof(string)).ToString();
        }

Verifying the Formatter Changes

Prerequisites

Verify the changes made to the formatter in a system that has Microsoft Outlook 2010 installed.

Procedure

Build and run the project to launch the Microsoft Outlook 2010 application.
Navigate to the Contacts folder, and then select any EPM Account, and double click to view the data.
Click on the Business option under the group Addresses, which will open up the Check Address dialog box.
In the Country/Region drop-down, now the Country text Germany is shown instead of DE.