Adding new form customization features in existing inbound integrations

Marked as obsolete (ref:

We've added some new features to the Integration Builder that let you configure more form options when you trigger an event using an inbound integration. This article explains how to modify an existing inbound integration so that it can use these new features.

As of October 2017, inbound integrations can now override the default values for the following form options:

  • Responses: You can create new responses, display existing responses, or modify parts of existing responses. This gives you control over the available response choices, and lets you customize things like which URL people should be redirected to when they respond to a notification.
  • Handling section: We've rounded out the handling section options so that you can configure anything that appears in the form's handling section, such as the length of time an event is active or what content to leave in a voicemail.
  • Response counts: You can configure the number of responses that are required before xMatters stops delivering new notifications to additional recipients.
  • Devices: You can change which types of devices are notified when you trigger the form; for example, you could configure a form to target only email devices. 

With the addition of these new customization options, we've started using a new back end to process inbound integrations. The new back end is backward-compatible and will continue to process existing integrations, but if you want to add new features to an existing integration you may need to modify your transformation scripts to be compatible with the syntax required by the new back end.

To access the new features described in this article, you'll need to update your script so that it uses the new format as described in the online help.  You can't mix-and-match parts of the old format and the new format in the same call to an inbound integration.

For inbound integrations that use the Create event option, this means you may need to change how you structure the payload you send to xMatters. For inbound integrations that use the Transform content to create event option, this means you may need to change how you build up the triggers object that is used with

A note about recipients

In particular, you may need to change how you structure recipients so that it conforms to the new structure. 

Previously, you could define the recipients using a helper method in a transformation script, like so: 

trigger.addRecipient ("mmcbride");

Or, you could add a recipient using the following syntax: 

var recipients =[];
"taregetName" : "mmcbride");
trigger.recipients = recipients;

Using either of these methods builds up the triggers object according to the old structure. If you want to access the new features described above, you'll need to structure the recipients using the new format, as shown below for inbound integrations that use a transformation script:

var recipients = [];
recipients.push({"id":"mmcbride", "recipientType": "PERSON"});
recipients.push({"id":"f19d8b10-923a-4c23-8348-06ced678075e", "recipientType": "GROUP", "responseCount" : 3});
trigger.recipients = recipients;


Note that including the "recipientType" field is optional, but recommended, since it helps xMatters process your event more efficiently.

Have more questions? Submit a request


  • 0
    LEON Johnny

    Great news for this feature.

    Will we have ability to also specify from an integration the 'Sender overrides' properties as well? This will allow us to reduce number of forms.



  • 1
    Travis DePuy

    Hey Johnny,

       The sender overrides is still not available in the API. I did track down your previous PM request about this and I poked it and added a link here. This should help bubble it up to PM. 

    Happy Wednesday!
        --- Travis

Please sign in to leave a comment.
Powered by Zendesk