Convert an outbound integration to a flow

From the very first release of Flow Designer, your outbound integrations appeared as event activity triggers on your flow canvases (you might already have connected steps to them). However, if you wanted to edit them, you still had to go into the Integration Builder. But we've continued to pack features into Flow Designer, and you can now work with 'Send a webhook' and 'Run a script' integrations right in Flow Designer.

What this means varies depending on the integration action. See the sections below on Send a webhook and Run a script integrations; 'Send to Integration Agent' integrations are unique, so you still need to use the Integration Builder to edit them.

Send a webhook integrations

Your 'Send a webhook' integrations are automatically migrated to flows, consisting of a trigger step to initiate the action and a webhook step to send the webhook request.

What does this mean for me?

This trigger + webhook combination continues to function the same way your integration did before. The webhook step uses the existing endpoint and any appended path specified in the integration, and any properties you set to be included in outbound integrations are automatically included in the webhook payload.

How do I work with this new flow?

There is one important thing to keep in mind when working with the converted flow: the body of the webhook request is migrated into a special body variable, used only in the Body input of the webhook step in the converted flow.

If you delete the body variable from the input of the webhook step, you cannot add it again; you'll need to recreate the payload you want to send, adding it to the Body input of the webhook step. Similarly, if you delete the trigger, the webhook step, or the connection between them, you'll have to recreate the payload.

However, this change also means you can replace the body variable with a new payload tailored to your needs, giving you more control over what information gets sent in the webhook.

You can find more information on setting up the webhook step in the topic on flow triggers, and information on legacy trigger payloads is available in the scripting reference.

Run a script integrations

'Run a script' integrations are not automatically converted, since we can't easily tell exactly what steps are hidden in there, but you can now edit the settings and the script in Flow Designer.

If you want to convert an outbound run a script integration into a flow, there are a couple of basic steps: find the steps that are hidden in the script and surface them as steps on your canvas. Breaking the script into its constituent steps makes it easier to manage, reuse, and troubleshoot, even if you're not a developer.

If you don't convert the integration, it will continue to function even though it's flagged as 'deprecated' (that's just our way of letting you know there's another — and we think, better — way of doing things). We'll give you lots of warning if that changes, though there are some minor changes to how you work with them.

If you want to convert the integration to take full advantage of the power and flexibility of Flow Designer, keep reading. We'll go through the process of converting an integration to a flow using an example: a 'Notification Escalation' integration designed to add a comment to a Jira issue and post to a chat when an event is escalated.

Step 1: Find the steps in your integration script

The first step is to look at the script and figure out what steps are hidden inside. In this example, there are actually three steps in this integration script...all of which we can replace with steps built right into Flow Designer:

  • the trigger that initiates the action when the escalation occurs
  • the request that adds a comment to the ticket, and
  • the request that posts to the chat channel.

Here's what that looks like as a flow:

Step 2: Add the steps hidden in the code

Flow Designer comes with a slate of built-in steps that perform actions both in other systems and in xMatters. To add one to a flow, drag it onto the canvas, connect it to the flow and configure its settings.

Trigger the flow

The first step to replace is the event activity that triggers the action.

This example uses the Escalations trigger, so we'll drag that trigger onto the canvas. The process is the same for any of the event activity triggers; the only difference between triggers is the event activity that initiates them and the information provided in the outputs specific to the activity.

Add a comment

In our example, we'll add a comment to the source application (in this exampe, Jira) and post to a chat channel (in Microsoft Teams).

The script finds the ticket ID then posts the following comment to the ticket, using the Jira endpoint set up in the workflow:

var msg = 'xMatters: ' + callback.recipient + ' escalated event ' + callback.eventIdentifier + ' at ' + callback.time ' + '. Now notifying next on-call members in .' + callback.group + '.'

Here's how you'd set up an Add Comment step to replicate the script — all without any scripting, so anyone on your team can add and update the step:

  1. Configure the Add Comment step inputs. We've already connected the step to the trigger, so we have the event and trigger properties available to drag into the inputs:

  1. Set the run location (if available). This sets whether the step should run on the cloud or on an xMatters agent; the Run Location tab only appears if the step is configured to allow running on an agent.
  2. On the Endpoints tab, select the existing endpoint for the application from the list (in this example, we had a Jira endpoint already configured).
Post to chat channel

The script posts a similar message in the service team's Teams channel so the team knows someone needs to take ownership.

var msg = 'xMatters: ' + callback.recipient + ' escalated event ' + callback.eventIdentifier + ' at ' + callback.time ' + '. Now notifying next on-call members.'

To replicate this with the Post to Channel step:

  1. Configure the Post to Channel message:

  1. On the Endpoints tab, select the existing endpoint for the application from the list (in this example, we had a Teams endpoint already set up).

That's it. We've turned that blob of code into a flow of discrete, reusable, and observable steps.

Step 3: Test your flow

This step is optional, but it's always a good idea to test the flow to make sure you're seeing the results you expect. You can open the Activity panel to see how the flow executed, and use it to help pinpoint any issues.

To test the escalation example, we'd initiate the event for the form, targeting a group we're the on-call member of, and hit the "escalate" response when we receive the notification. We'd then check Jira and our chat channel to see if the message was posted.

But my script isn't so simple...

If you have some unique functionality in your script that looks up information in another application or posts to an application we don't have a built-in step for (yet), there are a few options:

  • Maybe you have a switch statement in your script (for example, to add a different comment for manual escalations versus those that occur because an escalation delay elapses). Use a switch step that flips based on the escalation.escalationType trigger output.
  • For posting to another application, you can use the built-in webhook step to send a payload to any system that accepts HTTP POST requests.
  • If you want to get information from another application to enrich the flow, create a custom step.
  • If a built-in step almost meets your needs, but not quite, you can convert it to a custom step and modify it.

What if I'm happy as is?

That's okay. We understand that you've got a system that works for you. As mentioned, we'll let you know if a change comes along that will impact your existing integrations. There are some changes with how you work with legacy integrations in Flow Designer.