SharePoint Saturday Genève 2016

Developing Office 365 Connectors SharePoint Saturday Genève – 3 Décembre 2016 Developing Office 365 Connectors Paolo Pialorsi Senior Consultant, PiaSys.com paolo@pialorsi.com - @PaoloPia

Evaluez les sessions grâce à l’application SPS Genève ! Cherchez « SPSGenève » sur le store Et gagnez des licences DL

SharePoint Saturday Genève 2016 Sponsorship Level: Raffle SharePoint Saturday Genève 2016

Paolo Pialorsi Project Manager, Consultant, Trainer About 50 Microsoft certification exams passed MCSM – Charter SharePoint MVP Office Servers and Services SharePoint and Office 365 Dev PnP Core Team Member Focused on SharePoint and Office 365 since the beginning Author of many books about XML, SOAP, .NET, LINQ, SharePoint, and Office 365 Speaker at main IT conferences

Agenda Introducing Office 365 Connectors (and Groups) Creating Custom Office 365 Connectors Connector Cards Flavors

Introducing Office 365 Connectors

Office 365 Groups in a nutshell Modern digital workplace for collaboration Available in Office 365 only Available in hybrid topologies (with some requirements) Provided services (so far…) Conversations (with mailbox) OneDrive for Business shared Folder Calendar Notebook (OneNote) Planner integration SharePoint Site Client-side integration with Outlook 2016 and OD4B NGSC Mobile-aware client apps for iOS, Android, Windows Phone

Office 365 Connectors Extensions to update teams using Groups with information and updates from external products Enable delivery of relevant content and events Uses the webhooks technology Based on JSON messages delivered through HTTPS requests Content and events are delivered as «cards» There are about 100 connectors ready to use in the Connectors Catalog Trello, Asana, Twitter, Wunderlist, GitHub, JIRA, etc. Few months ago were just about 50 … numbers are growing really fast!

Office 365 Groups and Office 365 Connectors Demo Office 365 Groups and Office 365 Connectors

Office 365 Connectors Architecture 2 HTTP GET Provider Hosted App 3 HTTP GET Office 365 Group 1 HTTP POST (JSON Card)

Creating Custom Office 365 Connectors

Take it easy  … Use the pre-defined «Incoming Webhook» connector Register your webhook (name, image) Save the webhook URL and use it directly Using Fiddler or any other HTTP client Make HTTP POST requests against the webhook URL Content-type: application/json

Office 365 Connectors Take it easy Demo Office 365 Connectors Take it easy Content-type: application/json { "Title": "Hello SharePoint Days 2016!", "Text": "This is our first message from a webhook ..." }

Build your own «real» Connectors Go to the Connectors Developer Dashboard https://dev.outlook.com/Connectors/ConnectButton Register you connector http://go.microsoft.com/fwlink/?LinkID=780623 Landing page URL: «home page» for your connector Redirect URL: endpoint that handles connector’s webhook registration Get back the HTML for the «Connect to Office 365» button Play with the Connectors Sandbox to define your cards https://connectplayground.azurewebsites.net/ Publish the connector to the Store (Connectors Catalog), if needed https://dev.outlook.com/Connectors/ConnectButton

Connect to Office 365 «button» Asks to the end user to authorize your connector to communicate with the target Office 365 Group Redirects to the Redirect URL of the connector registration page Gets some querystring arguments Parameter Description state Optional parameter to provide custom state information to the Redirect URL app_id Identifier GUID for your application callback_url The Redirect URL, required to be under HTTPS, for the connector registration

Redirect URL You have to implement it by yourself Store the webhook URL in a safe and reliable place Handle any error code (AccessDenied, Invalid Request) Parameter Description state Optional parameter to provide custom state information group_name The name of the group selected by the user webhook_url The webhook URL to use for communicating with the target Office 365 Group error The error code that is returned if the application doesn't return successfully

POST Cards to the webhook Make HTTP POST requests against the webhook URL The body of the requests has to be a JSON message Content-type: application/json; There is a reference schema for the Cards See later …

HTTP Responses Response Code Description 200 OK – Everything worked properly and the card has been submitted to the target Group 400 Bad Request – The JSON card is not well-formed 404 Not Found – A request is sent to a webhook that does not exist 413 Payload Too Large – A request is sent to a webhook that is too large in size for processing 429 Too Many Request – Client is sending too many requests and Office 365 is throttling requests

Building a real Office 365 Connector Demo Building a real Office 365 Connector https://dev.outlook.com/Connectors/ConnectButton https://connectplayground.azurewebsites.net/

Submission Checklist (just for reference) Ensure that your connector is fully functional & thoroughly tested before submitting it to the Store. Test your connector cards in various clients where your users would use it: Outlook on the Web, Outlook 2016 & Outlook Groups mobile apps. Ensure that you strictly use Markdown for text decoration and not send HTML in your connector card payload. Maintain a balance between adding value and generating too much noise. Ensure that the user is not bogged down with too many notifications. Identify the right events to send connector cards for. Ensure that the information you send to the group is valuable to the members of the group. When sending reports or summaries, use a digest format and allow the user to choose the time and frequency of the reports. When sending connector cards make the best use of Markdown to highlight important parts of the card. Make your connector cards actionable by providing relevant actions whenever possible. Ensure that you have provisions for the user to pause or remove the configuration. Have clear user-facing documentation on the capabilities your connector offers. When registering your connector: Ensure that the name and logo of your connector does not infringe upon a trademark or copyright of any other product or service. Provide a high quality logo of type jpg, jpeg, png or gif that is under 60KB in size. Provide a short description of your application (e.g. 'Contoso Helpdesk brings companies & customers together'). Provide a detailed description of your connector (e.g. 'The Contoso Helpdesk connector notifies your Office 365 group about activity on your customer's tickets'). The landing page for your users is the page where users would be directed to complete the connector configuration. Make sure that you deep link to the page where you have added the connect button. If this is not possible, point this to your documentation page that has detailed on how to setup your connector. When publishing your connector to Store: Make sure to fill out step by step instructions and share test account information to let us test your connector.

When to do what? Yes No Yes No Yes No Targeting JUST ONE Office 365 Group? Any plan to reuse the same Connector? Go for the Incoming Webhook solution Yes No Done! Yes No Go for the «Real» Connector Model Want to share the Connector with all the Office 365 World? Publish on the Office Store Connectors Catalog Yes No

Connector Cards Flavors

Understanding Connector Cards They are JSON objects The text messages are based on Markdown (MD) syntax The JSON structure can be slightly complex https://dev.outlook.com/connectors/reference

Hello World Card – Text only JSON { "text": "Hello World!" }

Title and Text JSON { "text": "Card content!", "title": " Card Title", }

Title and Text with links JSON { "text": "SharePoint rocks! See [here](http://aka.ms/sharepointpnp)!", "title": "SharePoint PnP", }

Title, Text with links, and Action button JSON { "text": "SharePoint PnP rocks! See [here](http://aka.ms/sharepointpnp)", "title": "SharePoint PnP", "potentialAction": [ "@context": "http://schema.org", "@type": "ViewAction", "name": "Go to SharePoint PnP", "target": ["http://aka.ms/sharepointpnp"] } ]

Title, Text, Action button, and theme Color JSON { "text": "SharePoint PnP rocks! See [here](http://aka.ms/sharepointpnp)", "title": "SharePoint PnP", "themeColor": "FF1133", "potentialAction": [ "@context": "http://schema.org", "@type": "ViewAction", "name": "Go to SharePoint PnP", "target": ["http://aka.ms/sharepointpnp"] } ]

Cards Reference Some other useful properties/items: summary: simple text (no Markdown) Sections: title, activity*, facts, images, potentialAction, etc. entities potentialAction

Thank you!