360Works Email for Sending with Office 365 and Outlook

[Satin Doll]

I am working with 360Works Email plugin, 5.05 Enterprise version and FileMaker 20 - or, at least, trying to. 😉

I have seen some samples with the approach:
set variable [ $result = 
   EmailRegister (bunch of stuff) and 
   ... and ... and 
   Email Disconnect
]
Examples: http://docs.360works.com/index.php/360Works_Email/Documentation#Function_Detail

I have also seen that many of the email functions are listed as script steps. I'm comfortable with functions and script steps, but am wondering: why we have both, if there are differences in their usage, if there are best practices to use one over the other, etc.

Instead of using a complicated multi-part function, I'm trying to set separate actions for each Email function. This is partly so I can follow and debug the process more closely, but also because, ultimately, I expect to break out certain portions of the plugin use to be included at different points in the users' experience - for instance, verify registsration at startup, but don't create or send an email until a special button is clicked.

Most of the commands/functions are pretty straightforward, and I'm comfortable with verifying the plugin early, and creating an email later. But I'm having some difficulty in-between - with getting the URL and actually connecting.

The plugin has been purchased specifically for users on Mac with Office365 and Outlook. When I first tried connecting through FileMaker's native options, I got prompted to have verification sent to a phone number that belongs to the client's IT guy. We tried a few things that didn't work. I asked if we needed to use OAuth, and he said "no." But now that I'm into the plugin, I'm reading that EmailOffice365Connect requires OAuth. 

Now that I'm playing with the plugin, I'm still getting prompts. I think I haven't received a solid token yet, so I'm kind of stuck. I want to be able to put it in a field (text, right?), be able to see it and call it as I would any other chunk of data. Is that possible?

I especially don't want the end-user to have to click past a browser to go back and click in FileMaker to make the magic happen. I was able to get to that point a couple of times, but it is not how I want this all to work.

Some of the documentation says it's OK to use blanks, that 360Works has their own authentication, and I think I saw that work at one point. But now I'm just getting that Microsoft web page that wants to send a text to their IT guy again. I really hate bothering him unless it's going to solve the problem once and for all. If I could just get it to work in the demo file, I'd be more confident I could get it to work in my production file.

Once I get a token, is it good just for me (my client FMP)? for the file (hosted by FM Server)? for all the FM files I use with my client app? or ... ?

I keep hearing the token only needs to be refreshed periodically. How do I prevent an end-user from having to go through the initial set-up at some point in the future? Specifically, for a 90-day token (seems that's common), and a once-a-year activity, how would that work?

I keep seeing references to the Microsoft Azure Developer Account. Is that something I should set up? WOuld it be for me or for the client or the project or ...? 

At this point, we expect to send one email (providing an account name and default, volatile, initial password with basic instructions for using WebDirect screens), one at a time, with a click of a button at the layout for the account holder - no builk mail, no multiple recipients, no attachments, no email reading. Just need to send a basic email.

Any and all help appreciated!

[360Works]

Hi Satin Doll,

I'll try to address each of your questions as best I can.

Firstly, the script step vs calculation function methods:

These are effectively equivalent to one another. Starting in FileMaker 16, plugin functions became registrable using script steps in addition to the previously supported calculation function method. It's personal preference which you'd prefer to use, it simply changes how you do error capturing slightly. One thing to note is that if you're running scripts on the server, you will want to invoke EmailRegister at the beginning of each script, since the server does not retain in-memory sessions between script calls.

Next, Office365 Integration

The plugin (and really Microsoft) requires that you use OAuth to authenticate the email APIs. A couple of years ago Microsoft sunsetted the traditional IMAP login methods in favor of OAuth 2.0. if there is multi-factor authentication set up on any account you want to use with the plugin, you'll have to complete the MFA challenges in order to authenticate that account. Each account you want to send/receive mail with must be authenticated separately. That being said, re-authentication is usually never necessary. So long as you use the token and update it in your database at least once every 90 days, the refresh token will remain valid, and you won't need to re-authenticate any of your accounts. 

Once you have a token, it can be used from any instance of the Email plugin, whether FileMaker Pro or FileMaker Server, just remember what I said earlier about calling EmailRegister at the beginning of your server-side scripts.

You may configure your own Azure Developer Account if you'd prefer to keep the OAuth application within your own organization. Most people choose to use our Developer Account, which is also just fine as long as the organization allows it, which most do.

 

If you'd like more hands-on support, send us an email at [email protected] and we'd be happy to help you out! We also offer integration services so you can sit back and let us do all the heavy lifting!

 

Hopefully I've answered all your questions, please reach back out here or at our support inbox if you have any followup questions!

[Matt360Works]

Hello Satin, I am a developer at 360Works and can answer your questions.

Quote

but am wondering: why we have both, if there are differences in their usage, if there are best practices to use one over the other, etc.

We separate functions and script steps because in some cases you would like to store the results of the step, for this you can run it as a function. I typically encourage his approach as all of our script steps will return "ERROR" if there was an issue. While there is a method to handle errors with script steps doing so as a calculation is easier. We have documentation on handling this situation here.

You can also chain calls to the plugin, for example you can create an email, add a body, attach a file, and send it all within a single SetVariable call.

There are also some script steps that do not support all the same parameters, beyond that it comes down to personal preference. 
 

Quote

 I want to be able to put it in a field (text, right?), be able to see it and call it as I would any other chunk of data. Is that possible?

Yes, you are correct, and this is possible. Office365 does require OAuth, and a typical workflow would look something like this

1. Call to get the login Url and pass in the current token store, or and empty string
2. If the url is returned prompt the user to login by opening a browser with the URL, if not continue (check for ERROR as well)
3. Call EmailOffice365ConnectSMTP (or IMAP), make sure to save the response as this will contain the token if connected successfully
4. Check the response for a token or for an ERROR
5. If no error Store the token into a field and continue to email creation

This token is typically good for 90 days and will refresh without the need to login if used during this time, meaning that the user will not need to login in the majority of use cases, and the token should last virtually indefinitely. If you expect that 90 days may elapse without the token being used you can configure a scheduled script to connect and refresh the token, though that may not be considered the most secure option as it will prevent unused tokens from ever expiring. 

This token will work across devices so long as the user is logging in with the same Email. Many users will login on the client, save the token to a field, and then perform script on server to use the token in a headless environment. 

Keep in mind if there was a failed attempt and invalid text was saved to the token field you will need to manually clear this out, it can often be the cause of having trouble getting a valid token from the connect step.

We do have documentation on the steps here.

Now as for the 360Works Client and Secret this one is a bit tricky. In recent weeks Google has rolled back support for basic authentication and 3rd party app support for 'Unverified' apps. We have found that without a Client and Secret setup many implementations are failing. While I have not heard of Microsoft doing this I would encourage you to consider setting this up if possible, as it could prevent potential issues in the future if they follow suit. 
 

Quote

I keep seeing references to the Microsoft Azure Developer Account. Is that something I should set up?

For your use case this is likely not something you need to consider. The primary use would be if an organization wants the auth app to be within their organization. This is typically a security restriction or similar internal policy.

Please let me know if you have any other questions.
Matt
360Works Developer
 

[Satin Doll]

Matt et al - THANK YOU. I'm going to take a moment, digest your info, revise my process, and - no doubt - get back with more questions. Again, thanks!

[Satin Doll]

A bit of chicken and egg question here:

Matt wrote:

1. Call to get the login Url and pass in the current token store, or and empty string
2. If the url is returned prompt the user to login by opening a browser with the URL, if not continue (check for ERROR as well)
3. Call EmailOffice365ConnectSMTP (or IMAP), make sure to save the response as this will contain the token if connected successfully
4. Check the response for a token or for an ERROR
5. If no error Store the token into a field and continue to email creation

Note that at Step 3, I should "save the response as this will contain the token."

How does it RESPOND? Do you mean that I should capture the RESULT, the value of the variable (assuming I'm using the variables vs script steps method)?

But back to the farm: 

That function has parameters:
EmailOffice365ConnectSMTP ( username ; tokenStore { ; office365ClientId ; office365ClientSecret ; office365TenantId ; state } )

So "tokenStore" (I have to stop thinking of this as a purchase and start considering a STORED value) is EMPTY the very first time, but then uses that RESULT (per above) every time after?

Also, I'm not sure about state - I am setting $$state at the start of my script, and using it as a paramter for connect. Should I not RESET that variable each time the script is called? Should it only be once per session?

I just got off the phone with the client's IT guy. I ran my script and it got to the Microsoft message to send him a text message, which he got and gave me the code. Nothing was "responded" back. 

Curiously, after entering the code he gave me into my browser, MS came back and asked if I wanted to skip "(2 times left") or Next. I did Next. But there were just more prompts to set up stuff in MS and I don't see any reason I should be doing that. I thought maybe I'd try again, and click Skip instead, but couldn't.

I tried a couple more times, including after restarting FM, and I could see the MS prompt for only a split second, then I got the 360Works screen (Success, I can close the window), but I still couldn't do a connect, I get the 360Works Email Error dialog with "authentication failed."

This is similar - maybe the same - as what was going on previously: preliminary prompts to text him from MS, then 360Works stuff in the browser - with no final success. I thought maybe closing the file and re-opening it was what helped "clear out" the token as mentioned but, frankly, I don't see there was a token to be cleared and restarting did not help.

FM is so good in letting us send simple emails - IF you're using Apple Mail, especially. And, at least right now, that's all I'm looking for - no HTML, attachments, mailbox control, etc. - just with MSOffice365.

All help is appreciated!