Page 44 - MSDN Magazine, August 2017

You should always design your card in the app first. Once you’re happy with the card layout, you can then use the markup in your e-mail messages.
Calling an External Web Service
with HttpPOST Action
Now you have a message card with two actions. The OpenUri will open a browser and navigate to the URL specified in the action. For the Http- POST action, you’d like it to call your REST API that will approve the expense report. You replace the HttpPOST action with the following:
{
"@type": "HttpPost",
"name": "Approve",
"target": "https://api.contoso.com/expense/approve", "body": "{ \\\\"id\\\\": \\\\"98432019\\\\" }"
}
When a user clicks on the Approve button, a Microsoft server will make an HTTP POST request that’s similar to the following:
POST api.contoso.com/expense/approve Content-Type: application/json
{ "id": "98432019" }
The target is the URL, which the Microsoft server is going to make a POST request to, and the body is the content of the request. The body content is always assumed to be JSON.
Now you’ll send yourself an e-mail with the new markup. When you click on the Approve button, the action is completed successfully.
Figure 3 Card with One Section
ActionCard Action
Now let’s add a Reject button so users can reject an expense report. For reject, you need additional input from users to explain why the expense report is rejected.
The ActionCard action is designed for such scenarios. It con- tains one or more inputs and associated actions that can be either OpenUri or HttpPost. You insert an ActionCard action in between HttpPOST and OpenUri, as shown in Figure 4.
Actionable Messages will work with any Web service that can handle HTTP POST requests.
If you send yourself the updated markup, there are Approve, Reject and View Expense buttons. If you click on the Reject button, you can now enter comments before you reject the expense report.
Let’s take a look at the ActionCard action markup. Besides the type and name properties, it has an array of inputs and actions. In this example, you have a multiline TextInput that lets users enter text. The other supported inputs are DateInput and Multichoice- Input. For more details, refer to bit.ly/2t3bLJN.
You have an HttpPOST action that will make a call to the exter- nal Web service to reject the expense report. This is similar to the HttpPOST action for the approve action. One major difference is that you want to pass the comments entered by users to the Web service call. You can reference to the value of the text input by using {{rejectComment.value}}, where rejectComment is the ID of the text input.
Web Service for Actionable Messages
So far you’ve seen the markup for Actionable Messages in Outlook and how it works. In the rest of the article, I’ll describe how a Web service should handle requests coming from Actionable Messages in Outlook.
Actionable Messages will work with any Web service that can handle HTTP POST requests. In this example, your Web service is an API controller in ASP.NET MVC. Figure 5 shows your API controller.
There are two methods in this API controller, one for approval and another for rejection. The Web service must return an HTTP status code of 2xx for the action to be considered successful. The Web service can also include the CARD-ACTION-STATUS header in the response. The value of this header will be displayed to the user in a reserved area of the card. If you deploy the Web service to https://api.contoso.com and you click on the Approve button, you’ll get the notification that the operation was completed successfully, as shown in Figure 6.
You now have the Actionable Message working end to end. You can send out the Actionable Message and when the user clicks on the Approve button, an HTTP POST request is made to your Web service. Your Web service will process the request and return 200 OK. Outlook will then mark the action as done. Next, I’ll look at how you can secure your Web service.
"sections": [{
"text": "Please review the expense report below.", "facts": [{
"name": "ID",
"value": "98432019" }, {
"name": "Amount",
"value": "83.27 USD" }, {
"name": "Submitter",
"value": "Jonathan Kiev" }, {
"name": "Description",
"value": "Dinner with client" }]
}],
Figure 4 ActionCard Action
"potentialAction": [{ "@type": "HttpPost", ...
}, {
"@type": "ActionCard", "name": "Reject", "inputs": [{
"@type": "TextInput",
"id": "comment",
"isMultiline": true,
"title": "Explain why the expense report is rejected"
}], "actions": [{
"@type": "HttpPOST",
"name": "Reject",
"target": "https://api.contoso.com/expense/reject",
"body": "{ \\\\"id\\\\": \\\\"98432019\\\\", \\\\"comment\\\\": \\\\"{{rejectComment.value}}\\\\" }"
}] },{
"@type": "OpenUri",
... }]
38 msdn magazine
Microsoft Office