Help Center

Menu

Actions and triggers in JSON

This section covers the configuration of actions and triggers in a component.json file.

Actions and Triggers Object

The actions and triggers objects in the component.json describe the actions and triggers that exist within the component.

Actions are operations exposed to the flow builder that can be placed in any step except the first step of a flow.

Triggers are operations exposed to the flow builder that can only be placed in the first step of a flow.

Both action and trigger objects in component.json have similar structures; however, there are some differences between them described in this article.

Each key-value pair in the object represents an exposed action or trigger. The string key acts as the identifier for the action/trigger.

The structure used to describe each action or trigger is described below.

The component.json file should not have an actions field if the component has no actions. Likewise, the component.json file should not have a triggers field if the component has no triggers.

While neither field is an absolute requirement, all components must implement at least one action or at least one trigger.

Property name Action/Trigger Description

title

Both

Action or trigger’s title to be displayed in the UI.

description

Both

Action or trigger’s description to be displayed in the UI.

deprecated

Both

Used to flag the action/trigger as deprecated.

main

Both

Identifies the code entry point for the action/trigger.

type

Triggers

Only Identifies if the trigger should be a polling or webhook trigger.

fields

Both

Identifies configuration fields that provide flow-level configuration for the action/trigger.

dynamicMetadata

Both

Signals that the component dynamically communicates the expected structure of incoming and outgoing messages of the action/trigger.

metadata

Both

Statically defines the expected structure of incoming and outgoing messages of the action/trigger.

Title and description

The title and description fields are displayed in the UI.

Type

string

Examples
title: Upsert Object

description: Given criteria that match at most one object, update that object or create it if it does not exist
Title and description

Deprecated

Signals that this action or trigger should not be used in new flows and that existing flows should migrate to a different action/trigger.

Type

boolean

Default value

false

Deprecated

Main

Identifies the code entry point for the action or trigger.

For JavaScript components, the code entry point is identified as a path to a .js file that contains the code for the action or trigger. This path should be relative to the root of the component.

In the case of Java components, the code entry point is identified as a fully qualified Java class name that implements the logic for the action or trigger.

Type

string

Examples
JavaScript: ./lib/actions/upsertFile.js
Java: io.elastic.soap.actions.CallAction

Type (triggers only)

This identifies the type of trigger. There are two options: polling and webhook.

Setting the value to polling causes the platform to start the flow at regularly scheduled intervals based on a CRON expression.

Setting the value to webhook causes the platform to generate a URL when the flow is published. The flow is run when HTTP(S) requests arrive at this URL.

Type

string enum of polling or webhook

Example

polling

Default value

webhook

Fields object

The fields object describes the flow-specific configuration fields that must be set for the action or trigger.

For more information, read the Fields in JSON for more information.

Metadata: metadata and dynamicMetadata fields

More information on the metadata schema structure can be found in this article: Fields in JSON

These two properties indicate how the component communicates the expected structure of incoming and outgoing messages to the platform.

There are three options for how the message structure is communicated:

  • Incoming messages should be mapped to a static structure. The incoming and outgoing message structure is stored in the component repository with the code.

  • Incoming messages should be mapped to a dynamic structure. Once the platform has the credential and configuration field information, the platform calls a code entry point in the component to learn the metadata.

  • Incoming messages should not be mapped.

Dynamic Metadata

If the action/trigger uses dynamic metadata:

  • The dynamicMetadata value should be set.

  • The metadata property should be omitted.

Some examples when dynamic metadata is used include:

  • There is an action modifying an object whose structure can be customized (for example, Salesforce allows users to add new object types and tweak the properties/fields stored on existing objects).

  • The required fields change based on the configuration fields (for example, looking up a page of objects requires different inputs to looking up all objects).

When dynamic metadata is used, once all required configuration fields for an action/trigger have been submitted, the platform calls component code to learn the metadata.

JavaScript

When using dynamic metadata with JavaScript components, the dynamicMetadata field should be set to boolean true. The file containing the action/trigger with dynamic metadata needs to export a function getMetaModel(), which accepts the credential and configuration field information and returns the metadata as an object with two keys in and out to describe the typical structure of incoming and outgoing messages.

Java

When using dynamic metadata with Java components, the dynamicMetadata field should be set to a string that is the fully qualified name of a Java class that inherits the io.elastic.api.DynamicMetadataProvider class. Whenever a configuration field is edited, the metadata is refreshed.

Example of dynamic metadata loading

Static Metadata

If the action/trigger uses static metadata:

  • The dynamicMetadata value should be omitted.

  • The metadata property should be set, and at least the in property should be set.

Some examples when static metadata is used include:

  • There is an action modifying an object whose structure can never be customized (for example, updating Credit Card Data).

There are two possible formats for static metadata:

  • Metadata is inline in the component.json file. In this case, metadata is an object with two properties; in and out. Each property is an object that describes the expected structure of the incoming or outgoing messages.

  • Metadata is stored in external JSON files. In this case, metadata is an object with two properties; in and out. Each property is a string that contains a path (relative to the component’s root directory) to a JSON file which contains an object that describes the expected structure of the incoming or outgoing messages.

No In Metadata

If the action does not expect incoming messages to be transformed by the platform’s built-in mapper:

  • The dynamicMetadata value should be omitted

  • The metadata property should not have a value for the in property or be omitted completely

Some examples when no in metadata is used include:

  • The action contains mapping logic hardcoded (for example, code component).

  • The action applies JSONata or similar transformations (for example, splitter component).

  • The action has no inputs (for example, configuration component).

When the No In Metadata mode is selected, then there is not a mapping step between this component and the previous component.

Example

Example of action object implementation in the component.json file.

{
  "queryAction": {
    "title": "Query",
    "main": "./lib/actions/query.js",
    "metadata": {
      "in": {
        "type": "object",
        "properties": {
          "query": {
            "maxLength": "20000",
            "title": "SOQL Query",
            "type": "string",
            "required": "true"
          }
        }
      },
      "out": {}
    }
  }
}