Syndesis lets you obtain data from an application or service, operate on that data if you need to, and then send the data to a completely different application or service. You can do all this without writing code.

Explore Syndesis by creating sample integrations. A comparison table can help you decide which of these integrations to create first:

See also: Integrating Applications with Fuse Online

Choosing the sample integration to create first

You can create the sample integrations in any order. To help you decide which one to try first, the following table compares them.

 

Twitter to Salesforce

Salesforce to Database

AMQ to REST API

What it does

Captures and filters tweets that mention a particular Twitter user. For tweets that contain specified text, the integration passes data related to the tweet to Salesforce and Salesforce creates a new contact.

Captures updates in Salesforce and then calls a database stored procedure to synchronize a particular database table with the Salesforce updates.

Obtains delivery records from a Red Hat AMQ broker, executes a custom step to identify any items that were damaged when they were received, and connects to a REST API to provide contact information for vendors of damaged items.

What you learn about

Connecting to Twitter and Salesforce, how Syndesis interfaces with applications that use the OAuth protocol, mapping data fields received from one application to fields that the next connected application in the integration can operate on, filtering data to determine whether to continue integration execution.

Connecting to Salesforce and a SQL database, OAuth support, data mapping, how to update a SQL database as part of an integration.

Connecting to a Red Hat AMQ broker and a REST API, data mapping, uploading extensions for a step and for a REST API client connector, using a custom step and a custom API client connection.

Average minutes to complete

25

20

25

Notes about the time

This includes the time needed to obtain Twitter and Salesforce accounts. It does not include 5 - 12 minutes of waiting for Salesforce registration to take effect and for Syndesis to start running the integration.

20 minutes includes the time needed to obtain a Salesforce developer account but not the time spent waiting. If you already created the Twitter to Salesforce sample then it takes 10 minutes to create this integration.

This does not include the time it takes for Syndesis to start running the integration.

Prerequisites

Twitter developer account, Salesforce developer account

Salesforce developer account, sample todo application enabled, and sample Postgres database enabled

Sample todo application and sample Postgres database enabled

Implementing the Twitter to Salesforce sample integration

This sample integration watches Twitter for tweets that mention a particular Twitter user. When the integration finds such tweets, it filters them so that only those tweets that contain the text that you specify cause the integration to continue.

For tweets that contain the specified text, the integration passes data related to the tweet, including the Twitter user name, to Salesforce and Salesforce creates a new contact.

Prerequisites

  • You need a Twitter developer account. If you do not already have one, 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 [email protected] rather than a personal address such as [email protected].

  • You need an account in a Salesforce installation that is used for development. This account must have Salesforce API access, which is available in a Salesforce Enterprise account or a Salesforce Developer account. To obtain a free developer account, visit https://developer.salesforce.com/signup. It takes less than two minutes to obtain a Salesforce account.

To implement, deploy, and test this sample integration, the main steps are:

  1. Registering Syndesis as a Twitter client application

  2. Creating a Twitter connection

  3. Registering Syndesis as a Salesforce client application

  4. Creating a Salesforce connection

  5. Creating and deploying the Twitter to Salesforce sample integration

  6. Confirming that the Twitter to Salesforce integration works

  7. Cleaning up your integration

Registering Syndesis as a Twitter client application

In an integration, to connect to Twitter, the first thing you must do is register your Syndesis 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 Syndesis environment with Twitter only once.

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

Prerequisite

You are logged in to Syndesis.

Procedure

  1. In Syndesis:

    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 URLto copy the callback URL for your installation of Syndesis to the clipboard. You will need this URL later in this procedure.

    3. Click the Twitter entry to display the Consumer API Key and Consumer API Secret Key fields.

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

    1. Click Projects & Apps.

    2. On the Overview page, scroll down to click Create an app.

    3. In the App name field, enter a name such as My Syndesis Client.

    4. In the Application description field, enter a tip such as For leveraging tweets.

    5. Scroll down to Set up Your App and then click App settings.

    6. Next to Authentication Settings, click Edit.

    7. Switch on the Enable 3-legged OAuth option.

    8. In the Callback URLs field, paste the URL that you copied at the beginning of this procedure. It should be something like this: https://app-proj912876.7b63.fuse-ignite.openshiftapps.com/api/v1/credentials/callback

    9. In the Website URL field, paste the URL again and remove api/v1/credentials/callback from the end of the URL.

      You can skip the next few fields.

    10. Click Save.

    11. At the top of the page for the app that you just created, click the Keys and tokens tab.

    12. Under Consumer Keys, click View keys.

    13. Copy the API key.

  3. Return to your Syndesis Settings page and paste the Twitter consumer API key into the Syndesis Twitter Consumer API Key field.

  4. Return to the Twitter Keys and tokens tab and copy the consumer API secret key.

  5. Return to your Syndesis Settings page and paste the Twitter consumer API secret key into the Syndesis Twitter Consumer API Secret Key field.

  6. Click Save.

  7. Click the Twitter entry to collapse it.

Creating a Twitter connection

To create an integration that obtains data from Twitter, you must first create a Twitter connection. After you create a Twitter connection, you can use it in any number of integrations.

Prerequisites

  • You are logged in to Syndesis.

  • Syndesis is open in a web browser.

  • You registered your Syndesis environment as an application that can access Twitter.

  • You added the Twitter consumer API key and consumer API secret key that you received after registration to the Syndesis Settings page.

Procedure

  1. In Syndesis, in the left panel, click Connections to display any available connections.

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

    If Connect Twitter does not appear, then your Syndesis environment is not registered as a Twitter client application. See Registering Syndesis as a Twitter client application. When you try to create a Twitter connection and your Syndesis environment is not registered as a Twitter client application, then Syndesis displays multiple fields that prompt for authorization information. While you can create a Twitter connection by entering values in these fields, it is not recommended.

  5. Click Authorize app to return to Syndesis.

  6. In the 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. Click Save 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.

Registering Syndesis as a Salesforce client application

In an integration, to connect to Salesforce, the first thing you must do is register your Syndesis 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 Syndesis environment with Salesforce only once.

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

If you already registered Syndesis as a Salesforce client and created a Salesforce connection, skip to Creating and deploying the Twitter to Salesforce integration.

Prerequisite

You are logged in to Syndesis.

Procedure

  1. In Syndesis:

    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 URLto copy the callback URL for your Syndesis environment to the clipboard. You will need this URL toward the end of this procedure.

    3. Click the Salesforce entry 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 Syndesis URL, which you copied at the beginning of this procedure. For example: https://app-proj912876.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 Syndesis Settings page and paste the Salesforce-provided consumer key into the Syndesis Salesforce Client ID field.

  4. Return to Salesforce and copy the consumer secret that Salesforce provides.

  5. Return to your Syndesis Settings page and paste the Salesforce-provided consumer secret into the Syndesis Salesforce Client Secret field.

  6. Click Save.

  7. Click the Salesforce entry to collapse it.

Creating a Salesforce connection

To create an integration that accesses data in Salesforce, you must first create a Salesforce connection. After you create a Salesforce connection, you can use it in multiple integrations.

Prerequisites

  • You are logged in to Syndesis.

  • Syndesis is open in a web browser.

  • You must have already registered your Syndesis environment as an application that can access Salesforce.

  • You added the Salesforce client ID and client secret that you received after registration to the Syndesis Settings page.

    If you did not already register Syndesis, see Registering Syndesis as a Salesforce client application.

    Be sure to wait 2 - 10 minutes after registering your Syndesis installation as a Salesforce client before you try to create a Salesforce connection.

Procedure

  1. In Syndesis, in the left panel, click Connections to display available connections.

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

    If Connect Salesforce does not appear, then your Syndesis environment is not registered as a Salesforce client application. See Registering Syndesis as a Salesforce client application. When you try to create a Salesforce connection and your Syndesis environment is not registered as a Salesforce client application, then Syndesis displays multiple fields that prompt for authorization information. While you can create a Salesforce connection by entering values in these fields, it is not recommended.

    Note

    The following error indicates that Salesforce does not have the correct Syndesis 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 Syndesis callback URL is specified according to the instructions in Registering Syndesis as a Salesforce client application.

  5. Click Allow to return to Syndesis.

  6. In the 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. Click Save 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.

Creating and deploying the Twitter to Salesforce sample integration

To create and deploy an integration that uses the Twitter and Salesforce connections that you created, the main steps are:

Prerequisites

  • You registered your Syndesis environment as a Twitter client and created a Syndesis Twitter connection.

  • You registered your Syndesis environment as a Salesforce client and created a Syndesis Salesforce connection.

  • Syndesis is open and you are logged in.

Choosing the start connection

In Syndesis, to create the sample Twitter to Salesforce integration, the first task is to choose the start connection.

Prerequisites

  • You created a Twitter connection.

Procedure

  1. On the left, click Integrations.

  2. Click Create Integration.

  3. On the Choose a connection page, click the Twitter connection that you created. If you gave it the example name, you would click Twitter Connect 1. When the integration starts, it uses the credentials defined in this connection to connect to Twitter.

  4. On the Choose an action page, to the right of the Mention action entry, click Select.

  5. On the Configure the action page, click Next. No configuration is required.

Next step

When the integration is running, after connecting to Twitter, the integration monitors Twitter for mentions that include your Twitter screen name. A match triggers the next step in the integration. However, before you add steps that operate on data between connections, you choose the connection that the integration uses to finish its work.

Choosing the finish connection

In Syndesis, to continue creating the Twitter to Salesforce sample integration, after you add the start connection, you add the finish connection to the integration.

Prerequisites

  • You added the Twitter connection to the integration as the start connection.

  • Syndesis is prompting you to add the finish connection.

  • You created a Salesforce connection.

Procedure

  1. On the Choose a connection page, click the Salesforce connection that you created. If you gave it the example name, you would click SF Connect 1. This integration finishes by using the credentials defined in this connection to connect to Salesforce.

  2. On the Choose an action page, to the right of the New record entry, click Select.

  3. On the Configure the action page, click in the Object name field and select Contact as the Salesforce record to create.

  4. Click Next to add the finish connection to the integration.

Adding a basic filter step

In Syndesis, to continue creating the Twitter to Salesforce sample integration, add a basic filter step that checks tweets that mention you for particular content. At integration execution time, processing continues only if that content is present.

Prerequisites

  • You added the Twitter connection as the integration’s start connection.

  • You just added the Salesforce connection as the integration’s finish connection.

Procedure

  1. In the integration visualization, click the plus sign, which displays the steps that you can add to the integration.

  2. Click Basic Filter.

  3. In the Property Name field, start to enter text and when text appears below the field, click it. The Twitter text field, which contains a tweet, is the data that you want the filter to evaluate.

  4. In the Operator field, accept contains as the condition to be met for the integration to continue.

  5. In the Keywords field, enter #RedHatIsGreat or some other text that you choose for the value to check for. A tweet that mentions you must contain the text you enter here for the integration to continue operating on this data.

  6. Click Done to add the basic filter step to the integration.

Adding a data mapping step

To continue creating the Twitter to Salesforce sample integration, add a data mapping step that correlates Twitter mention fields to Salesforce contact fields.

Prerequisites

  • The integration’s start connection is to Twitter.

  • The integration’s finish connection is to Salesforce.

  • You just added the filter step between the two connections.

Procedure

  1. In Syndesis, in the integration visualization, click the plus sign that is between the filter step and the finish connection.

  2. Click Data Mapper and wait a few moments. When the data fields appear, the Sources panel on the left displays the Twitter fields and the Target panel on the right displays the Salesforce fields.

  3. Map the Twitter name field to the Salesforce FirstName and LastName fields:

    1. In the Sources panel, click the magnifying glass magnifying glassto display the search field and enter name.

    2. Under the user folder, click the name field and then click the Create New Mapping icon.

    3. In the Mapping Details panel, in the Targets field, type FirstName to filter the list of target fields and then select /FirstName. The data mapper displays a line from the source name field to the target FirstName field.

    4. In the Mapping Details panel, in the Targets field, type LastName to filter the list of target fields and then select /LastName.

      The data mapper displays another line from the Twitter name field, but this time it goes to the Salesforce LastName field. The blue lines indicate the current focus.

      Note

      If you accidentally map the wrong fields then delete the incorrect mapping by clicking the trash can icon in the data mapper’s Mapping Details panel.

  4. Map the Twitter screenName field to the Salesforce Title field:

    1. In the Sources panel, click the screenName field.

    2. On the right, at the top of the Target panel, click the magnifying glass magnifying glassto display the search field and enter Title.

    3. Click the Title field. The data mapper displays a line from the Twitter screenName field to the Salesforce Title field.

  5. Map the Twitter text field to the Salesforce Description field:

    1. In the Sources search field, enter text and click the text field. Be sure to click the toplevel text field. Do not click one of the text fields that is contained in the user field.

    2. In the Target search field, enter description.

    3. Click the Salesforce Description field to create the mapping.

  6. In the upper right, click the grid icon gridto display the list of mappings, which should look like this: Data Mappings

  7. In the upper right, click Done.

Giving the integration a name and deploying it

When the Twitter to Salesforce sample integration is complete then you can deploy it and see how it works.

Prerequisites

  • The integration’s start connection is Twitter.

  • The integration’s finish connection is Salesforce.

  • The integration has a filter step.

  • You just added a data mapping step to the integration.

Procedure

  1. In the upper right corner, click Publish.

  2. In the Name field, enter a name of your choice that distinguishes this integration from any other integrations. For example: Twitter to Salesforce Sample Integration.

  3. In the Description field, optionally enter some information about the integration.

  4. Click Save and publish.

    Syndesis starts to deploy the integration and then displays the integration summary. Near the top, you can see a progress indicator that shows the publishing stages. Syndesis is generating the runtime for the integration and will start it when the runtime is ready. This takes a few minutes.

    A Syndesis account is limited to a specific number of integrations that can be running at one time. For details, see the pricing plan. If you are already running the maximum number of integrations, then you must stop an integration before you can start running another one.

  5. If you are already running the maximum number of integrations, follow these steps to stop an integration:

    1. In the left panel, click Integrations.

    2. In the entry for the integration that you want to stop, click ThreeVerticalDotsKebabon the far right.

    3. In the popup, click Stop.

  6. After stopping an integration, start another integration as follows:

    1. In the left panel, click Integrations.

    2. In the entry for the integration that you want to start, click ThreeVerticalDotsKebabon the far right.

    3. In the popup, click Start.

Confirming that the Twitter to Salesforce integration works

To confirm that the Twitter to Salesforce sample integration is working, create some tweets and check for results in Salesforce.

Prerequisites

  • In Syndesis, Running appears next to the name that you specified for the Twitter to Salesforce sample integration when you published it.

  • You can access your Twitter and Salesforce accounts.

Procedure

  1. In Syndesis in the panel on the left, click Integrations to see that the integration you created is a Running integration. If you entered the example name, you would see that Twitter to Salesforce Sample Integration is running.

  2. Confirm that the integration does not create a contact record when a tweet does not contain the text you specified in the basic filter step:

    1. In Twitter, send a tweet that:

      • Mentions your Twitter handle

      • Does not contain the text that you specified in the basic filter step

        For example: @Aslan #likesRedHat.

    2. Wait for the polling interval to elapse, which can be 30 - 60 seconds.

    3. In Salesforce, confirm that there is not a new contact record for the name that is associated with the Twitter account that you used to tweet.

  3. Confirm that the integration creates a new contact record when it should:

    1. In Twitter, send a tweet that:

      • Mentions your Twitter handle

      • Contains the text that you specified in the basic filter step

        For example: @Aslan knows #RedHatIsGreat.

    2. Wait for the polling interval to elapse.

    3. In Salesforce, do the following:

      1. Log in to your regular Salesforce account, not your Salesforce developer account.

      2. On your home page, under Recent Items you should see your new contact.

      3. Click on it to view the details.

        The new contact record should have the name that is associated with the Twitter account that you used to tweet. The text of your tweet should be in the Description field, and your Twitter screen name should be in the Title field.

  4. Optionally, view the integration log to troubleshoot an unexpected result or to learn more about integration execution:

    1. In Syndesis, in the left panel, click Integrations.

    2. View your Twitter to Salesforce integration.

    3. In the integration’s summary page, click the Activity tab.

    4. Click the integration execution for which you want to view activity information.

Cleaning up your integration

When you are done working with a sample integration, you should stop it and delete it so that you can use the resources for another integration.

Prerequisites

  • You are finished working with a sample integration that you published.

Procedure

  1. In Syndesis, in the left panel, click Integrations.

  2. In the main panel, identify the entry for the sample integration that you want to stop.

  3. In that entry, to the right, click Kebab Menuand then click Stop.

  4. Click Stop to confirm that you want to stop running the integration.

  5. In the entry for the integration that you just stopped, to the right, click Kebab Menuand then click Delete.

  6. Click Delete to confirm that you want to delete the integration.

Implementing the Salesforce to database sample integration

This sample integration captures updates in Salesforce and then calls a database stored procedure, which synchronizes that database with the Salesforce updates.

Prerequisites

  • You need an account in a Salesforce installation that is used for development. This account must have Salesforce API access, which is available in a Salesforce Enterprise account or a Salesforce Developer account. To obtain a free developer account, visit https://developer.salesforce.com/signup. It takes less than two minutes to obtain a Salesforce account.

    If you already created the Twitter to Salesforce sample integration:

    • Syndesis is already registered as a Salesforce client. You do not need to do this again.

    • You already have a Salesforce connection, which you can reuse in this sample integration.

    If you did not already create the Twitter to Salesforce sample integration, then you must register Syndesis as a Salesforce client and create a Salesforce connection in order to complete the Salesforce to database sample integration.

To implement, deploy, and test this sample integration, the main steps are:

  1. Registering Syndesis as a Salesforce client application

  2. Creating a Salesforce connection

  3. Creating and deploying the Salesforce to database sample integration

  4. Confirming that the Salesforce to database integration works

  5. Cleaning up your integration

Registering Syndesis as a Salesforce client application

In an integration, to connect to Salesforce, the first thing you must do is register your Syndesis 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 Syndesis environment with Salesforce only once.

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

If you already registered Syndesis as a Salesforce client and created a Salesforce connection, skip to Creating and deploying the Salesforce to database integration.

Prerequisite

You are logged in to Syndesis.

Procedure

  1. In Syndesis:

    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 URLto copy the callback URL for your Syndesis environment to the clipboard. You will need this URL toward the end of this procedure.

    3. Click the Salesforce entry 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 Syndesis URL, which you copied at the beginning of this procedure. For example: https://app-proj912876.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 Syndesis Settings page and paste the Salesforce-provided consumer key into the Syndesis Salesforce Client ID field.

  4. Return to Salesforce and copy the consumer secret that Salesforce provides.

  5. Return to your Syndesis Settings page and paste the Salesforce-provided consumer secret into the Syndesis Salesforce Client Secret field.

  6. Click Save.

  7. Click the Salesforce entry to collapse it.

Creating a Salesforce connection

To create an integration that accesses data in Salesforce, you must first create a Salesforce connection. After you create a Salesforce connection, you can use it in multiple integrations.

Prerequisites

  • You are logged in to Syndesis.

  • Syndesis is open in a web browser.

  • You must have already registered your Syndesis environment as an application that can access Salesforce.

  • You added the Salesforce client ID and client secret that you received after registration to the Syndesis Settings page.

    If you did not already register Syndesis, see Registering Syndesis as a Salesforce client application.

    Be sure to wait 2 - 10 minutes after registering your Syndesis installation as a Salesforce client before you try to create a Salesforce connection.

Procedure

  1. In Syndesis, in the left panel, click Connections to display available connections.

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

    If Connect Salesforce does not appear, then your Syndesis environment is not registered as a Salesforce client application. See Registering Syndesis as a Salesforce client application. When you try to create a Salesforce connection and your Syndesis environment is not registered as a Salesforce client application, then Syndesis displays multiple fields that prompt for authorization information. While you can create a Salesforce connection by entering values in these fields, it is not recommended.

    Note

    The following error indicates that Salesforce does not have the correct Syndesis 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 Syndesis callback URL is specified according to the instructions in Registering Syndesis as a Salesforce client application.

  5. Click Allow to return to Syndesis.

  6. In the 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. Click Save 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.

Creating and deploying the Salesforce to database sample integration

To create and deploy an integration that uses the Salesforce connection that you created and the database connection that is provided with Syndesis, the main steps are:

Prerequisites

  • You registered your Syndesis environment as a Salesforce client.

  • You created a Syndesis Salesforce connection.

  • Syndesis is open and you are logged in.

Choosing the start connection

In Syndesis, to create the sample Salesforce to database integration, the first task is to choose the start connection.

Prerequisites

  • You created a Salesforce connection.

Procedure

  1. In Syndesis, on the left, click Integrations.

  2. Click Create Integration.

  3. On the Choose a connection page, click your Salesforce connection. If you specified the example name, you would click SF Connect 1.

  4. On the Choose an action page, to the right of On create, click Select.

  5. In the Object name field, select Lead.

  6. Click Next to add the start connection to the integration.

Next step

When the integration is running, after connecting to Salesforce, the integration watches for notifications that a Salesforce Lead record was created. When the integration finds such a notification, it passes the new lead’s data to the next step in the integration. However, before you can add the next step, you must choose the integration’s finish connection.

Choosing the finish connection

In Syndesis, to continue creating the Salesforce to database sample integration, after you add the start connection, you add the finish connection to the integration.

Prerequisites

  • You added the Salesforce connection to the integration as the start connection.

  • Syndesis is prompting you to add the finish connection.

Procedure

  1. In Syndesis, on the Choose a connection page, click the PostgresDB connection. This integration finishes by using the credentials defined in this database connection to connect to the provided sample database.

  2. On the Choose an action page, select Invoke stored procedure, which passes data to a stored procedure.

  3. In the Procedure name field, accept add_lead, which is the provided stored procedure to run in the sample database. The selected procedure determines the requirements for additional steps in the integration, for example, which Salesforce data fields need to be mapped to which database fields.

  4. Click Next to add the finish connection to the integration.

Adding a data mapping step

To continue creating the Salesforce to database sample integration, add a data mapping step that correlates Salesforce lead fields to fields in the sample database.

Prerequisites

  • The integration’s start connection is to Salesforce.

  • The integration’s finish connection is to the PostgresDB sample database.

Procedure

  1. In Syndesis, in the integration visualization, click the plus sign.

  2. Click Data Mapper and wait a few moments. When the data fields appear, the Sources panel on the left displays the Salesforce fields and the Target panel on the right displays the database fields.

  3. Map the Salesforce Company field to the database company field. On the left, in the Sources panel, click Company and drag it to the Target panel onto company.

    The data mapper displays a line from the source field to the target field.

  4. Map the Sources (Salesforce) Email field to the Target (database) email field.

  5. Map two Salesforce fields (FirstName and LastName) to the database first_and_last_name field:

    1. In the Target panel, click first_and_last_name and then click the Create New Mapping icon.

    2. In the Mapping Details panel, in the Sources field, select /FirstName and then select /LastName.

      When you are done you should see a line from each of the source fields to the target field.

  6. Add the following mappings:

    Map This Salesforce FieldTo This Database Field

    LeadSource

    lead_source

    Status

    lead_status

    Phone

    phone

    Rating

    rating

  7. In the upper right, click Done.

Giving the integration a name and deploying it

When the Salesforce to database sample integration is complete then you can deploy it and see how it works.

Prerequisites

  • The integration’s start connection is Salesforce.

  • The integration’s finish connection is to the sample database that is provided with Syndesis.

  • You just added a data mapping step to the integration.

Procedure

  1. In Syndesis, in the upper right, click Publish to give it a name.

  2. In the Name field, enter a name for the integration. For example, Salesforce to Database Sample Integration.

  3. Click Save and publish.

    Syndesis starts to deploy the integration and then displays the list of integrations in this environment. The entry for your Salesforce to database integration displays a progress indicator that shows the publishing stages. Syndesis is generating the runtime for the integration and will start it when the runtime is ready. This takes a few minutes.

    A Syndesis account is limited to a specific number of integrations that can be running at one time. For details, see the pricing plan. If you are already running the maximum number of integrations, then you must stop an integration before you can start running another one.

  4. If you are already running the maximum number of integrations, follow these steps to stop an integration:

    1. In the left panel, click Integrations.

    2. In the entry for the integration that you want to stop, click ThreeVerticalDotsKebabon the far right.

    3. In the popup, click Stop.

  5. After stopping an integration, start another integration as follows:

    1. In the left panel, click Integrations.

    2. In the entry for the integration that you want to start, click ThreeVerticalDotsKebabon the far right.

    3. In the popup, click Publish.

Confirming that the Salesforce to database integration works

To confirm that the Salesforce to database integration is working, create a new lead in Salesforce and then open the web app that Syndesis provides for viewing updates to the sample database.

Prerequisites

  • In Syndesis, Running appears next to the name that you specified for the Salesforce to database sample integration when you published it.

  • You can access your Salesforce account.

Procedure

  1. In the left panel, click Integrations.

  2. If necessary, wait until your sample integration is a Running integration. If you used the example name, you would see that Salesforce to Database Sample Integration is Running.

  3. In your Salesforce installation, create a new lead. Be sure to enter data in the fields that you mapped: Company, Email, FirstName, LastName, LeadSource, Status, Phone, and Rating.

  4. In a new browser window, insert todo- in front of the URL for your Syndesis environment. For example: http://todo-app-proj761432.6a63.fuse-ignite.openshiftapps.com/.

    Your Syndesis environment provides the To Do app, which has a REST API for accessing a database that contains tasks. In the AMQ to REST API sample integration tutorial, there are instructions for uploading an OpenAPI document for the To Do app to create an API client connector.

  5. In the To Do App display, you should see a notification that a new lead was created in the database.

  6. Optionally, view the integration log to troubleshoot an unexpected result or to learn more about integration execution:

    1. In Syndesis, in the left panel, click Integrations.

    2. View your Salesforce to database integration.

    3. In the integration’s summary page, click the Activity tab.

    4. Click the integration execution for which you want to view activity information.

Cleaning up your integration

When you are done working with a sample integration, you should stop it and delete it so that you can use the resources for another integration.

Prerequisites

  • You are finished working with a sample integration that you published.

Procedure

  1. In Syndesis, in the left panel, click Integrations.

  2. In the main panel, identify the entry for the sample integration that you want to stop.

  3. In that entry, to the right, click Kebab Menuand then click Stop.

  4. Click Stop to confirm that you want to stop running the integration.

  5. In the entry for the integration that you just stopped, to the right, click Kebab Menuand then click Delete.

  6. Click Delete to confirm that you want to delete the integration.

Implementing the AMQ to REST API sample integration

This sample integration connects to a Red Hat AMQ broker to obtain item delivery records for a hypothetical enterprise. The integration then executes a custom step that operates on the records to identify any items that were damaged when they were received. After a simple data mapping, the integration connects to a REST API to obtain contact information for vendors of damaged items.

The other sample integrations use connectors and data operations that are built into Syndesis. This integration also does that, but in addition, it provides instructions for customizing and extending Syndesis by leading you through the procedures for:

  • Adding a custom data operation by uploading an extension.

  • Adding a custom REST API client connector by uploading an OpenAPI document.

Syndesis provides the extension file and the OpenAPI document.

To implement the AMQ to REST API sample integration, the main steps are:

  1. Creating an AMQ connection

  2. Making a custom step available

  3. Creating a REST API connector

  4. Creating a REST API connection

  5. Creating and deploying the AMQ to REST API sample integration

  6. Confirming that the AMQ to REST API integration works

  7. Cleaning up your integration

Creating an AMQ connection

The AMQ to REST API sample integration starts by connecting to an AMQ broker (Red Hat AMQ) that is provided in your OpenShift project. Before you start to create the integration itself, you must start the broker and create a connection to that broker.

Procedure

  1. Verify that the broker has started:

    1. In a browser, go to your OpenShift web console.

    2. In the console, click Project.

    3. On the Overview page, in the Inventory section, click Services.

    4. Click broker-amq-tcp and then click Pods. The status of the pod should be Running.

  2. Create the AMQ connection:

    1. In Syndesis, in the left panel, click Connections to display any available connections.

    2. Click Create Connection to display Syndesis connectors.

    3. Click the Red Hat AMQ connector.

    4. Configure the connection by entering:

      1. In the Broker URL field, enter tcp://broker-amq-tcp:61616 as the location to obtain data from.

      2. In the User name field, enter amq as the user name for the account that accesses this AMQ broker.

      3. In the Password field, enter topSecret as the password for the account that accesses this AMQ broker.

      4. Leave the other fields blank.

    5. Click Validate. Syndesis immediately tries to validate the connection and displays a message that indicates whether validation is successful. If validation fails, check the values you entered and try again.

    6. When validation is successful, click Next.

    7. In the Name field, enter your choice of a name that helps you distinguish this connection from any other connections. For example, enter Red Hat AMQ Broker 1.

    8. In the Description field, optionally enter any information that is helpful to know about this connection. For example, enter Connection to the provided Red Hat AMQ message broker.

    9. Click Save to see that the connection you created is now available. If you entered the example name, you would see that Red Hat AMQ Broker 1 is now available.

Making a custom step available

Syndesis provides a number of steps that operate on integration data between connections. If Syndesis does not provide a between-connections step that meets your need, a developer can code an extension that defines one or more custom steps that operate on data between connections. The developer gives you a .jar file that contains the extension. You then upload the extension in Syndesis to make the custom step(s) available for use in integrations.

The AMQ to REST API sample integration uses a custom step that operates on data between connections to identify items that were damaged when they were received.

Procedure

  1. In a new browser tab, go to https://github.com/syndesisio/fuse-online-sample-extension/releases.

  2. Download the Damage Reporter extension’s .jar file.

  3. In Syndesis, in the left panel, click Customizations > Extensions.

  4. Click Import Extension.

  5. Click in the dotted-line box and select the downloaded .jar file that contains the extension. Syndesis validates the file, extracts and displays the extension’s ID, name, description, and type, and lists Damage Reporter as the custom step that the extension defines.

  6. Click Import Extension. Syndesis makes the custom step available and displays the list of extensions that have been imported.

Additional resources

For information about coding an extension and creating its .jar file, see:

Creating a REST API connector

Syndesis can create connectors for REST APIs that support Hypertext Transfer Protocol (HTTP)/1.0 or HTTP/1.1. To do this, Syndesis requires a valid OpenAPI 3 (or 2) document that describes a REST API that you want to connect to.

Your Syndesis environment provides the To Do app, which has a REST API for accessing a database that contains tasks. Your environment also provides an OpenAPI document for this API.

Procedure

  1. Download the icon for the todo app:

    1. In the Syndesis navigation panel, click Home.

    2. Copy the URL into a text editor.

    3. At the beginning of the URL, insert todo-.

    4. At the end of the URL, add /images/todo_icon.png.

    5. Use the http scheme instead of https.

      The result is something like this: http://todo-app-proj217402.6a63.fuse-ignite.openshiftapps.com/images/todo_icon.png

    6. Paste this URL into a new browser window and download the todo_icon.png file to a location on your file system. You will upload this icon in Step 11.

  2. Identify the URL for your Syndesis environment’s copy of the OpenAPI document:

    1. In the Syndesis navigation panel, click Home.

    2. Copy the URL into a text editor.

    3. At the beginning of the URL, insert todo-.

    4. At the end of the URL, add swagger.json.

    5. Use the http scheme instead of https.

      The result is something like this: http://todo-app-proj217402.6a63.fuse-ignite.openshiftapps.com/swagger.json

    Note
    		Specification of http rather than https avoids a runtime error if TLS certificates are not valid. In production environments, ensure that valid certificates are in place, and always specify secure URLs (https) to obtain an OpenAPI document.

  3. In the Syndesis navigation panel, click Customizations > API Client Connectors.

  4. Click Create API Connector.

  5. Select Use a URL.

  6. In the input box, paste the URL for your OpenAPI document and click Next.

  7. On the Review Actions page, click Next. If you see a warning, you can ignore it.

  8. Click Next.

  9. On the Specify Security page, accept HTTP Basic Authentication and specify a username and password, such as admin and admin. Note that, for this sample app, the username and password are not verified.

  10. Click Next.

  11. On the Todo App API summary page:

    1. For the Connector Icon, click Choose File and then navigate to the location of the todo_icon.png that you downloaded in Step 1.

    2. If you want to, you can change the values in the Name and Description fields.

    3. In the Host field, accept the name of the service host, which is something like this: http://todo-app-proj217402.6a63.fuse-ignite.openshiftapps.com.

    4. In the Base URL field, accept the part of the URL that follows the host name in service requests: /api.

  12. Click Save.

    Syndesis displays the API Client Connectors. There is a new entry for the Todo App API that you just created.

Creating a REST API connection

In an integration, before you can connect to a REST API, you create a REST API client connector and then use that connector to create a connection. You already created a REST API connector for the To Do app. Follow the instructions here to use that connector to create a connection to the To Do app REST API.

Prerequisite

  • You created the Todo App REST API connector.

Procedure

  1. In Syndesis, in the left panel, click Connections to display any available connections.

  2. Click Create Connection to display available connectors.

  3. Click the Todo App API connector that you just created.

    Syndesis populates the Host and Base Path fields from the OpenAPI document that you provided when you created the connector.

  4. In the Username field, enter any value. For this sample integration, user name and password values are required but they are not used.

  5. In the Password field, enter any value.

  6. Click Next.

  7. In the Name field, enter your choice of a name that helps you distinguish this connection from any other connections. For example, enter Todo App API Client.

  8. In the Description field, optionally enter any information that is helpful to know about this connection. For example, enter Connection to the provided Todo app REST API.

  9. Click Save to see that the connection you created is now available.

Creating and deploying the AMQ to REST API sample integration

To create and deploy the AMQ to REST API sample integration, the main steps are:

  1. Choosing the start connection

  2. Choosing the finish connection

  3. Adding a damage reporter step

  4. Adding a data mapping step

  5. Giving the integration a name and deploying it

Prerequisites

  • You created a connection to the provided Red Hat AMQ broker.

  • You created an API Client connection to the provided Todo app.

  • You uploaded the extension that provides the Damage Reporter step.

Choosing the start connection

In Syndesis, to create the sample AMQ to REST API sample integration, the first task is to choose the start connection.

Prerequisites

  • You started the provided Red Hat AMQ broker.

  • You created a connection to that message broker.

Procedure

  1. In Syndesis, on the left, click Integrations.

  2. Click Create Integration.

  3. On the Choose a connection page, click your AMQ connection. If you specified the example name, you would click Red Hat AMQ Broker 1.

  4. On the Choose an action page, select the Subscribe for messages action to receive messages from the queue you specify.

  5. In the Destination name field, enter inventoryReceived for the name of the queue to obtain data from.

  6. Click in the Destination type field and select Queue.

  7. Leave the other fields blank.

  8. Click Next. Syndesis prompts you to specify the output data type. This is not needed for this sample integration.

  9. Click Next to add the start connection to the integration.

Next step

When the integration is running, after connecting to Red Hat AMQ, the integration watches for messages on the inventoryReceived queue. When a message is available, the integration passes it to the Damage Reporter step. However, before you can add that step to the integration, you must choose the integration’s finish connection.

Choosing the finish connection

In Syndesis, to continue creating the AMQ to REST API sample integration, after you add the start connection, you add the finish connection to the integration.

Prerequisites

  • You uploaded the provided OpenAPI document to create the Todo App API connector.

  • You used the Todo App API connector to create a Todo App API connection.

Procedure

  1. In Syndesis, on the Choose a connection page, click the To Do app connection that you created. If you assigned the example name, you would click Todo App API Client.

  2. On the Choose an action page, select Create new task, which provides information about who to contact to address a particular damaged item.

  3. Click Next to add the finish connection to the integration.

Adding a damage reporter step

With the start and finish connections in place, you are ready to add the custom step that receives the messages from the Red Hat AMQ broker and identifies any items that were damaged when they were received.

Prerequisite

  • You uploaded the extension that provides the Damage Reporter custom step.

  • You added the start and finish connections to the integration.

Procedure

  1. In Syndesis, in the integration visualization, click the plus sign.

  2. Click Damage Reporter.

  3. Click Next to add the Damage Reporter step to the integration.

Adding a data mapping step

To continue creating the AMQ to REST API sample integration, you need to add a data mapping step. This step correlates the task field in the output from the damage reporter step to the task field in the database that the REST API accesses.

Prerequisite

  • You added the Damage Reporter step to the integration.

Procedure

  1. In Syndesis, in the integration visualization, click the plus sign that is between the Damage Reporter step and the finish connection.

  2. Click Data Mapper. In the data mapper, the Source panel on the left displays the fields in the output from the damage reporter step. The Target panel on the right displays the fields in the database that the API accesses.

  3. In the Source panel, click the task field and then click the Create New Mapping icon.

    The Mapping Details panel opens.

  4. In the Mapping Details target panel, under Targets, select /body/task.

  5. In the upper right, click Done.

Result

The integration is complete and it is ready to be published. On the left, in the integration visualization panel, you might see a warningData Type Mismatch warning icon. You can ignore it.

Giving the integration a name and deploying it

The AMQ to REST API sample integration is complete when it has a Red Hat AMQ start connection, a Damage Reporter step, a data mapper step, and it finishes with a Todo App Client API connection. Follow the instructions here to deploy it.

Prerequisites

  • You added the start and finish connections to the integration.

  • You added a Damager Reporter step between the start and finish connections.

  • You added a data mapper step between the Damage Reporter step and the connection to the Todo App API.

Procedure

  1. In Syndesis, in the upper right, click Publish.

  2. In the Name field, enter a name for the integration. For example, AMQ to REST API Sample Integration.

  3. Optionally, in the Description field, enter information that might be helpful to know about this integration.

  4. In the upper right corner, click Save and publish.

    Syndesis starts to deploy the integration and then displays the list of integrations in this environment. In the entry for your AMQ to REST API integration, you can see a progress indicator that shows the publishing stages. Syndesis is generating the runtime for the integration and will start it when the runtime is ready. This takes a few minutes.

    A Syndesis account is limited to a specific number of integrations that can be running at one time. For details, see the pricing plan. If you are already running the maximum number of integrations, then you must stop an integration before you can start running another one.

  5. If you are already running the maximum number of integrations, follow these steps to stop an integration:

    1. In the left panel, click Integrations.

    2. In the entry for the integration that you want to stop, click ThreeVerticalDotsKebabon the far right.

    3. In the popup, click Stop.

  6. After stopping an integration, start another integration as follows:

    1. In the left panel, click Integrations.

    2. In the entry for the integration that you want to start, click ThreeVerticalDotsKebabon the far right.

    3. In the popup, click Start.

Confirming that the AMQ to REST API integration works

After you create and publish the AMQ to REST API sample integration, you can confirm that it works as defined.

Prerequisite

In Syndesis, in the list of integrations, Running appears next to the AMQ to REST API integration that you created and deployed.

Procedure

  1. In a new browser window, go to the To Do app display by inserting todo- in front of the URL for your Syndesis environment. For example: http://todo-app-proj761432.6a63.fuse-ignite.openshiftapps.com/.

  2. In the To Do app display, click Show JMS Form to display an input box that contains an XML message.

  3. Click Send JMS Message to send that message to the Red Hat AMQ broker in your OpenShift project.

    Successful execution returns a task from the To Do app client API. The task identifies the ID of the damaged item and the contact information for its vendor. If the task does not appear in a moment or two, try reloading the page.

  4. Edit the XML message to specify two damaged items:

    1. Click Show JMS Form to display the message input box again.

    2. In the XML message, change the entry for the undamaged item to specify damaged="true".

    3. Click Send JMS Message. The To Do app client API returns a new task that contains IDs for two damaged items and contact information for the two vendors.

  5. Edit the XML message to specify an ID that you make up:

    1. Click Show JMS Form.

    2. In the XML message, for the item that has damaged="true", change the item ID, for example, to 1234.

    3. Click Send JMS Message. The To Do app client API returns a new task with the item ID that you just entered.

  6. Optionally, view the integration log to troubleshoot an unexpected result or to learn more about integration execution:

    1. In Syndesis, in the left panel, click Integrations.

    2. View the entry for your AMQ to REST API integration.

    3. In the integration’s summary page, click the Activity tab.

    4. Click the integration execution for which you want to view activity information.

Cleaning up your integration

When you are done working with a sample integration, you should stop it and delete it so that you can use the resources for another integration.

Prerequisites

  • You are finished working with a sample integration that you published.

Procedure

  1. In Syndesis, in the left panel, click Integrations.

  2. In the main panel, identify the entry for the sample integration that you want to stop.

  3. In that entry, to the right, click Kebab Menuand then click Stop.

  4. Click Stop to confirm that you want to stop running the integration.

  5. In the entry for the integration that you just stopped, to the right, click Kebab Menuand then click Delete.

  6. Click Delete to confirm that you want to delete the integration.