How to Implement the GetAll Function with Filter: Contact

Context

As described in the Creating and Working with SAP Business Workflow Templates section we create a GWM Outlook Add-in, and we then use it in Outlook. In this section we will see how we can extend the code generated on the completion and building of the GWM template.

Note In this document, we use the GWDEMO service shipped by SAP along with SAP Gateway system for demo purpose. The name of the service GWDEMO is provided by the SAP administrator at the time of service activation, and therefore may vary in your SAP Gateway system. Get in touch with the SAP administrator to activate the service and get the exact service name. You can also select any OData feed which can be modeled as an Outlook Contacts entity.

In this section, as an example for extending the generated code, we will add a filter to the GetAll function to assist the user to fetch onselect, the recipient when forwarding a task.

Procedure

Follow the steps in Creating and Working with Contact Template section to create a Contact template.
Note When creating the template, ensure to name the template as EPM Accounts .

Once the project is generated, we will start to extend the project to add a filter. Before extending the project, let us review how the Outlook add-in functions, and how the structure of the generated project is represented.

The GWM Outlook project generates the GWM Outlook add-in template with classes required for handling connectivity to SAP system to do the following functions:

Read and update data from the SAP system into Microsoft Outlook
Basic UI for showing data in custom properties and associated entities tab
Formatter to convert SAP data to Outlook data, and validators to perfrom basic validation operations such as, mandatory property check

The table below describes the major classes generated by GWM Outlook Add-in wizard.

Class Name	Description
BusinessConnectivityHelper	This class handles the connectivity to the OData endpoint. It performs the required handling to enable authentication to the SAP Gateway endpoint. It also initiates the call to the SAP Gateway endpoint with requestId and SAP Passport required for enterprise readiness.
Logger	This class provides the API to log the necessary information to the Event Viewer, or local file. The class uses System.Trace API and therefore the logging can be enabled through app.config. SeeLogging in the GWM Generated Application. This class can be extended to support any other custom logging FW (including third party logs).
<proxyName>SAPExtensions	This is the extension class to the generated proxy which contains OData4SAP semantics information such as, labels, filter values as maintained in the service in the SAP Gateway system.
<outlookitemtype>InspectorWrapper	This is the wrapper class over the “Outlook” inspector which can be extended to perform specific operation during the launch of the outlook item UI. Example, we can extend the class to display custom task panes. See Custom Task Pane with analytics.
UserPropertiesTab	This is the Windows Form class which provides the UI to show the Outlook custom properties, which cannot be viewed in the standard Outlook UI by default. This class can be extended to show more custom properties, e.g complex properties (for more information refer to part II of this series)
AssociatedEntitesTab	This is the Windows Form class which provides the UI to show the associated entities tab. This class can be extended to show more associated entities or even data coming from the different OData endpoint (for more information refer to part III of this series)
<ApplicationName>BussinessApplication	This class provides the functionality to map the SAP business entity with the Outlook fields, and provides API to fetch records from SAP, create, update and delete record from SAP. In some cases, the method implementation may be blank depending on the service. For example, in case the OData service does not support create operation (like in this case), then the create method will be blank. This class can be extended to provide a different mapping, or even to show more information in the task pane.
<ApplicationName>Validator	This class provides the functionality to validate the data entered by the user. By default, we perform the validation for mandatory properties (in case the mandatory property is missing, an error is displayed to the user). This can be extended to perform custom validation as well

The next step is to verify the default Outlook functions:

Note These steps should be verified on a system where Microsoft Office Outlook 2010 profession edition is installed

In the Solutions Explorer region, navigate to BusinessEntity BusinessConnectivityHelper.cs .
Double click the BusinessConnectivityHelper.cs to open it.
Enter the user login credentials in basic authentication as required for the end user.
Run the project to deploy it within Outlook application.
Select EPM_Accounts from the Outlook ribbon and click on the button GetAll EPMAccounts to fetch records from the SAP system.
Note The name of the button in the GetAll drop-down will be the name provided in the GWM wizard.

All the Outlook Contacts items will be fetched from the SAP system with the mapping as defined in the wizard.
Select any Outlook Contacts item and double click to open it.
Click on the AssociatedEntities tab to view the associated entities
All the selected associated entities are grouped as tabs under the Associated Entities custom tab.
Click on the EPMAccount Properties to view the custom properties which were not mapped to the standard properties. The name and content of this tab may vary depending on the name and properties selected for the Custom Properties tab view in the wizard.

Extending the Generated Code

Context

We will show extensibility by displaying only the Accounts relevant for a specific country.

This will be implemented by introducing the Country code parameter as a property in the Application Configuration settings. The advantage of maintaining a value in the Application configuration is that it can be changed by the user later, and the new value will be read by the Outlook project without the need to build and deploy the project again.

Procedure

From the Solution Explorer region, expand the SAP Service Reference folder.
Double click on the App.config to open it.

The Application configuration files contain settings specific to an application. This file contains configuration and settings that the application can read at runtime.

Add a new configuration for country code and provide a value DE, under appSettings .
```
<appSettings>
    <add key="CountryCode" value="DE" />
</appSettings>
```
In the Solution Explorer region navigate to Project folder Outlook Contacts Template (displays the name as given while creating the template) <Template>BusinessApplication.cs .
Note The name of the project folder and BusinessApplication may vary depending on the template name provided in the wizard.
Search for the GetAllData method in the BusinessApplication.cs.

Write the following custom code to read the configurations from the App.config file

string countryCode =  ConfigurationReaderHandler.Instance.GetConfigValue("CountryCode");

When a project is generated, the SAP.IW.GWM.Common dll will be created in the References folder under the Solution Explorer region.

In this DLL, there is a class ConfigurationReaderHandler that contains the method GetConfigValue. This method reads the configuration maintained in the file, App.config at runtime, hence in the above code, we call the method in the ConfigurationReaderHandler class.

To fetch the filtered data from the SAP system, let us use the $filter feature provided by the OData standards.

Use the WCF EF 4.0 AddQueryOption method to pass the system query name ($filter in our case) and the filter condition for example, CountryCode eq ‘DE’ to fetch the filtered data.

//var serviceresponse = serviceContext.BusinessPartnerCollection.Execute() as QueryOperationResponse<GWDEMO.BusinessPartner>;
and add the following code snippet
QueryOperationResponse<GWDEMO.BusinessPartner> serviceresponse = null;
                if (string.IsNullOrEmpty(countryCode))
                {
                    serviceresponse = serviceContext.BusinessPartnerCollection.Execute() as QueryOperationResponse<GWDEMO.BusinessPartner>; 
                }
                else
                {
                    serviceresponse = serviceContext.BusinessPartnerCollection.AddQueryOption("$filter", string.Format("CountryCode eq '{0}'", countryCode)).Execute() as QueryOperationResponse<GWDEMO.BusinessPartner>;
                }

Note The value of the filter condition may depend on the available filterable properties of the selected OData service. In case of the GWDEMO service, the CountryCode property of the BusinessPartnerCollection can be used to fetch the list of EPM accounts filtered on the country code.

Verifying the Filter in Outlook

Prerequisites

Verify the filter condition on a system where Microsoft Office 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.
Click on GetAll to get the filtered list of records from SAP system.