Microsoft 365 Community Community Demos, 14 Jul 2021

Previous Meeting Next Meeting

⏯

youtube image

►

From YouTube: Using message recipients changed event in Outlook

Description

In this 12-minute developer-focused demo, Elizabeth Samuel showcases an Outlook event-based activation capability in preview to tag external recipients. If external recipients are on an e-mail, then the message is automatically tagged as [External] and appends disclaimer. Presently available for web and Windows desktop. Features include Event-based activation – OnMessageRecipientsChanged event (preview), SessionData property bag (preview) and AppendOnSend (v1.9). The event activates whenever recipients are changed during message compose. This PnP Community demo is taken from the Office Add-ins community call – July 2021, recorded on July 14, 2021.

Demo Presenter: Elizabeth Samuel – Senior Dev Writer (Microsoft)

Supporting documents:
• Sample - Use Outlook event-based activation to tag external recipients (preview) | https://github.com/OfficeDev/PnP-OfficeAddins/tree/main/Samples/outlook-tag-external

Stay connected:
• Twitter https://twitter.com/microsoft365dev
• YouTube https://aka.ms/M365DevYouTube
• Blog https://aka.ms/m365pnp/community/blog

A

Hello today I'll be walking you through a pnp. We recently added on the message: recipients, change events and outlook. This pmp is meant to showcase the event case activation feature, particularly the on message: recipient change event. That's now in preview, the feature itself event-based activation is available in requirements at 1.10, but this particular agent is in preview.

A

The pmp also uses session data property bag apis still in preview, and the append on send async apis as well released in 1.9 the event activates. Whenever recipients are changing messaging posts, including replies and forwards, it's only available in outlook on web browser and windows. For now what the sample does is we tag external recipients in the sense that, if you add recipients that are external to your organization, we add the term external and square brackets to the subject and on send there will be a disclaimer saying: hey this email has external recipients.

A

So I'm going to share my screen, so you can see outlook okay, so let's install the manifest, so I'm installing a manifest directly from the pnp repo here on the url. You can also download the manifest and install it on the file.

A

Okay, so now, let's do a new.

A

A

So we have our external tag and, let's add some text.

A

Let's remove this see that the external tag wants to.

A

Be there's also a log that you can look at just bring that over here. So we have a whole bunch of debugging debugging logs that are included, so you can tell what's going on throughout right. This was when we removed it.

A

We added back it's an external user, abc control. It said the disclaimer set the subject.

A

You can also do this in outlook on the web, so I have this up.

A

A

And then we see that we have our tag in the subject and we have what this came up. That was appended okay. So now, let's try this in on the browser. Okay,.

A

So I'll do any message.

A

It'll come up momentarily.

A

A

A

Right so we have.

A

All right here we go okay, showing us an external use, though. Let's do.

A

A

And it will do the exact same thing as the other one. So let's send.

A

A

Okay, so this was the one we sent previously, and this is the one we just sent here all right awesome so for the pnp repo. This is where the sample lives in outlook tag external and we have.

A

The readme here includes a lot of stuff. We talked about some more details so instead of working through that I'll go to the code.

A

I have open and visual studio code.

A

So the manix test in the manifest in order to use the event-based activation feature on this particular event on message: recipients changed.

A

You need to define here the launch event, the runtime, so the key pieces here for this feature are inversion.

A

A

Okay solution overrides 1.1: you need to define runtimes so in run times runtime. This one is used by outlook on the web and this one the override, is used by windows directly.

A

So those two values- webview runtime, url and gs- runtime url- are defined lower down in the resources section, so in desktop form factor. You need to declare um your extension pointers launch event and have this event, which is the one we're working with on message. Recipients changed, and this is the function name that will be associated with this event in your javascript file.

A

So, as you see here, we have our webview runtime url and our gs runtime url, which are the html file and the js file respectively, because we're using append on send. You also need to declare the appendage and extend extended permission. Excuse me right so the html in html we pretty much need to use the beta version of office. Js and, of course, declare commands here.

A

Here is the association you need to make. This should be the name of the file, the name of the function you have in the manifest file, which is that you're associating with- and this is the name of the function, the actual name of the function in here. So to some extent you could actually mean that something completely different, and that would be fine too.

A

Okay, so I'll walk you through this now.

A

This is the handler with the same name, tag external on message, recipients, change, handler funding and basically the event that comes back. It contains these at least these three fields, so there's a property called change, recipients field and there's a one for the two, the c the bcc and what we do is for like say the two field.

A

We actually, then call get async on the to field if the two feel changed um and use that information to determine if there are any external recipients and based on that, so for the purpose of this pnp, we're only checking for if external user is the type of recipient any of them, then we set the session data to if it's external or not, we set it to true or false or two fields.

A

So in this case we're saying the external two is true: if there is like, in our case with k or abc at contoso, that we did have external users, and so it will get tagged as true, but if we didn't like when it was empty, then for the sake was false, so we do a similar um function for cc and the bcc fields in the set session data, as we discussed you set whatever the key is so tag external 2, bcc cc and depending on on that, we actually just go ahead.

A

So if it's true, you say: okay, we know it's true, let's go ahead and tag it as external, so that will go ahead and do things like you know, updating the subject and setting dependence and they sync with the disclaimer.

A

If, however, it was false so that particular field that change didn't say anything about didn't, have any external um recipients, then we call check for external to see if anything else in the property bag already says that I have external things. So, for example, if we added in the to field that we have abc at contoso, but in the cc field we actually added someone within the organization, then in adding that one, it will say. Oh I have no externals.

A

So now we go check the property bag and we see that the two fields did have externals, but the recipients can change them too, and so that way we will keep the external tag and not remove it unnecessarily.

A

Right so then we go into tag external, which does the tagging of the subject, if need be, set append on send async with the disclaimer that we declared, and then that will happen here.

A

But if there were no external recipients, they were all internal or there are no recipients in the email.

A

Instead remove external tag from the subject. If it's there.

A

And we clear the disclaimer by calling append on send async with null value and that's basically the pmp. So if you have give it a try, please do give it a try and if you have any comments or questions or any kind of feedback about it. Let us know. Thank you very much for your attention.

A