Graph API Outlook - Inconsistencies in SendMail-function

[til.minet]

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

[ewilson]

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

[ewilson]

@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
------------------------------

[til.minet]

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

[ewilson]

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

[SheabinGeorge]

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

[ewilson]

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

[SheabinGeorge]

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

[ewilson]

@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
------------------------------

[SheabinGeorge]

@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
------------------------------