Email Parser

This repository contains a Shared Library and a template/example Workflow for parsing inbound emails that can be used to chain and trigger a subsequent Form or Integration. The setup is fairly simple, and the Shared Library may be used in any number of Workflow.

Pre-Requisites

• xMatters account - If you don't have one, get one!

Files

• EmailParserTemplate.zip - This example Workflow has a simple form for initiating via Email, and another form that is initiated after parsing the received email to trigger the first Form.
  The Workflow also includes the Shared Library ("Email Parser"), an Inbound Integration to trigger the chained/follow-on Form, and one Outbound Integration that is triggered when the Inbound Form is activated and calls the Email Parser.
• Email_Parser.js - This is the JavaScript source file for the Shared Library.
  You can copy and paste that as a Shared Library into any existing or new Workflow.
• Outbound_Integration-Parse_Inbound_Email.js - An example Outbound Integration triggered by Event Status Updates and should be associated with whatever Form you have created to recieve inbound emails to start the Notification Events. In the example Workflow, this is associated with the Form called "Inbound Email Form".
  You may use this as an example of how to use the Shared Library.
  The actual code is specific to this Template Workflow, so you will need to adjust it if you paste it into your own existing Workflow.

How it works

Conceptually, the parser, propParser(body, propInfo), operates on two inputs:

1. body - The text version of the body from the inbound email, and
   
2. propInfo - An object that defines the parsing parameters as follows:
   

propName:
   Name of property to search for in the source
propValueTerminator: 
   If value is a specific length, then use that number here
   If value is variable length, then use the next string in 
      the payload as a value terminator.
      This terminator can be something like "\n", or another next
      value like "Business Criticality"
isSingleton:
   If true, return the first occurance
   If false, use the optional field "delim" to define separator
delim: (Optional)
   If isSingleton is true, then put this string between the 
      parsed / found values
targetPropName:
   The name of the property to populate in the target object

The process is based on two Forms:

1. A Form configured for Email Initiation. You should at a minimum configure the mappings for the From, Subject, and text representation of the Email body. This is the Form named "Inbond Email Form" in the sample Workflow.
2. Another Form configured to be sent out with the values that are parsed out from the first Form. This Form is called "Outbound Email Form" in the sample Workflow. It has discrete properties that map to the values that will be parsed.

The process flow is started when the "Inbound Email Form" is initiated by Email . That is, xMatters receiving an email targeted to the Forms pre-defined email address.
At that point an Event is created in xMatters for that "Inbound Email Form", which in turn triggers the Outbound Integration that is associated with that Form's Status Update Trigger. (See the example in the sample Workflow.).
The code in the trigger will call the parser and fill in the properties for the target form.
Then the code will trigger a new Event targeting the "Outbound Email Form" in our example.

Installation

Installation is simple.
You can either import the Sample Workflow , or you can add a Shared Library to an existing Workflow using the Email_Parser.js,
and create your own Outbound Integration using the Outbound_Integration-Parse_Inbound_Email.js
If you are going to try using the Sample Workflow, you will need to set the Constant called EMAIL_FORM_TO_INITIATE_URL.
This should point to the Inbound Integration address for the "Outbound Email Form" using URL Authentication.
Note you will only need the URL from the /api forward (e.g. /api/integration/1/functions/f024ae5a-41a5-4fb0-b6b6-0a6e1002588c/triggers?apiKey=4f6cab6d-8542-4e2e-b83a-b7e0f028f663) .

Testing

To test the integration, send a formatted email to yoru Form's email address... you can target "nobody" as the Recipient, or specify a Group Name, or User ID.
For example, mailto:[email protected]
Then, if you're using the Sample Workflow, try with an email body formatted like this:

Prop1: [This is Prop1's value, and is enclosed with square brackets]

Prop2: ListValue1,ListValue2,ListValue3

Troubleshooting

If you're having problems, check the Activity Stream of the Outbound Integration.
Also make sure that the Inbound Email Form was initiated. You should have a new Event in the Reports tab if the Email was received and accepted by xMatters.
You will need to make sure that the email Sender's From address is associated with an xMatters User account, and that this User has an Email device with the Sender's From address.