Connecting Apps for Office with SAP - Part III: Mail App
Juergen Grebe, Microsoft
Holger Bruchelt, SAP
This document is part of series of articles and code samples on the topic of Connecting Apps for Office with SAP.
- Connecting Apps for Office with SAP - Part I: Word App
- Connecting Apps for Office with SAP - Part II: Excel App
- Connecting Apps for Office with SAP - Part III: Mail App
The app described in this document is available as a free download from the Office Store. Look for the 'SAP CRM Activity' app.
1.1 Apps for Office
With Office 2013, Microsoft has introduced the apps for Office platform which enables the user to experience the power of the web within the Office 2013 applications (Word, Excel, Outlook, PowerPoint, and Project).
An app for Office is basically a webpage that is hosted inside the Office client application. You can use apps to extend the functionality of a document, workbook, email message, or appointment. Apps can run in multiple environments and clients, including rich Office desktop clients, Office Web Apps, mobile browsers, and also on-premises and in the cloud. After you develop your apps and publish them to the Office Store or to an onsite catalog, they will be available to consumers within their Office 2013 and Office 365 applications.
These are document-centric apps that can assist the user when working with one or more documents in Word, Excel, PowerPoint and Project.
These are document-centric apps that add embedded content/functionality into a document in Excel and Excel Web Application.
These are mailbox-centric apps in the Outlook client or Outlook Web App (OWA) client and they extend Outlook items with custom UI and behaviors.
An app for Office can provide the user experience of any modern web application. What makes the platform really powerful is the ability of the
app to interact with a document through an API. The app can read and write to a document, workbook, presentation, project plan, message or appointment and handle application and user events.
This document focuses on the specific aspects of developing an app for Office that connects with an SAP business system. The solution outlined in this document is a simple solution which illustrates the capabilities of the new app for Office platform and the types of enterprise productivity scenarios that it enables.
1.2 SAP CRM Activity App
The app described in this document is the SAP CRM Activity app, a mail app for Outlook and Outlook Web App (OWA) in Office 365.The scenario for the sample app is a user in Outlook who uses the calendar functionality to schedule customer appointments. Customer information and related customer activities are often tracked in an SAP CRM system. Using the SAP CRM Activity app, the user can create an activity in the SAP CRM system directly from within Outlook.
The CRM Activity app will show up in the app bar in the appointment form and the user can start the app by clicking it.
Click on any of the embedded images below for a better rendering.
With the app started in the appointment form, the user can select a sales account and create the activity in the SAP CRM system with the click of a button. The values for activity category, description, planned start and end dates are filled automatically based on the data in the appointment form.
The app is not only available in the Outlook rich client, but also in the browser-based Outlook Web App (OWA) in Office 365.
The same functionality for creating an activity in SAP CRM is available in Outlook Web App (OWA) within Office 365.
2.1 App Hosting
Mail apps are registered on an Exchange server, for this sample app an Office 365 environment was used. This will make an app available for the users with a mailbox on the Exchange server. The web application files of the mail app have to be hosted by a web server that is accessible by the Exchange server. You can host the web application files in a hosting infrastructure of your choice, for example in a Windows Azure web site.
2.2 SAP Data Access
2.2.1 Activities in SAP CRM
To create an activity in the SAP CRM system, a custom function modules Z_ACTIVITY_CREATE was developed. Internally, the function module uses a standard SAP function to create the activity.
Using the approach of developing a custom ABAP wrapper function module has the benefit of simplifying the in and out parameters for the function call and thereby simplifying the definition of the data model in SAP NetWeaver Gateway.
2.2.2 SAP NetWeaver Gateway
Using SAP NetWeaver Gateway, access business data in a SAP CRM or SAP ERP system can be enabled for a variety of consumers and devices in a standardized format based on the REST/OData protocols. NetWeaver Gateway provides a number of different configuration and integration options.
For this sample application, a data model was developed using the built-in Service Builder tool. The data model defines the entity (CRMActivity), the entity set (CRMActivityCollection) as well as the basic operations for the entity (only Create was required for this sample app). The data provider interfaces and backend operation proxies were auto-generated by the Service Builder tool in NetWeaver Gateway and did not require any additional coding effort.
2.3 Security and Authentication
2.3.1 Same-origin Policy
There are a number of ways of overcoming same-origin policy enforcement when you develop an app for Office, however some of them require support on the resource server. Among the techniques that are often referenced as ways to deal with the same-origin policy issue are JSON/P and CORS (cross-origin resource sharing), however they are currently not supported on SAP NetWeaver Gateway.
Another technique is to set up a reverse proxy on the web server. With a reverse proxy, the web app can forward a request to the resource server, without the browser knowing that another remote server is involved. Because our sample app was autohosted in an Office 365 environment, a reverse proxy could not be configured.
The approach used for the sample app was to use a server-side request handler (server-side proxy). The request handler is part of the web app and invoked by the client-side script with a relative URI. The request handler does the work of making the resource request to the SAP NetWeaver Gateway server and passes the result set back to the client script.
2.3.2 App Permissions
The developer can specify the level of permissions that the app will require in the app manifest file, for a mail app it can range from Restricted to ReadWriteMailbox. The end user has visibility to the requested permission of the app before the app is loaded for the first time. For the sample app, the permission level is ReadWriteMailbox to enable the app to store the CRM activity creation status in the mail item.
2.3.3 SAP NetWeaver Gateway Security
For incoming requests from a client application, the SAP NetWeaver system supports several authentication mechanisms. In addition to basic authentication, X.509 client certificates and SAML assertions are supported for single sign-on (SSO) scenarios.
For the sample SAP CRM Activity app, basic authentication over HTTPS was implemented. For apps that modify data in SAP, including this sample SAP CRM Activity app , SAP NetWeaver Gateway requires a Cross-Site Request Forgery (CSRF) token to be retrieved first (GET request) and then submitted with the modifying request (POST request). A trusted RFC connection was configured between the SAP NetWeaver Gateway system and the SAP CRM system, enabling single authentication in NetWeaver Gateway.
3 Sample Solution Details
This section describes the main elements and code that was developed for the SAP CRM Activity app.
The complete solution is available for download on MSDN: Connecting Apps for Office with SAP - Part III: Mail App. You will need Visual Studio 2012, the Microsoft Office Developer Tools for Visual Studio 2012 and Word 2013 to compile and run the sample solution.
3.1 App Manifest
The XML manifest file of an app for Office enables the developer to declaratively describe properties that identify and describe the app for deployment. For the sample app, the properties shown below were used.
3.2 App Loading and Initialization
The Home.js file contains the initialize function that must be executed when a page is loaded. Common app functionality, such as notifications, are defined in the App.js file of the project and are initialized with the app.initialize() function call.
The function will enable access to the current mailbox item (appointment) and read its custom properties.
The description, planned start and end dates for the activity are populated with the values from the appointment item.
Finally, a click handler is registered for the Create button in the UI.
3.3 App Content
When the app is started, the Home.html page is displayed.
The page displays the SAP logo on the right. The content area displays the Sales Account selection drop-down. In the sample app, the values for the list are specified in the HTML file. The values for Activity Category, Activity Description, Planned Start and End data are displayed below.
A Create button is shown at the bottom of the content area which allows the user to create an activity in the SAP CRM system with the values shown in the app.
Once the CRM activity is created, the Create button is replaced with a status indicating that the CRM activity for the appointment has been created.
3.4 CREATING AN ACTIVITY IN SAP CRM
This functions formats the values for CRM activity (start and end date, account, category, description) and constructs an XML string representing the request data. The function uses the JQuery AJAX function to invoke the request handler, passing the XML string with the activity data in the request. After successful creation of the activity in SAP CRM, a notification message is displayed to the user, the Create button is hidden and the status of the activity is displayed and stored with the appointment item.
Please see the sample solution file for the complete source code of this function.
3.5 Storing Activity Status
After the activity is created successfully in the SAP CRM system, the app will store a status property (‘crm_activity’) with a value (‘created’) with the appointment item. When the custom property is set, the app will hide Create button, and show the status of the activity. This will prevent the user from creating duplicate activities in the SAP CRM system.
This callback function checks the value for the custom property crm_activity in the appointment item. If the property has a value of ‘created’ it will hide the Create button and show the activity status.
This function sets the custom property after successful creation of an activity in the SAP CRM system. The property is saved with the appointment item.
The request handler performs the actual work of making the OData request to the SAP NetWeaver Gateway server. The request handler adds the credentials to the request and first invokes a GET request to get the CSRF (Cross-Site Request Forgery) token from SAP NetWeaver Gateway. The CSRF token together with a cookie is added to the subsequent POST request which will create the activity in SAP CRM.
The certificate validation callback function was added to handle situations where a name mismatch can occur between the domain name in the certificate and the domain name in the request URL (e.g. when the NetWeaver Gateway system is cloud-hosted).
The remaining code in the request handler is to construct the XML document with the parameters for the CRM activity. The XML document is submitted with the POST request to the SAP NetWeaver Gateway OData service.
The response data is received by the hander and sent back to the client script as XML string.
Please see the sample solution file for the complete source code of this function.
3.6 Activity Data in SAP CRM
3.6.1 Custom Structure ZACTIVITY
A custom data structure ZACTIVITY was created with the properties of the CRM activity that are relevant for the app, including activity type, description, category, partner, start and end dates. This structure was used to define the CRMActivity entity in the SAP NetWeaver Gateway data model.
Click on any of the images below for a better rendering.
3.6.2 Function Z_CRM_ACTIVITY_CREATE
The app uses a custom function module Z_CRM_ACTIVITY_CREATE to create the activity in the SAP CRM system. The custom function module is a wrapper around the standard SAP function module BAPI_ACTIVITYCRM_CREATEMULTI. The wrapper approach was used to simplify the input and output parameters and aligning them with the data structure of the CRMActivity entity in the SAP NetWeaver Gateway data model. The wrapper approach also allowed to call the BAPI_TRANSACTION_COMMIT function to commit the posting of the activity in the SAP CRM system.
3.7 NetWeaver Gateway Data Model
3.7.1 Entity Type CRMActivity
You use the SAP NetWeaver Gateway Service Builder (transaction SEGW) to define your data model. The CRMActivity entity was defined using the menu option Import -> DDIC Structure is based on the structure ZACTIVITY.
3.7.2 Entity Set CRMActivityCollection
You define the CRMActivityCollection based on the CRMActivity entities.
3.7.3 CRMActivityCollection - Create Mapping
The Create operation is mapped to the custom remote enabled function module Z_ACTIVITY_CREATE in SAP CRM. The activity properties ProcessType, Description, Category, PartnerFct, PartnerNo, ApptType, DateFrom, DateTo, TimeFrom, TimeTo are defined as input parameters. The activity properties Guid and ObjectId are returned as output parameters.
3.7.4 CRMActivityCollection – Read and Query Mapping
While technically not required, it is good practice to implement and map the Read and Query operations for the CRMActivity entity. The operations can be very helpful for testing the OData service, for example to retrieve a single activity entity in XML format that can be used as input for testing the Create operation.
3.7.5 Service Maintenance
Using transaction /IWFND/MAINT_SERVICE you can maintain the OData service in SAP NetWeaver Gateway. Ensure that your service is created, that you have an active OData service (ICF) node and that a system alias for the SAP CRM system is assigned.
3.7.6 Testing the OData service
Using the SAP NetWeaver Gateway Client (transaction /IWFND/GW_CLIENT), you can test the service. For example, to test the Create operation for the activity entity, select HTTP Method POST and specify as Request URI: /sap/opu/odata/sap/Z_OFFICE_CRM_DEMO_SRV/CRMActivityCollection. In the request body, paste the xml input structure for the activity to be created.
3.8 Publishing the app
Publishing your app is a three-step process. In the first step, you will publish the web application project in Visual Studio to your hosting provider, for example to a Windows Azure web site.
When you publish your web for the first time, you will have to create a profile for your web hosting environment.
In the second step, you will publish the app project (the project with the app manifest) to a location where you can deploy it to your Exchange server. You can also do this directly from your Visual Studio project.
When you publish your app for the first time, you will have to create a profile for your web hosting environment.
The app file CRMActivity.app will be available in a folder where it can be deployed to your Exchange server.
Finally, in the third step, you add the app file to your Exchange Online server. Logon to your Office 365 environment as Administrator. Go to your Exchange admin center and select organization -> apps to add the app and make it available for your Outlook users.
3.9 Using the app
The app will be available for users with a mailbox on your Exchange server and will be displayed in the Outlook appointment form.
For Office 365 users, the app will be available in the browser-based Office Web App (OWA).
The sample SAP CRM Activity solution outlined in this document illustrates how an app for Office can be connected with an SAP business system and enable new types of enterprise productivity solutions. The app provides an easy-to-use and responsive user experience that consumers are expecting from today’s web applications. Further, the app illustrates how SAP data can be integrated in to a productivity scenario in a way that was previously not possible.
The solution showcases SAP NetWeaver Gateway, a technology from SAP to connect consumers and devices to data inside an SAP business system. Using the Service Modeler in SAP NetWeaver Gateway, data can be exposed in a standardized OData format and does not require the app developer to have any specific SAP knowledge. Although outside of the scope of this document, single sign-on and write-back scenarios are enabled by SAP NetWeaver Gateway.
5 For more Information
Apps for Office and SharePoint Dev Center: http://dev.office.com
Apps for Office and SharePoint Blog: http://blogs.msdn.com/b/officeapps
SAP NetWeaver Gateway Community: http://scn.sap.com/community/netweaver-gateway
SAP NetWeaver Gateway Online Help: http://help.sap.com/nwgateway
6 About the Author
Christoph Schuler has been involved in the design and development of integrated SAP solutions for over 15 years. He has been leading the design and development of commercial software products for Microsoft/SAP interoperability, including the .NET Data Provider and Duet Enterprise. Christoph works as a consultant, architect and instructor for Microsoft/SAP solutions and is the principal consultant at Connected ERP. You can reach him at firstname.lastname@example.org.