A Flow Custom Connector to read O365 Communications API


A while back I wrote a blog post walking through how one could use Azure Functions, The Office365 Communications API and Microsoft Planner to help with change management in Office 365.  The post was pretty popular – over 10k visits – which is good for my blog – but the consensus was that it was to hard to implement.  Not everyone wants to get deep and dirty with Azure functions (even if I did just use the PowerShell variety!).  The right answer for this problem should always have been Flow and I’m still surprised that we haven’t got an out of the box connector.  I (finally) found a little time – so had a go at creating a custom connector for Flow that would read all of the Messages, both Message Center and Incident – and then you could do with them what you wanted!

Stepping back – the following shows the result of my previous endeavors – and I won’t quite be getting that far with this blog post – and I’ll point out the areas that would still need to be addressed.

Screen shot of a Planner plan with O365 Message Center content

The first step is to create our connector – and as this is going to read the Message Center – you need to be an admin – and you will also need to create an App Registration for the connector – so that needs you to be an admin too (or to know one who will work with you to make this happen!).

App Registration

In Azure Active Directory admin center choose App registrations (or the Preview, which I will be using) and click New registration.  You can call it what you like – mine is O365MC – I just want this for my Contoso users and it is a Web app – leave the redirect blank and click Register.

AAD Register an application page - with name set, restricted to Contoso and a Web app

The next stage is permissions – so I click View API Permissions (I’m hiding my Application (client) ID and Directory (tenant) ID – you will need to use your own.

image

Next click on Add a permission – then select Office 365 Management APIs

Choosing to add permissions Choosing the right type of API

– and choose Delegated permission on the next pane – and I’m only interested in Service Health (which includes Message Center) so have selected just that one option and clicked Add permission.

Selecting permisisons

The final permission step is to Grant admin consent – so it should look like this:

Adding the right permissions for ServiceHealth read

Next we need a key for our application so that our connector can prove who it is.  Certificates and Keys can be found in the left navigation with your API registration selected. Clicking New client secret creates the key.  I chose 2 years for expiry.  Copy it from here as it won’t give you a second chance.

Adding a client secret We should be good to go now – so we can proceed with our connector.

Custom Connector

Go to https://flow,microsoft.com and then to Data in the left navigation and Custom Connectors.  Click Create custom connector to get started.  I’m creating from Blank – if you know what Postman and OpenAPI are then feel free to take another approach.  I used Postman and there are some good explanation articles around but none specific to these APIs.  Give your connector a name – mine is O365 Message Center Connector and then click continue.  The 1st page of 4 then appears – General information

image

The important pieces here are the Host - manage.office.com and the Base URL - /api/v1.0/contoso.com/ServiceComms/Messages.  Feel free to add an icon, colour and description – then click forward to Security, and select OAuth 2.0 from the initial option – then Azure Active Directory from the drop down at the top of the OAuth 2.0 form.

image

I’ve filled in the Resource URL – https://manage.office.com, and the other fields can be set with the data from your App registration.

Client ID is the Application (Client) ID.   Client secret is the key you generated.  The rest leave as is, and advance to Definition.  For now we will just enter the General information and the Request, by selecting import from sample and then just selecting GET and entering a URL.

image

The full URL is of the form - https://manage.office.com/api/v1.0/<your domain here>/ServiceComms/Messages/api/v1.0/<your tenant name here>.onmicrosoft.com/ServiceComms/Messages

The request is easiest defined by using the json of a returned request as a sample – and if you scroll to the end I have added a sample json you could use.  Just clich add default response – paste in the json and click import.

Importing response json

To see what this did – you can click the ‘default’ button and it will show what it stripped out of the response.  This was a Message Center Response but this could also be used for Incidents.  There are things you can do on this page like hide some of these – or make them ‘important’ (they show up first) – but just for playing around you can leave it at that point.

Response selections

We are nearly there – but we also need to enter the Reply URl back in our App permissions – this was added as the Redirect URL on the 2. Security page once we saved that page.  Click the page icon to the right of the URL to copy.

Getting redirect URL for App reply URL

Once you have it – back to your App Registration and add a redirect Url – then save

Redirect URL setting

OK, now for the exciting part – Create and Test!  Back to your CustomConnector and click Create connector up at the top right and then click Test – the 4th stage.  We first need to add a connection – so click the + New connection

Adding Connection

This will prompt you to log in – then you have a new active option – Test operation – so go ahead and click it and see what happens?  Hopefully OK (200)

Response showing things worked

So that is working!  Next we can try it in a Flow, and I’m keeping it simple with a schedule to start things off – and run once a day – then this schedule triggers my next thing – which is my custom connector (find it under custom).  I then have an Apply to each – automatic as it detects there will be multiple ‘values’ (Items).  To keep things simple I’m just interested in Project Online items – so I filter Title for ‘Project’ – and then I create a new task in an existing Plan – and add the ID to the Title – then update the Task Details with the actual message.  I added the dates for good measure.  I wasn't intending this as a Flow tutorial – but hopefully you can follow from this screenshot.

Screenshot of Flow

After this Flow runs I have two new Tasks – and Task details too!

Plan with MessagesTask details with message center message

To get the same features as my Azure Functions example you’d have to have a much more complex Flow – updating Tasks that already exist – copying in the External Links too – but making sure they were not NULL (@empty is your friend) – as well as adding different assignees based on the Task Title and putting in a differen tbucket.  All perfectly possible – but beyond the scope of this posting which was really about getting connected to the Message Center.  Enjoy!

And this is the json to copy in for the response sample.

{

"@odata.context": "https://office365servicecomms-prod.cloudapp.net/api/v1.0/d740ddf6-53e6-4eb1-907e-34facc13f08b/$metadata#Messages",

"value": [

{

"@odata.type": "#Microsoft.Office365ServiceComms.ExposedContracts.MessageCenterMessage",

"AffectedWorkloadDisplayNames": [

"SharePoint Online"

],

"AffectedWorkloadNames": [

"SharePoint"

],

"Status": "",

"Workload": null,

"WorkloadDisplayName": null,

"ActionType": "Action",

"AffectedTenantCount": 0,

"AffectedUserCount": null,

"Classification": "Advisory",

"EndTime": "2018-10-30T23:59:00Z",

"Feature": null,

"FeatureDisplayName": null,

"Id": "MC120728",

"ImpactDescription": null,

"LastUpdatedTime": "2017-09-25T16:15:21Z",

"MessageType": "MessageCenter",

"Messages": [

{

"MessageText": "Beginning September 30, 2018, Visio Web Access (Visio Service) and its Web Part for SharePoint Online will no longer be available. Instead of Visio Web Access you will be able to use Visio Online and to migrate your organization’s web parts to a newer experience with the new Javascript (JS) APIs for Visio Online. Visio Online enables high fidelity viewing, sharing, and collaboration in your favorite browser, without installing the client for all Office 365 licenses. It supports embedding Visio diagrams in SharePoint Online using a modern file viewer web part and with IFrame along with JS API programmability.  \n \n[How does this affect me?]  \nBeginning September 30, 2018, users in your organization will only be able to view Visio diagrams in their browser, but not create or edit. Visio Online viewing is available to most Office 365 subscriptions. \n\n[What do I need to do to prepare for this change?]  \nInstead of using Visio Web Access (Visio Service) and its Web Part for SharePoint Online, we recommend using either: \n- Visio Online and the Document Web Part [Document Web part instead of Visio Web part] \n- iFrame in SharePoint Online for Visio Web Part [iFrame with Visio Online APIs instead of Visio Web Part with Visio Services JS APIs] \n \nPlease click Additional Information to learn more.",

"PublishedTime": "2017-09-25T16:15:21Z"

}

],

"PostIncidentDocumentUrl": null,

"Severity": "High",

"StartTime": "2017-09-25T16:15:21Z",

"Title": "We're removing Visio Web Access from SharePoint Online",

"ActionRequiredByDate": "2018-09-30T23:59:00Z",

"AnnouncementId": 0,

"Category": "Plan For Change",

"ExternalLink": "https://go.microsoft.com/fwlink/?linkid=858892",

"IsDismissed": false,

"IsRead": false,

"IsMajorChange": false,

"PreviewDuration": 30,

"AppliesTo": "",

"MilestoneDate": "2017-09-25T16:06:43Z",

"Milestone": "",

"BlogLink": "",

"HelpLink": "",

"FlightName": "",

"FeatureName": ""

}

]

}

Comments (0)

Skip to main content