topic RE: Graph API Outlook - Inconsistencies in SendMail-function in Digital Exchange

Graph API Outlook - Inconsistencies in SendMail-function

til.minet — Thu, 22 Jul 2021 15:28:00 GMT

Hello community,

We recently established our app registration and are getting ready to use the Graph API objects from the DX. I started to experiment with the Graph API Outlook VBO and found the following issues. I am a little worried that I just scratched the surface.

There are three different requests that allow me to send or prepare e-mail-messages. "Send Mail", "Create Message" and "Create Message in Folder".

I suppose "Send Mail" would be one of the actions most commonly used. The input parameters allow me to define a body content - but I cannot choose if I want to send the body as text or HTML. The parameter has no description and I can only find out what content is expected by looking in the Web API definition. If I want to send an e-mail in HTML, which we mostly did with the Outlook VBO. Even worse: There is a parameter "saveToSentItems" in the request body which is also hard-coded. The description of the Send Mail-action tells me that the message is saved in "Sent Items" by default. Too bad that this parameter is hard-coded as "false" in the request body.

To my understanding it should be possible to choose the content type as an input parameter. Same for saveToSentItems.

Next action is "Create Message". Same story, but the content type is hard coded as "HTML". No description about that either.

And, to sum this up, "Create Message in Folder". From my understanding this should at least behave the same way as "Create Message", but see for yourself - hard coded body content as text again.

Do I misunderstand something or is there still room for optimization in this API definition? With these mistakes in even the most basic actions I tend to get the feeling that it might be easier and less frustrating to create the whole definitions myself.

Does anybody have more experience with the other assets? Are the other ones more usable than this one?

Best regards
Til

------------------------------
Til Minet
RPA Developer
EWE AG Germany
Oldenburg
------------------------------

RE: Graph API Outlook - Inconsistencies in SendMail-function

ewilson — Thu, 22 Jul 2021 17:38:00 GMT

Hello @til.minet,

Thank you for the feedback regarding the Microsoft Graph for Outlook integration. From the looks of it, these template definitions were pulled directly from Microsoft's examples with some minor changes. Unfortunately, that flag wasn't changed. I've brought this up with the developer and we'll get them changed in the asset on the DX.

On the bright side, you can always change that integration in your own environment, or use it as the basis to create a new version of your own.

Cheers,

------------------------------
Eric Wilson
Director, Integrations and Enablement
Blue Prism Digital Exchange
------------------------------

RE: Graph API Outlook - Inconsistencies in SendMail-function

ewilson — Thu, 22 Jul 2021 18:11:00 GMT

@til.minet,

FYI - We just pushed a v2.1 to the Digital Exchange that has those entries converted to variables and a minor change to the Update Message action to remove the inference entry.

As I mentioned previously, you can always customize the body to suit your needs. Perhaps in the future we'll just set the template to a single input JSON blob that the user can specify. Then you're free to adjust as needed outside of the action definition.

Cheers,

------------------------------
Eric Wilson
Director, Integrations and Enablement
Blue Prism Digital Exchange
------------------------------

RE: Graph API Outlook - Inconsistencies in SendMail-function

til.minet — Wed, 28 Jul 2021 08:17:00 GMT

Hi @ewilson,

Thank you for that nearly instant reply and fix of the mentioned points!

I downloaded the latest version of the asset and played around with it a bit . Sadly I soon encountered more problems and decided to follow your recommendation to use the VBO as the basis to build my own definition. I am a bit disappointed to go that way because it keeps me locked out of receiving further updates of the asset in the DX, which somehow damages the sense of the DX for me. If new updates are released I could keep two copies of the API definition - one as the untouched original from the DX and one as my own fork. But even then, it is not possible in Blue Prism to copy single actions from one API definition to another one and I have to manually adapt everything. Might be easier to just keep my own fork and create new actions as needed.

So what are the new issues I encountered?

No attachments possible. The asset has no action to add attachments to a message. Adding attachments in the "Send Mail" action is not possible with a pre-defined body template. That part of the template must only be in the request body if I actually want to add an attachment. But it makes sense to add an action "Upload attachment to message ID" - in this case you can first create a message and add as many attachments as needed to the draft before sending. Attachments have the same 4 MB limitation as in sharepoint, so another bunch of actions is necessary to manage an upload sessions and upload a large file in increments.
No BCC recipients. In some circumstances we need to send mails with "To", "CC" and "BCC", so BCC is a necessary input for us.
Not more than one recipient for each of the three types possible. I think this is a major problem and results of having a fixed request template. The request template allows you to add one recipient, not more. It is impossible to seperate multiple recipients by semicolon or comma character. The whole part ("toRecipients": [{"emailAddress": {"address": "[Email Address]"}}) needs to be duplicated for each recipient.

I tried to build a solution to cope with the above mentioned problems. I edited the API definition to include actions for file upload and modified the action "Create message" to have just one input parameter "Request body". This input parameter receives the whole JSON string needed to create the message.

Creating the request body and, if needed, adding attachments is supposed to be easy for me and my fellow developers. So what I needed in the next step is a VBO that has an action "Send Mail" which combines some logic and several API calls. My VBO has a collection holding the structure needed for the request body to create the message without attachments. First I add all recipients as necessary, then create the message as draft. Afterwards attachments are added if needed, then the message gets sent. Only this way I can build a user-friendly solution which has the same functionality and usability as actions in the Outlook VBO.

Another flaw I encountered: Building up the collection and then converting to JSON with the VBO "Utility - JSON" will produce an invalid request body in many situations. When adding only one recipient for To, CC or BCC the VBO will create a JSON array out of that. Graph API does not accept that. Luckily I found an alternative JSON object somewhere in the forums ("toarnold - Utility - Json") which works. It has an input flag "ForceSingleRowAsObject" which produces a valid body.

To sum this up: The idea of creating Graph API definitions in the DX is great and gives me a good starting point, but without amendments and hours of additional work it does not work as an easy to use solution for me. And after the editing I am locked out of any updates of the asset.

Best regards
Til

------------------------------
Til Minet
RPA Developer
EWE AG Germany
Oldenburg
------------------------------

RE: Graph API Outlook - Inconsistencies in SendMail-function

ewilson — Wed, 28 Jul 2021 15:17:00 GMT

Hi @til.minet

Thanks again for the feedback. There's a lot in your post, so I'll attempt to address the various items you've touched on in order.

Web API Management
You are correct, there is no easy way to copy action definitions between different Web API definitions. I believe there's an Idea open for this sort of flexibility on the core product Ideas page, but it would likely require a significant overhaul of the current Web API user interface. With that said, it is possible to copy functionality between different Web APIs in a round-about way. Basically you have to export the two Web APIs as .bprelease's. Then you can perform the changes in the actual XML. It's not ideal, but it does work.

Digital Exchange
Regarding your comment about damaging your sense of the DX, I think you're overlooking something important here. The Digital Exchange is not just a place to go and grab static, canned integrations. We want it to be a community of Blue Prism developers. What I mean by that is we want/need your input. If there are enhancements to an asset that you've made in your environment or that you just think make sense there's an Ideas page that you can find here. I'd encourage you to submit ideas for any enhancements. If you've already built changes into a fork of an asset in your environment, you can attach that asset to your idea. After that, we can take it through our review process and, assuming no issues, post it as an update to the asset page (giving you full credit).

Alternatively, you can submit your own asset to the DX. We have partners and community developers that take core Blue Prism assets, extend/improve them, and then post submit them to the DX. As you may have noticed the vast majority of Blue Prism assets on the DX are released under the MIT license which allows anyone to create derivative work without needing approval from Blue Prism.

Graph API for Outlook
As you've pointed out, the Graph integration for Outlook is not perfect. We have discussed making the input for many of the actions a simple Text input value that you can use to pass in your own generated JSON body. That's actually what we've done with other Graph integrations. Our intent with the Outlook integration was to try and make it as accessible to non-developers as possible. In doing so, we've limited the power users like yourself. I think the ideal solution is to change from a Template body to a Custom Code body where we generate the body based on input. And then we can expose various input data items. That would be easier for non-developers while giving power users more flexibility. However, given the vast number of configurable options Microsoft makes available for the various endpoints this would be no small undertaking, so in the interim we will probably change some of those actions to accept just the JSON blob.

Utility - JSON and Outlook Fields To, CC, and BCC
You mentioned that the Graph utility does not accept a JSON array as the values for To, CC, or BCC. To clarify, Graph does accept a JSON array as input, just not the JSON array format that's output by the Utility - JSON VBO. Microsoft's own examples show the input for toRecipients as an array of emailAddress entries. Unfortunately, the way the JSON utility currently functions, it wraps any Collection in a top-level array, and it looks like embedded Collections (if you want to added additional addresses) also in an array. So we'll take a look at what we can do to address that.

I hope these responses help in some way.

Cheers,

------------------------------
Eric Wilson
Director, Integrations and Enablement
Blue Prism Digital Exchange
------------------------------

RE: Graph API Outlook - Inconsistencies in SendMail-function

SheabinGeorge — Mon, 31 Jan 2022 19:22:00 GMT

Hello,

I am facing a similar issue when trying to send to multiple recipients.

Has there been any progress or any workarounds on using the Graph API to send to multiple addresses?

Thanks,
Sheabin

------------------------------
Sheabin George
------------------------------

RE: Graph API Outlook - Inconsistencies in SendMail-function

ewilson — Mon, 31 Jan 2022 20:12:00 GMT

Hello @Sheabin George,

The Microsoft Graph - Outlook integration has not been updated since this past November. Unfortunately, the limitation regarding sending to multiple recipients has not been addressed yet, but it is on our list. In the meantime, you can address this in your local copy in various ways. The easiest/quickest would be to define extra input parameters if you know that you'll always be addressing emails to X destination addresses, and then adjust the JSON template to include those extra To addresses.

If the number of destination addresses is dynamic (i.e. changes from one message to the next) then you'd really want to pass in a Collection of those addresses. For that, you would need to switch from using a JSON template for the body to using Custom Code to generate the JSON body based on the input.

Does that make sense?

Cheers,

------------------------------
Eric Wilson
Director, Integrations and Enablement
Blue Prism Digital Exchange
------------------------------

RE: Graph API Outlook - Inconsistencies in SendMail-function

SheabinGeorge — Wed, 02 Feb 2022 20:31:00 GMT

Thanks Eric for the clarification.

It makes sense however, do you have any example of a dynamic custom code that changes based on the collection? Thank you.

Thanks in advance,
Sheabin

------------------------------
Sheabin George
------------------------------

RE: Graph API Outlook - Inconsistencies in SendMail-function

ewilson — Wed, 02 Feb 2022 23:57:00 GMT

@Sheabin George,

We've spent some time this week to update the Send Mail action. There is now a version 2.3.0 of the connector available on the Digital Exchange. You can find it here.

The revised action supports passing in Collections for TO, CC, and BCC addresses. We've also added support for passing in a Collection of file attachments for the email. The user guide has been updated to include information about the new parameters, including the expected layout of the new Collections.

Cheers,

------------------------------
Eric Wilson
Director, Integrations and Enablement
Blue Prism Digital Exchange
------------------------------

RE: Graph API Outlook - Inconsistencies in SendMail-function

SheabinGeorge — Thu, 03 Feb 2022 17:58:00 GMT

@ewilson

Thank you Eric and team for the quick turnaround on this fix and implementation.
I was able to test the collections of the addresses and file attachments.

However, upon testing an email without any file attachments threw the following exception:
Internal : Unexpected error Cannot execute action "Send Mail" due to an error when running custom code: Unable to cast object of type 'System.DBNull' to type 'System.Byte[]'.

Any suggestions on this?

Thanks,
Sheabin

------------------------------
Sheabin George
------------------------------

RE: Graph API Outlook - Inconsistencies in SendMail-function

ewilson — Thu, 03 Feb 2022 18:11:00 GMT

@Sheabin George,

Are you passing an empty Collection into the Attachment input or leaving the value blank? I just tested the solution with no attachments (as pictured) and it worked fine.

Cheers,

------------------------------
Eric Wilson
Director, Integrations and Enablement
Blue Prism Digital Exchange
------------------------------

RE: Graph API Outlook - Inconsistencies in SendMail-function

SheabinGeorge — Thu, 03 Feb 2022 18:19:00 GMT

@ewilson

Correct, deleting the data input on the Send Mail action works however, we are trying is a templatized process for emails depending the automation process.
This field will need to be a dynamic.

So when I passed it with the collection values as blank, it throws the exception.
Will a modification need to happen to the Common Code under the API? Or under SendMail Request custom code?

Thanks,

------------------------------
Sheabin George
------------------------------

RE: Graph API Outlook - Inconsistencies in SendMail-function

ewilson — Thu, 03 Feb 2022 18:41:00 GMT

@Sheabin George,

Replace the code in the Body Content portion of the Send Mail -> Request section with the following code:

// Create a new SendMailRequest instance and set the properties using our input values.
// NOTE: Empty collections (ex. BCC Addresses) will not be included in the serialized JSON.
SendMailRequest req = new SendMailRequest();
req.Message = new Message();
req.Message.Subject = Email_Subject;
req.Message.Body = new Body
			{
			  ContentType = Email_Body_Content_Type,
			  Content = Email_Body_Content
			};
req.Message.ToRecipients = ConvertAddressCollectionToList(To_Addresses);
req.Message.CcRecipients = ConvertAddressCollectionToList(CC_Addresses);
req.Message.BccRecipients = ConvertAddressCollectionToList(BCC_Addresses);

if ((File_Attachments != null) && (File_Attachments.Rows.Count > 0))
  req.Message.Attachments = AttachFiles(File_Attachments);
else
  req.Message.Attachments = null;
	
req.SaveToSentItems = Save_to_Sent_Items_Folder.ToString().ToLower();

// Set Request_Content to the serialized object instance.
Request_Content = JsonConvert.SerializeObject(req, Formatting.Indented, new JsonSerializerSettings { NullValueHandling = NullValueHandling.Ignore });

Cheers,

------------------------------
Eric Wilson
Director, Integrations and Enablement
Blue Prism Digital Exchange
------------------------------

RE: Graph API Outlook - Inconsistencies in SendMail-function

ewilson — Thu, 03 Feb 2022 18:48:00 GMT

@Sheabin George,

Looking into this a bit further, the original code works fine even with an empty Collection (no rows). Does your Collection have a row with no data in the actual fields? Can you post a picture of the actual Collection definition and the Initial Values tab?

Cheers,

------------------------------
Eric Wilson
Director, Integrations and Enablement
Blue Prism Digital Exchange
------------------------------

RE: Graph API Outlook - Inconsistencies in SendMail-function

SheabinGeorge — Thu, 03 Feb 2022 20:34:00 GMT

@ewilson,

I tried the code above and ran into the same issue.

Here are the screen shots you requested:

Thanks,

------------------------------
Sheabin George
------------------------------

RE: Graph API Outlook - Inconsistencies in SendMail-function

ewilson — Thu, 03 Feb 2022 21:26:00 GMT

@Sheabin George,

Is there a reason you have an empty row in the attachments collection? If not, remove it and both sets of code will work as expected.

Cheers,

------------------------------
Eric Wilson
Director, Integrations and Enablement
Blue Prism Digital Exchange
------------------------------

RE: Graph API Outlook - Inconsistencies in SendMail-function

ElliotBarling — Wed, 27 Apr 2022 10:01:00 GMT

Hi @ewilson

Late to the party here but I am trying to get the Graph API set up in the dev environment and could comply just use some help with how the Send Mail function works. A previous team set up the API infrastructure and as it stands I have the following inputs for the send mail function:

The body of the Send Mail Request simply states [Message JSON]
I have been told I need to generate the JSON using the JSON collection action but I don't even know what to include in the collection!

Thanks in advance

------------------------------
Elliot Barling
------------------------------

RE: Graph API Outlook - Inconsistencies in SendMail-function

ewilson — Wed, 27 Apr 2022 10:52:00 GMT

Hi @Elliot Barling,

It looks like you're trying to use the Microsoft Graph - Users asset. If you need to send email I'd suggest you switch to using the Microsoft Graph - Outlook asset instead. While the Users object will work it is less refined than the Outlook object.

To answer your specific question, any time you see a reference to entering a JSON object/blob the expectation is that you'll look at the specific API reference. In this case that means the Microsoft Graph v1 API Reference. You can find details of the Message object at the following link:

https://docs.microsoft.com/en-us/graph/api/resources/message?view=graph-rest-1.0

Scroll to the bottom of the page and you'll find the an example of the overall JSON definition. An important thing to remember is that not all of what's shown in required. This is another reason why using the Microsoft Graph - Outlook object is a better choice.

Cheers,

------------------------------
Eric Wilson
Director, Integrations and Enablement
Blue Prism Digital Exchange
------------------------------

RE: Graph API Outlook - Inconsistencies in SendMail-function

ElliotBarling — Wed, 27 Apr 2022 11:04:00 GMT

Thanks @ewilson

How would I get hold of the Microsoft Graph - Outlook asset?
Apologies, absolute novice with this Graph stuff!

Thanks
Elliot

------------------------------
Elliot Barling
------------------------------

RE: Graph API Outlook - Inconsistencies in SendMail-function

ewilson — Wed, 27 Apr 2022 11:13:00 GMT

@Elliot Barling,

Always check the Digital Exchange first for any assets. If you're not familiar with the DX, it's our online marketplace. Pretty much everything Blue Prism puts out (software and connector-wise) can be found on the DX.

https://digitalexchange.blueprism.com/dx/entry/3439/solution/microsoft-graph-api---outlook

Cheers,

------------------------------
Eric Wilson
Director, Integrations and Enablement
Blue Prism Digital Exchange
------------------------------