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.
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:
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:
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:
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.
Click here for the next installment of the GIG!