The information in this article is the intellectual property of xMatters and is intended only for use with xMatters products by xMatters customers and their employees. Further, this intellectual property is proprietary and must not be reused or resold.
When using the Email trigger step in xMatters Flow Designer, the entire email body gets placed into an output of the trigger so you can use it in steps in the flow.
But, because we can't know what might be in your email, it's just a block of text (or text and some HTML) — not so useful, right? Guess what... you can create a custom step to pull out discrete information from the email body and put it into outputs for you to use in your flows.
The setup
To walk through setting up this email parsing step, let's assume we have a web form that users of our Stellar suite of applications fill out when they encounter an issue. The form has the fields Application, Issue Type, Summary, and Description. When the user hits submit, this information gets sent to xMatters via email. The Summary gets put into the subject line, while the rest of the information is in the body.
Here's our simple web form:
Which gets sent to xMatters in an email that looks something like this:
Notice how each line is preceded by a label. That's important later.
The custom step to parse the email body
If you have a standard email format, it's simple to create a custom step that looks for keywords or labels in the email and then passes the information that follows into an output. There is a little bit of code involved, but you can copy-paste-tweak our sample if code makes you twitchy.
Open a flow in Flow Designer and go to the Custom tab in the palette.
Click Create a custom step to open the New Custom Step dialog box.
In Settings, give the step a descriptive name (for example, Stellar Support Email Parser) and a description. You can also change the icon if you want.
-
Click the Inputs tab and add a single input, giving it a name and help text. This input is where people will map the email body output from the Email trigger, so maybe name it something like Plain Text Body and add help text letting people know they should use the plain text output, not the HTML output (or vice versa).
You might also want to up the maximum length, depending on how verbose your users are in their descriptions
-
Click the Outputs tab and create an output for each item in your email that you want to pass down the flow.
Keep in mind that the output label doesn't need to match the label in the email — we can use the script to map an input with one name to an output with a completely different name. In this example, I'll add the outputs System (Application in the email), Details (Description), and Subsystem (Issue Type). Notice how there is no output for Summary; because this was the subject of the email, it's already available in the email.subject output of the Email trigger.
If you plan to search or filter on these values later (for example, in alert views or downstream steps), it's a good idea to map only the key pieces of information you care about into dedicated outputs. That way, you can avoid having to search the entire email body, which xMatters does not support by default.
If the information you need is buried in a very long or complex email body, consider creating extra outputs for pre‑cleaned values and use your script to strip out extra line breaks, whitespace, or markup before assigning the value to the output.
Click Save. Next we'll move on to the script, so click the Script tab.
The script
In the script, you basically need to bring in the body, then have an item for each output that maps it to a keyword in the email.
Here's the format to map email item to output:
Keep adding to map as many email items to outputs as needed, then click Save. When you're done, test your parsing step to make sure it works like you expect.
Here's the entire script for this example:
var body = input['Plain Text Email'];
// Application -> System
var tmp = body.match(/Application: (.*)/);
if (tmp && tmp.length > 1) {
// Trim leading/trailing spaces to avoid filtering issues later
output['System'] = tmp[1].trim();
}
// Description -> Details
tmp = body.match(/Description: ([\s\S]*)/);
if (tmp && tmp.length > 1) {
// Remove extra newlines that can appear in HTML-to-text conversions
var cleanedDescription = tmp[1].replace(/\n+/g, ' ').trim();
output.Details = cleanedDescription;
}
// Issue Type -> Subsystem
tmp = body.match(/Issue Type: (.*)/);
if (tmp && tmp.length > 1) {
output['Subsystem'] = tmp[1].trim();
}Use the step in a flow
Drag the step onto the canvas after an Email trigger.
Map one of the HTML body outputs to the input you created.
Drag another step onto the canvas that can consume the information from the email parsing step outputs (for example, an xMatters Create Event step) and connect it to the email parsing step.
Map the outputs of the parsing step into the inputs of that step then click Done on the step and Save on the canvas.
Open the Email trigger and click Test Email to send a test email, making sure you include the labels the script needs (in this example, Application, Description, and Issue Type).
Check the Activity panel to make sure everything processed as expected.
That's it! You can find more information on creating, managing, and using custom steps in Flow Designer in the xMatters online help and learn more about using the email trigger in Easy as Pie: Advanced Email Initiation.
Comments
4 commentsPlease sign in to leave a comment.
Hi Christine. I knew I would have a need to do this at some point...and a request just came my way. I'll give it try and let you know.
Hi Colum, I look forward to hearing about your experience (and any suggestions for improvement). If it's helpful, it likely because the idea and source material came from our awesome xPert Travis DePuy.
I gave it a try. It was quick to set up and works perfectly. Hats off to both you and Travis.
Awesome! Thanks for the update.