Configure forms for email initiation

You can configure a communication plan form for email initiation, allowing you to initiate an event by sending an email to xMatters. When xMatters receives the form initiation email, it maps the values of the email subject and body fields to text properties in the form according to field mapping configured for the form.

You can map the following email fields to form properties:

  • Subject: The subject of the email message.
  • From: The sender of the email message.
  • Body (Text): The content of the email message that is sent as plain text.
  • Body (HTML): The content of the email that is sent as HTML.

For example, consider a form that has two text properties Summary and Further Instructions. You could map the subject of the email to the Summary property, and map the plain text body of the email to the Further Instructions property:

When you send the form initiation email, you then set the subject and body of the message as shown below:

When the event is initiated, the Summary field is set to Take cover now, and the Further Instructions field is set to Go to the nearest available shelter and take cover until the storm has passed.

Some forms have required properties that must be set before the form can be initiated. If a form has required text properties, you must map them to an email field and the field must be assigned a value when the form is initiated. You should also ensure that the length of the text in the email field does not exceed the maximum length of the mapped form property, or it will be truncated.

Other non-text form properties, such as lists, hierarchies, numbers, etc. cannot be set using email form initiation. Forms that contain these properties cannot be initiated by email unless they have been assigned default values.

To configure a form for email initiation:
  1. Click the Developer tab, and then click Communication Plans.
  2. Locate the communication plan that contains the form you want to configure, and click Edit > Forms.
  1. Locate the form that you want to configure, and click the Not Deployed drop-down list (this label may be different if some deployment options are already selected).
  2. Select Set Up Email Initiation.
  3. In the Set Up Email Initiation dialog box, map the fields of the email message to text properties of the form. 
    1. Required text properties on the form must be mapped to an email field.
  1. To change the form ID, click the editable section of the sample email address and type the new form ID.
    1. By default, the form ID is the name of the target form without spaces and in lower case.
    2. You may want to change the form ID to be more readable, or you may want to change it to something hard to guess for security reasons.
  2. Make note of the sample email address that is displayed on this form and share it with users who want to initiate the form by email.
    1. The sample email address shows how to initiate this form with yourself as a recipient. When you initiate the form by email, you can replace your user ID with the user ID, group name, or dynamic team name of the recipient you want to target. For an example, see Initiate a form by email.
  3. Click Save Changes.
  4. Ensure that the users or roles you want to be able to initiate the form have sender permissions for the form in the web user interface.
  5. To disable email initiation for a form, de-select the Enable Email Initiation check box from the form's deployment settings menu.

Renaming a communication plan form does not change the email address that you use to initiate the form. If you change the name of the form and want to update the form initiation email address to match, you can manually update the form ID in the Set Up Email Initiation dialog box.