This sample has been moved to: Outlook-Add-in-JavaScript-MakeEWSRequest. The description below does not match the new version.  

Old Description:

This sample accompanies the MSDN article Calling Web services from a mail app.

The JavaScript code in this sample shows a simple request for the subject of the current email message. While this is a simple request, it does demonstrate the steps required to create an EWS service request and the best practices for making the request.
The code that creates the EWS XML request includes two methods. The first method, getSoapEnvelope(), wraps a SOAP envelope around a web service request. Because the SOAP envelope is standard for all EWS requests, this method can be reused to wrap any EWS request.

The second method, getSubjectRequest(), returns the EWS request to get the subject field of an item. The id parameter is the Exchange item identifier for the requested item. Note the following about the request:

• The ItemShape element is used to restrict the response to the base shape IdOnly. This limits the response to only the item identifier for the item and prevents excessive data from being sent back from the server.
• The AdditionalProperties element is used to add the Subject field to the response. By using the IdOnly base shape and a list of additional properties, you can limit the size of the response from the server to just the data that your app requires.

The sendRequest() method is called when you click the Make EWS request button in the app UI. It gets the Exchange identifier of the current item and passes it to the getSubjectRequest() and getSoapEnvelope() methods, then makes an asynchronous call to the Exchange server by using the makeEwsRequestAsync method. The makeEwsRequestAsync method takes two parameters: the EWS request wrapped in its SOAP envelope, and a callback method that is called when the asynchronous request to EWS is complete. You can add a third optional userContext parameter to the makeEwsRequestAsync method if you have to provide additional information to the callback method.

The callback() method is called with a single parameter, asynchResult. The asynchResult object has two members:

• value – The contents of the response from EWS.
• context – The userContext parameter passed to the makeEwsRequestAsync method.

The callback method in the sample displays the contents of the response in a scrollable div element in the UI, but your code can use the response in more sophisticated ways.

Prerequisites

This sample requires that you have the following:

• Visual Studio 2012, with the apps for Office project templates.
• A computer running Exchange 2013 with at least one email account, or an Office 365 developer account.
• Internet Explorer 9 or Internet Explorer 10 Preview.
• Familiarity with JavaScript programming and web services.

Key components of the sample

The sample solution contains the following files:

• EWSRequest project
  • EWSRequest.xml – The manifest file for the mail app for Outlook.
• EWSRequestWeb project
  • EWSRequest.html – The HTML user interface for the mail app for Outlook.
  • Scripts\EWSRequest.js – The JavaScript file that handles requesting and using the EWS request.
  • Scripts\Lib – The mail app for Outlook and Outlook Web App API.

Configure the sample

The mail app will be activated on any email message in the user's Inbox. You can make it easier to test the app by sending one or more email messages to your test account before you run the sample app.

Build the sample

Press F5 to build and deploy the sample application. Complete the following tasks to deploy the application:

1. Connect to an Exchange account by providing the email address and password on an Exchange 2013 server.
2. Allow the server to configure the email account.

Run and test the sample

You run and test the sample in the web browser that is started by Visual Studio when you build and deploy the sample.

If you are running the sample on an Exchange server that is using the default self-signed certificate, you will receive a certificate error when the web browser starts. After you verify that the web browser is opening the correct URL by looking at the web address, you can click Continue to this Web site to start Outlook Web App.

Follow these steps to run the sample:

1. Log on to the email account by entering the account name and password.
2. Select a message in the Inbox.
3. Wait for the App bar to appear over the message.
4. In the App bar, click EWSRequest.
5. When the EWS Request mail app appears, click the Make EWS request button to request the subject of the current message from the Exchange server.
6. You can review the response XML that is returned by the request.

Troubleshooting

The following are common errors that can occur when you use Outlook Web App to test a mail app for Outlook:

• The App bar does not appear when a message is selected. If this occurs, restart the application by selecting Debug – Stop Debugging in the Visual Studio window, then press F5 to rebuild and deploy the app.
• Changes to the JavaScript code may not be picked up when you deploy and run the app. If the changes are not picked up, clear the cache on the web browser by selecting Tools – Internet options and clicking the Delete… button. Delete the temporary Internet files and then restart the app.

Related content

• Create EWS Solutions
• makeEwsRequestAsync method