1. SharePoint Saturday Genève 2016

2. Developing Office 365 Connectors
SharePoint Saturday Genève – 3 Décembre 2016
Developing Office 365 Connectors
Paolo Pialorsi
Senior Consultant, PiaSys.com

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

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

5. 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

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

7. Introducing Office 365 Connectors

8. 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

9. 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!

10. Office 365 Groups and Office 365 Connectors
Demo
Office 365 Groups and Office 365 Connectors

11. Office 365 Connectors Architecture2
HTTP GET
Provider Hosted App 3
HTTP GET
Office 365 Group 1
HTTP POST
(JSON Card)

12. Creating Custom Office 365 Connectors

13. 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

14. 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 ..." }

15. Build your own «real» Connectors
Go to the Connectors Developer Dashboard
Register you connector
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
Publish the connector to the Store (Connectors Catalog), if needed

16. 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

17. 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

18. 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 …

19. 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

20. Building a real Office 365 Connector
Demo
Building a real Office 365 Connector

21. 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.

22. 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

23. Connector Cards Flavors

24. Understanding Connector Cards
They are JSON objects
The text messages are based on Markdown (MD) syntax
The JSON structure can be slightly complex

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

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

27. Title and Text with links
JSON
{ "text": "SharePoint rocks! See [here](
"title": "SharePoint PnP", }

28. Title, Text with links, and Action button
JSON {
"text": "SharePoint PnP rocks! See [here](
"title": "SharePoint PnP",
"potentialAction": [
"
"ViewAction",
"name": "Go to SharePoint PnP",
"target": [" } ]

29. Title, Text, Action button, and theme Color
JSON {
"text": "SharePoint PnP rocks! See [here](
"title": "SharePoint PnP", "themeColor": "FF1133",
"potentialAction": [
"
"ViewAction",
"name": "Go to SharePoint PnP",
"target": [" } ]

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

31. Thank you!