Red Hat Training

A Red Hat training course is available for Red Hat Fuse

Connecting Fuse Online to Applications and Services

Red Hat Fuse 7.1

Instructions for Using Provided Connectors

Red Hat Fuse Documentation Team

Abstract

Follow step-by-step instructions for creating connections and adding them to integrations.

Preface

To integrate applications, you create a connection to each application or service that you want to integrate. You then create an integration and add a connection to it for each integration or service that you want to integrate.

Fuse Online supports numerous connectors that serve as templates for creating connections. The following topics provide details for creating connections and adding them to integrations:

Chapter 1. Connectors that are supported by Fuse Online

Fuse Online supports the following connectors.

NameDescription

Amazon S3

Retrieve data from an Amazon S3 bucket or copy data into a bucket.

AMQ

Obtain messages from an ApacheMQ broker or publish messages to an ApacheMQ broker.

AMQP

Obtain messages from an Advanced Message Queue Protocol broker or publish messages to an AMQP broker.

Dropbox

Download files from Dropbox or upload files to Dropbox.

FTP/SFTP

Download files from an FTP or SFTP server or upload files to an FTP or SFTP server.

Gmail

Obtain messages sent to a particular Gmail account and send messages from a particular Gmail account.

HTTP/HTTPS

Connect to an HTTP or HTTPS endpoint and execute the GET, PUT, POST, DELETE, HEAD, OPTIONS, TRACE, OR PATCH method.

Kafka

Obtain streams of records from or publish streams of records to a Kafka topic that you specify

MQTT

Obtain messages from an MQ Telemetry Transport broker or publish messages to an MQTT broker.

REST APIs

Create a custom REST API client connector by uploading an OpenAPI specification. You can then create a connection to that REST API.

Salesforce

Create, update, fetch, or delete a Salesforce record.

SAP Concur

Obtain all SAP Concur lists, obtain a particular list, create a new list, or update a list. Other SAP Concur actions are Technology Preview features.

ServiceNow

Obtain records from or copy records to your ServiceNow instance.

Slack

Send a message to a Slack user or channel.

SQL databases

Invoke a SQL statement or a SQL stored procedure on an Apache Derby, MySQL, or PostgreSQL database. To connect to other types of SQL databases, you upload a Fuse Online library extension that contains a JDBC driver for that database.

Twitter

Trigger execution of an integration upon tweets that mention you or that contain data you specify.

Webhook

Trigger integrations with HTTP GET or POST requests.

If Fuse Online does not provide a connector that you need, an experienced developer can create an extension that defines a custom connector. For information about coding the extension and creating its .jar file, which you upload to Fuse Online, see Tooling User Guide, Developing extensions for Fuse Online integrations and Integrating Applications with Fuse Online, Developing extensions.

Chapter 2. Connecting to Amazon S3

An integration can retrieve data from an Amazon S3 bucket or copy data into an Amazon S3 bucket. To do this, you create an Amazon S3 connection and then add that Amazon S3 connection to an integration. For details, see:

2.1. Prerequisites for creating an Amazon S3 connection

To create an Amazon S3 connection, you must know the following:

  • Amazon S3 access key ID that is associated with the Amazon Web Services (AWS) account that created, or will create, the bucket that you want the connection to access.

    You can create a connection that accesses a bucket that does not yet exist. In this case, when the integration starts running then it use the AWS account associated with this access key ID to try to create the bucket.

  • Amazon S3 secret access key that is associated with the AWS account that created or will try to create (when the integration starts running) the bucket that you want the connection to access.

  • Name of the bucket that you want to access or its Amazon Resource Name (ARN).

    If the bucket you specify does not yet exist then the connection tries to create a bucket with the name that you specify. Because S3 allows a bucket to be used as a URL that can be accessed publicly, the bucket name that you specify must be globally unique. Also, it must meet S3 bucket naming requirements.

    If the bucket you specify does not exist in the AWS account that is associated with the Amazon S3 access key ID, but it does exist in another AWS account, then the connection does not create the bucket and an integration that uses this connection cannot start running.

  • Region in which the bucket is located or the region in which you want the connection to create the bucket.

A user with the login credentials for the AWS account that created or will create the bucket obtains the Amazon S3 keys as follows:

  1. Go to https://aws.amazon.com/s3/.
  2. Hover over My Account, select AWS Management Console and sign in to the console with the AWS account that created the bucket that you want to access or with the account that you want the connection to use to create the bucket.
  3. In the console, in the upper right, click the down arrow next to the user name and click My Security Credentials.
  4. Expand Access Keys and click Create New Access Keys.
  5. Follow the prompts to obtain the keys.

2.2. Create an Amazon S3 connection

To create an Amazon S3 connection:

  1. In Fuse Online, in the left panel, click Connections to display any available connections.
  2. In the upper right, click Create Connection to display Fuse Online connectors.
  3. Click the Amazon S3 connector.
  4. In the Access Key field, enter the Amazon S3 access key ID, provided by AWS, for the AWS account that created the bucket that you want this connection to access. If the bucket you want the connection to access does not already exist then when Fuse Online tries to start running the integration, it uses the AWS account associated with this access key to create the bucket. However, if the bucket already exists in some other AWS account, then the connection cannot create the bucket and the integration cannot start.
  5. In the Bucket Name or Amazon Resource Name field, enter the name of the bucket that you want this connection to access or enter the bucket’s ARN. If the bucket does not already exist in either the AWS account being used or in any other AWS account, then the connection creates it. For details about bucket name requirements, see Section 2.1, “Prerequisites for creating an Amazon S3 connection”.
  6. In the Region field, select the AWS region in which the bucket resides. If the connection creates the bucket, then it creates it in the selected region.
  7. In the Secret Key field, enter the Amazon S3 secret access key, provided by AWS, for the account that created, or will create, the bucket that you want this connection to access.
  8. Click Validate. Fuse Online immediately tries to validate the connection and displays a message that indicates whether or not validation is successful. If validation fails, revise the configuration details as needed and try again.
  9. When validation is successful, click Next.
  10. In the Connection Name field, enter your choice of a name that helps you distinguish this connection from any other connections. For example, enter Obtain S3 Data.
  11. In the Description field, optionally enter any information that is helpful to know about this connection. For example, enter Sample S3 connection that obtains data from the northeast bucket.
  12. In the upper right, click Create to see that the connection you created is now available. If you entered the example name, you would see that Obtain S3 Data appears as a connection that you can choose to add to an integration.

2.3. Add an Amazon S3 connection to an integration

You must create an Amazon S3 connection before you can add an Amazon S3 connection to an integration. If you did not already create an Amazon S3 connection, see Section 2.1, “Prerequisites for creating an Amazon S3 connection”.

The procedure for adding an Amazon S3 connection to an integration varies according to whether you want to use the S3 connection to start the integration, finish the integration, or access data in the middle of the integration. See the following topics:

2.3.1. Start an integration by obtaining data from Amazon S3

To start an integration by obtaining data from an Amazon S3 bucket, add an Amazon S3 connection as the start connection:

  1. In the Fuse Online panel on the left, click Integrations.
  2. Click Create Integration.
  3. On the Choose a Start Connection page, click the Amazon S3 connection that you want to use to start the integration.

  4. On the Choose an Action page, click the action that you want the connection to perform:

    • Get Object obtains a file from the bucket that the connection accesses. In the File Name field, enter the name of the file that you want to obtain. If the specified file is not in the bucket, it is a runtime error.

    • Poll an Amazon S3 Bucket periodically obtains files from the bucket that the connection accesses. To configure this action:

      1. In the Delay field, accept the default of 500 milliseconds as the time that elapses between polls. Or, to specify a different polling interval, enter a number and select its time unit.

      2. In the Maximum Objects to Retrieve field, enter the largest number of files that one poll operation can obtain. The default is 10.

        To have no limit on the number of files that can be obtained, specify 0 or a negative integer. When Maximum Objects to Retrieve is unlimited, the poll action obtains all files in the bucket.

        If the bucket contains more than the specified maximum number of files then the action obtains the files that were most recently modified or created.

      3. In the Prefix field, optionally specify a regular expression that evaluates to a string. If you specify a prefix then this action retrieves a file only when its name starts with that string.
      4. Indicate whether you want to Obtain files and then delete them from the bucket.
  5. After you configure the action, click Done to specify the action’s output type. See Specifying connection action input and output types.

2.3.2. Finish an integration by adding data to Amazon S3

To finish an integration by copying data to Amazon S3, add an Amazon S3 connection as the finish connection:

  1. Start creating the integration.
  2. Add and configure the start connection.
  3. On the Choose a Finish Connection page, click the Amazon S3 connection that you want to use to finish the integration.

  4. Click the action that you want the connection to perform:

    1. Copy Object adds one or more objects to the bucket.

      To add one file to the bucket, you can enter its name in the File Name field.

      To add multiple files to the bucket, do not specify a file name. In this case, the action adds all objects that it obtains from the previous integration step(s).

      If you used the poll action to obtain multiple files and you specify a file name then the Copy Object action adds only the last file that was received from the poll action.

    2. Delete Object deletes an object from the bucket. In the File Name field, specify the name of the object that you want to delete. If the specified file is not in the bucket, the integration continues with no error.
  5. After you configure the chosen action, click Next to specify the action’s input type. See Specifying connection action input and output types.

2.3.3. Add data to Amazon S3 in the middle of an integration

In the middle of an integration, to add data to Amazon S3, add an Amazon S3 connection between the start and finish connections:

  1. Add the start and finish connections.
  2. In the left panel, hover over the plus sign that is in the location where you want to add the Amazon S3 connection.
  3. In the pop-up, click Add a Connection.
  4. Click the Amazon S3 connection that you want to use as a middle connection in the integration.

  5. Click the action that you want the connection to perform:

    1. Copy Object adds one or more objects to the bucket.

      To add one file to the bucket, you can enter its name in the File Name field.

      To add multiple files to the bucket, do not specify a file name. In this case, the action adds all objects that it obtains from the previous integration step(s).

      If you used the poll action to obtain multiple files and you specify a file name then the Copy Object action adds only the last file that was received from the poll action.

    2. Delete Object deletes an object from the bucket. In the File Name field, specify the name of the object that you want to delete. If the specified file is not in the bucket, the integration continues with no error.
  6. After you configure the chosen action, click Next to specify the action’s input type. See Specifying connection action input and output types.

Chapter 3. Connecting to AMQ

In an integration, you can obtain messages from an ApacheMQ (AMQ) broker or publish messages to an AMQ broker. AMQ uses the OpenWire protocol for communication between clients and message brokers. To communicate with the following broker types, use the AMQ connector to create a connection to the broker of interest:

  • Apache ActiveMQ broker that does not support AMQP
  • AMQ 6 broker

To communicate with one of the following broker types, use the AMQP connector to create a connection to the broker of interest:

  • Apache ActiveMQ broker that supports AMQP
  • Apache ActiveMQ Artemis
  • AMQ 7 broker
  • EnMasse, which is an open source messaging platform

See Chapter 4, Connecting to AMQP.

To use the AMQ connector, see:

3.1. Create an AMQ connection

To create an AMQ connection:

  1. In Fuse Online, in the left panel, click Connections to display any available connections.
  2. In the upper right, click Create Connection to display connectors.
  3. Click the AMQ Message Broker connector.

  4. Configure the connection by entering:

    1. In the Broker URL field, enter the location that you want to send data to or obtain data from, for example, tcp://localhost:61616.
    2. In the User Name field, enter the user name for the account that you want to use to access this broker.
    3. In the Password field, enter the password for the account that you want to use to access this broker.
    4. In the Client ID field, enter the ID that allows connections to close and reopen without missing messages. The destination type must be a topic.
    5. If this connection will be used in a development environment, you can save some time by disabling Check Certificates. Disabling the checking of certificates is a convenience for development environments. For secure production environments, always enable Check Certificates.
    6. In the Broker Certificate field, paste the broker’s PEM certificate text. This is required except when you disable checking the certificates.
    7. In the Client Certificate field, paste the client’s PEM certificate text. Content in this field is always optional.
  5. Click Validate. Fuse Online immediately tries to validate the connection and displays a message that indicates whether validation is successful. If validation fails, revise the configuration details as needed and try again.
  6. If validation is successful, click Next.
  7. In the Connection Name field, enter your choice of a name that helps you distinguish this connection from any other connections. For example, you might enter AMQ 1.
  8. In the Description field, optionally enter any information that is helpful to know about this connection. For example, enter Sample AMQ connection that uses a provided broker.
  9. In the upper right, click Create to see that the connection you created is now available. If you entered the example name, you would see that AMQ 1 appears as a connection that you can choose to add to an integration.

3.2. Add an AMQ connection to an integration

You must create an AMQ connection before you can add it to an integration. If you did not already create an AMQ connection, see Section 3.1, “Create an AMQ connection”.

The procedure for adding an AMQ connection to an integration varies according to whether you want to use the AMQ connection to start the integration, finish the integration, or publish messages in the middle of an integration. See the following topics:

3.2.1. Start an integration based on receiving AMQ messages

To trigger execution of an integration based on receiving a message from an AMQ broker, add an AMQ connection as the start connection:

  1. In the Fuse Online panel on the left, click Integrations.
  2. Click Create Integration.
  3. On the Choose a Start Connection page, click the AMQ connection that you want to use to start the integration.
  4. On the Choose an Action page, click the Subscribe for messages action to receive messages from the queue or topic you specify.

  5. To configure the action:

    1. In the Destination Name field, enter the name of the queue or topic to receive data from.
    2. For the Destination Type, accept Queue or select Topic.
    3. In the Durable Subscription ID field, to allow connections to close and reopen without missing messages, enter the durable subscription ID. The destination type must be a topic.
    4. In the Message Selector field, if you want to receive only data that satisfies a particular condition, enter a filter expression.
  6. Click Next to specify the action’s output type. See Specifying connection action input and output types.

3.2.2. Finish an integration by publishing AMQ messages

To finish an integration by publishing messages to an AMQ broker, add an AMQ connection as the finish connection:

  1. Start creating the integration by adding and configuring the start connection.
  2. On the Choose a Finish Connection page, click the AMQ connection that you want to use to finish the integration.
  3. On the Choose an Action page, click the Publish messages action to publish messages to the queue or topic you specify.
  4. In the Destination Name field, enter the name of the queue or topic to send messages to.
  5. For the Destination Type, accept Queue or select Topic.
  6. Select Persistent to guarantee message delivery even if a connection fails.
  7. Click Next to specify the action’s input/output type. See Specifying connection action input and output types.

3.2.3. Publish AMQ messages in the middle of an integration

In the middle of an integration, to publish messages to an AMQ broker, add an AMQ connection between the start and finish connections. You must be creating or editing an integration. The integration’s start and finish connections must have already been added.

To add an AMQ connection as a middle connection:

  1. In the integration visualization panel on the left, click the plus sign that is in the location where you want to add the connection.
  2. Click Add a connection.
  3. On the Choose a Connection page, click the AMQ connection that you want the integration to use after the start connection and before the finish connection.

  4. On the Choose an Action page, select one of the following actions:

    • Publish messages action to publish messages to the queue or topic you specify. To configure this action:

      1. In the Destination Name field, enter the name of the queue or topic to send messages to.
      2. For the Destination Type, accept Queue or select Topic.
      3. Select Persistent to guarantee message delivery even if a connection fails.

    • Request response using messages to send messages to the JMS destination you specify and receive a response. To configure this action:

      1. In the Destination Name field, enter the name of the queue or topic to send messages to.
      2. For the Destination Type, accept Queue or select Topic.
      3. In the Message Selector field, if you want to receive only responses that satisfy a particular condition, enter a filter expression.
      4. In the Named Reply To field, enter the name of a queue or topic. The destination sends its response to this queue or topic.
      5. Select Persistent to guarantee message delivery even if a connection fails.
      6. In the Response Time Out field, specify the number of milliseconds that this connection waits for a response message before throwing a runtime exception. The default is 5000 milliseconds (5 seconds).
  5. Click Next to specify the action’s input type and then the action’s output type. See Specifying connection action input and output types.

Chapter 4. Connecting to AMQP

In an integration, you can obtain messages from or publish messages to an Advanced Message Queue Protocol (AMQP) broker. AMQP defines communication between clients and message brokers. To communicate with the following broker types, use the AMQP connector to create a connection to the broker of interest:

  • Apache ActiveMQ broker that supports AMQP
  • Apache ActiveMQ Artemis
  • AMQ 7 broker
  • EnMasse, which is an open source messaging platform

To communicate with one of the following broker types, use the AMQ connector to create a connection to the broker of interest:

  • Apache ActiveMQ broker that does not support AMQP
  • AMQ 6 broker

See Chapter 3, Connecting to AMQ.

Note

It is possible to use the AMQP connector to create a connection to an Apache ActiveMQ broker that does not support AMQP or to an AMQ 6 broker. Doing this requires transport configuration in the broker. For information about configuring the broker, see Red Hat JBoss A-MQ Managing and Monitoring Brokers, Adding Client Connection Points. For information about the configuration values to specify, see Red Hat JBoss A-MQ Connection Reference, Advanced Message Queuing Protocol (AMQP).

To use the AMQP connector, see:

4.1. Create an AMQP connection

To create an AMQP connection:

  1. In Fuse Online, in the left panel, click Connections to display any available connections.
  2. In the upper right, click Create Connection to display connectors.
  3. Click the AMQP Message Broker connector.

  4. Configure the connection by entering:

    1. In the Connection URI field, enter the location you want to send data to or obtain data from.
    2. In the User Name field, enter the user name for the account that you want to use to access this broker.
    3. In the Password field, enter the password for the account that you want to use to access this broker.
    4. In the Client ID field, enter the ID that allows connections to close and reopen without missing messages. The destination type must be a topic.
    5. If this connection will be used in a development environment, you can save some time by disabling Check Certificates. Disabling the checking of certificates is a convenience for development environments. For secure production environments, always enable Check Certificates.
    6. In the Broker Certificate field, paste the broker’s PEM certificate text. This is required except when disable checking the certificates.
    7. In the Client Certificate field, paste the client’s PEM certificate text. Content in this field is always optional.
  5. Click Validate. Fuse Online immediately tries to validate the connection and displays a message that indicates whether validation is successful. If validation fails, revise the configuration details as needed and try again.
  6. If validation is successful, click Next.
  7. In the Connection Name field, enter your choice of a name that helps you distinguish this connection from any other connections. For example, you might enter AMQP 1.
  8. In the Description field, optionally enter any information that is helpful to know about this connection. For example, enter Sample AMQP connection
  9. In the upper right, click Create to see that the connection you created is now available. If you entered the example name, you would see that AMQP 1 appears as a connection that you can choose to add to an integration.

4.2. Add an AMQP connection to an integration

You must create an AMQP connection before you can add an AMQP connection to an integration. If you did not already create an AMQP connection, see Section 4.1, “Create an AMQP connection”.

The procedure for adding an AMQP connection to an integration varies according to whether you want to use the connection to start an integration, finish an integration, or publish messages in the middle of an integration. See the following topics:

4.2.1. Start an integration based on receiving AMQP messages

To trigger execution of an integration based on receiving messages from an AMQP broker, add an AMQP connection as the start connection:

  1. In the Fuse Online panel on the left, click Integrations.
  2. Click Create Integration.
  3. On the Choose a Start Connection page, click the AMQP connection that you want to use to start the integration.
  4. On the Choose an Action page, click the Subscribe for messages action to receive messages from the queue or topic you specify.

  5. To configure the action:

    1. In the Destination Name field, enter the name of the queue or topic to receive data from.
    2. For the Destination Type, accept Queue or select Topic.
    3. In the Durable Subscription ID field, to allow connections to close and reopen without missing messages, enter the durable subscription ID. The destination type must be a topic.
    4. In the Message Selector field, if you want to receive only data that satisfies a particular condition, enter a filter expression.
  6. Click Next to specify the action’s output type. See Specifying connection action input and output types.

4.2.2. Finish an integration by publishing AMQP messages

To finish an integration by publishing messages to an AMQP broker, add an AMQP connection as the finish connection. You must be creating or editing an integration. You must have already added the start connection. Follow these instructions:

  1. On the Choose a Finish Connection page, click the AMQP connection that you want to use to finish the integration.
  2. On the Choose an Action page, click Publish messages to publish messages to the queue or topic you specify.
  3. In the Destination Name field, enter the name of the queue or topic to send messages to.
  4. For the Destination Type, accept Queue or select Topic.
  5. Select Persistent to guarantee message delivery even if a connection fails.
  6. Click Next to specify the action’s input and output type. See Specifying connection action input and output types.

4.2.3. Publish messages to AMQP in the middle of an integration

In the middle of an integration, to publish messages to an AMQP broker, add an AMQP connection between the start and finish connections. You must be creating or editing an integration. You must have already added the start and finish connections to the integration. Follow these instructions:

  1. In the integration visualization panel on the left, click the plus sign in the location where you want to add the connection.
  2. Click Add a connection.
  3. On the Choose a Connection page, click the AMQP connection that you want the integration to use after the start connection and before the finish connection.

  4. On the Choose an Action page, select one of the following actions:

    • Publish messages to publish messages to the queue or topic you specify. To configure this action:

      1. In the Destination Name field, enter the name of the queue or topic to send messages to.
      2. For the Destination Type, accept Queue or select Topic.
      3. Select Persistent to guarantee message delivery even if a connection fails.

    • Request response using messages to send messages to the JMS destination you specify and receive a response. To configure this action:

      1. In the Destination Name field, enter the name of the queue or topic to send messages to.
      2. For the Destination Type, accept Queue or select Topic.
      3. In the Message Selector field, if you want to receive only responses that satisfy a particular condition, enter a filter expression.
      4. In the Named Reply To field, enter the name of a queue or topic. The destination sends its response to this queue or topic.
      5. Select Persistent to guarantee message delivery even if a connection fails.
      6. In the Response Time Out field, specify the number of milliseconds that this connection waits for a response message before throwing a runtime exception. The default is 5000 milliseconds (5 seconds).
  5. Click Next to specify the action’s input and output type. See Specifying connection action input and output types.

Chapter 5. Connecting to Dropbox

In an integration, you can download files from Dropbox or upload files to Dropbox. The following topics provide the details:

5.1. Register Fuse Online as a Dropbox client

You must register your Fuse Online environment as a client application that can access Dropbox. This lets you create any number of integrations that connect to Dropbox. In other words, you need to register a particular Fuse Online environment with Dropbox only once.

In each Fuse Online environment, there can be only one registration of Fuse Online as a Dropbox client application. However, while each Dropbox connection uses the same registration, it can use different user credentials.

Perform these steps:

  1. In Fuse Online:

    1. In the left panel, click Settings.
    2. On the Settings page, near the top, to the right of the callback URL, click Copy Callback URL to copy the callback URL for your installation of Fuse Online to the clipboard. You will need this URL toward the end of this procedure.

  2. In another browser tab, go to https://www.dropbox.com and do the following:

    1. Sign in to the Dropbox account that has the data that you want to access in an integration.
    2. After signing in, go to https://www.dropbox.com/developers/apps.
    3. Click Create App.
    4. Select Dropbox API.
    5. Near the top of the page, in the sentence that starts with During registration, enter this callback URL:, paste the URL that you copied to the clipboard at the beginning of this procedure. For example, the URL that you paste is something like this: https://app-proj9128.7b63.fuse-ignite.openshiftapps.com/api/v1/credentials/callback.
    6. Choose whether Fuse Online can access a single folder or all of the folders and files.
    7. Specify a name for your Dropbox app. For example, you might specify Fuse Online Access From Aslan LLC. The name you specify must be unique in the set of Dropbox app names.
    8. Check the box to indicate that you agree to Dropbox API terms and conditions.
    9. Click Create App.
    10. In the Dropbox Settings page for your new app, in the input field for OAuth2 Redirect URIs, paste your Fuse Online URL, which you copied to the clipboard at the beginning of this procedure.
    11. Click Add.

Your Fuse Online environment is now registered as a Dropbox client, which means that Fuse Online can access content in the Dropbox account that you signed into.

5.2. Create a Dropbox connection

A connection to Dropbox requires registration of Fuse Online as an application that can access Dropbox. If you did not already register Fuse Online, see Section 5.1, “Register Fuse Online as a Dropbox client”.

Follow the instructions below to create a Dropbox connection. You can use the same Dropbox connection in multiple integrations.

To create a Dropbox connection:

  1. In a new browser tab, go to https://www.dropbox.com and do the following:

    1. Sign in to the Dropbox account in which you created the app that registers access from your Fuse Online installation.
    2. Go to https://www.dropbox.com/developers/apps.
    3. Click the Fuse Online app to display its settings.

  2. In another browser tab, in Fuse Online, do the following:

    1. In the left panel, click Connections to display any available connections.
    2. In the upper right, click Create Connection to display the available connectors.
    3. Click the Dropbox connector.

  3. Go back to the Dropbox settings display for your app and do the following:

    1. Scroll down to see Generated Access Token.
    2. Click Generate.
    3. Copy the generated access token to the clipboard.
  4. Back in Fuse Online, in the Configure Connection page, in the Access Token field, paste the generated access token.
  5. In the Client Identifier field, enter the name that you specified when you created the Dropbox app.
  6. Click Validate. Fuse Online displays a message that indicates whether it can validate this connection. If validation fails, try again and be sure to enter the correct values.
  7. When validation is successful, in the upper right, click Next.
  8. In the Connection Name field, enter your choice of a name that helps you distinguish this connection from any other connections. For example, enter Dropbox Connect 1.
  9. In the Description field, optionally enter any information that is helpful to know about this connection. For example, enter Sample Dropbox connection that can access all content in our company Dropbox account.
  10. In the upper right, click Create to see that the connection you created is now available. If you entered the example name, you would see that Dropbox Connect 1 appears as a connection that you can choose to add to an integration.

5.3. Add a Dropbox connection to an integration

You must create a Dropbox connection before you can add a Dropbox connection to an integration. If you did not already create a Dropbox connection, see Section 5.2, “Create a Dropbox connection”.

You must be creating an integration or updating an integration to add a connection to that integration. If you need to, see the general procedure for creating an integration. or see updating integrations.

The procedure for adding a Dropbox connection to an integration varies according to whether you want to use the connection to start an integration, finish an integration, or access Dropbox in the middle of an integration. See the following topics:

5.3.1. Start an integration by obtaining files from Dropbox

To start an integration by downloading files from Dropbox, add a Dropbox connection as the start connection:

  1. In the Fuse Online panel on the left, click Integrations.
  2. Click Create Integration.
  3. On the Choose a Start Connection page, click the Dropbox connection that you want to use to start the integration.
  4. On the Choose an Action page, click the Download action to obtain one or more files from the Dropbox account that this connection accesses.
  5. To configure the action, in the Folder or file name path to download field, specify the filename path for the content that you want the integration to obtain. In this release, you can download only a single file.
  6. Click Next to specify the action’s output type. See Specifying connection action input and output types.

5.3.2. Finish an integration by adding files to Dropbox

To finish an integration by uploading files to Dropbox, add a Dropbox connection as the finish connection:

  1. Start creating the integration, add and configure the start connection.
  2. On the Choose a Finish Connection page, click the Dropbox connection that you want to use to finish the integration.
  3. On the Choose an Action page, click the Upload action to add the current integration data to the Dropbox account that this connection accesses.
  4. In the Remote Path field, enter the local filename path for file that you want to upload. Dropbox stores the file with the same path and name. In this release, you can upload only a single file.

  5. For the Upload mode,

    • Select Add to upload a file only when a file with the same name is not already in the same Dropbox folder. If a file with the same name is already in the same Dropbox folder, then the file is not uploaded and the integration continues. This is the behavior regardless of whether the content in the file you are trying to upload has been updated.
    • Select Force to ensure that the file is uploaded even if a file with the same name is present in the same Dropbox folder. Dropbox overwrites the file that it already has with the file that you are uploading.
  6. Click Next to specify the action’s input type. See Specifying connection action input and output types.

5.3.3. Access Dropbox in the middle of an integration

To upload a file to Dropbox in the middle of an integration, add a Dropbox connection between the start and finish connections. You must be creating or editing an integration. You must add the start and finish connections first. Follow these instructions:

  1. In the integration visualization panel on the left, hover over the plus sign that is in the location where you want to add a Dropbox connection.
  2. In the popup, click Add a connection.
  3. On the Choose a Connection page, click the Dropbox connection that you want the integration to use.

  4. On the Choose an Action page, click Upload to add the current integration data to the Dropbox account that this connection accesses. To configure this action:

    1. In the Remote Path field, specify the local path and file name of the file you want to upload. Dropbox stores the file with the same path and name. In this release, you can upload only a single file.

    2. For the Upload mode,

      • Select Add to upload a file only when a file with the same name is not already in the same Dropbox folder. If a file with the same name is already in the same Dropbox folder, then the file is not uploaded and the integration continues. This is the behavior regardless of whether the content in the file you are trying to upload has been updated.
      • Select Force to ensure that the file is uploaded even if a file with the same name is present in the same Dropbox folder. Dropbox overwrites the file that it already has with the file that you are uploading.
  5. Click Next to specify the action’s input and output type. See Specifying connection action input and output types.

Chapter 6. Connecting to an FTP or SFTP server

In an integration, you can connect to an FTP or SFTP server to download or upload files by creating an FTP or SFTP connection. You can then add this connection to any number of integrations. The following topics provide details:

6.1. Create an FTP or SFTP connection

To create a connection to an FTP server or an SFTP server:

  1. In Fuse Online, in the left panel, click Connections to display any available connections.
  2. In the upper right, click Create Connection to display Fuse Online connectors.

  3. To create a connection that uses File Transfer Protocol, click the FTP connector.

    Or, to create a connection that uses Secure File Transfer Protocol, click the SFTP connector.

  4. Configure the connection.

    • For an FTP connection:

      • Host is the only parameter that you must specify. Enter the host name of the server that you want to connect to. For example, if the name of your FTP host is FTP.WEST, then you would enter exactly that, FTP.WEST. Do not specify the protocol, for example, you should not specify something like this: ftp://FTP.WEST.
      • Port is required and has a default value of 21. This is the port that the FTP server is listening on.
      • All other parameters are either not required or have default values. The defaults are suitable for most integrations. Descriptions of these parameters are after this procedure.

    • For an SFTP connection, there must be values for these parameters:

      • Host is the host name of the SFTP server that you want to connect to. For example, if the name of your SFTP host is SFTP.EAST, then you would enter exactly that, SFTP.EAST. Do not specify the protocol, for example, you should not specify something like this: sftp://SFTP.EAST.
      • Port has a default of 22. This is the port that the SFTP server is listening on.
      • User name of the account that you want to use to access the SFTP server.
      • Password that is associated with that user name.
      • All other parameters have default values. The defaults are suitable for most integrations. Descriptions of these parameters are after this procedure.
  5. Click Validate. Fuse Online immediately tries to validate the connection and displays a message that indicates whether or not validation is successful. If validation fails, revise the configuration details as needed and try again.
  6. When validation is successful, click Next.
  7. In the Connection Name field, enter your choice of a name that helps you distinguish this connection from any other connections. For example, enter XLight FTP Server.
  8. In the Description field, optionally enter any information that is helpful to know about this connection.
  9. In the upper right, click Create to see that the connection you created is now available. If you entered the example name, you would see that XLight FTP Server appears as a connection that you can choose to add to an integration.

Descriptions of other parameters

  • Connect timeout defaults to 10000 milliseconds and indicates a maximum wait of 10 seconds to establish the connection. If 10 seconds elapse without a connection then Fuse Online waits for the number of milliseconds defined by Reconnect delay and then tries to reconnect.
  • Reconnect delay defaults to 1000 milliseconds and indicates the wait time before trying to reconnect again.
  • Maximum reconnect attempts defaults to 3. Fuse Online tries as many as 3 times to establish a connection.
  • Binary file transfer mode is used by default. Select No for ASCII transfer mode.
  • Passive connection mode defaults to Yes, which is usually the preferred mode. In passive mode, the client opens communication channels with the server as a way to avoid firewall issues. If you select No then active mode is used.
  • Disconnect from the server after use defaults to No. The connection remains established after it performs the action. Select Yes if you want to disconnect from the server after the connection performs the upload or download.
  • Data timeout defaults to 30000 milliseconds and indicates the maximum length of time that Fuse Online waits for a reply.

6.2. Add an FTP or SFTP connection to an integration

After you create an FTP connection or an SFTP connection, you can add it to any number of integrations. See the following topics:

6.2.1. Obtain files from an FTP or SFTP server

To trigger integration execution when an FTP or SFTP connection finds the file(s) you are interested in, you must add an FTP or SFTP connection as an integration’s start connection.

To add an FTP or SFTP connection as a start connection:

  1. In the Fuse Online panel on the left, click Integrations.
  2. Click Create Integration.
  3. On the Choose a Start Connection page, click the FTP or SFTP connection that you want to use to poll an FTP or SFTP server.
  4. On the Choose an Action page, click Download.
  5. In the File name expression field, if you are interested in a single file, then enter an Apache Camel Simple language expression that resolves to a file name. You cannot specify a regular expression. The connection polls (periodically checks) the server for this file and downloads it when it is found. Leave this field blank if you want to download more than one file.
  6. In the FTP directory field, enter the absolute or relative path of the server directory to poll. The connection watches this directory for any content and downloads all files when it finds any content.
  7. In the Milliseconds before polling starts field, accept the default of 1000 milliseconds or change the number of milliseconds.
  8. In the Milliseconds before the next poll field, accept the default of 500 milliseconds or change the number of milliseconds. This is the interval between polls.
  9. In the Delete after download field, accept the default of No or select Yes to download the file(s) and then delete it(them) from the server.
  10. Click Next to specify the action’s output type. See Specifying connection action input and output types.

6.2.2. Upload files to an FTP or SFTP server

To finish an integration by uploading files to an FTP or SFTP server, you add an FTP or SFTP connection as the finish connection. You can also upload files to an FTP or SFTP server in the middle of an integration. To do this, you add an FTP or SFTP connection as a middle connection.

To add an FTP or SFTP connection that uploads files:

  1. Start creating the integration.
  2. Add and configure the start connection.

  3. On the Choose a Finish Connection page, do one of the following:

    • To finish an integration by uploading files, click the FTP or SFTP connection that you want to use.
    • To upload files in the middle of an integration, click the connection you want to use to finish the integration. Configure that connection. When the finish connection is part of the integration, in the left panel, hover over the plus sign where you want to add an FTP or SFTP connection and click Add a connection. Click the FTP or SFTP connection that you want to use to upload files in the middle of an integration.
  4. On the Choose an Action page, click Upload.
  5. In the File name expression field, if you want to upload only one particular file, then enter an Apache Camel Simple language expression that resolves to a file name. This is the name of the file that the action uploads to the server. You cannot specify a regular expression. To upload more than one file, leave this field blank.
  6. In the FTP directory field, enter the absolute or relative name of a server directory. If the File name expression field contains an expression, then the connection stores the specified file in this directory. If the File name expression field is blank, then the connection uploads to this directory all files that were received from the previous integration step.

  7. In the If file exists field, indicate the behavior when you are uploading a file that has the same path and name as a file that is on the server. Accept the default, Override, to overwrite the file that is on the server with the file that you are uploading. Or, select one of the following:

    • Append adds the content in the file being uploaded to the file that is on the server.
    • Fail throws GenericFileOperationException. The integration does not enter an error state.
    • Ignore does not upload the file. The integration continues running under the assumption that everything is okay.
    • Move renames one of the files.
    • TryRename uploads the file with a temporary name and renames the file to the desired name. This operation does not check for the existence of a file with the desired name, which makes the operation faster on most servers than when existence checks are done.
  8. In the Temporary file prefix while copying field, specify a string. The connection prepends this string to the name of a file while it is being uploaded. This enables the connection to write to a temporary file on the server and then rename that temporary file to have the correct name. This is useful for reducing locks when uploading very large files.
  9. In the Temporary file name while copying field, specify a string. The connection renames a file being uploaded to have this name while it is being uploaded. This enables the connection to write to a temporary file on the server and then rename that temporary file to have the correct name. This is useful for reducing locks when uploading very large files.
  10. Click Next to specify the action’s input type. See Specifying connection action input and output types.

Chapter 7. Connecting to Gmail

To trigger an integration when a particular Gmail account receives an email, add a Gmail connection to an integration as its start connection. In an integration, to send an email from a particular Gmail account, add a Gmail connection as the integration’s finish connection, or as a middle connection.

The general steps for connecting to Gmail in an integration are:

  1. Register Fuse Online as a client application that can access the Gmail API.
  2. Create a Gmail connection. When you do this you choose the Gmail account that the connection is authorized to access.
  3. If your integration sends an email from a Gmail account, decide how to populate an email to send.
  4. Add a Gmail connection to an integration.
  5. For a Gmail connection that sends an email, optionally map integration data to the email fields.

Information and instructions are in the following topics:

7.1. Register Fuse Online as a Gmail client application

To be able to connect to Gmail in an integration, you register your Fuse Online environment as a client application that can access Gmail. Registration authorizes Fuse Online to access Gmail. With registration in place, you can create any number of Gmail connections and any number of integrations that connect to Gmail. While each Gmail connection uses the same registration, each connection can use different user credentials to access a different Gmail account.

To authorize your Fuse Online environment to access Gmail:

  1. In Fuse Online, in the left navigation panel, click Settings.
  2. On the Settings page, near the top, to the right of the callback URL, click Copy Callback URL to copy the callback URL for your Fuse Online environment to the clipboard. You will need this URL toward the end of this procedure.

  3. In another browser tab, go to https://console.developers.google.com and do the following:

    1. Confirm that you are signed in to the Gmail account that you want to use to register Fuse Online as a Gmail client application. Or, choose a different Gmail account and sign in to that account.
    2. Ensure that you want to use the current Google project to grant authorization to Fuse Online. Or, choose or create another project. If this Google account does not already have a project, you must create one. For information about Google projects and how you might want to organize your use of projects, click the Google help icon in the upper right.
    3. You should see the APIs and Services dashboard. If you do not, then in the upper left corner, click the Navigation menu icon and select APIs and Services > Dashboard.
    4. Click the Gmail API card.
    5. In the Gmail API page, click Enable.

    6. In the page that appears, in the left navigation panel, click Credentials and then click the OAuth consent screen tab. In this tab, do the following:

      1. In the Product name shown to users field, enter a name for the client application. For example, enter Fuse Online client application.
      2. Skip the other fields.
      3. Click Save.
    7. To the right of Create Credentials, click the down arrow to display a menu and select OAuth client ID.

    8. Select Web application and in the page that appears, do the following:

      1. In the Name field, enter a name for the OAuth client ID for your Fuse Online environment. This is different from the name that you entered for the client application itself. For example, enter OAuth client ID for Fuse Online.
      2. Skip Authorized JavaScript origins.
      3. In the Authorized redirect URIs field, paste the callback URL that you copied from your Fuse Online environment at the beginning of this procedure.
      4. Click Create to display the client ID and client secret for your Fuse Online environment.
    9. To the right of the client ID field, click the Copy icon to copy the client ID to your clipboard.
  4. Return to the Fuse Online Settings page, expand the Gmail entry, and in the Gmail Client ID field, paste the Gmail client ID that you just copied.
  5. Return to the Google developers site and to the right of the client secret field, click the Copy icon to copy the client secret to your clipboard.
  6. Return to the Fuse Online Settings page and in the Gmail Client Secret field, paste the Gmail client secret that you just copied.
  7. Click Save. You should get a Registration Successful! notification.
  8. Click Ok to collapse the fields. With registration in place, you can create a Gmail connection.

7.2. Create a Gmail connection

A connection to Gmail requires registration of Fuse Online as an application that can access Gmail. If you did not already register Fuse Online, see Section 7.1, “Register Fuse Online as a Gmail client application”.

When you create a Gmail connection, you authorize the connection to access one particular Gmail account. After you create a Gmail connection, you can add it to multiple integrations.

To create a Gmail connection:

  1. In Fuse Online, in the left panel, click Connections to display any available connections.
  2. In the upper right, click Create Connection to display the available connectors. A connector is a template that you use to create one or more connections.
  3. Click the Gmail connector.

  4. In the Configure Connection page, click Connect Gmail, which takes you to a Sign in with Gmail page.

    If Connect Gmail does not appear, then your Fuse Online installation is not registered as a Gmail client application. See Section 7.1, “Register Fuse Online as a Gmail client application”. When your installation is not registered with Gmail, then when you try to create a Gmail connection, Fuse Online displays multiple fields that prompt for authorization information. While you can create a Gmail connection by entering values in these fields, you should register with Gmail first, and then create a Gmail connection after registration is in place.

  5. In the page that is prompting you to sign in to Gmail, enter the email address of the Google account that you want this connection to access from Fuse Online and click Next.
  6. In response to openshiftapps.com wants to access your Google Account, click Allow to return to Fuse Online.
  7. In the Fuse Online Connection Name field, enter your choice of a name that helps you distinguish this connection from any other connections. For example, enter Gmail Connect 1.
  8. In the Description field, optionally enter any information that is helpful to know about this connection. For example, enter Sample Gmail connection that uses jkim Gmail account credentials.
  9. In the upper right, click Create to see that the connection you created is now available. If you entered the example name, you would see that Gmail Connect 1 appears as a connection that you can choose to add to an integration.

7.3. Alternatives for populating email to send

A Gmail connection that finishes an integration or that is in the middle of an integration sends an email from the Gmail account that the connection is authorized to access. There are several ways to populate the content of the email that the connection sends. Before you add a Gmail connection that sends an email, consider how you want to populate that email.

The alternatives for populating an email to send are as follows:

  • Add a data mapper step just before the Gmail connection that sends an email. In this data mapper step, map data fields that are output from previous integration steps to Gmail connection Send Email action fields. The Send Email action fields are:

    • Email to
    • Email subject
    • Email text
    • Email cc
    • Email bcc

    If you add a data mapper step then you can map one, some, or all Send Email action fields.

  • When you add a Gmail connection to an integration, configure the action by specifying values in the Send Email action fields. You can specify values in one, some, or all fields.

  • Use both a data mapper step and Send Email action configuration to populate the fields. In other words, you can configure the Send Email action by specifying one or more fields and also add a data mapper step that populates other fields.

    A value that you specify directly in a Send Email action field has precedence over a value that is mapped to the Send Email action field. In other words, suppose you populate a Send Email field by specifying a value when you add the connection and configure the action and also by mapping a value to the same field. The value that you specify in the action configuration always overrides the value that was mapped. For example, suppose you specify people@redhat.com in the Email to action field and you also map an email field from a previous step to the Gmail Email to field. The integration always uses people@redhat.com and only people@redhat.com as the email address.

When you add a Gmail connection that sends an email, no action configuration parameters are required. This is because you might choose to populate an email entirely by mapping integration data to the Send Email action fields. However, the presence of an email address in the Email to field, either by configuration specification or by mapping, is required. Without an email address to send the message to, Fuse Online generates a runtime error and the integration stops executing.

7.4. Add a Gmail connection to an integration

You must create a Gmail connection before you can add it to an integration. If you did not already create a Gmail connection, see Section 7.2, “Create a Gmail connection”.

The procedure for adding a Gmail connection to an integration varies according to whether you want to use the Gmail connection to:

  • Trigger an integration based on email that is received by the account that the connection has authorization to access. Periodically, the connection obtains the email and sends it to the next step in the integration. To do this, add a Gmail connection as an integration’s start connection.
  • Send an email from the account that the connection is authorized to access. To do this, add a Gmail connection in the middle of an integration or as the integration’s finish connection.

See the following topics:

7.4.1. Obtain emails that are received by a Gmail account

To trigger execution of an integration based on email received by a particular Gmail account, add a Gmail connection as the start connection of an integration. When you created the Gmail connection you authorized it to access the particular Gmail account that you want to obtain emails from.

When the integration is running, the Gmail connection checks this account for emails at intervals that you control. When the connection finds an unread email, it passes the email to the next step in the integration and, by default, marks the email as read.

To trigger an integration based on email received by a particular Gmail account:

  1. In the Fuse Online panel on the left, click Integrations.
  2. Click Create Integration.
  3. On the Choose a Start Connection page, click the Gmail connection that you want to use to start the integration.
  4. On the Choose an Action page, click the Receive Email action.

  5. To configure the Receive Email action:

    1. In the Delay field, accept the default of 30 seconds or specify how often you want the integration to check for new email.
    2. In the Labels field, leave it blank to obtain any unread email. To obtain only certain emails, specify a comma separated list of labels that are used in the Gmail account that the connection is accessing. By default, the integration obtains the unread emails that have those labels.
    3. Select Mark as read to ensure that the connection does not return the same email twice. If Mark as read is not selected, the connection returns emails that are in the account’s in box, whether or not they were previously read. Or, if you specify one or more labels, then the integration return emails that have those labels whether or not they were already read.

    4. In the Max Results field, accept the default of 5 or indicate the maximum number of emails that the connection can return for each poll. If the connection finds more than this number of unread emails, then it returns the most recent Max Results emails.

      When a Gmail connection returns more than one email, the integration processes the emails as a batch. In other words, Fuse Online executes the integration once for the batch.

    5. Click Done to add this Gmail connection as the start connection in the integration. The connection appears as the first step in the integration flow.

7.4.2. Send an email from a Gmail account

In an integration, you can send an email from a Gmail account either in the middle of the integration or to finish the integration. To do this, add a Gmail connection to the middle of an integration or as the integration’s finish connection.

Before you add a Gmail connection that sends an email, decide how you want to populate the fields in the email. See Section 7.3, “Alternatives for populating email to send”.

To add a Gmail connection that sends an email from the authorized Gmail account:

  1. Start creating the integration.
  2. Add and configure the start connection.

  3. On the Choose a Finish Connection page, do one of the following:

    • To finish an integration by sending an email from a Gmail account, click the Gmail connection that is authorized to access the Gmail account that you want to send the email from.

    • To send an email in the middle of an integration:

      1. Click the connection that you want to use to finish the integration.
      2. Configure that connection.
      3. When the finish connection is part of the integration, in the left panel, hover over the plus sign where you want to add a Gmail connection and click Add a connection.
      4. Click the Gmail connection that you want to use to send an email in the middle of an integration.
  4. On the Choose an Action page, click Send Email.

  5. On the Configure Send Email page, do one of the following:

    • Leave all fields blank if you plan to add a data mapper step just before this connection and you plan to map integration data to the Send Email fields.

    • Enter information in one or more fields:

      1. In the Email To field, enter one email address or a comma separated list of email addresses to send the email to.
      2. In the Email Subject field, enter text that states the subject of the email.
      3. In the Email Text field, enter the message that you want to send.
      4. In the Email cc field, enter a comma separated list of email addresses to which you want to send copies of the email.
      5. In the Email bcc field, enter a comma separated list of email addresses to which you want to send blind copies of the email.

    • Leave some fields blank and enter information in some fields.

      If you plan to add a data mapper step just before this Gmail connection, and you want to map integration data to some email fields, leave those fields blank in the action configuration. Enter values in other action fields as needed.

      A value that you specify in a Send Email action configuration field has precedence over a value that is mapped from a previous step. For more information about this, see Section 7.3, “Alternatives for populating email to send”.

  6. Click Done to add the connection to the integration.

The connection appears in the integration flow in the location where you added it. If you plan to add a data mapper step before this connection, first add any other connections that you plan to add to this integration. Then add the data mapper step.

Chapter 8. Connecting to HTTP and HTTPS endpoints

In an integration, you can connect to HTTP and HTTPS endpoints to execute the GET, PUT, POST, DELETE, HEAD, OPTIONS, TRACE, or PATCH method. To do this, create an HTTP or HTTPS connection and then add it to an integration. The following topics provide details:

8.1. Create a connection to an HTTP or HTTPS endpoint

To create a connection to an HTTP or HTTPS endpoint:

  1. In Fuse Online, in the left panel, click Connections to display any available connections.
  2. In the upper right, click Create Connection to display Fuse Online connectors.
  3. If you want to use Hyper Text Transfer Protocol to connect to the endpoint, then click the HTTP connector. If you want to use Secure Hyper Text Transfer protocol, then click the HTTPS connector.
  4. In the Base URL field, enter the endpoint path. For example, www.mycompany.com/sales.
  5. Click Validate. Fuse Online immediately tries to validate the connection and displays a message that indicates whether validation is successful. If validation fails, revise specification of the base URL and try again.
  6. If validation is successful, click Next.
  7. In the Connection Name field, enter your choice of a name that helps you distinguish this connection from any other connections. For example, enter HTTPS My Company Sales.
  8. In the Description field, optionally enter any information that is helpful to know about this connection.
  9. In the upper right, click Create to see that the connection you created is now available. If you entered the example name, you would see that HTTPS My Company Sales appears as a connection that you can choose to add to an integration.

8.2. Add an HTTP or HTTPS connection to an integration

After you create an HTTP or HTTPS connection, you can use it in any number of integrations as follows:

  • To start an integration by periodically invoking an HTTP or HTTPS endpoint, add an HTTP or HTTPS connection as the integration’s start connection.
  • To finish an integration by invoking an HTTP or HTTPS endpoint once, add an HTTP or HTTPS connection as the integration’s finish connection.
  • In the middle of an integration, to invoke an HTTP or HTTPS endpoint once, add an HTTP or HTTPS connection after the start connection and before the finish connection.

If you are creating an integration, Fuse Online prompts you to choose and configure the start connection, and then choose and configure the finish connection. To add a middle connection, hover over the plus sign in the left panel at the location where you want to add the connection, and select Add a connection.

In all of these situations, Fuse Online displays the available connections. To add an HTTP or HTTPS connection:

  1. Click the HTTP or HTTPS connection that you want to add to the integration.

  2. Select the action that you want the connection to perform:

    • If you are adding a start connection, then Periodic invoke URL is the only available action. This action invokes the endpoint at intervals that you specify and triggers the integration if the endpoint returns any data.
    • If you are adding a finish or middle connection, then Invoke URL is the only available action. This action invokes the endpoint once.
  3. In the URL Path field, specify the location of the endpoint that you want to invoke.

  4. In the HTTP Method field, select the method that you want the connection to perform. The default method is GET.

    • GET obtains the content at the URL path.
    • PUT replaces the content at the URL path with the integration data.
    • POST stores the integration data at the URL path to create new content.
    • DELETE removes content at the URL path.
    • HEAD obtains metadata about the content at the URL path.
    • OPTIONS obtains communication option settings at the URL path.
    • TRACE obtains information for testing and diagnostic purposes.
    • PATCH partially updates the content at the URL path according to the integration data.
  5. If you are adding a start connection, which periodically invokes the URL, then in the Period field, accept the default interval of 1 second or specify a number and its unit (milliseconds, seconds, minutes, or hours) to indicate how long to wait between invocations.
  6. Click Done to specify the action’s input or output type. See Specifying connection action input and output types.

Chapter 9. Connecting to Kafka

Apache Kafka is a distributed streaming platform that you can use to obtain and publish data. In an integration, you can subscribe for data from a Kafka topic that you specify or publish data to a Kafka topic that you specify. To do this, create a connection to Kafka and then add that connection to an integration. Details are in the following topics:

9.1. Create a connection to a Kafka broker

To create a Kafka connection:

  1. In Fuse Online, in the left panel, click Connections to display any available connections.
  2. In the upper right, click Create Connection to display connectors.
  3. Click the Kafka connector.
  4. In the Kafka bootstraps URI field, enter a comma separated list of Kafka broker URIs. Each URI should be in the form host:port.
  5. Click Validate. Fuse Online immediately tries to validate the connection and displays a message that indicates whether validation is successful. If validation fails, revise the input parameter and try again.
  6. If validation is successful, click Next.
  7. In the Connection Name field, enter your choice of a name that helps you distinguish this connection from any other connections. For example, you might enter Kafka West.
  8. In the Description field, optionally enter any information that is helpful to know about this connection.
  9. In the upper right, click Create to see that the connection you created is now available. If you entered the example name, you would see that Kafka West appears as a connection that you can choose to add to an integration.

9.2. Add a Kafka connection to an integration

You must create a Kafka connection before you can add it to an integration. If you did not already create a Kafka connection, see Section 9.1, “Create a connection to a Kafka broker”.

The procedure for adding a Kafka connection to an integration varies according to whether you want to use the Kafka connection to obtain data or publish data. See the following topics:

9.2.1. Obtain data from a Kafka broker

To trigger execution of an integration based on receiving data from a Kafka broker, add a Kafka connection as the start connection. When the integration is running, the Kafka connection continuously watches for data in the Kafka topic that you specify. When the connection finds new data, it passes that data to the next step in the integration.

To execute an integration each time a Kafka topic receives a message:

  1. In the Fuse Online panel on the left, click Integrations.
  2. Click Create Integration.
  3. On the Choose a Start Connection page, click the Kafka connection that you want to use to start the integration.
  4. On the Choose an Action page, click the Subscribe action to receive data from the topic that you specify.
  5. In the Topic Name field, click the down carat to display a list of topics and click the topic that you want to subscribe to.
  6. Click Next to specify the action’s output type. See Specifying connection action input and output types.

9.2.2. Publish data to a Kafka broker

In an integration, you can publish data to a Kafka broker to finish an integration. To do this, add a Kafka connection as the integration’s finish connection. To publish data to a Kafka broker in the middle of integration, add a Kafka connection to an integration after the start connection and before the finish connection.

To add a Kafka connection that publishes data:

  1. Start creating the integration.
  2. Add and configure the start connection.

  3. On the Choose a Finish Connection page, do one of the following:

    • To finish an integration by publishing data, click the Kafka connection that you want to use.
    • To publish data in the middle of an integration, click the connection that you want to use to finish the integration. Configure that connection. When the finish connection is part of the integration, in the left panel, hover over the plus sign where you want to add a Kafka connection and click Add a connection. Click the Kafka connection that you want to use to publish a message in the middle of an integration.
  4. On the Choose an Action page, click Publish.
  5. In the Topic Name field, click the down carat to display a list of topics and click the topic that you want to publish to.
  6. Click Next to specify the action’s input type. See Specifying connection action input and output types.

Chapter 10. Connecting to MQTT

MQ Telemetry Transport (MQTT) is a lightweight, machine-to-machine, internet of things, connectivity protocol. In an integration, you can obtain messages from or publish messages to an MQTT broker. To do this, create a connection to the MQTT broker of interest and then add that connection to an integration. Details are in the following topics:

10.1. Create a connection to an MQTT broker

To create an MQTT connection:

  1. In Fuse Online, in the left panel, click Connections to display any available connections.
  2. In the upper right, click Create Connection to display connectors.
  3. Click the MQTT Message Broker connector.

  4. To configure the connection:

    1. In the MQTT broker URL field, enter the location of the MQTT broker that you want to send data to or obtain data from. This is the only required field.
    2. In the User Name field, optionally enter the user name for the MQTT account whose credentials you want to use to access the broker.
    3. In the Password field, if you specified a user name, then specify the password associated with that account.
    4. In the Client ID field, optionally enter the ID that allows connections to close and reopen without missing messages. The connection must subscribe to or publish to a topic.
  5. Click Validate. Fuse Online immediately tries to validate the connection and displays a message that indicates whether validation is successful. If validation fails, revise the input parameters and try again.
  6. If validation is successful, click Next.
  7. In the Connection Name field, enter your choice of a name that helps you distinguish this connection from any other connections. For example, you might enter MQTT West.
  8. In the Description field, optionally enter any information that is helpful to know about this connection.
  9. In the upper right, click Create to see that the connection you created is now available. If you entered the example name, you would see that MQTT West appears as a connection that you can choose to add to an integration.

10.2. Add an MQTT connection to an integration

You must create an MQTT connection before you can add it to an integration. If you did not already create an MQTT connection, see Section 10.1, “Create a connection to an MQTT broker”.

The procedure for adding an MQTT connection to an integration varies according to whether you want to use the MQTT connection to obtain a message or publish a message. See the following topics:

10.2.1. Obtain a message from an MQTT broker

To trigger execution of an integration based on receiving a message from an MQTT broker, add an MQTT connection as the start connection. When the integration is running, the MQTT connection continuously watches for messages on the MQTT queue or topic that you specify. When the connection finds a message, it passes it to the next step in the integration. An MQTT connection handles one message at a time.

To start an integration when a message from an MQTT broker is found:

  1. In the Fuse Online panel on the left, click Integrations.
  2. Click Create Integration.
  3. On the Choose a Start Connection page, click the MQTT connection that you want to use to start the integration.
  4. On the Choose an Action page, click the Subscribe action to receive messages from the queue or topic that you specify.
  5. In the MQTT queue/topic name field, enter the name of the queue or topic to subscribe to in order to receive data.
  6. Click Next to specify the action’s output type. See Specifying connection action input and output types.

10.2.2. Publish a message to an MQTT broker

In an integration, you can publish a message to an MQTT broker to finish an integration. To do this, add an MQTT connection as the integration’s finish connection. To publish a message to an MQTT broker in the middle of integration, add an MQTT connection to an integration after the start connection and before the finish connection.

To add an MQTT connection that publishes a message:

  1. Start creating the integration.
  2. Add and configure the start connection.

  3. On the Choose a Finish Connection page, do one of the following:

    • To finish an integration by publishing a message, click the MQTT connection that you want to use.
    • To publish a message in the middle of an integration, click the connection that you want to use to finish the integration. Configure that connection. When the finish connection is part of the integration, in the left panel, hover over the plus sign where you want to add an MQTT connection and click Add a connection. Click the MQTT connection that you want to use to publish a message in the middle of an integration.
  4. On the Choose an Action page, click Publish.
  5. In the MQTT queue/topic name field, specify the name of the queue or topic to publish the message to.
  6. Click Next to specify the action’s input type. See Specifying connection action input and output types.

Chapter 11. Connecting to REST APIs

In an integration, to connect to a REST API, you must have created a connector for that API by uploading an OpenAPI specification that describes the API. See Integrating Applications with Fuse Online, Adding REST API client connectors.

When a connector for the REST API you want to connect to is available in Fuse Online, the steps for connecting to that REST API are:

11.1. Register Fuse Online as an API client

Before Fuse Online creates an API client connector, it prompts you to indicate the API’s security requirements. For APIs that use OAuth, when Fuse Online creates the connector it also adds an entry for the API to the Fuse Online Settings page. This is where you provide the API client ID and the API client secret that authorize Fuse Online to access the API.

If the API you want to connect to does not use OAuth, skip this section and see Section 11.2, “Create an API client connection”.

To register Fuse Online as an authorized API client application:

  1. In Fuse Online:

    1. On the Settings page, near the top, to the right of the callback URL, click Copy Callback URL to copy the callback URL for your Fuse Online environment to the clipboard. You will need this URL later in this procedure.
    2. Look for the name of the API you want to connect to and click its Register button to display its client ID and client secret fields.

  2. In another browser window, you must register Fuse Online as an OAuth client of the API you want to connect to. The exact steps for doing this vary for each API service. Typically, the API service provides an OAuth custom application setting page. Go to that page and do the following:

    1. Provide the Fuse Online callback URL, which you copied at the beginning of this procedure.
    2. Respond to any other prompts that require your input.
    3. Obtain the client ID and client secret that the API service assigns to your Fuse Online environment.

  3. Return to the Fuse Online Settings page entry for the API service you are registering with and do the following:

    1. Paste the assigned client ID.
    2. Paste the assigned client secret.
    3. Click Save.

11.2. Create an API client connection

To create a connection to a REST API:

  1. In Fuse Online, in the left panel, click Connections to display any available connections.
  2. In the upper right, click Create Connection to display available connectors.
  3. Click the connector for the API that you want to create a connection for.
  4. Respond to prompts for additional information. The definition of the API determines what Fuse Online prompts for. For example, for an API that uses HTTP Basic Authorization, Fuse Online prompts for the user name and password to use to access the API. For an API that uses OAuth, Fuse Online displays a button for you to click so that Fuse Online can verify its registration credentials for connecting to the API.
  5. In the Connection Name field, enter your choice of a name that helps you distinguish this connection from any other connections.
  6. In the Description field, optionally enter any information that is helpful to know about this connection.
  7. In the upper right, click Create to see that you can now choose the connection you created and add to an integration.

11.3. Add an API client connection to an integration

Before you can add an API connection to an integration, you must create a connection to that API. See Section 11.2, “Create an API client connection”.

In this release, in an integration, a connection to an API can be the finish connection or a middle connection. It cannot be the start connection. The instructions below assume that Fuse Online is prompting you to select a finish connection or a connection that is not the start connection.

To add an API connection to an integration:

  1. On the page that displays available connections, click the API connection that you want to add to the integration.
  2. Click the action that you want the connection to perform. The actions that are available are based on the resource operations specified in the OpenAPI file that was uploaded to Fuse Online and that describes the API you are connecting to.
  3. Depending on the action you select, enter any parameters that Fuse Online prompts for.
  4. Click Done.

The connection appears in the integration flow in the location where you added it.

Chapter 12. Connecting to Salesforce

To connect to Salesforce in an integration, see the following topics:

12.1. Register Fuse Online as a Salesforce client application

You must register your Fuse Online environment as a client application that can access Salesforce. This lets you create any number of integrations that connect to Salesforce. In other words, you need to register a particular Fuse Online environment with Salesforce only once.

In each Fuse Online environment, there can be only one registration of Fuse Online as a Salesforce client. However, while each Salesforce connection uses the same registration, it can use different user credentials.

Perform these steps to register Fuse Online as a Salesforce client application:

  1. In Fuse Online:

    1. In the left panel, click Settings.
    2. On the Settings page, near the top, to the right of the callback URL, click Copy Callback URL to copy the callback URL for your Fuse Online environment to the clipboard. You will need this URL toward the end of this procedure.
    3. To the right of the Salesforce entry, click Register to display the Client ID and Client Secret fields.

  2. In another browser tab, log in to your Salesforce account and follow the steps below to create a connected app. These instructions assume that you are using the Salesforce Classic user interface. To switch from the Salesforce Lightning Experience interface, click your profile icon and select Switch to Salesforce Classic. For additional information, see the Salesforce documentation for Create a Connected App.

    1. In Salesforce, in the upper right, click Setup.
    2. In the left panel, select Build > Create > Apps.
    3. Scroll down to Connected Apps and click New.
    4. Enter the required information and then select Enable OAuth Settings.
    5. In the Callback URL field, paste your Fuse Online URL, which you copied at the beginning of this procedure. For example: https://app-proj9128.7b63.fuse-ignite.openshiftapps.com/api/v1/credentials/callback.

    6. For OAuth Scopes, add:

      • Access and manage your data (api)
      • Allow access to your unique identifier (openid)
      • Perform requests on your behalf at any time (refresh_token, offline_accesss)
    7. Select Configure ID token and then Include Standard Claims.
    8. Scroll down and click Save.
    9. Scroll up to see that Salesforce indicates a short wait: SF message to wait a few minutes
    10. Click Continue.
    11. Copy the consumer key that Salesforce provides.
  3. Return to your Fuse Online Settings page and paste the Salesforce-provided consumer key into the Salesforce Client ID field.
  4. Back in Salesforce, copy the consumer secret that Salesforce provides.
  5. Return to your Fuse Online Settings page and paste the Salesforce-provided consumer secret into the Salesforce Client Secret field.
  6. Click Save and then click Ok.

12.2. Create a Salesforce connection

A connection to Salesforce requires registration of Fuse Online as an application that can access Salesforce.

Be sure to wait 2 - 10 minutes after registering your Fuse Online installation as a Salesforce client before you try to create a Salesforce connection. After you create a Salesforce connection, you can use it in multiple integrations.

To create a Salesforce connection:

  1. In the left panel, click Connections to display available connections.
  2. In the upper right, click Create Connection to display the available connectors. A connector is a template for creating one or more connections.
  3. Click the Salesforce connector.

  4. Click Connect Salesforce to display a Salesforce authorization page. You might need to log in to Salesforce before you see the authorization page.

    Note

    The following error indicates that Salesforce does not have the correct Fuse Online callback URL:

    error=redirect_uri_mismatch&error_description=redirect_uri%20must%20match%20configuration

    If you get this error message, then in Salesforce, ensure that the Fuse Online callback URL is specified according to the instructions in Section 12.1, “Register Fuse Online as a Salesforce client application”.

  5. Click Allow to return to Fuse Online.
  6. In the Connection Name field, enter your choice of a name that helps you distinguish this connection from any other connections. For example, enter SF Connect 1.
  7. In the Description field, optionally enter any information that is helpful to know about this connection. For example, enter Sample Salesforce connection that uses my Salesforce login credentials.
  8. In the upper right, click Create to see that the connection you created is now available. If you entered the example name, you would see that SF Connect 1 appears as a connection that you can choose to add to an integration.

12.3. Add a Salesforce connection to an integration

You must create a Salesforce connection before you can add a Salesforce connection to an integration. If you did not already create a Salesforce connection, see Section 12.2, “Create a Salesforce connection”.

You must be creating an integration or updating an integration to add a connection to that integration. If you need to, see the general procedure for creating an integration. or see updating integrations.

The instructions below assume that Fuse Online is prompting you to select a start connection, a finish connection or a middle connection.

To add a Salesforce connection to an integration:

  1. On the page that displays available connections, click the Salesforce connection that you want to add to the integration. When the integration uses the connection you select to connect to Salesforce, Fuse Online uses the credentials defined in that connection.
  2. Click the action that you want the selected connection to perform. Each Salesforce connection that you add to an integration performs only the action you choose.
  3. Specify the Salesforce object that the action operates on, for example, it might be a contact, lead or price book entry. Click in the Object field to select from a list of Salesforce objects or enter the name of the object.
  4. Click Done to add the connection to the integration.

The connection appears in the integration flow in the location where you added it.

Chapter 13. Connecting to SAP Concur

SAP Concur manages business expenses, travel, and invoices. In an integration, you can connect to SAP Concur to obtain all lists, obtain a particular list, create a list, or update a list. There are additional, unsupported actions that a SAP Concur connection can perform. See the note below.

For example, suppose that you store project codes in a SQL database and you need the same project codes in SAP Concur so that expenses can be associated with projects. You can create an integration that connects to your SQL database and runs a stored procedure that obtains any new project codes. The integration can then connect to SAP Concur and upload the new project codes to the appropriate list.

Important

In this release, the SAP Concur connector is a Technology Preview feature.

See the following topics:

13.1. User roles for connecting to SAP Concur

SAP Concur has an implementation site for development work and a production site for live use. The implementation site simulates the production site. This lets you create and refine an integration before you use it in production with the live SAP Concur site.

At any one time, a Fuse Online environment can connect to the SAP Concur implementation site or the SAP Concur production site. In other words, a particular Fuse Online environment does not support connections to both SAP Concur sites at the same time. Each Fuse Online environment requires its own credentials for accessing each SAP Concur site and the credentials for the implementation site are different from the credentials for the production site.

Consequently, the expectation is that someone in a system administrator-like role would do the following:

  1. Obtain two sets of OAuth credentials from SAP Concur:

    • One set for access to the SAP Concur implementation site
    • Another set for access to the SAP Concur production site
  2. Configure the SAP Connector for access to appropriate SAP Concur site.
  3. Create a SAP Concur connection.

A business user can then create an integration that uses the SAP Concur connection.

13.2. Obtain SAP Concur implementation site OAuth credentials

To obtain credentials for accessing the SAP Concur implementation site, contact SAP Concur directly and tell them:

  • You want to register Fuse Online as a new app that is authorized to access the SAP Concur implementation site.
  • You want a new set of OAuth credentials for their implementation site.
  • The credentials must include the LIST scope.
  • Optionally, to obtain permission to perform actions other than the list actions, ask for other scopes.

  • The OAuth grant type for these credentials should be Authorization Grant Flow.

    To use a REST client, such as Postman, to send a request to the SAP Concur implementation site, you need credentials with an OAuth grant type of Password.

  • The Fuse Online callback URL for the environment that that you want credentials for, which is something like this:

    https://syndesis.my-minishift.syndesis.io/api/v1/credentials/callback

    In this URL, syndesis.my-minishift.syndesis.io matches the OpenShift route to your Fuse Online environment.

The response from SAP Concur should provide:

  • A username and password for logging in to the SAP Concur implementation site.
  • Client ID and client secret values that you will specify in the Fuse Online development environment Settings page to configure the Fuse Online SAP Concur connector.

13.3. Obtain SAP Concur production site OAuth credentials

To obtain OAuth credentials that authorize Fuse Online to access the SAP Concur production site, go to the SAP Concur Developer Center Getting Started page and follow the instructions there.

13.4. Configure the SAP Concur connector

To connect to SAP Concur in an integration, you must configure the Fuse Online SAP Concur connector. You can then use the connector to create a connection to SAP Concur.

Prerequisites

  • You know whether you want to configure the SAP Concur connector to access the SAP Concur implementation site or the SAP Concur production site.
  • You obtained OAuth credentials that authorize your Fuse Online environment to access the appropriate SAP Concur site.

Procedure

  1. In Fuse Online, in the left panel, click Settings.
  2. On the Settings page, expand the SAP Concur entry.
  3. In the Client ID field, enter the client ID that you received from SAP Concur.

  4. In the Client Secret field, enter the client secret that you received from SAP Concur.

    Fuse Online populates the other fields.

  5. Click Save.

    Fuse Online immediately tries to validate the configuration. If validation is not successful, correct the input values and try again. If validation is successful, you can create a SAP Concur connection, which you can add to an integration.

  6. To create a SAP Concur connection, click the create a connection link in the success message. Or, to create a connection later, click Ok to contract the SAP Concur entry in the Settings page.

13.5. Create a SAP Concur connection

To connect to SAP Concur in an integration, you must first create a SAP Concur connection, which you can then add to any number of integrations. When you create a SAP Concur connection, you authorize the connection to access SAP Concur with the login credentials that you enter when you create the connection.

Prerequisites

  • In the Fuse Online environment in which you are creating the connection, you must have configured the SAP Concur connector.
  • You should know whether the connector is configured for access to the SAP Concur implementation site or the SAP Concur production site.
  • You must have a user name and password for logging in to the SAP Concur site for which the SAP Concur connector is configured.

Procedure

  1. In Fuse Online, in the left panel, click Connections to display any available connections.
  2. In the upper right, click Create Connection to display the available connectors. A connector is a template that you use to create one or more connections.
  3. Click the SAP Concur connector.

  4. In the Configure Connection page, click Connect SAP Concur, which takes you to the SAP Concur site for which the connector is configured.

    If Connect SAP Concur does not appear, then the SAP Concur connector in your Fuse Online environment is not configured. See Section 13.4, “Configure the SAP Concur connector”.

    If redirect_uri is improper or not previously registered appears, then the SAP Concur connector configuration is incorrect. Return to the Fuse Online Settings page to update and validate the connector configuration.

  5. On the SAP Concur OAuth site:

    1. Enter the email address for the SAP Concur account that you want this connection to use to access SAP Concur.
    2. Ensure that Username is selected.
    3. Click Continue.
    4. Enter the SAP Concur password associated with the email address.
    5. Click Sign In, which returns you to Fuse Online.
  6. In the Fuse Online Connection Name field, enter your choice of a name that helps you distinguish this connection from any other connections. For example, enter SAP Concur Test1.
  7. In the Description field, optionally enter any information that is helpful to know about this connection. For example, enter Sample SAP Concur connection to the implementation site.
  8. In the upper right, click Create to see that the connection you created is now available. If you entered the example name, you would see that SAP Concur Test1 appears as a connection that you can choose to add to an integration.

13.6. Add a SAP Concur connection to an integration

In an integration, a connection to SAP Concur is a middle or finish connection and not a start connection. A connection to SAP Concur can obtain all lists, obtain a list that you specify, update a list, or create a list. There are other actions as well.

Prerequisites

Procedure

The instructions below assume that Fuse Online is prompting you to select a finish connection or a middle connection.

  1. On the page that displays available connections, click the SAP Concur connection that you want to add to the integration. When the integration uses the connection you select to connect to SAP Concur, Fuse Online uses the credentials defined in that connection.

  2. Click the action that you want the selected connection to perform. Each SAP Concur connection that you add to an integration performs only the action you choose. In this release, the supported actions are:

    • Get all lists
    • Get a single list, which you identify by its ID
    • Create a new list
    • Update a list

    For details about these actions, visit the SAP Concur developer center.

  3. Click Done to add the connection to the integration.

The connection appears in the integration flow in the location where you added it.

13.7. Map integration data fields to SAP Concur fields

In most integrations, you need to add a data mapping step before a connection to SAP Concur. In the data mapping step, you map data fields that are available from previous integration steps to SAP Concur action parameters. In the data mapper, the Target panel displays the SAP Concur parameters for the action that you selected when you added the SAP Concur connection to the integration.

In this release, you might want to invoke the following SAP Concur actions.

  • Get all lists requires the limit parameter. The offset parameter is optional.
  • Get a single list requires the id parameter.
  • Create a new list requires the content parameter.
  • Update a list requires the id and content parameters.

Suppose that an integration starts by executing a SQL stored procedure that obtains new project codes. The integration finishes by adding new project codes to SAP Concur. The following procedure provides an example of a data mapper step before the SAP Concur connection.

  1. In Fuse Online, in the left panel, hover over the plus sign that is between the database connection and the SAP Concur connection to display a pop-up in which you click Add a Step.
  2. Click Data Mapper. When the data fields appear, the Sources panel on the left displays the fields that are available from the database connection. In this example, the source fields include concur-list-id and project-code. The Target panel on the right displays the SAP Concur id and content parameters for the update list action, which the connection performs.
  3. Map the concur-list-id source field to the id target field.
  4. Map the project-code source field to the content target field.
  5. In the upper right, click Done to add the data mapper step to the integration.

Chapter 14. Connecting to ServiceNow

An integration can retrieve records from a ServiceNow table or add records to a ServiceNow import set. To do this, you create a ServiceNow connection and then add that connection to an integration. For details, see:

14.1. Create a ServiceNow connection

In an integration, to connect to your company’s ServiceNow instance, you must create a ServiceNow connection.

Prerequisites

  • A ServiceNow administrator at your site must have created a ServiceNow account for you.
  • You must know the URL for your ServiceNow instance as well your ServiceNow user name and password.
  • If the ServiceNow administrator also created a ServiceNow client ID and client secret for you, then you must know these values.

Procedure

  1. In Fuse Online, in the left panel, click Connections to display any available connections.
  2. In the upper right, click Create Connection to display Fuse Online connectors.
  3. Click the ServiceNow connector.

  4. Configure this ServiceNow connection:

    1. In the Instance Name field, enter the name of the ServiceNow instance that you want to obtain records from or copy records to. For example, if the URL for your ServiceNow instance is https://abc12345.service-now.com then the instance name is abc12345.
    2. In the User Name field, enter your ServiceNow user name.
    3. In the User Password field, enter your ServiceNow password.
    4. Optionally, in the Client ID field, enter your client ID if you received one from your ServiceNow administrator.
    5. Optionally, in the Client Secret field, enter your client secret if you received one from your ServiceNow administrator.
    6. Click Validate. Fuse Online immediately tries to validate the connection and displays a message that indicates whether or not validation is successful. If validation fails, revise the configuration details as needed and try again.
    7. When validation is successful, click Next.
  5. In the Connection Name field, enter your choice of a name that helps you distinguish this connection from any other connections. For example, enter ServiceNow Con 1.
  6. In the Description field, optionally enter any information that is helpful to know about this connection. For example, enter ServiceNow connection that uses administrative credentials.
  7. In the upper right, click Create to see that the connection you created is now available. If you entered the example name, you would see that ServiceNow Con 1 appears as a connection that you can choose to add to an integration.

14.2. Add a ServiceNow connection to an integration

After you create a ServiceNow connection, you can add it to an integration. The procedure for adding a ServiceNow connection to an integration varies according to whether you want to use the ServiceNow connection to obtain records from ServiceNow or to copy records to ServiceNow.

Prerequisite

You must create a ServiceNow connection before you can add it to an integration. See Section 14.1, “Create a ServiceNow connection”.

When you have a ServiceNow connection, see:

14.2.1. Start an integration by obtaining records from ServiceNow

To start an integration by obtaining records from ServiceNow, add a ServiceNow connection to an integration as the start connection.

Prerequisites

Procedure

  1. In the Fuse Online panel on the left, click Integrations.
  2. Click Create Integration.
  3. On the Choose a Start Connection page, click the ServiceNow connection that you want to use to start the integration.
  4. On the Choose an Action page, click Retrieve Record to obtain records from a ServiceNow table that you select.

  5. Configure the Retrieve Record action:

    1. Click in The table name field and select the table that you want to obtain records from.
    2. In The query used to filter the result set field, enter a ServiceNow query. For example, consider the state=1^impact=2 query on a table that keeps records about incidents. This query returns records for new incidents (state=1) that have a medium impact (impact=2). If you do not enter a query and the records in the table do not change, then the connection obtains the same records every time.
    3. In the Limit of elements per page field, enter the maximum number of records that you want the connection to obtain. In this release, you must enter a value, the recommendation is to enter 1000 or less, and pagination is not supported.
    4. In the Period field, indicate how often you want to obtain records. The default is every minute. In other words, by default, Fuse Online executes this integration every 60 seconds.
    5. Click Done.

Results

  • Fuse Online generates a JSON schema that defines the structure of the obtained records. This enables you to add a data mapping step before the next connection in the integration if data mapping is needed.
  • Fuse Online prompts you to choose a finish connection.

14.2.2. Copy records to ServiceNow during or to finish an integration

During an integration, or to finish an integration, you can copy records to ServiceNow. To do this, add a ServiceNow connection to an integration as the finish connection or as a middle connection.

Prerequisites

  • You are creating or editing an integration.
  • The integration has a start connection.
  • You know the name of the ServiceNow import set that you want to add records to. Your ServiceNow administrator can help you identify the appropriate import set.
  • The ServiceNow import set must have been configured to handle the addition of records.

Procedure

  1. Do one of the following:

    • To finish the integration by copying records to ServiceNow, on the Choose a Finish Connection page, click the ServiceNow connection that you want to use to finish the integration.
    • To copy records to ServiceNow in the middle of an integration, after the integration has a start connection and a finish connection, in the integration visualization panel on the left, hover over the plus sign that is in the location where you want to copy records to ServiceNow. Click Add a connection, and click the ServiceNow connection that you want to add to the integration.
  2. Click the Create Record action.
  3. Click in The Import Set name field and select the import set that you want to add records to.
  4. Click Next.

Results

  • Fuse Online adds the connection to the integration.
  • If a data mapper step is needed before this connection, then in the integration visualization panel, Fuse Online displays Data Type Mismatch on the connection.

Chapter 15. Connecting to Slack

In an integration, you can connect to an instance of Slack and deliver a message to a particular user or to a channel. For example, this is useful when an integration downloads a file from an FTP server and processes it in some way. You can finish an integration by notifying a Slack channel or user that the process was successful.

To connect to Slack in an integration, create a Slack connection. You can then add that same connection to any number of integrations. Details are in the following topics:

15.1. Create a Slack connection

To create a connection to an instance of Slack:

  1. In Fuse Online, in the left panel, click Connections to display any available connections.
  2. In the upper right, click Create Connection to display Fuse Online connectors.
  3. Click the Slack connector.
  4. In the Slack webhook URL field, enter the webhook URL of the Slack instance to send messages to. This is the only required parameter.

  5. Optionally, enter values for additional parameters:

    1. In the Sending username for messages field, enter the user name that the bot has when it sends messages to Slack.

    2. In the Message avatar emoji field, specify one emoji, which the bot uses as the message avatar when it sends a message. Examples: :smile:, :wave:, :question:.

      Tip

      Search on emoji cheat sheet to see some emoji codes.

    3. In the Message avatar icon URL field, specify the URL of the avatar that the bot uses when it sends messages to Slack.

    If you specify an emoji and an icon URL, then the integration uses the icon URL.

  6. Click Validate. Fuse Online immediately tries to validate the connection and displays a message that indicates whether validation is successful. If validation fails, revise the connection configuration values and try again.
  7. If validation is successful, click Next.
  8. In the Connection Name field, enter your choice of a name that helps you distinguish this connection from any other connections. For example, enter Slack for Company Sales.
  9. In the Description field, optionally enter any information that is helpful to know about this connection.
  10. In the upper right, click Create to see that the connection you created is now available. If you entered the example name, you would see that Slack for Company Sales appears as a connection that you can choose to add to an integration.

15.2. Add a Slack connection to an integration

In an integration, to send a message to a Slack channel or user, first create a Slack connection. You can then add that connection to any number of integrations as a finish connection or as a middle connection. It does not make sense to add a Slack connection that starts an integration because you must map the message content from a previous step to a Slack connection field. In other words, a data mapping step must be in the integration just before the Slack connection.

To add a Slack connection to an integration, you must be creating or editing an integration. If you are creating an integration, then Fuse Online might be prompting you to choose a finish connection. To add a middle connection, hover over the plus sign in the left panel in the location where you want to add the connection and select Add a connection.

To add a Slack connection:

  1. Click the Slack connection that you want to add to the integration.

  2. Select the action that you want the connection to perform.

    • Click Username to send a message to one user. To configure this action, in the User name field, specify the name of the user to send the message to.
    • Click Channel to publish a message on a channel. To configure this action, in the Channel field, specify the channel to publish the message to. The integration sends the integration data in a message to that channel.
  3. Click Done to add the connection to the integration.
  4. After you add all connections to the integration, add a data mapping step just before the Slack connection. In the mapping step, map a string from a previous step to the Slack message field. This string should contain the message that you want to send to the Slack user or channel. See Add data mapping step.

Chapter 16. Connecting to SQL databases

In an integration, you can connect to any of the following types of SQL databases:

  • Apache Derby
  • MySQL
  • PostgreSQL

You create a connection to the database that you want to access in an integration and then you add that connection to an integration.

To connect to other types of databases, you must upload a JDBC driver for that database.

See the following topics for details:

16.1. Create a database connection

You create a separate connection for each database that you want to connect to in an integration. You can use the same connection in multiple integrations.

A database connection operates on a database table that you specify or invokes a stored procedure that you specify. The database table or the stored procedure must exist when an integration connects to the database.

To create a database connection:

  1. Ensure that the JDBC driver for the database that you want to connect to is on your classpath. If you uploaded a JDBC driver library extension to connect to a proprietary database, then the upload process puts the driver on your classpath. See Creating JDBC driver library extensions.
  2. In Fuse Online, in the left panel, click Connections to display any available connections.
  3. In the upper right, click Create Connection to display Fuse Online connectors.
  4. Click the Database connector.

  5. Configure the connection by entering:

    1. In the Connection URL field, enter the JDBC URL for the database that you want to connect to. For example, enter jdbc:postgresql://ignite-db1234/sampledb.
    2. In the Username field, enter the name of the account that you want to use to access the database. Ensure that the specified password and user name are for the same account.
    3. In the Password field, enter the password associated with the user account you want to use to access the database.
    4. In the Schema field, enter the name of the schema for the database. If the connection URL specifies the schema, ensure that this field indicates the same schema as the connection URL. For example, enter sampledb.
  6. Click Validate. Fuse Online tries to validate the connection and displays a message that indicates whether validation is successful. If validation fails, revise the configuration details as needed and try again.
  7. If validation is successful, click Next.
  8. In the Connection Name field, enter your choice of a name that helps you distinguish this connection from any other connections. For example, enter PostgreSQL DB 1.
  9. In the Description field, optionally enter any information that is helpful to know about this connection. For example, enter Sample PostgreSQL connection that uses my login credentials.
  10. In the upper right, click Create to see that the connection you created is now available. If you entered the example name, you would see that PostgreSQL DB 1 appears as a connection that you can choose to add to an integration.

16.2. Add a database connection to an integration

You must create a database connection before you can add a database connection to an integration. If you did not already create the database connection, see Section 16.1, “Create a database connection”.

See the instructions for where in the integration you want to access the database:

16.2.1. Start an integration by accessing a database

To start an integration by accessing a database:

  1. In the Fuse Online panel on the left, click Integrations.
  2. Click Create Integration.
  3. On the Choose a Start Connection page, click the database connection that you want to use to start an integration.

  4. On the Choose an Action page, click one of the following:

    • Periodic SQL invocation obtains data by periodically invoking the SQL query you specify.
    • Periodic stored procedure invocation obtains data by periodically invoking the stored procedure you specify or select.

  5. If you selected Periodic SQL invocation, in the Query field, enter a SQL SELECT statement to obtain one or more records. For example: SELECT * from my_db_table. The database table that contains the data you want must already exist.

    If you selected Periodic stored procedure invocation, in the Procedure name field, select or enter the stored procedure to invoke to obtain the data of interest. The stored procedure you specify must already exist. The database administrator should have created any stored procedures you need to use in an integration.

  6. In the Period field, enter an integer and indicate whether the unit is milliseconds, seconds, minutes, hours, or days. For example, if you specify 5 minutes then the connection invokes the specified query or stored procedure every five minutes.
  7. Click Done.

Fuse Online tries to validate the connection, which includes checking that a specified SQL query is syntactically correct and confirming that the query or stored procedure target data exists. If verification is successful then Fuse Online adds the start connection to the integration. If verification fails then Fuse Online displays a message about the problem. Update your input as needed and try again.

16.2.2. Access a database in the middle or to complete an integration

To finish an integration by accessing a database, add a database connection as the finish connection. To access a database in the middle of an integration, add a database connection between the start and finish connections. The instructions below assume that you are on the Fuse Online Choose a Finish Connection page or the Choose a Connection page.

To add a database connection:

  1. Click the database connection for the database you want to access.

  2. On the Choose an Action page, click one of the following:

    • Invoke SQL operates on data by executing the SQL statement you specify.
    • Invoke stored procedure operates on data by invoking the stored procedure you specify or select.

  3. If you selected Invoke SQL, in the SQL Statement field:

    • For a middle connection, enter a SQL SELECT statement that obtains one or more records or enter a SQL INSERT, UPDATE, or DELETE statement that operates on one or more records. The database table that contains the data must already exist.
    • For a finish connection, enter a SQL INSERT, UPDATE or DELETE statement to operate on one or more records.

    If you selected Invoke stored procedure, in the Procedure name field, select or enter the name of the stored procedure to invoke to operate on the data of interest. The stored procedure you specify must already exist. The database administrator should have created any stored procedures you need to use in an integration.

    • See the information below about specifying placeholder parameters in queries.
  4. Click Done.

Fuse Online tries to validate the connection, which includes checking that a specified SQL query is syntactically correct and confirming that the query or stored procedure target data exists. If verification is successful then Fuse Online adds the connection to the integration. If verification fails then Fuse Online displays a message about the problem. Update your input as needed and try again.

Specifying parameters in queries

When you access a database in the middle of an integration or to complete an integration, you can specify placeholder parameters in the SQL query or there can be placeholders in the stored procedure. For example: 

INSERT INTO TODO(task, completed) VALUES(:#param_1, :#param_2)
DELETE FROM TODO WHERE task LIKE :#param_3

To specify the values of these placeholders, add a data mapping step to your integration before the database connection. In the data mapping step, map the appropriate source data fields to the target data fields, for example, map source data to the :#param_1, :#param_2, and :#param_3 target fields. See Add a data mapping step.

16.3. Connect to proprietary databases

To connect to a proprietary SQL database, the main tasks that must be accomplished are as follows:

  1. A developer creates a library extension that contains the JDBC driver for the database that you want to access in an integration. See Creating JDBC driver library extensions.
  2. The developer provides a .jar file that contains the library extension.
  3. You upload that .jar file to Fuse Online. See Making extensions available.
  4. You create a connection to your database by selecting the Fuse Online Database connector and specifying the connection URL for your database. See Creating database connections.
  5. In an integration, you add the connection to your database. See Adding database connections.

Chapter 17. Connecting to Twitter

To connect to Twitter in an integration, see the following topics:

You need a Twitter developer account to authorize access from your Fuse Online environment to Twitter. If you do not already have a Twitter developer account, go to https://apps.twitter.com, sign in to Twitter, and click Apply for a developer account. Obtaining the developer account is quick when you provide a professional email address, such as me@redhat.com rather than a personal address such as you@gmail.com.

17.1. Register Fuse Online as a Twitter client application

You must register your Fuse Online environment as a client application that can access Twitter. This lets you create any number of integrations that connect to Twitter. In other words, you need to register a particular Fuse Online environment with Twitter only once.

In each Fuse Online environment, there can be only one registration of Fuse Online as a Twitter client application. However, while each Twitter connection uses the same registration, it can use different user credentials.

Perform these steps:

  1. In Fuse Online:

    1. In the left panel, click Settings.
    2. On the Settings page, near the top, to the right of the callback URL, click Copy Callback URL to copy the callback URL for your installation of Fuse Online to the clipboard. You will need this URL later in this procedure.
    3. To the right of the Twitter entry, click Register to display the Consumer Key and Consumer Secret fields.

  2. In another browser tab, go to your Twitter developer account, sign in if you need to, and do the following:

    1. In the upper right, next to the name of your developer project, click the down caret and click Apps.
    2. In the upper right, click Create an app.
    3. In the App name field, enter a name such as My Fuse Online Client.
    4. In the Application description field, enter a tip such as For leveraging tweets.
    5. In the Website URL field, paste the URL that you copied at the beginning of this procedure and remove api/v1/credentials/callback from the end of the URL.
    6. Select Enable Sign in with Twitter.
    7. In the Callback URLs field, paste the URL again. It should be something like this: https://app-proj9128.7b63.fuse-ignite.openshiftapps.com/api/v1/credentials/callback.
    8. A 100-character description of how you plan to use this app is required. For convenience, you can copy and paste: This is a demo application so that I can evaluate how to integrate Twitter with my enterprise applications.
    9. Click Create.
    10. Click Create again to confirm that you reviewed the developer terms.
    11. At the top of the page for the app you just created, click the Keys and tokens tab.
    12. Copy the API key.
  3. Return to your Fuse Online Settings page, paste the Twitter consumer API key into the Twitter Consumer Key field.
  4. On the Twitter Keys and tokens tab, copy the consumer API secret key. and paste it into the Fuse Online Twitter Consumer Secret field.
  5. Click Save and then click Ok.

17.2. Create a Twitter connection

A connection to Twitter requires registration of Fuse Online as an application that can access Twitter. If you did not already register Fuse Online, see Section 17.1, “Register Fuse Online as a Twitter client application”.

After you create a Twitter connection, you can use it in multiple integrations.

To create a Twitter connection:

  1. In Fuse Online, in the left panel, click Connections to display any available connections.
  2. In the upper right, click Create Connection to display the available connectors. A connector is a template that you use to create one or more connections.
  3. Click the Twitter connector.
  4. Click Connect Twitter to display a Twitter authorization page. You might need to log in to Twitter before you see the authorization page.
  5. Click Authorize app to return to Fuse Online.
  6. In the Connection Name field, enter your choice of a name that helps you distinguish this connection from any other connections. For example, enter Twitter Connect 1.
  7. In the Description field, optionally enter any information that is helpful to know about this connection. For example, enter Sample Twitter connection that uses my Twitter login credentials.
  8. In the upper right, click Create to see that the connection you created is now available. If you entered the example name, you would see that Twitter Connect 1 appears as a connection that you can choose to add to an integration.

17.3. Add a Twitter connection to an integration

You must create a Twitter connection before you can add a Twitter connection to an integration. If you did not already create a Twitter connection, see Section 17.2, “Create a Twitter connection”.

A connection to Twitter must be the start connection in an integration. You must be creating an integration and being prompted to choose its start connection or you can be updating an integration to change its start connection. If you need to, see the general procedure for creating an integration. or see updating integrations.

To add a Twitter connection to an integration:

  1. On the page that displays available connections, click the Twitter connection that you want to add to the integration. When the integration uses the selected connection to connect to Twitter, Fuse Online uses the credentials defined in that connection.

  2. Click the action that you want the selected connection to perform. A Twitter connection that you add to an integration performs only the action you choose.

    • Mention triggers execution of the integration when a tweet contains your handle.
    • Search triggers execution of the integration when a tweet contains text that you specify.
  3. Optionally, enter the configuration information that Fuse Online prompts for. For example, the Search action prompts you to specify how often to search and keywords to search for.
  4. Click Done to add the connection to the integration.

The connection appears in the integration flow as the start connection.

Chapter 18. Triggering integrations with HTTP requests (Webhook)

You can trigger an integration by sending an HTTP GET or POST request to an HTTP endpoint that Fuse Online exposes.

18.1. General procedure for using the Fuse Online webhook

To trigger execution of an integration with an HTTP GET or POST request, you must do the following:

  1. Decide whether you want to send a GET or POST request to Fuse Online.
  2. Plan your integration to handle this request.

  3. Create the connection that finishes the integration.

    Fuse Online provides a Webhook connection that you use as the start connection.

  4. Create any other connections that you want to add to the integration.

  5. Create the integration:

    1. Add the Webhook connection as the start connection.

    2. Add the finish connection and then any other connections that are required in the integration. The finish connection and any middle connections handle the HTTP request that triggers execution of the integration. It is up to you to choose and specify the most appropriate HTTP request for accomplishing your goals. Keep the following in mind:

      • Add a connection to the application that contains the data that you want to obtain or that contains the data that you want to update.
      • A GET request is limited to specification of key/value parameters.
      • A POST request can provide an arbitrary body, such as an XML or JSON instance.
      • Fuse Online returns only an HTTP status header and does not return any data. Consequently, you can define an integration that is triggered by a GET request and that updates data rather than obtaining data. Likewise, you can define an integration that is triggered by a POST request and that obtains data rather than updating data.

    3. Add a data mapper step after the Webhook connection.

      For a GET request, map the parameter fields in the HTTP request to the data fields in the next connection.

      For a POST request, you might have specified the output data shape in the request by passing a JSON instance, JSON schema, XML instance, or XML schema. If you did not, then when you add a Webhook connection as the start connection of an integration, Fuse Online prompts you to specify the output data type. If you do not, then the default Webhook connection output data type is in JSON format.

    4. Add any other steps that the integration needs.
  6. Publish the integration and wait for it to be Running.
  7. Go to the integration summary page and copy the external URL that Fuse Online provides.
  8. Modify this external URL to construct your GET or POST request.
  9. Implement the application that sends the HTTP GET or POST request to Fuse Online.

18.2. Use the Webhook connection

Fuse Online provides a Webhook connection that you can use in any number of integrations as the start connection. Each time you add this Webhook connection to an integration, Fuse Online provides a new random token for use with that integration. You paste this token at the end of your GET or POST request.

If you inadvertently delete the Webhook connection, create a new one as follows:

  1. In Fuse Online, in the left panel, click Connections to display any available connections.
  2. In the upper right, click Create Connection to display connectors.
  3. Click the Webhook connector.
  4. In the Connection Name field, enter your choice of a name that helps you distinguish this connection from any other connections. For example, you might enter Webhook 1.
  5. In the Description field, optionally enter any information that is helpful to know about this connection. For example, enter Sample Webhook connection.
  6. In the upper right, click Create to see that the connection you created is now available. If you entered the example name, you would see that Webhook 1 appears as a connection that you can choose to add to an integration.

18.3. Create an integration that an HTTP request can trigger

To trigger an integration with an HTTP GET or POST request:

  1. In the Fuse Online panel on the left, click Integrations.
  2. Click Create Integration.
  3. On the Choose a Start Connection page, click the Webhook connection.
  4. On the Choose an Action page, click the Incoming Webhook action.

  5. In the Webhook Configuration page, Fuse Online displays the webhook token that Fuse Online generates for this integration.

    When you construct the HTTP request, this token is the last part of the URL. After you publish this integration and it is running, Fuse Online displays the Fuse Online external URL, which has this token at the end.

  6. Click Next.

  7. In the Specify Output Data Type page:

    1. In the Select Type field, select JSON schema.
    2. In the Definition field, paste the JSON schema that defines the data types of the parameters in the HTTP request. See Section 18.6, “About the JSON schema for specifying request parameters”.
    3. In the Data Type Name field, specify a name for this data type. Although this is optional, if you specify a name, it appears in the data mapper Sources list, which can make it easier to correctly map fields.
    4. Optionally, in the Data Type Description field, provide some information that helps you distinguish this data type.
    5. Click Done.
  8. Add the finish connection to the integration.
  9. Add any other needed connections.
  10. Immediately after the start connection, add a data mapper step.
  11. Add any other needed steps.
  12. Click Publish, give the integration a name and optionally, a description, and click Publish again.

18.4. How Fuse Online handles HTTP requests

You can specify an HTTP GET or POST request to trigger execution of an integration. Although a GET request usually obtains data and a POST request usually updates data, you can use either request to trigger an integration that does either operation. Any parameters in the request are available for mapping to data fields in the next connection that is in the integration. For details, see Section 18.6, “About the JSON schema for specifying request parameters”.

A Webhook connection only passes the data it receives to the next connection in the integration. When Fuse Online receives an HTTP request, it:

  • Returns an HTTP status header to the requester. When a request successfully triggers an integration, the Fuse Online return code is 201. When a request fails to trigger an integration, the Fuse Online return code is 5xx.
  • Does not return any other data to the requester. In other words, there is no data in the HTTP body of the response that contains the status header.
  • Passes the data in the request to the next connection in the integration.

This means that you can define an integration that is triggered by a GET request and that updates data rather than obtaining data. Likewise, you can define an integration that is triggered by a POST request and that obtains data rather than updating data.

18.5. Guidelines for an HTTP client that invokes a Fuse Online Webhook

When you implement a client that sends an HTTP request to Fuse Online, your implementation should:

  • Add to the Fuse Online-provided external URL to construct a URL that makes a GET or POST request.
  • In the URL request, specify HTTP header and query parameter values whose data types adhere to the io:syndesis:webhook JSON schema. See Section 18.6, “About the JSON schema for specifying request parameters”. When header and query parameters adhere to this data type specification, then you can map parameter fields to fields that the next connection in the integration can process.
  • If the request succeeds, handle a returned success code of 201.
  • If the request fails, handle an HTTP 5xx error code.
  • Not expect any other response from Fuse Online. In other words, sending the request does not directly return data to the requesting client other than the return code.

18.6. About the JSON schema for specifying request parameters

In an integration, you typically map header and query parameters in the HTTP request to data fields that the next connection in the integration can process. To make this possible, when you add the Webhook connection to the integration, specify the output data type in a JSON schema that has the following structure: 

{
  "$schema": "http: //json-schema.org/schema#",
   "id": "io:syndesis:webhook",
   "type": "object",
   "properties": {
      "parameters": {
         "type": "object",
         "properties": { 1
         }
      },
      "body": {
         "type": "object",
         "properties": { 2
         }
      }
   }
}

To add the data structures that you need, in the JSON instance for your HTTP request:

1
Specify query parameters in the properties section under the parameters object.
2
Specify the HTTP body schema in the properties section under the body object.

While all data that an HTTP client sends is available in the integration, when a Webhook connection’s data shape conforms to this JSON schema, then query parameters and body content are available for mapping.

For examples, see Section 18.7, “How to specify HTTP requests”.

18.7. How to specify HTTP requests

The following examples show how to specify HTTP requests for the Fuse Online Webhook.

Webhook example of POST request with only HTTP body

Consider an integration that starts with a Webhook connection and then creates a row in the Todo table of the Fuse Online-provided database:

Webhook-Data Mapper-DB integration

During creation of this integration, when you add the Webhook start connection, you specify its output data type with a JSON instance that has this content: {"todo":"text"}:

Specify Data Shape Image

When you add the PostgresDB connection as the finish connection, you select the Invoke SQL action and specify this SQL statement:

INSERT INTO TODO (TASK) VALUES (:#TASK)

After you add the database connection, you add a mapping step:

Map Todo to Task

You save and publish the integration. When it is running, you can copy the external URL that Fuse Online provides:

External URL

To understand the parts of the external URL, consider this sample URL:

https://i-webhook-to-db-myproject.192.168.64.4.nip.io/webhook/bvGvQdpq308BcHIQQYeysFOK4plFISmghNHkRyOOk3YppitvOd

ValueDescription

i-

Fuse Online always inserts this value at the beginning of the URL.

webhook-to-db

The name of the integration.

myproject

The OpenShift namespace that contains the pod that is running the integration.

192.168.64.4.nip.io

The DNS domain that is configured for OpenShift. This indicates the Fuse Online environment that is providing the webhook.

webhook

Appears in each Webhook connection URL.

bvGvQdpq308BcHIQQYeysFOK4plFISmghNHkRyOOk3YppitvOd

Webhook connection token that Fuse Online provides when you add a Webhook connection to an integration. The token is a random string that provides security in that it makes the URL hard to discern, which prevents anyone else from sending a request.

In a request, you can specify the token that Fuse Online provides or you can define your own. If you define your own, ensure that it is hard to guess.

As you can see in the external URL, Fuse Online constructs the host name from the name of the integration, the name of the OpenShift namespace, and the OpenShift DNS domain. Fuse Online removes illegal characters and converts spaces to hyphens. In the sample external URL, this is the host name:

https://i-webhook-to-db-myproject.192.168.64.4.nip.io

To use curl to invoke the webhook, you would specify the command as follows:

curl -H 'Content-Type: application/json' -d '{"todo":"from webhook"}' https://i-webhook-to-db-myproject.192.168.64.4.nip.io/webhook/bvGvQdpq308BcHIQQYeysFOK4plFISmghNHkRyOOk3YppitvOd

  • The -H option specifies the HTTP Content-Type header.
  • The -d option sets the HTTP method to POST by default.

Execution of this command triggers the integration. The database finish connection inserts a new task into the tasks table. To see this, display the Todo app at, for example, https://todo-myproject.192.168.64.4.nip.io, Click Update and you should see from webhook as a new task.

Webhook example of POST request with query parameters

For this example, consider the same integration as in the previous example:

Webhook-Data Mapper-DB integration

But in this example, you define the Webhook connection output data type by specifying a JSON schema with this content: 

{
  "type": "object",
  "definitions": {},
  "$schema": "http://json-schema.org/draft-07/schema#",
  "id": "io:syndesis:webhook",
  "properties": {
    "parameters": {
      "type": "object",
      "properties": {
        "source": {
          "type": "string"
        },
        "status": {
          "type": "string"
        }
      }
    },
    "body": {
      "type": "object",
      "properties": {
        "company": {
          "type": "string"
        },
        "email": {
          "type": "string"
        },
        "phone": {
          "type": "string"
        }
      }
    }
  }
}

In this JSON schema:

  • The id must be set to io.syndesis.webhook.
  • The parameters section must specify the HTTP query parameters.
  • The body section must specify the body content and it can be as complex as you need it to be. For example, it can define nested properties as well as arrays.

This provides the information that the Webhook connector needs to prepare the content for the next step in the integration.

To use curl to send an HTTP request, invoke a command such as the following:

curl -H 'Content-Type: application/json' -d '{"company":"Gadgets","email":"sales@gadgets.com","phone":"+1-202-555-0152"}'https://i-webhook-params-to-db-myproject.192.168.42.235.nip.io/webhook/ZYWrhaW7dVk097vNsLX3YJ1GyxUFMFRteLpw0z4O69MW7d2Kjg?source=web&status=new

When the Webhook connection receives this request it creates a JSON instance that looks like this: 

{
  "parameters": {
    "source": "web",
    "status": "new"
  },
  "body": {
    "company": "Gadgets",
    "email": "sales@gadgets.com",
    "phone": "+1-202-555-0152"
  }
}

It is this internal JSON instance that enables the following mapping:

Map to Add Lead

Webhook examples with GET

To trigger an integration with a GET request that does not provide input data, specify the Webhook connection output data shape as a JSON instance with the definition '{}'. You can then invoke the following curl command, which does not specify query parameters:

curl 'https://i-webhook-params-to-db-myproject.192.168.42.235.nip.io/webhook/ZYWrhaW7dVk097vNsLX3YJ1GyxUFMFRteLpw0z4O69MW7d2Kjg'

Important

In this release, it is a known problem that specification of a JSON schema for a Webhook connection output data shape is not applied to GET requests. Consequently, the only way to access query parameters in a GET request is to create an extension that accesses the query parameters from Camel message headers. It is expected that this limitation will be removed in a future release.

When this limitation is removed then you can change the previous POST example to send a GET request with query parameters but no body. You would specify the Webhook connection output data shape as a JSON schema with the definition as shown below. 

{
  "type": "object",
  "definitions": {},
  "$schema": "http://json-schema.org/draft-07/schema#",
  "id": "io:syndesis:webhook",
  "properties": {
    "parameters": {
      "type": "object",
      "properties": {
        "source": {
          "type": "string"
        },
        "status": {
          "type": "string"
        }
      }
    },
    "body": {
      "type": "object"
    }
  }
}

This schema defines an empty body. Here is the curl command that sends the GET request:

curl 'https://i-webhook-params-to-db-myproject.192.168.42.235.nip.io/webhook/ZYWrhaW7dVk097vNsLX3YJ1GyxUFMFRteLpw0z4O69MW7d2Kjg?source=web&status=new'`

In this release, this example works only if you create an extension that accesses the query parameters.

Legal Notice

Copyright © 2019 Red Hat, Inc.
The text of and illustrations in this document are licensed by Red Hat under a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is available at http://creativecommons.org/licenses/by-sa/3.0/. In accordance with CC-BY-SA, if you distribute this document or an adaptation of it, you must provide the URL for the original version.
Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.
Red Hat, Red Hat Enterprise Linux, the Shadowman logo, the Red Hat logo, JBoss, OpenShift, Fedora, the Infinity logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.
Linux® is the registered trademark of Linus Torvalds in the United States and other countries.
Java® is a registered trademark of Oracle and/or its affiliates.
XFS® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries.
MySQL® is a registered trademark of MySQL AB in the United States, the European Union and other countries.
Node.js® is an official trademark of Joyent. Red Hat is not formally related to or endorsed by the official Joyent Node.js open source or commercial project.
The OpenStack® Word Mark and OpenStack logo are either registered trademarks/service marks or trademarks/service marks of the OpenStack Foundation, in the United States and other countries and are used with the OpenStack Foundation's permission. We are not affiliated with, endorsed or sponsored by the OpenStack Foundation, or the OpenStack community.
All other trademarks are the property of their respective owners.