Inbound Email Integration (GIG part 3)

Well, so far on our Getting Integrated Guide adventure, we've touched on different ways to get events in and then part 2 was about building an actual plan and sending events via a form in the UI. But often there will be a need to have external systems kick off the event workflow. One of the simplest ways to get events into xMatters On Demand is using Email. Email is ubiquitous and everyone knows how to use it and building integrations with it is easy as pie..... or muffins in this case. 

We'll dredge up our Muffins Communication Plan from The GIG part 2 (and from our foray into SOAP UI) and set it up to accept events from email. So, roll up your sleeves and let's get started. 

Login to your favorite xMatters On Demand environment, and navigate over to the Developer tab and select the Bakery Customers plan (cruise over to the GIG part 2 if you need to download this one). In the drop down next to the Form name, there is an item for "Set Up Email Initiation":

 


Clicking this item displays a dialog with drop downs for mapping the incoming email fields to properties on the form as well as displaying the target email address. 


Let's have the Subject contain the Flavor and the Body (Text) contain the Baker's Notes. We are going to use the "Body (Text)" map because otherwise the raw HTML will show up in our outbound email. Like so: 


Before clicking Save Changes, make note of the email address. It will be composed of several parts that help route the email to this form. The first part is the recipient. In this example case it is "tdepuy" (my logged in user), followed by the characteristic @ sign, followed by the form name (spaces removed) followed by the company and deployment name. I have mine blacked out so y'all can't spam me, but an example might be: 

user@muffinsready.acme.na1.xmatters.com

In the Set Up Email Initiation dialog, you can change how the form name is used if that makes things clearer. Click Save Changes and we're ready to test!


Crack open that old email client, put in a Flavor in the subject and some notes from the baker in the body. I have removed my email signature to help keep things cleaner. 


  

Hit send on the email and head back to your xMod instance and check out the Reports tab. There should be a new event, and if you hover over the right side of the row, you will be able to view the message:

 Success! 

 

So, you probably don't want to target this "tdepuy" guy or whoever your logged in user is.... but what if I told you that you could change the "to" part of the email to be any Group or User in xMatters! Woah! 

So, crack open your favorite email client again and craft another email, but this time let's target the "VIP Customers" group. Note that the group name has a space, so we'll have to enclose it in "s, like so:

email.png


Er, note that Outlook won't send this, but gmail had no problems and Mac people should be fine. If actual people using Outlook are initiating your events and have a good chance of using Outlook, then you might add the "VIP Customers" to a group called "VIPCustomers" with no escalation delay. This will serve as a wrapper or alias and will be seamless to the end users. On the other hand, given all these issues, I would just encourage not having spaces in the Group Names if they are to be targeted via inbound email. 

 

At this point we've demonstrated we can send an email to an address and have it create an event in xMatters. For our testing, we were sending the emails, but often these emails might be sent from a system that lacks the capability for a more powerful integration. 

In our next installment, we'll add some callbacks so when users respond, we can update some other system. So keep an eye out for GIG part 4. 

Happy Emailing!

 

 Click here for the next installment of the GIG!

 

Have more questions? Submit a request

9 Comments

  • 0
    Avatar
    nathan salisbury

    Is it possible for xMatters to forward an attachment that was included in an inbound email integration? Use case: forwarding an email with .wav file attachment from our voice mail system into xmatters email integration and it notifying our on call tech with the wav file attached.

  • 0
    Avatar
    Travis DePuy

    Hey Nathan, Sorry I was out for a few days. As Iain mentioned in your other thread, this isn't an option right now.

  • 0
    Avatar
    Jason Miller

    Hi Travis,

    I was happy to find using the tip about a wrapper group as an alias on this page.

    We are having a hard time sending to group with spaces in the name (almost all of our groups) because most of the clients we are using (primarily Outlook during form development) are not allowing it. Unfortunately having to add a wrapper group for each group that will receive email injection notifications is unnecessary overhead and maintenance but it is a viable workaround. I would love to see this handled better though, like being able to remove the spaces or replace them with dashes and the system would map it to the correct group. Even though quotes are allowed per the SMTP spec I tend to think it is a bad practice.

    One additional note, I was able to use quotes in Gmail but not in Google Inbox. Google is starting to push more and more to have people use Inbox over Gmail.

  • 0
    Avatar
    Travis DePuy

    Hey Jason. It's always nice to hear someone finds something I write useful! Thanks for the feedback. I hear you about the pain of adding the wrapper. So, you're suggesting that we could target "VIP Customers" by sending the email to VIP-Customers@muffinsready.acme.na1.xmatters.com and have xMatters do a "look up" or a mapping of some sort?

  • 0
    Avatar
    Jason Miller

    Exactly. Some kind of documented conversion process just like that. Where users doing email injection know to replace the space in a group name with hypes and xMatters will find a match in the system with spaces.

    Of course this process needs to take into account groups with hyphens in the name. For example if the target group name is actually "VIP-Customers" in xMatters the system can't just assume it is looking for "VIP Customers" because the incoming email was to vip-customers@muffins.... I am thinking it should look for an exact match like it does today and if no match is found then replace hyphens in the incoming address with spaces and perform the lookup again.

  • 0
    Avatar
    Travis DePuy

    Ok, I'll get an enhancement request created. And just to point out, this will only really be useful for people not using Outlook. In all my testing, Outlook refused to send to a recipient with spaces. Quotes or no.

  • 0
    Avatar
    Travis DePuy

    Er, no, I had that wrong. Entering this enhancement request will ALLOW people using Outlook to target groups with spaces by using -s instead. Yea, that makes more sense. sorry for the confusion

  • 0
    Avatar
    Jason Miller

    Thanks!

    Not being able to send to an address with spaces has been my experience with both Outlook and Google Inbox. It look like the list of clients that can use quotes is shrinking.

    Regarding Google email, I am able to send using the older Gmail UI but when I try with the same exact account to send via the Inbox UI the address is rejected, with and without quotes.

  • 0
    Avatar
    Jason Miller

    I think in general using a dash for a space is cleaner than trying to use quotes (IMHO of course).

Please sign in to leave a comment.
Powered by Zendesk