Red Hat Training

A Red Hat training course is available for Red Hat Fuse

Chapter 10. Developing extensions for Ignite integrations

Ignite is a Red Hat Fuse feature that provides a web interface for integrating applications. Without writing code, a business expert can use Ignite to connect to applications and optionally operate on data between connections to different applications. If Ignite does not provide a feature that an integrator needs, then a developer can create an extension that defines the needed behavior.

You can use Fuse Tooling to develop extensions that provide features for use in Ignite. An extension defines:

  • One or more custom steps that operate on data between connections in an integration

    or

  • One custom connector

In Ignite, a connector represents a specific application to obtain data from or send data to. Each connector is a template for creating a connection to that specific application. For example, the Salesforce connector is the template for creating a connection to Salesforce. If Ignite does not provide a connector that the Ignite user needs, you can develop an extension that defines a custom connector.

In Ignite, a data operation that happens between connections in an integration is referred to as a step. Ignite provides steps for operations such as filtering and mapping data. To operate on data between connections in ways that are not provided by Ignite built-in steps, you can develop an Ignite extension that defines one or more custom steps.

10.1. Overview of tasks

Here is an overview of the tasks for developing an Ignite extension:

  1. In Red Hat Developer Studio, create an Ignite extension project and select Custom Connector or Custom Step as the extension type.

  2. Depending on the extension type, write the code for the extension:

    • For a Custom Connector: Define the base Camel component, the connector icon, global connector properties, and the connector actions.
    • For a Custom Step: Add routes, define actions, and specify any dependencies.
  3. Build a .jar file.
  4. Provide the .jar file to the Ignite user.

The Ignite user uploads the .jar file to Ignite and can then add the custom connector or custom step defined in the extension to an integration. The Ignite user uploads the .jar file to Ignite, which makes the custom connector or custom step(s) available for use. For information about Ignite and how to create integrations, see Integrating Applications with Ignite.

10.2. Prerequisites

Before you begin, you need the following information and knowledge:

  • A description of the required functionality for the Ignite custom connector or step (from the Ignite user).
  • The Ignite version number for the extension.
  • For a custom connector, an icon image file in PNG or SVG format. Ignite uses this icon when it displays the flow of an integration. If you do not provide an icon, then Ignite generates one when the .jar that contains the extension is uploaded.

  • You should be familiar with:

    • Ignite
    • Spring Boot XML or Java
    • Apache Camel routes (if you want to create a route-based step extension)
    • JSON
    • Maven

10.3. Creating a custom connector

In Ignite, a custom connector consists of one or more connection configuration parameters, one or more connection actions, and optional configuration parameters for each action.

Here is an overview of the tasks for developing a custom connector:

  1. In Red Hat Developer Studio, create an Ignite extension project and select Custom Connector as the extension type.
  2. Write the code for the extension. Define the base Camel component, the connector icon, global connector properties, and the connector actions.

10.3.1. Creating an Ignite Extension project for a custom connector

A Fuse Tooling Ignite extension project provides a starting point for a custom connector.

To create a Fuse Tooling Ignite extension project, follow these steps:

  1. In Red Hat Developer Studio, select New → Project → Red Hat Fuse → Fuse Ignite Extension Project.

    The New Fuse Ignite Extension Project wizard opens.

    IgniteExtWiz page1

  2. Enter the name and location for the project, then click Next.

    IgniteExtWiz page2
  3. Select the Fuse Ignite version.

  4. Specify the following extension details:

    • ID — A value that you define and that is unique in the Ignite environment. This value will be visible in Ignite when the Ignite user imports the extension .jar file.
    • Name — The name of the extension. This value will be visible in Ignite as the extension name. In Ignite, on the Customizations → Extensions tab, the user can see a list of the names and descriptions of extensions that have been uploaded to Ignite.
    • Description — An optional description of the extension content.
    • Version — The version of the extension. For example, if this is the initial version, you could type 1.0. If you are updating a version, you could type 1.1 or 2.0.

  5. Select Custom Connector for the kind of Fuse Ignite extension that you want to create.

    IgniteExtWiz connector
  6. Click Finish.

The new project appears in the Red Hat Developer Studio Project Explorer view. It includes the following files for a custom connector extension:

  • In the src/main/resources/META-INF/syndesis folder:

    • A descriptor file: syndesis-extension-definition.json

      This is the file that you edit to: * Add top-level global properties, connector actions, and action properties. * Change the Extension Id, Name, Version, or Description values.

    • A default icon image file: icon.png

      You can optionally replace this file with your own icon image (PNG or SVG) file.

  • A Maven Project Object Model file: pom.xml

    This file contains information about the project and configuration details used by Maven to build the project, including default extension dependencies. You edit this file to add custom dependencies. The scope for any dependency that Red Hat ships is provided, for example: 

    <dependency>
    <groupId>io.syndesis.extension</groupId>
    <artifactId>extension-api</artifactId>
    <scope>provided</scope>
</dependency>
<dependency>
    <groupId>org.apache.camel</groupId>
    <artifactId>camel-core</artifactId>
    <scope>provided</scope>
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter</artifactId>
    <scope>provided</scope>
</dependency>

10.3.2. Writing code for the custom connector

After you create the Ignite extension project, you write the code that defines the custom connector elements based on the description of the required functionality provided to you by the Ignite user. The Table 10.1, “Custom connector elements” table shows how the elements of the custom connector that you create in Fuse Tooling correspond to elements in Ignite.

Table 10.1. Custom connector elements

Fuse Tooling elementIgnite elementDescription

Global (top-level) property

Connection configuration parameter

When an Ignite user creates a connection from this connector, the user specifies a value for this property as part of the configuration of the connection.

Action

Connection action

In Ignite, for a connection created from this connector, an Ignite user selects one of these actions.

Property defined in an action

An action configuration parameter

When an Ignite user configures the action that the connection performs, the Ignite user specifies a value for this property as part of the configuration of the action.

To write the code that implements a custom connector for Ignite:

  1. Open the syndesis-extension-definition.json file in the Editor view and write the code that defines the global properties, the actions that the custom connector can perform, and each action’s properties.

    Each global property corresponds to a connection configuration parameter in Ignite. Each action property corresponds to an Ignite connection actionconfiguration parameter. In Ignite, when the user selects a custom connector, Ignite prompts for values for each connection configuration parameter. A custom connector can be for an application that uses the OAuth protocol. In this case, be sure to specify a global property for the OAuth client ID and another global property for the OAuth client secret. The Ignite user will need to specify values for these parameters for a connection created from this connector to work.

    Each connector action declares a base Camel component scheme.

    The example provided by the New Fuse Ignite Extension Project wizard uses the telegram Camel component scheme: 

    {
  "schemaVersion" : "v1",
  "name" : "Example Ignite Extension",
  "extensionId" : "ignite.extension.example",
  "version" : "1.0.0",
  "actions" : [ {
    "id" : "io.syndesis:telegram-chat-from-action",
    "name" : "Chat Messages",
    "description" : "Receive all messages sent to the chat bot",
    "descriptor" : {
      "componentScheme" : "telegram",
      "inputDataShape" : {
        "kind" : "none"
      },
      "outputDataShape" : {
        "kind" : "java",
        "type" : "org.apache.camel.component.telegram.model.IncomingMessage"
      },
      "configuredProperties" : {
        "type" : "bots"
      }
    },
    "actionType" : "connector",
    "pattern" : "From"
  }, {
    "id" : "io.syndesis:telegram-chat-to-action",
    "name" : "Send a chat Messages",
    "description" : "Send a messages to the chat (through the bot).",
    "descriptor" : {
      "componentScheme" : "telegram",
      "inputDataShape" : {
        "kind" : "java",
        "type" : "java.lang.String"
      },
      "outputDataShape" : {
        "kind" : "none"
      },
      "propertyDefinitionSteps" : [ {
        "description" : "Chat id",
        "name" : "chatId",
        "properties" : {
          "chatId" : {
            "kind" : "parameter",
            "displayName" : "Chat Id",
            "type" : "string",
            "javaType" : "String",
            "description" : "The telegram's Chat Id, if not set will use CamelTelegramChatId from the incoming exchange."
          }
        }
      } ],
      "configuredProperties" : {
        "type" : "bots"
      }
    },
    "actionType" : "connector",
    "pattern" : "To"
  } ],
  "properties" : {
    "authorizationToken" : {
      "kind" : "property",
      "displayName" : "Authorization Token",
      "group" : "security",
      "label" : "security",
      "required" : true,
      "type" : "string",
      "javaType" : "java.lang.String",
      "secret" : true,
      "description" : "Telegram Bot Authorization Token"
    }
  }
}

  2. If the custom connector requires additional dependencies, add them to the project’s pom.xml file. The default scope for dependencies is runtime. If you add a dependency that Red Hat ships, define its scope as provided, for example: 

    <dependencies>
    <dependency>
          <groupId>org.apache.camel</groupId>
          <artifactId>camel-telegram</artifactId>
          <scope>provided</scope>
    </dependency>
      </dependencies>

When you finish writing the code for the custom connector, build the .jar file as described in Section 10.5, “Building the Ignite extension JAR file”.

10.4. Creating custom steps

After you create the Ignite extension project, you write the code that defines the custom steps based on the description of the required functionality provided to you by the Ignite user. Within a single extension, you can define more than one custom step and you can define each custom step with Camel routes or with Java beans.

10.4.1. Creating an Ignite Extension project for custom steps

To create a Fuse Tooling Ignite extension project, follow these steps:

  1. In Red Hat Developer Studio, select New → Project → Red Hat Fuse → Fuse Ignite Extension Project.

    The New Fuse Ignite Extension Project wizard opens.

    IgniteExtWiz page1

  2. Enter the name and location for the project, then click Next.

    IgniteExtWiz page2
  3. Select the Fuse Ignite version.

  4. Specify the following extension details:

    • ID — A value that you define and that is unique in the Ignite environment. This value will be visible in Ignite when the Ignite user imports the extension .jar file.
    • Name — The name of the extension. This value will be visible in Ignite as the extension name. In Ignite, on the Customizations → Extensions tab, the user can see a list of the names and descriptions of extensions that have been uploaded to Ignite.
    • Description — An optional description of the extension content.
    • Version — The version of the extension. For example, if this is the initial version, you could type 1.0. If you are updating a version, you could type 1.1 or 2.0.
  5. Select Custom Step for the kind of Fuse Ignite extension that you want to create.

  6. Select the template for the custom step:

    IgniteExtWiz step
    • Camel route — Provides a sample Camel route.

    • Java bean — Provides a sample Java bean.

      Note

      The template that you select provides a starting point for your project. If you want to create one or more custom steps based on Camel routes and one or more other custom steps based on Java beans within the same extension, start with one of the templates and then add the needed file and dependencies for the other type of custom step.

  7. Click Finish.

The new project appears in the Red Hat Developer Studio Project Explorer view. It includes the following files depending on the template that you selected for the custom step:

  • In the src/main/resources/META-INF/syndesis folder:

    • A descriptor file: syndesis-extension-definition.json

      This is the file that you edit to: * Add one or more actions. An action in the `.json `file becomes a custom step in Ignite. In an action element, a property in the `.json `file becomes a step configuration parameter in Ignite. * Change the Extension Id, Name, Version, or Description values.

    • For a Camel route template, a Camel context file: extensions/log-body-action.xml

      This file contains a sample route with a log component. You customize the Camel routes in this file.

    • For a Java bean template, a Java file: extensions/extension.java

      This file contains a sample POJO-based logging extension.

  • A Maven Project Object Model file: pom.xml

    This file contains information about the project and configuration details used by Maven to build the project, including default extension dependencies. You edit this file to add custom dependencies. The scope for any dependency that Red Hat ships is provided, for example: 

    <dependency>
    <groupId>io.syndesis.extension</groupId>
    <artifactId>extension-api</artifactId>
    <scope>provided</scope>
</dependency>
<dependency>
    <groupId>org.apache.camel</groupId>
    <artifactId>camel-core</artifactId>
    <scope>provided</scope>
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter</artifactId>
    <scope>provided</scope>
</dependency>

10.4.2. Writing code for the custom step

After you create the Ignite extension project, you write the code that defines the custom step(s)based on the description of the required functionality provided to you by the Ignite user.

Table 10.2, “Custom step elements” shows how the elements of the custom step that you create in Fuse Tooling correspond to elements in Ignite.

Table 10.2. Custom step elements

Fuse Tooling elementIgnite elementDescription

Action

Custom Step

In Ignite, after the user imports the step extension, the custom step(s) appear(s) on the Choose a step page.

Property defined in an action

A custom step configuration parameter

In Ignite, when the user selects a custom step, Ignite prompts for values for configuration parameters.

To write the code that implements a custom step for Ignite:

  1. For a Camel route-based step, in the extension.xml file, create routes that address the purpose of the extension. The entrypoint of each route must match the entrypoint that you define in the syndesis-extension-definition.json file, as described in Step 2.

    For a Java bean-based step, edit the java file.

  2. In the syndesis-extension-definition.json file, write the code that defines the actions and their properties. You need a new action for each entrypoint.

    Each action that you create corresponds to a custom step in Ignite. You can use different types of code for each action. That is, you can use a Camel route for one action and a Java bean for another action.

    Each property corresponds to an Ignite step configuration parameter. In Ignite, when the user selects a custom step, Ignite prompts for values for configuration parameters. For example, a custom log step might have a level parameter that indicates how much information to send to the log.

    Here is the template for the .json file that contains the extension metadata, including properties that will be filled in by the user in Ignite after uploading the extension and adding its custom step to an integration: 

    {
  "actions": [
    {
      "actionType": "extension",
      "id": "${actionId}",
      "name": "Action Name",
      "description": "Action Description",
      "tags": [
           "xml"
      ],
      "descriptor": {
        "kind": "ENDPOINT|BEAN|STEP",
        "entrypoint": "direct:${actionId}",
        "inputDataShape": {
          "kind": "any"
        },
        "outputDataShape": {
          "kind": "any"
        },
        "propertyDefinitionSteps": []
      }
    }
  ],
  "tags": [
    "feature",
    "experimental"
  ]
}
    Note

    The tags are ignored in this release. They are reserved for future use.

  3. To edit the extension dependencies, open the `pom.xml `file in the editor. If you add a dependency, you must define its scope.

When you finish writing the code for the custom step(s), build the .jar file as described in Section 10.5, “Building the Ignite extension JAR file”.

10.5. Building the Ignite extension JAR file

To build the .jar file for the extension:

  1. In the Project Explorer view, right-click the project.
  2. From the context menu, select Run As → Maven clean verify.
  3. In the Console view, you can monitor the progress of the build.
  4. When the build is complete, refresh the target folder in the Project Explorer view (select the project and then press F5).

  5. In the Project Explorer view, open the target folder to see the generated .jar file:

    The name of the .jar file follows Maven defaults: ${artifactId}-${version}.jar

    For example: custom:step-camel-1.0.0.jar

    This .jar file defines the extension, its required dependencies, and its metadata: Extension Id, Name, Version, Tags, and Description. For example: 

    {
    "schemaVersion" : "v1",
    "name" : "Example Ignite Extension",
    "description" : "Logs a message body with a prefix",
    "extensionId" : "ignite.extension.example",
    "version" : "1.0.0",
    "actions" : [ {
        "id" : "Log-body",
        "name" : "Log Body",
        "description" : "A simple xml Body Log with a prefix",
        "descriptor" : {
            "kind" : "ENDPOINT",
            "entrypoint" : "direct:log-xml",
            "resource" : "classpath:META-INF/syndesis/extensions/log-body-action.xml",
            "inputDataShape" : {
                "kind" : "any"
            },
            "outputDataShape" : {
                "kind" : "any"
            },
            "propertyDefinitionSteps" : [ {
                "description" : "Define your Log message",
                "name" : "Log Body",
                "properties" : {
                    "prefix" : {
                        "componentProperty" : false,
                        "deprecated" : false,
                        "description" : "The Log body prefix message",
                        "displayName" : "Log Prefix",
                        "javaType" : "String",
                        "kind" : "parameter",
                        "required" : false,
                        "secret" : false,
                        "type" : "string"
                    }
                }
            } ]
        },
        "tags" : [ "xml" ],
        "actionType" : "step"
    } ],
    "dependencies" : [ {
        "type" : "MAVEN",
        "id" : "io.syndesis.extension:extension-api:jar:1.3.0.fuse-000014"
    } ],
    "extensionType" : "Steps"
}

10.6. Providing the JAR file to the Ignite user

Provide the following to the Ignite user:

  • The .jar file
  • A document that describes the extension. For a step extension, include information about data shapes that each action in the step extension requires as input or provides as output (for data mapping).

In Ignite, the user uploads the .jar file as described in Integrating Applications with Ignite.