Red Hat Training

A Red Hat training course is available for Red Hat Fuse

Chapter 13. Developing extensions for Ignite integrations

Ignite is a Red Hat JBoss 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. In Ignite, a data operation is referred to as a step in an integration.

Ignite provides steps for operations such as filtering and mapping data. To operate on data in ways that are not provided by Ignite built-in steps, you can develop an Ignite extension to define one or more custom steps.

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

  1. In Red Hat JBoss Developer Studio, create an Ignite extension project.
  2. 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 step(s) defined in the extension to an integration. For information about Ignite and how to build integrations, see Integrating Applications with Ignite.

Prerequisites

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

  • A description of the required functionality for the Ignite custom step (from the Ignite user).

  • The version of each of the following components for the extension:

    • Spring Boot
    • Camel
    • Ignite

  • You should be familiar with :

    • Spring Boot XML or Java
    • Apache Camel routes
    • Ignite

Creating an Ignite Extension project

To use the Fuse tooling to create an extension project, follow these steps.

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

    The New Fuse Ignite Extension Project wizard opens.

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

  3. Specify the versions of the extension dependencies:

    • Spring Boot Version
    • Camel Version
    • Fuse Ignite Version
  4. (Optional) Click Verify to confirm that the specified Camel version is available to the project.
  5. Click Next.

  6. Specify the following extension details:

    • Extension id - A value that you define and that is unique in the Ignite environment. This value will be visible in Ignite when the user imports the extension .jar file.
    • Version - The version of the extension. For example, if this is the initial version, you could enter 1.0. If you are updating a version, you could enter 1.1 or 2.0.
    • Name - The name of the extension. This value will be visible in Ignite as the extension’s name. In Ignite, on the 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 custom steps that the extension defines.
    • Tags - An optional comma-separated list of values. Note that these tags are ignored in this release. They are reserved for future use.
  7. Click Finish.

The new project appears in the Red Hat JBoss Developer Studio Project Explorer view. It includes the following files:

  • A descriptor file: META-INF/syndesis/syndesis-extension-definition.json

    This is the file that you edit to add actions and their properties. An action in the .json file becomes a custom step in Ignite. A property becomes an action parameter in Ignite.

  • A Camel context file: extension.xml

    This file contains a sample route with a log component. You customize the Camel routes in this 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 or to edit the Extension Id, Name, Version, Tags, or Description values.

Developing the steps for the Ignite extension

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

  1. 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.

  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 property corresponds to an action parameter. In Ignite, when the user selects a custom step, Ignite prompts for values for action properties. For example, a custom log step might have a level property that indicates how much information to sent to the log.

    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 XML for one action and Spring Boot routes and beans for another action.

    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. The scope for any dependency that Red Hat ships is provided, for example: 

    <dependency>
      <groupId>io.syndesis.integration-runtime</groupId>
      <artifactId>runtime-api</artifactId>
      <version>${syndesis.version}</version>
      <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>

    Note: You can optionally edit the Extension Id, Name, Version, Tags, or Description values.

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 popup 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 and 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}-$6.3.jar

    For example: ignite-extension-1.0.0-SNAPSHOT

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

    {
  "name" : "Syndesis Extension (XML)",
  "description" : "A simple Syndesis Extension (XML)",
  "extensionId" : "com.mycompany:syndesis-extension-example-xml",
  "version" : "1.0.0-SNAPSHOT",
  "tags" : [ "experimental", "feature" ],
  "actions" : [ {
    "id" : "log-body",
    "name" : "simple-log-body",
    "description" : "A simple xml based logging extension",
    "descriptor" : {
      "kind" : "ENDPOINT",
      "entrypoint" : "direct:log-body",
      "inputDataShape" : {
        "kind" : "any"
      },
      "outputDataShape" : {
        "kind" : "any"
      },
      "propertyDefinitionSteps" : [ ]
    },
    "tags" : [ "xml" ],
    "actionType" : "extension"
  } ],
  "dependencies" : [ {
    "type" : "MAVEN",
    "id" : "io.syndesis.integration-runtime:runtime-api:jar:1.2.1"
  }, {
    "type" : "MAVEN",
    "id" : "org.apache.camel:camel-core:jar:2.20.1"
  }, {
    "type" : "MAVEN",
    "id" : "org.springframework.boot:spring-boot-starter:jar:1.5.8.RELEASE"
  } ],
  "properties" : { }
}

Next steps

Provide the following to the Ignite user:

  • The .jar file
  • A document that describes the extension, including information about data shapes that each action in the 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.