Red Hat Training

A Red Hat training course is available for Red Hat Fuse

Chapter 5. Creating integrations

After some planning and preparation, you are ready to create an integration. In the Ignite web interface, when you click Create Integration, Ignite guides you through the procedure to create an integration.

It is assumed that you are familiar with the information in these topics:

The following topics provide information and instructions for creating an integration:

5.1. Preparing to create an integration

Preparation for creating an integration starts with answers to the questions listed in Section 1.5, “Planning integrations”. After you have a plan for the integration, you need to do the following before you can create the integration:

  1. Determine whether an application that you want to connect to uses the OAuth protocol. For each application that uses OAuth, register Ignite as a client that is authorized to access that application. See Section 3.1.2, “Obtaining authorization to access applications”.
  2. Determine whether an application that you want to connect to uses HTTP basic authentication. For each application that does, identify the user name and password for accessing that application. You need to provide this information when you create the integration.
  3. For each application that you want to integrate, create a connection. See Section 3.1.1, “About creating connections”.

5.2. Procedure for creating an integration

To create an integration:

  1. In the left panel in Ignite, click Integrations.
  2. In the upper right, click Create Integration.

  3. Choose and configure the start connection:

    1. On the Choose a Start Connection page, click the connection you want to use to start the integration. When this integration is running, Ignite will connect to this application and obtain data that you want the integration to operate on.
    2. On the Choose an Action page, click the action you want this connection to perform. The available actions vary for each connection.
    3. On the page for configuring the action, enter values in the fields.
    4. Click Done to add the start connection.

  4. Choose and configure the finish connection:

    1. On the Choose a Finish Connection page, click the connection you want to use to complete the integration. When this integration is running, Ignite will connect to this application with the data that the integration has been operating on.
    2. On the Choose an Action page, click the action you want this connection to perform. The available actions vary for each connection.
    3. On the page for configuring the action, enter values in the fields.
    4. Click Done to add the finish connection.
  5. Optionally, add one or more connections between the start connection and the finish connections. For each connection, choose its action and enter any required configuration details.
  6. Optionally, add one or more steps that operate on integration data between connections. See Section 5.3, “Adding steps between connections”.
  7. When the integration contains all needed steps, click Save as Draft or Publish according to whether you want to start running the integration.
  8. In the Integration Name field, enter a name that distinguishes this integration from any other integrations.
  9. In the Description field, enter a description, for example, you can indicate what this integration does.
  10. If you are ready to start running the integration, in the upper right, click Publish. Otherwise, click Save as Draft.

In the Ignite Integrations page, you can see your new integration in the list of integrations. If you published the integration, then you can see that Ignite is in the process of publishing it. It may take a few moments for the status of the integration to become Published, which means that it is running. If you saved the integration as a draft, then Draft appears on the integration’s entry.

Click the integration’s entry to see a summary of the integration, including its version history, logs for each execution, and aggregate execution metrics.

5.3. Adding steps between connections

After you add connections to an integration, you can optionally add steps between connections. Each step operates on data obtained from the previous connection(s) and any other previous steps and makes the data available to the next step in the integration.

Often, you must map data fields that are received from a connection to data fields that the next connection in the integration can operate on. After you add all connections to your integration, check the integration visualization panel on the left. For each connection that requires data mapping before it can operate on the input data, Ignite displays DataTypeMismatchWarning . Click this icon to see Data Type Mismatch: Add a data mapping step before this connection to resolve the difference. Click the link in the message to display the Configure Mapper page in which you specify the data mapping step.

For details about adding additional steps, see the following topics:

5.3.1. Add a data mapping step

You can add a step to an integration to map data from the previous connection(s) and any other steps to the next connection. For example, suppose the integration data contains a Name field and the next connection in the integration has a CustomerName field. You need to map the source Name field to the target CustomerName field.

When you add a data mapper step you might be creating a new integration or editing an integration. The flow of the integration appears in the left panel.

To add a data mapper step:

  1. In the left panel, where you want to add a data mapper step, hover over the PlusSignToAddStepOrConnection .
  2. In the popup that appears, click Add a Step.
  3. On the Choose a Step page, click Data Mapper.

For details, see Chapter 6, Mapping data to fields for the next connection.

5.3.2. Add a basic filter step

You can add a step to an integration to filter the data that the integration operates on. In a filter step, Ignite inspects the data and continues the integration only if the content meets criteria that you define. For example, in an integration that obtains data from Twitter, you can specify that you want to continue the integration by operating only on tweets that contain "Red Hat".

Add all connections to your integration before you add additional steps. When you add a step, Ignite operates on the data it receives from the previous connection(s) and any other previous step(s).

If you cannot define the filter you need in a basic filter step, see Section 5.3.3, “Add an advanced filter step”.

You can add a step when you are creating an integration or editing an integration. The flow of the integration appears in the left panel. To add a filter step:

  1. In the left panel, where you want to add a filter step to the integration, hover over the PlusSignToAddStepOrConnection and in the popup that appears, click Add a Step.
  2. On the Add a Step page, click Basic Filter.

  3. On the Configure Basic Filter Step page, in the Continue only if incoming data match field, select one of the following options:

    • Accept the default that all defined rules must be satisfied.
    • Indicate that only one rule must be satisfied by selecting ANY of the following.

  4. Define the filter rule:

    1. For this field: In the field on the left, enter the name of the field that contains the content you want the filter to evaluate. For example, suppose the data coming in to the step consists of tweets that mention your Twitter handle. You want to continue the integration only when the tweet contains certain content. The tweet is in a field named text so you enter or select text as the value in the first field.

      You can define the field value in the following ways:

      • Start typing. The data name field has a typeahead feature that provides a list of possible completions for you in a pop-up box. Select the correct one from the box.
      • Click in the text field. A dropdown box appears with a list of available fields. Select the field of interest from the list.
    2. This condition must be satisfied: In the middle field, select a condition from the dropdown box. The setting defaults to Contains. For the integration to continue, the condition that you select in this field must be true for the value that you enter in the third field.
    3. For this value: In the third field, enter a value to filter on. For example, if you want to operate on mentions of a certain product from the Twitter feed, you would enter the product name here.

  5. Optionally, click + Add another rule and define another rule.

    You can delete a rule by clicking the trash can icon next to the entry.

  6. When the filter step is complete, click Done to add it to the integration.

5.3.3. Add an advanced filter step

In a filter step, Ignite inspects the data and continues the integration only if the content meets criteria that you define. If the basic filter step does not let you define the exact filter you need, then add an advanced filter step.

Add all connections to your integration before you add additional steps. When you add a step, Ignite operates on the data it receives from the previous connections and any additional step(s).

When you add a step you might be creating a new integration or editing an integration. The flow of the integration appears in the left panel.

To add an advanced filter step:

  1. In the left panel, where you want to add an advanced filter step to the integration, hover over the PlusSignToAddStepOrConnection and in the popup that appears, click Add a Step.
  2. Select Advanced Filter.
  3. In the edit box, use the Camel Simple Expression language to specify a filter expression.
  4. Click Done.

5.3.4. Add a log step

Ignite provides log information for each integration version that it executes. To learn what information is automatically logged, see Section 7.5, “Viewing integration log information”.

To log additional information between any two steps, add a log step to the integration. For each message that it receives, a log step can provide one or more of the following:

  • The message’s header, which provides metadata about the message.
  • The message’s body, which provides the content of the message.
  • Text that you specify either explicitly or through evaluation of an Apache Camel Simple language expression.

To add a log step, you must be creating a new integration or editing an integration. The integration must already have its start and finish connections.

To add a log step:

  1. In the integration visualization panel on the left, hover over the Plus Sign at the location where you want to add a log step.
  2. In the popup, click Add a Step.
  3. On the Choose a Step page, click Log.

  4. On the Configure Log Step page, select the content that you want to log. If you select Custom text, then in the text input field, enter one of the following:

    • The text that you want to log
    • A Camel Simple language expression

    If you enter an expression, Ignite resolves the expression and logs the resulting text.

  5. When log step configuration is complete, click Done.
  6. When the integration is complete, publish it to start seeing output from the new log step.

After an integration that has a log step has been executed, output from its log step appears in the integration’s Activity tab. See Section 7.5, “Viewing integration log information”.

5.3.5. Add a custom step

If Ignite does not provide a step that you need in an integration, a developer can define one or more custom steps in an extension. A custom step operates on integration data between connections. See Section 4.2.2, “Making custom features available”.

You add a custom step to an integration in the same way that you add a built-in step. Create an integration, choose the start and finish connections, add other connections as needed and then add additional steps. When you add a step, Ignite operates on the data it receives from the previous step(s).

When you click Add a Step, the list of available steps includes any custom steps that are defined in extensions that were uploaded to your installation of Ignite.

At the top of the list of steps, in the Name field, you can select Custom Steps to display only custom steps.

Click the custom step that you want to add to the integration. Ignite prompts you for any information required to perform the step. This information varies for each custom step.