Custom Action Types

Components can include custom action types for integrating with third-party services whenever an action is emitted. A component provides the functionality for the integration by creating a microservice that uses a trigger or stream service to perform its custom logic.

When an action is generated, IA will publish a message to the topic:
component/action/custom/{custom_action_type_id}/request.

The custom service listens for this message, performs the integration, and then publishes a response to the topic:
component/action/custom/{custom_action_type_id}/response.

This allows IA to store the success or failure result in the action history.

Here’s an example of a custom action type with the ID my_custom_action_type, implemented with a microservice using a message topic trigger:

JS

function customActionTypeService(req, resp) {

  // parse the incoming message
  const messagePayload = JSON.parse(req.params.body);
  // parse the action's config to access the fields configured within the IA UI
  const actionConfig = JSON.parse(messagePayload.action.config);
  // format fields as necessary, this is useful for taking advantage of IA's action templating
  // in this example, the action type's schema includes a message field
  const formattedMessage = actionUtils.formatMessage(actionConfig.message, messagePayload);

  const mqttClient = new MQTT.Client();

  callMyThirdPartyIntegration().then(function() {
    // publish back to IA to store success state in action history
    mqttClient.publish('component/action/custom/my_custom_action_type/response', JSON.stringify({
      success: true,
      payload: messagePayload,
    }));

    // exit the micro service
    resp.success('done');
  }).catch(function(error) {
    console.error('Failed to call third party integration', error);
    
    // publish back to IA to store failure state in action history
    mqttClient.publish('component/action/custom/my_custom_action_type/response', JSON.stringify({
      success: false,
      payload: messagePayload,
      error: JSON.stringify(error)
    }));

    // exit the micro service with an error
    resp.error('error');
  })
}

IA exposes a library called actionUtils that allows custom action types to leverage templating. The library is structured as follows:

TYPESCRIPT

const actionUtils = {
  formatMessage: (field: string, actionPayloadMessage: ActionPayloadMessage) => string;
  formatRecipients: (field: string | string[], actionPayloadMessage: ActionPayloadMessage) => string[];
}

Here are some additional useful types:

TYPESCRIPT

/**
 * ActionPayloadMessage is the payload that is published to the request topic.
 * For full list of ActionPayloadMessage properties, refer to the
 * Template Field Options help text in your rule's edit modal
 */
interface ActionPayloadMessage {
  action: {
    id: string;
    // JSON stringified value of the action's config
    config: string;
    // ... other action properties
  };
  triggerMessage: {
    id: string;
    label: string;
    // ... other triggerMessage properties
  };
  event: {
    id: string;
    // ... other event properties
  }
}

/**
 * This is the interface for the response from a custom action type.
 * Custom action type code services should publish this to the response topic.
 * success indicates that the action was processed successfully or not. It's used to indicate what to store in the action history.
 * The payload property is necessary to match the response with a request
 */
type CustomActionMessageResponse =
  | {
      success: true;
      payload: ActionTopicMessage;
    }
  | {
      success: false;
      payload: ActionTopicMessage;
      error: string;
    };