Chapter 4. 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 Fuse Online. This integration also does that, but in addition, it provides instructions for customizing and extending Fuse Online 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.
Fuse Online provides the extension file and the OpenAPI document.
Prerequisites
- You must be logged in to Fuse Online.
- You are working in a Fuse Online environment that is running in an OpenShift Container Platform project in which an administrator added the Fuse Online sample data, which provides the sample PostgresDB connection, the AMQ Broker, and the To Do app for confirming that the integration works as expected.
To implement the AMQ to REST API sample integration, the main steps are:
- Section 4.1, “Creating an AMQ connection”
- Section 4.2, “Making a custom step available”
- Section 4.3, “Creating a REST API connector”
- Section 4.4, “Creating a REST API connection”
- Section 4.5, “Creating and deploying the AMQ to REST API sample integration”
- Section 4.6, “Confirming that the AMQ to REST API integration works”
- Section 4.7, “Cleaning up your integration”
4.1. 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
Verify that the broker has started:
- In a browser, go to your OpenShift web console.
- In the console, click Project.
- On the Overview page, in the Inventory section, click Services.
-
Click broker-amq-tcp and then click Pods. The status of the pod should be
Running
.
Create the AMQ connection:
- In Fuse Online, in the left panel, click Connections to display any available connections.
- Click Create Connection to display Fuse Online connectors.
- Click the Red Hat AMQ connector.
Configure the connection by entering:
-
In the Broker URL field, enter
tcp://broker-amq-tcp:61616
as the location to obtain data from. -
In the User name field, enter
amq
as the user name for the account that accesses this AMQ broker. -
In the Password field, enter
topSecret
as the password for the account that accesses this AMQ broker. - Leave the other fields blank.
-
In the Broker URL field, enter
- Click Validate. Fuse Online 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.
- When validation is successful, click Next.
-
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
. -
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.
- 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.
4.2. Making a custom step available
Fuse Online provides a number of steps that operate on integration data between connections. If Fuse Online 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 Fuse Online 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
- In a new browser tab, go to https://github.com/syndesisio/fuse-online-sample-extension/releases.
-
Download the Damage Reporter extension’s
.jar
file. - In Fuse Online, in the left panel, click Customizations > Extensions.
- Click Import Extension.
-
Click in the dotted-line box and select the downloaded
.jar
file that contains the extension. Fuse Online 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. - Click Import Extension. Fuse Online 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:
4.3. Creating a REST API connector
Fuse Online can create connectors for REST APIs that support Hypertext Transfer Protocol (HTTP)/1.0 or HTTP/1.1. To do this, Fuse Online requires a valid OpenAPI 3 (or 2) document that describes a REST API that you want to connect to.
Your Fuse Online 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
Download the icon for the
todo app
:- In the Fuse Online navigation panel, click Home.
- Copy the URL into a text editor.
-
At the beginning of the URL, insert
todo-
. -
At the end of the URL, add
/images/todo_icon.png
. Use the
http
scheme instead ofhttps
.The result is something like this: http://todo-app-proj217402.6a63.fuse-ignite.openshiftapps.com/images/todo_icon.png
-
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.
Identify the URL for your Fuse Online environment’s copy of the OpenAPI document:
- In the Fuse Online navigation panel, click Home.
- Copy the URL into a text editor.
-
At the beginning of the URL, insert
todo-
. -
At the end of the URL, add
swagger.json
. Use the
http
scheme instead ofhttps
.The result is something like this:
http://todo-app-proj217402.6a63.fuse-ignite.openshiftapps.com/swagger.json
NoteSpecification of
http
rather thanhttps
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.- In the Fuse Online navigation panel, click Customizations > API Client Connectors.
- Click Create API Connector.
- Select Use a URL.
- In the input box, paste the URL for your OpenAPI document and click Next.
- On the Review Actions page, click Next. If you see a warning, you can ignore it.
- Click Next.
-
On the Specify Security page, accept HTTP Basic Authentication and specify a username and password, such as
admin
andadmin
. Note that, for this sample app, the username and password are not verified. - Click Next.
On the Todo App API summary page:
-
For the Connector Icon, click Choose File and then navigate to the location of the
todo_icon.png
that you downloaded in Step 1. - If you want to, you can change the values in the Name and Description fields.
-
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
. -
In the Base URL field, accept the part of the URL that follows the host name in service requests:
/api
.
-
For the Connector Icon, click Choose File and then navigate to the location of the
Click Save.
Fuse Online displays the API Client Connectors. There is a new entry for the Todo App API that you just created.
4.4. 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
- In Fuse Online, in the left panel, click Connections to display any available connections.
- Click Create Connection to display available connectors.
Click the Todo App API connector that you just created.
Fuse Online populates the Host and Base Path fields from the OpenAPI document that you provided when you created the connector.
- In the Username field, enter any value. For this sample integration, user name and password values are required but they are not used.
- In the Password field, enter any value.
- Click Next.
-
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
. -
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.
- Click Save to see that the connection you created is now available.
4.5. 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:
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.
4.5.1. Choosing the start connection
In Fuse Online, 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
- In Fuse Online, on the left, click Integrations.
- Click Create Integration.
- On the Choose a connection page, click your AMQ connection. If you specified the example name, you would click Red Hat AMQ Broker 1.
- On the Choose an action page, select the Subscribe for messages action to receive messages from the queue you specify.
-
In the Destination name field, enter
inventoryReceived
for the name of the queue to obtain data from. - Click in the Destination type field and select Queue.
- Leave the other fields blank.
- Click Next. Fuse Online prompts you to specify the output data type. This is not needed for this sample integration.
- 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.
4.5.2. Choosing the finish connection
In Fuse Online, 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
- In Fuse Online, 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.
- On the Choose an action page, select Create new task, which provides information about who to contact to address a particular damaged item.
- Click Next to add the finish connection to the integration.
4.5.3. 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
- In Fuse Online, in the integration visualization, click the plus sign.
- Click Damage Reporter.
- Click Next to add the Damage Reporter step to the integration.
4.5.4. 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
- In Fuse Online, in the integration visualization, click the plus sign that is between the Damage Reporter step and the finish connection.
- 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.
In the Source panel, click the
task
field and then click the Create New Mapping icon.The Mapping Details panel opens.
- In the Mapping Details target panel, under Targets, select /body/task.
- 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 Data Type Mismatch warning icon. You can ignore it.
4.5.5. 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
- In Fuse Online, in the upper right, click Publish.
-
In the Name field, enter a name for the integration. For example,
AMQ to REST API Sample Integration
. - Optionally, in the Description field, enter information that might be helpful to know about this integration.
- Optionally, add one or more custom environment variables for an integration.
- Optionally, in the Labels field, add one or more labels. A label is a key-value pair tag that you can apply to an integration for later filtering and selecting in OpenShift. For example, an OpenShift admin user can filter the list of running pods or deployments by label.
In the upper right corner, click Save and publish.
Fuse Online 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. Fuse Online is generating the runtime for the integration and will start it when the runtime is ready. This takes a few minutes.
A Fuse Online 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.
If you are already running the maximum number of integrations, follow these steps to stop an integration:
- In the left panel, click Integrations.
- In the entry for the integration that you want to stop, click on the far right.
- In the popup, click Stop.
After stopping an integration, start another integration as follows:
- In the left panel, click Integrations.
- In the entry for the integration that you want to start, click on the far right.
- In the popup, click Start.
4.6. 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 Fuse Online, in the list of integrations, Running appears next to the AMQ to REST API integration that you created and deployed.
Procedure
-
In a new browser window, go to the To Do app display by inserting
todo-
in front of the URL for your Fuse Online environment. For example:http://todo-app-proj761432.6a63.fuse-ignite.openshiftapps.com/
. - In the To Do app display, click Show JMS Form to display an input box that contains an XML message.
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.
Edit the XML message to specify two damaged items:
- Click Show JMS Form to display the message input box again.
-
In the XML message, change the entry for the undamaged item to specify
damaged="true"
. - 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.
Edit the XML message to specify an ID that you make up:
- Click Show JMS Form.
-
In the XML message, for the item that has
damaged="true"
, change the item ID, for example, to1234
. - Click Send JMS Message. The To Do app client API returns a new task with the item ID that you just entered.
Optionally, view the integration log to troubleshoot an unexpected result or to learn more about integration execution:
- In Fuse Online, in the left panel, click Integrations.
- View the entry for your AMQ to REST API integration.
- In the integration’s summary page, click the Activity tab.
- Click the integration execution for which you want to view activity information.
4.7. 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
- In Fuse Online, in the left panel, click Integrations.
- In the main panel, identify the entry for the sample integration that you want to stop.
- In that entry, to the right, click and then click Stop.
- Click Stop to confirm that you want to stop running the integration.
- In the entry for the integration that you just stopped, to the right, click and then click Delete.
- Click Delete to confirm that you want to delete the integration.