Skip to Content
Technical Articles

SAP Cloud Platform – Connect to Outlook mail using Open Connectors

SAP announced the new ‘Open Connectors’ service in SAP Cloud Platform last month. I tried my hand with the Outlook mail connector in the Cloud trial account. I found it easy to connect and integrate third party cloud applications using Open Connectors.

SAP Cloud Platform Open Connectors simplifies and accelerates connectivity to third-party cloud applications. It provides robust, feature rich, pre-built connectors to an extensible library of over 150 of the most popular third-party cloud applications.

 

There is a blog series by Divya Mary – https://blogs.sap.com/2018/09/19/part-1-enable-sap-cloud-platform-open-connectors-in-trial/ in which she connects HubSpot with SAP Cloud platform. You can read her blog series for detailed information behind some of the steps covered here.

In this blog, I will explain the steps to consume APIs from Outlook mail through pre-built connector.

You will need the following:

  1. A trial account in SAP Cloud Platform (Neo) (http://account.hanatrial.ondemand.com)
  2. ‘Open Connectors’ service is enabled in your trial account. Refer https://blogs.sap.com/2018/09/19/part-1-enable-sap-cloud-platform-open-connectors-in-trial/ for the steps.
  3. An Outlook email account for authentication.

Once you have all these, you are good to go. It takes just a few minutes to set up and test the integration.

  1. Login to SAP Cloud Platform Trial account and go to ‘Open Connectors’ service.

2. Click on ‘Connectors’ to view the catalog of available connectors. Hover over the tile for ‘Outlook Email’ and click on ‘Authenticate’. This will retrieve the oAuth keys which will be used for authentication. This is done by signing into your outlook mail account.

3. Click on ‘Create Instance’.

4. You will get the following screen, once the instance is created. Now we can test the Mail APIs before integrating them with API Portal. Click on ‘Test in the API docs’ tile.

5. Scroll to find ‘Get /messages’ under messages. Click on ‘Try it out’.

6. You will be presented with all the parameters you can pass to make the API call. Notice that the Authorization field is pre-filled.

7. Let’s try to get all the emails with a subject that begins with ‘STICKET’. This is done by entering the where condition. As the documentation suggests, the condition should follow CEQL search expression. Click on execute. You can see the response with the list of emails that fit the given criteria.

Notice the curl command with the harmonized RESTFul URIs to your third-party application and the normalized authentication token.

Try posting a message/sending an email from the connected account.

Note: Copy the entire CURL command and keep it. We will need the URL and authorization token to connect from API proxy.

Now let us consume and manage the connection to the third-party mail application in SAP Cloud Platform API management.

8. Login to the API portal and create an API proxy with the details below.

 

URL https://api.openconnectors.ext.hanatrial.ondemand.com/elements/api-v2/messages
Name OutlookAPI
Title OutlookAPI
Description OutlookAPI
API Base Path /elements/api-v2/messages

9. Go to Policies. Select ‘PreFlow’ under  ‘ProxyEndPoint’. Add  ‘Assign Message’ Policy (from Mediation policies).

10. Add the following code to the policy.

<!-- This policy can be used to create or modify the standard HTTP request and response messages -->
<AssignMessage async="false" continueOnError="false" enabled="true" xmlns='http://www.sap.com/apimgmt'>
 
	<!-- Sets a new value to the existing parameter -->
	<Set>
	<Headers>
	    <Header name="Authorization">User XXXXX, Organization XXXX, Element XXXX</Header>
	</Headers>
		</Set>
	<IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
	<AssignTo createNew="false" type="request">request</AssignTo>
</AssignMessage>

Replace the Authorization value in the <Header> tag with the value from the CURL command.

11. Update the policy. Save and Deploy the API proxy.

12. Let’s test the proxy. Go to Test console in the API portal. Click on the API proxy we just    created.

Make sure you remove the ‘/SwaggerJSON’ at the end of the url and click on ‘Send’. This will try to retrieve all the mails. It returns around 200 mails. We can set the pageSize parameter while calling the API.

13. Add a ‘where’ condition to filter the emails being retrieved. Now, it will retrieve only the emails that satisfy the condition. (I tried the ‘orderBy’ parameter. It did not work for me. I am investigating this issue).

14. Finally, try sending an email. Choose Post and enter the body of the request.

{
  "Body": {
    "Content": "test "
  },
  "Subject": "Subject from API",
  "ToRecipients": [
    {
      "EmailAddress": {
        "Address": "xxxx@xxxx.com",
        "Name": "Sharadha"
      }
    }
  ]
}

Click ‘Send’

15.  Notice the status code – 200 as response.

16. Check for the email in the recipient mail box.

Let me know if you have any questions. Have fun exploring!

4 Comments
You must be Logged on to comment or reply to a post.
  • Hi Sharadha,

    Thank you for the blog. It was really useful to get started with Open Connectors. It works fine for me.

    Is the token valid for only certain time frame? Looks like when i tried the same get message service, it was reporting as ErrorCode: ‘PP_E_RPS_REASON_TIMEWINDOW_EXPIRED’. But i did the authentication again and it worked.

    is outlook connector using below api to consume the service?

    https://docs.microsoft.com/en-us/previous-versions/office/office-365-api/api/version-2.0/mail-rest-operations

    • To answer your first question, the connector by default uses ‘OAuth 2.0’, which has a token expiration time for security purposes.  The application which utilizes the connector should take care of refreshing the token when required.

      “OAuth 2.0 is an authorization protocol that allows applications to access external services on behalf of a specific user. It is a two-legged process. In the first step, the application being granted access (in this Cloud Elements), directs the user to a special `authorization url`, where the user signs into his account on the external service and explicitly grants permission to the application to access his data. In the second step, the authorized application requests an access token from the external service’s `token url`. This token is then used to retrieve data from the external service on subsequent requests. For security purposes, this token expires after some time, which varies between services. In order to continue accessing the external service, the application can send a `refresh token` to a `refresh url` and receive a new `access token`. Below, you will enter the relevant to allow Cloud Elements to complete the OAuth 2.0 flow for this service.”

      But for testing purposes (not recommended for production) you can change the authentication to basic and give the user/password. You can also have a look at other authentication options provided by this connector and choose the one which suits your project.

      For your second, I cannot confirm how the connector works internally as it is delivered by SAP. But logically, it should use the Microsoft APIs for interfacing with Outlook.

      -Sharadha

       

  • Great blog!! Thanks Shradha for sharing it:)

    In case If one wants to consume the open connector services of Outlook from Cloud Platform Integration an endpoint url and credentials are required. Hope these details are available in the response received after deploying the service on SAP Clout platform. Please confirm/clarify.

     

  • Hi Sharada

    Thank you for the simple illustration of Open Connectors in the context of Outlook mail. In the API Docs, i was able to explore apis to read messages. But would it be a possibility to read calendar events from outlook?

    Best Regards

    Vivek