Outbound Connections¶

Outbound Connections are used to send the live output that TSI produces to external systems. Several types of external systems such as iPaaS, MQTT brokers and CMMS/EAM systems can be connected to Falkonry TSI via Webhook, MQTT and ReST APIs.

The output data from the Falkonry TSI gets delivered in the order it is generated. For real time data delivery, a connection must be in PRODUCTION status. This connection may change it's status to PAUSED, in case TSI cannot connect to the external systems after certain number of retry attempts. In such case, use the Connection UI to see the error details and change the status back to PRODUCTION after the connectivity is revolved.

Note

Currently only Rules output is supported for outbound integration.|

Connection Types¶

The types of Outbound Connections available are as follows:

1. MQTT Connection¶

This type of Outbound Connection allows you to connect any MQTT broker with Falkonry TSI. This connection delivers live output data produced by the TSI as MQTT messages for each configured signal. The JSON formatted messages are published by TSI as it connects to the MQTT broker over the internet.

Example message template

Use below example template to receive alerts from Rules.

{
  "time": "{{context.time}}",
  "value": "{{context.value}}",
  "tenant": "{{context.tenant}}",
  "rule": "{{context.rule}}",
  "rule_name": "{{context.ruleName}}",
  "description": {{context.ruleDescription | tojson}},
  "asset_id": "{{context.assetKey}}"
}

Authentication and Security

This connection expects the MQTT broker to be accessible over the internet for TSI to connect to it. This connection needs to be configured with MQTT broker endpoint, port, topic, client ID and security credentials when creating the connection in TSI.

The data transfer is secured by basic as well as certificate-based authentication. For TSI to reliably connect to the MQTT broker over the internet, it is recommended to configure the network security with a range of whitelisted IP addresses to allow connection requests from TSI.

Note

Please contact Falkonry Support to get the list of IP addresses to allow MQTT connection.

2. Webhook Connection¶

This type of Outbound Connection allows you to trigger a webhook event in the external system. This connection delivers live output data produced by the TSI as HTTP requests for each configured signal. The JSON formatted HTTP payload are delivered by TSI as it connects to the external system over the internet. This type of connection also allows you to connect iPaaS platforms as well as trigger workflows to send an email.

Use below example template to receive alerts from Rules.

{
  "time": "{{context.time}}",
  "value": "{{context.value}}",
  "tenant": "{{context.tenant}}",
  "rule": "{{context.rule}}",
  "rule_name": "{{context.ruleName}}",
  "description": {{context.ruleDescription | tojson}},
  "asset_id": "{{context.assetKey}}"
}

Authentication and Security

This connection expects the external system to be accessible over the internet for TSI to connect to it. This connection needs to be configured with HTTP/HTTPS URI and security credentials as HTTP headers when creating the connection in TSI.

The data transfer can be secured by setting up the HTTP header based authentication. For TSI to reliably connect to the external system over the internet, it is recommended to configure the network security with a range of whitelisted IP addresses to allow connection requests from TSI.

Note

Please contact Falkonry Support to get the list of IP addresses to allow HTTP/HTTPS connection.

3. Zapier Connection¶

This type of Outbound Connection allows you to trigger workflows created by you in Zapier. This connection delivers live alerts generated by Rules as HTTP requests. Each alert is delivered as JSON formatted HTTP payload using the configured Zapier webhook URL.

Checkout this example to know how you can build an email integration with Zapier.

Use below example template to receive alerts from Rules.

{
  "time": "{{context.time}}",
  "value": "{{context.value}}",
  "tenant": "{{context.tenant}}",
  "rule": "{{context.rule}}",
  "rule_name": "{{context.ruleName}}",
  "description": {{context.ruleDescription | tojson}},
  "asset_id": "{{context.assetKey}}"
}

Authentication and Security

This connection expects Zapier endpoint to be accessible over the internet for TSI to connect to it. This connection needs to be configured with HTTP/HTTPS URL provided by Zapier for each workflow when creating the connection in TSI.

The data transfer is secured by HTTPS communication. Since Zapier webhook URL does not have a HTTP header based authentication, it is necessary to treat the webhook URL as secret.

Note

Please contact Falkonry Support to get the list of IP addresses to allow HTTP/HTTPS connection.

4. CMMS/EAM Connection¶

This type of Outbound Connection allows you to connect CMMS/EAM systems with Falkonry TSI. This connection can be used to automatically create work orders or work requests in the CMMS/EAM system when any of the Rules generates an alert. This connection uses one of our partners, Makini to establish connectivity.

Note

Please contact Makini or Falkonry Support as you plan to connect your preferred CMMS/EAM system with TSI.

Checkout this example on how you can connect eMaint with Falkonry Cloud.

Use below example template to create work order for an alert produced by TSI.

{
  "title": "{{context.ruleName}}",
  "description": {{context.ruleDescription | tojson}},
  "assetKey": "{{context.assetKey}}",
  "status": "Open",
  "createdAt": "{{context.time}}",
  "scheduledAt": "{{context.time}}"
}

Use below example template to create work requests for an alert produced by TSI.

{
  "title": "{{context.ruleName}}",
  "description": {{context.ruleDescription | tojson}},
  "assetKey": "{{context.assetKey}}",
  "userRequestedKey": {{context.userRequestedKey}}",
  "customFields": {
      "stattype": "O"
  }
}

Authentication and Security

This connection between Makini and CMMS/EAM is managed and secured by Makini. You can required to connect your preferrred CMMS/EAM system with Makini and allow Makini to perform CRUD operations, before creating this connection in TSI. The connection between TSI and Makini is secured by API token generated by Makini. This API token has an expiry of 30 days and needs to be rotated accordingly.

Note

Read here to know how you can bring asset information into Falkonry Cloud from various CMMS/EAMs systems.

5. ReST API¶

Signal Data API can be used to retrieve the output data from the TSI generated signals. Each output data type (predictions, confidence score, and explanation score) is referenced as Signal or Connected Source with an unique identity in TSI. The Signal or Connected Source ID can be used to retrieve the output data by performing a time range query.

Get the Connected Source or Signal ID from All Signals section in the TSI UI and use the Signal Data API to retrieve the data.

Authentication and Security

All the TSI APIs use REST (Representational State Transfer). The APIs are secured by token-based authentication.

The Authorization HTTP header is required to be specified with Bearer \<your-access-token> in each request to authenticate as a user and have the same permissions as the user itself. This access token needs to be generated via the TSI UI.

Creating a Connection¶

When creating an Outbound connection in TSI, review the available connection types and select the connection type supported by the external system you currently have. For transferring historical output from Falkonry TSI, use ReST APIs.

Setting up a Connection¶

When creating the connection use the template section to configure the data format and the payload. The current supported format is JSON, and following properties are available to be used in the payload.

Property Name	Purpose
`context.time`	Timestamp of the TSI output in UTC time (ISO format). Example: `2024-01-01T00:00:00Z`.
`context.value`	Value of the TSI output. For Rules, the value can be either `true` or `false`.
`context.signal`	ID of the output signal.
`context.signalName`	Name of the output signal.
`context.tenant`	Account ID in Falkonry TSI.
`context.connection`	ID of the outbound connection.
`context.connectionName`	Name of the outbound connection.
`context.rule`	ID of the rule when integrating with Rules.
`context.ruleName`	Name of the rule when integrating with Rules.
`context.ruleDescription`	Description of the rule when integrating with Rules.
`context.<custom-property-key>`	Custom fields set as properties on the TSI assessment with prefix `outbound.`. Contact Falkonry Support to add additional context to the message payload.

After the connectivity details are provided, it is required to configure the signal sources. This is where you can configure the type of TSI output you want to send to external system.

The available sources are:

Signal Source	Signal Type	Use
Rules	Alerts	To send alerts generated by the selected rules.
Rules	Rule output	To send rule output of the selected rules. This contains the rule output each time the rule gets evaluated. The value can be `true` as well as `false`.