Red Hat Training

A Red Hat training course is available for Red Hat Fuse

Chapter 4. Adding and managing customizations

Ignite lets you add API client connectors and custom steps to integrations. A custom step operates on integration data between connections. See the following topics for details:

4.1. Adding REST API client connectors

Ignite can create connectors for Representational State Transfer Application Programming Interfaces (REST APIs) that support Hypertext Transfer Protocol (HTTP). To do this, Ignite requires a valid Swagger 2.0 specification that describes a REST API that you want to connect to. If the API service provider does not make a Swagger specification available then you must create the Swagger specification.

The following topics provide information and instructions for adding REST API connectors:

After you create a REST API client connector, for details about using that connector in an integration, see Section 3.10, “Connecting to REST APIs”.

4.1.1. Requirements for API client connectors

After you upload a Swagger specification to Ignite, a connector to the API becomes available. An integrator can select the connector, create an API client connection, and then add that connection to an integration.

When Ignite creates an API client connector, it maps each resource operation in the Swagger specification to an action. The action name and action description comes from documentation in the Swagger specification.

Ignite connectors support OAuth 2.0 and HTTP Basic Authorization. If access to the API requires Transport Layer Security (TLS) then the API needs to use a valid certificate that is issued by a recognized Certificate Authority (CA).

An API that uses OAuth must have an authorization URL that takes a client callback URL as input. For Ignite to obtain authorization to access an API that uses OAuth, you provide the Ignite callback URL at the client API authorization URL. The details for doing this are described in Section 3.10.1, “Register Ignite as an API client”.

Ignite cannot create connectors for APIs that support the HTTP 2.0 protocol.

4.1.2. About Swagger specification content

The following topics provide information about the content of the Swagger specification that Ignite uses to create a connector to a REST API:

4.1.2.1. Guidelines for Swagger specifications

The more detail that the Swagger specification provides, the more support Ignite can offer when connecting to the API. For example, the API definition is not required to declare data types for requests and responses. Without type declarations, Ignite defines the corresponding connection action as typeless. However, in an integration, you cannot add a data mapping step immediately before or immediately after an API connection that performs a typeless action.

One remedy for this is to add more information to the Swagger specification before you upload it to Ignite. Identify the Swagger resource operations that will map to the actions you want the API connection to perform. In the Swagger specification, ensure that there is a JSON schema that specifies each operation’s request and response types.

If the Swagger specification for the API declares support for application/json content type and also application/xml content type then the connector uses the JSON format. If the Swagger specification specifies consumes or produces parameters that define both application/json and application/xml, then the connector uses the JSON format.

4.1.2.2. Providing client credentials in parameters

When Ignite tries to obtain authorization to access an OAuth2 application, it uses HTTP basic authentication to provide client credentials. If you need to, you can change this default behavior so that Ignite passes client credentials to the provider as parameters instead of using HTTP basic authentication. This affects the use of the tokenUrl endpoint that is used to obtain an OAuth access token.

Important

To specify that Ignite should pass client credentials as parameters, in the securityDefinitions section of the Swagger specification, add the x-authorize-using-parameters vendor extension with a setting of true. In the example below, the last line specifies x-authorize-using-parameters:

securityDefinitions:
  concur_oauth2:
    type: 'oauth2'
    flow: 'accessCode'
    authorizationUrl: 'https://example.com/oauth/authorize'
    tokenUrl: 'https://example.com/oauth/token'
    scopes:
      LIST: Access List API
    x-authorize-using-parameters: true

The setting of the x-authorize-using-parameters vendor extension is true or false:

  • true indicates that client credentials are in parameters.
  • false, the default, indicates that Ignite uses HTTP basic authentication to provide client credentials.

4.1.2.3. Automatically refreshing access tokens

If an access token has an expiration date, then Ignite integrations that use that token to connect to an application stop running successfully when the taken expires. To obtain a new access token, you must either reconnect to the application or re-register with the application.

If you need to, you can change this default behavior so that Ignite automatically requests a new access token in the following situations:

  • When the expiration date has been reached.
  • When HTTP response status codes that you specify are received.
Important

To specify that Ignite should automatically try to obtain a new access token in the situations described, in the securityDefinitions section of the Swagger specification, add the x-refresh-token-retry-statuses vendor extension. The setting of this extension is a comma separated list that specifies HTTP response status codes. When an access token’s expiration date is reached or when Ignite receives a message from an OAuth2 provider and the message has one of these response status codes, then Ignite automatically tries to obtain a new access token. In the example below, the last line specifies x-refresh-token-retry-statuses:

securityDefinitions:
  concur_oauth2:
    type: 'oauth2'
    flow: 'accessCode'
    authorizationUrl: 'https://example.com/oauth/authorize'
    tokenUrl: 'https://example.com/oauth/token'
    scopes:
      LIST: Access List API
    x-refresh-token-retry-statuses: 401,402,403
Note

Sometimes, an API operation fails and a side effect of that failure is that the access token is refreshed. In this situation, even when obtaining a new access token is successful, the API operation still fails. In other words, Ignite does not retry the failed API operation after it receives the new access token.

4.1.3. Creating API client connectors

To create an API client connector:

  1. In the Ignite navigation panel, click Customizations to display the API Client Connectors tab. Any API client connectors that are already available are listed here.
  2. Click Create API Connector.
  3. On the Create API Client Connector page, do one of the following:

    • Click Browse and select the Swagger file that you want to upload.
    • Select Use a URL and paste the URL for your Swagger specification in the input field.
  4. Click Next. If there is invalid or missing content, Ignite displays information about what needs to be corrected. Select a different Swagger file to upload or click Cancel, revise the Swagger file, and upload the updated file.

    If the specification is valid and complete, Ignite displays a summary of the actions that the connector will provide. This might include errors and warnings about the action specifications.

  5. To revise the Swagger file, click Cancel, revise the Swagger file, and upload the updated file.

    If you are satisfied with the action summary, click Next.

  6. Indicate the API’s security requirements by selecting one of the following:

    1. No Security
    2. HTTP Basic Authorization — Enter the user name and password you want to use to access the API.
    3. OAuth — Ignite prompts you to enter:

      1. Authorization URL is the location for registering Ignite as a client of the API. Registration authorizes Ignite to access the API. See Section 3.10.1, “Register Ignite as an API client”. The Swagger specification or other documentation for the API should specify this URL. If it does not then you must contact the service provider to obtain this URL.
      2. Access Token URL is required for OAuth authorization. Again, the Swagger specification or other documentation for the API should provide this URL. If it does not then you must contact the service provider.
  7. Click Next. Ignite displays the connector’s name, description, host, and base URL as indicated by the Swagger file. For connections that you create from this connector,

    • Ignite concatenates the host and base URL values to define the endpoint for the connection. For example, if the host is https://example.com and the base URL is /api/v1 then the connection endpoint is https://example.com/api/v1.
    • Ignite applies the schema specified in the Swagger file to data mapping steps. If the Swagger file supports more than one schema then Ignite uses the TLS (HTTPS) schema.
  8. Review the connector details and optionally upload an icon for the connector. If you do not upload an icon, Ignite generates one. You can upload an icon at a later time. When Ignite displays the flow of an integration, it displays a connector’s icon to represent connections that are created from that connector.

    To override a value obtained from the Swagger file, edit the field value that you want to change. After Ignite creates a connector, you cannot change it. To effect a change, you need to upload an updated Swagger file so that Ignite can create a new connector.

  9. When you are satisfied with the connector details, click Create API Connector.

For details about using your new API connector, see Section 3.10, “Connecting to REST APIs”.

4.1.4. Updating API client connectors

You cannot update an API client connector. If there is an update to the API’s Swagger specification, then you must upload an updated Swagger file and create a new API client connector.

To update integrations to use connections based on the updated Swagger specification:

  1. Create a new API client connector based on the updated Swagger specification.
  2. Create a new connection from the new connector.
  3. Edit the integration to remove the old connection and add the new connection.
  4. Publish the updated integration.

4.1.5. Deleting API client connectors

You cannot delete a connector when there is a connection that was created from that connector and this connection is being used in an integration. After you delete an API client connector, you cannot use a connection that was created from that connector.

To delete an API client connector:

  1. In the left panel, click Customizations.
  2. In the API Client Connectors tab, to the right of the name of the connector that you want to delete, click Delete.
  3. Read the confirmation popup to be sure that you want to click Delete.

4.2. Adding extensions

Extensions let you add customizations to Ignite so you can integrate applications the way you want to.

The following topics provide details:

4.2.1. About extensions

If Ignite does not provide a feature that you need, then a developer can code an extension that lets you integrate data the way you need to. An extension defines one of the following:

  • A single custom connector for creating connections to a particular application or service that you want to integrate.
  • One or more custom steps that operate on integration data between connections.
  • A JDBC driver for connecting to a proprietary SQL database, such as Oracle.

Share your requirements with a developer who codes the extension. The developer gives you a .jar file that contains the extension. You then upload the .jar file in Ignite to make the custom connector, custom step(s), or JDBC driver available for use within Ignite.

An extension .jar file that you upload to Ignite always contains exactly one extension.

For an example of uploading and using an extension that provides a step that operates on data between connections, see the AMQ to REST API sample integration tutorial.

For custom connectors and custom steps, information about coding the extension and creating the .jar file is in the Tooling User Guide.

For information about creating extensions that provides JDBC drivers, see Section 4.2.4, “Creating JDBC driver library extensions”.

4.2.2. Making custom features available

To make a custom feature available for use in an integration, you upload the extension to Ignite as follows:

  1. In the left Ignite panel, click Customizations.
  2. At the top, click Extensions.
  3. Click Import Extension.
  4. Drag and drop, or choose, the .jar file that contains the extension that you want to upload.

    A developer needs to make this file available to you. Ignite immediately tries to validate that the file contains an extension. If there is a problem, Ignite displays a message about the error. You must coordinate with the extension developer to obtain an updated .jar file, which you can then try to upload.

  5. Review the extension details.

    After Ignite validates the file, it extracts and displays the extension’s name, ID, description, and type. The type indicates whether the extension defines a custom connector, or one or more custom steps for operating on data between connections, or a JDBC driver for a proprietary database. An extension that provides a JDBC driver is referred to as a library extension.

    For a connector extension, Ignite displays the actions that are available to a connection that is created from this custom connector. In the extension, the developer might have provided an icon that Ignite can use to represent the application connections created from this connector. While you do not see this icon in the extension details page, it appears when you create connections from the custom connector. If the extension developer did not provide an icon in the extension, then Ignite generates an icon.

    For a step extension, Ignite displays the name of each custom step that the extension defines.

    For a library extension, if this extension contains a newer version of a JDBC driver that you previously uploaded, then you must remove the older version from your classpath. Ensure that your classpath has only one version of this driver and that the reference is to the newer driver you are uploading. Integrations that are running and that use connections based on the older driver are not affected. New connections that you create will use the new driver. If you publish an integration that has a connection that was created with the older driver, Ignite automatically uses the new driver instead.

  6. Click Import Extension. Ignite makes the custom connector or custom step(s) available and displays the extension’s details page.

See also:

4.2.3. Managing extensions

After you start using customizations provided in extensions, you can identify the integrations that use those customizations. This is helpful to do before you update or delete an extension.

For details, see:

4.2.3.1. Identifying integrations that use extensions

Before you update or delete an extension, you should identify the integrations that use customizations provided by that extension. To do this:

  1. In the left Ignite panel, click Customizations.
  2. At the top, click Extensions.
  3. In the list of extensions, find the entry for the extension that you want to update or delete and click it.

Ignite displays details about the extension including a list of any integrations that use a customization provided by the extension.

4.2.3.2. Updating extensions

To update an extension:

  1. Obtain an updated .jar file for the extension from the developer.
  2. In Ignite, in the left panel, click Customizations.
  3. Click the Extensions tab.
  4. At the right of the entry for the extension that you want to update, click Update.
  5. Click Browse, select the updated .jar file, and click Open.
  6. Confirm that the extension details are correct and click Update.
  7. In the details page for the updated extension, determine which integrations use the connector or custom step(s) defined in the extension.

It is up to you to know exactly what is required to update each integration that uses a custom connector or a custom step from the updated extension. At the very least, you must stop (click Unpublish) and restart (click Publish) each integration that uses a customization defined in the updated extension. See Section 7.3, “Unpublishing integrations”.

In some cases, you might need to edit the integration to change or add configuration details for a customization. You must communicate with the extension developer to understand how to update integrations.

4.2.3.3. Deleting extensions

You can delete an extension even if a running integration uses a step that is provided by that extension or uses a connection that was created from a connector that was provided by that extension. After you delete an extension, you cannot publish an integration that uses a customization that was provided by that extension.

To delete an extension:

  1. In the left Ignite panel, click Customizations.
  2. At the top, click Extensions.
  3. In the list of extensions, find the entry for the extension that you want to delete and click Delete, which appears at the right of the entry.

There might be unpublished or draft integrations that use a customization provided by an extension that you delete. To publish one of these integrations, you will need to edit the integration to remove the customization. See Section 4.2.3.1, “Identifying integrations that use extensions” and Section 7.10, “Updating integrations”.

4.2.4. Creating JDBC driver library extensions

To connect to a SQL database other than Apache Derby, MySQL, and PostgreSQL, a developer creates an extension that wraps a JDBC driver for the database you want to connect to. After uploading this extension to Ignite, the Ignite-provided Database connector can access the driver to validate and create connections to the proprietary database.

The Syndesis open source community provides a project for creating an extension that wraps a JDBC driver. This kind of extension is referred to as a library extension because the result of uploading the extension is that you can use the built-in Database connector to create connections to your proprietary database. You do not create a new connector for your particular database.

Package one driver only in an extension. This makes it easier to manage the extension as part of managing your particular database. However, it is possible to create a library extension that wraps more than one driver.

To use the Syndesis project, you must have a GitHub account.

To create a JDBC driver library extension:

  1. Ensure access to the JDBC driver for the database you want to connect to by doing one of the following:

    1. Confirm that the driver is in a Maven repository.
    2. Download the driver.
  2. In a browser tab, go to https://github.com/syndesisio/syndesis-extensions
  3. Fork the syndesis-extensions repository to your GitHub account.
  4. Create a local clone from your fork.
  5. In your syndesis-extensions clone:

    1. If the driver is not in a Maven repository, copy the driver into the syndesis-library-jdbc-driver/lib folder.
    2. Edit the syndesis-library-jdbc-driver/pom.xml file:

      1. Update the value of the Name element to be a name that you choose for this extension.
      2. Update the value of the Description element to provide helpful information about this extension.
      3. If the driver is in a Maven repository, ensure that a reference to that Maven repository is in the pom.xml file.
      4. Examine the rest of the content of the pom.xml file and change any relevant metadata as needed.
    3. In the syndesis-library-jdbc-driver folder, execute mvn clean package to build the extension.

The generated .jar file is in the syndesis-library-jdbc-driver/target folder. Provide this .jar file for uploading to Ignite.