Chapter 8. Managing integrations
A common set up is to have a Fuse Online development environment, a Fuse Online test environment, and a Fuse Online deployment environment. To facilitate this, Fuse Online provides the ability to export an integration from one Fuse Online environment and then import that integration into another Fuse Online environment. The information and procedures for managing integrations are the same in each kind of Fuse Online environment, unless specifically noted.
The following topics provide information to help you manage your integrations:
- Section 8.1, “About integration lifecycle handling”
- Section 8.2, “Putting integrations into and out of service”
- Section 8.3, “Logging information about integration execution”
- Section 8.4, “Monitoring integrations”
- Section 8.5, “Testing integrations”
- Section 8.6, “Tips for troubleshooting integration execution”
- Section 8.7, “Updating integrations”
- Section 8.8, “Adjusting the memory and CPU configuration attributes for an integration”
- Section 8.9, “Deleting integrations”
- Section 8.10, “Copying an integration to another environment”
8.1. About integration lifecycle handling
After you create and publish an integration, you might want to update what the integration does. You can edit a draft of the published integration and then replace the running version with the updated version. To facilitate this, for each integration, Fuse Online maintains multiple versions as well as each version’s state. An understanding of integration versions and states helps you to manage your integrations.
Description of integration versions
In each Fuse Online environment, each integration can have multiple versions. Support for multiple integration versions has several benefits:
- If you publish a version that does not work correctly, then you can return to running a correct version of the integration. To do that, you stop the incorrect version and start a version that runs the way you want it to.
- As requirements or tools change, you can incrementally update an integration. You do not need to create a new integration.
Fuse Online assigns a new version number each time it starts running a new version of an integration. For example, suppose you publish the Twitter to Salesforce sample integration. After it has been running, you update the integration to use a different account to connect to Twitter. You then publish the updated integration. Fuse Online stops the running version of the integration, and publishes the updated version of the integration with an incremented version number.
The initial integration that was running is version 1. The updated integration that is now running is version 2. If you edit version 2, for example to use a different account to connect to Salesforce, and you publish that version then it becomes version 3 of the integration.
There can be exactly one draft version of an integration. Fuse Online has a definition for the draft version of an integration but it has never run this version of the integration. The draft version of an integration does not have a number. When you edit an integration, you are updating the draft version of the integration.
In Fuse Online, you can see a list of the versions of an integration in the integration’s summary page. To view this page, in the left navigation panel, click Integrations. In the entry for the integration that you are interested in, click View.
Description of integration states
In Fuse Online, in the list of integration versions, each entry indicates the state of that version, which is one of the following:
State | Description |
Running | A Running version is executing; it is in service. Only one version of an integration can be running. That is, only one version at a time can be in the Running state. |
Stopped | A Stopped version is not running. The draft version of an integration is in the Stopped state. Each integration that was running at one time and then stopped is in the Stopped state. If no version of this integration is in the Running state, then you can start a version that is stopped. |
Pending | A pending version is in transition. Fuse Online is in the process of either starting this version of the integration or stopping this version of the integration, but the integration is not yet running or stopped. |
Error | An integration version that is in the Error state encountered an OpenShift error while being started or while running. The error suspended start-up or execution. If this happens, try starting an earlier integration version that ran correctly. Alternatively, contact technical support for help. To do that, in any Fuse Online page, in the upper right, click the icon and select Support. |
8.2. Putting integrations into and out of service
After you create an integration, you can save it as a draft or publish it to start running it. When you publish an integration, Fuse Online assembles the needed resources, builds the integration runtime, deploys the OpenShift pod that will run the integration, and then starts running the integration.
At any time, you can click a button to stop running the integration. When you want to start the integration again, Fuse Online already has what it needs so starting it takes less time than when you published it to run it for the first time.
The process of starting a version of an integration for the first time is referred to as publishing the integration. The following topics provide details:
8.2.1. About publishing integrations
To run a version of an integration for the first time, you publish it. Publishing an integration builds and deploys the integration runtime. The integration starts running. After publishing an integration, you can stop it and restart it. Exactly one version of an integration can be running at one time.
Alternatives for publishing
To run an integration for the first time, publish it by doing one of the following:
- At the end of the procedure in which you create or edit the integration, in the upper right, click Publish.
Publish the draft version of an integration:
- In the left Fuse Online panel, click Integrations.
- In the list of integrations, to the right of the draft entry, click and select Publish.
About the publication progress
Fuse Online displays the progress of the publication process, which has several stages:
- Assembling creates pod resources needed to build the integration.
- Building gets the integration ready to deploy.
- Deploying waits for deployment of the pod that will run the integration.
- Starting waits for the pod to start running the integration.
- Deployed indicates that the integration is running.
During start-up, you can click View Logs to display OpenShift logs that provide start-up information.
Integration status after publication
When publishing the integration is complete, the Running status appears next to the integration name. The pod is running the integration.
8.2.2. Stopping integrations
Each integration can have exactly one version that is running. A running version is in the Running state. At any time, you can stop running an integration.
Prerequisite
The integration that you want to stop is in the Running state.
Procedure
- In the left Fuse Online panel, click Integrations.
- In the list of integrations, identify the entry for the integration that you want to stop running. The entry shows that this integration is Running.
- On the far right of this integration’s entry, click and select Stop.
Result
Fuse Online stops running the integration. Stopping and then Stopped appears in the integration’s entry in the list of integrations.
8.2.3. Starting integrations
The first time that you start an integration, the process is referred to as publishing the integration because Fuse Online has to build the integration runtime before it can run the integration. At any time, you can stop running an integration and then start it again.
Prerequisite
The integration that you want to start is in the Stopped state.
Procedure
- In the left navigation panel, click Integrations.
- In the list of integrations, on the right of the entry for the integration that you want to start, click .
- Select Start.
Result
Fuse Online displays Starting as the status of that integration version, and then Running when the integration is running again.
8.2.4. Restarting older integration versions
You might publish an integration that does not work the way you want it to. In this situation, you can stop the incorrect version and replace it with a version that you published previously and that runs correctly.
Prerequisites
- A version of the integration is running but you want to stop it.
- You have another version of the integration and you want to run that one.
Procedure
- In the left panel, click Integrations to display a list of the the integrations in this environment.
- Click the entry for the integration for which you want to publish an older version. Fuse Online displays a list of the versions of the integration.
- In the entry for the version that is running, at the far right, click and select Stop.
- Click OK to confirm that you want to stop running this version.
- Wait for Stopped to appear to the right of the integration name near the top of the page.
To publish the older version as is, skip to the next step. Or, before you publish the older version, you can update it:
- In the entry for the integration version that you want to update, at the far right, click and select Replace Draft.
- Update the integration as needed.
- When updates are complete, in the upper right, click Publish, and then click Publish to confirm. This takes the place of the next two steps.
- To publish the older version as is, in the entry for the integration version that you want to start running again, at the far right, click and select Start.
- Click Start to confirm that you want to start this version of the integration.
Result
Fuse Online starts the integration, which takes a few minutes. When the integration is running, then Running version n appears to the right of the integration’s name.
8.3. Logging information about integration execution
For each execution of an integration, for each step in a flow, Fuse Online provides the following activity information:
- The date and time that the step was executed
- How long it took to execute the step
- Whether execution was successful
- The error message if execution was not successful
To view this information in Fuse Online, display the integration’s summary and then click the Activity tab.
To obtain further details about integration execution, you can log information about the messages that an integration processes by adding a log step to an integration flow. For each message that an integration receives, a log step can provide one or more of the following:
- The message’s context, which provides metadata about the message, including the message’s header.
- The message’s body, which provides the content of the message.
- Text that you specify either explicitly or through evaluation of an Apache Camel Simple language expression.
The Log connection that was available in previous releases is no longer available to be added to integrations. Add a log step instead of a log connection.
Prerequisites
- You are creating or editing a flow and Fuse Online is prompting you to add to the integration. Or, Fuse Online is prompting you to choose a finish connection.
Procedure
- In the flow visualization, click the plus sign where you want to add a log step. Skip this step if Fuse Online is prompting you to choose a finish connection.
- Click Log.
On the Configure Log Step page, select the content that you want to log. If you select Custom Text, then in the text input field, enter one of the following:
- The text that you want to log
- A Camel Simple language expression
If you enter an expression, Fuse Online resolves the expression and logs the resulting text.
- When log step configuration is complete, click Next to add the step to the flow.
Next step
When the flow is complete, publish the integration to start seeing output from the new log step.
Additional resources
After a flow that has a log step has been executed, output from the log step appears in the integration’s Activity tab. See Viewing integration activity information.
8.4. Monitoring integrations
Fuse Online provides various ways for you to monitor the execution of your integrations. See:
8.4.1. Viewing integration history
Fuse Online maintains each version of an integration. You can always view a list of the versions of each integration.
Procedure
- In the left panel, click Integrations to display a list of the integrations in your environment.
- At the right of the entry for the integration whose versions you want to see, click View.
Result
In the page that appears, the History section lists the versions of the integration. The icon identifies the current version, which is the most recently, successfully running version. For each version, you can also see the date on which it was last started.
To edit, start, or stop a particular version, click the to the right of the version’s entry. Select the operation that you want to perform.
8.4.2. Viewing information about an integration’s activity
Fuse Online provides activity information for each execution of an integration. This information is part of the integration’s log. For each step in a flow, Fuse Online provides:
- The date and time that the step was executed
- How long it took to execute the step
- Whether execution was successful
- The error message if execution was not successful
At any time, you can view this information.
Prerequisites
- There is or was a running integration for which you want to view activity information.
- This integration has been executed at least once.
Procedure
- In the left panel, click Integrations.
- At the right of the entry for the integration for which you want to view activity information, click View.
- In the integration’s summary page, click the Activity tab.
- Optionally, enter date and/or keyword filters to limit the executions listed.
- Click the integration execution for which you want to view activity information.
For an API Provider integration or a webhook step, the information in the integration’s Activity tab reflects the communication between the Fuse Online integration and the client that invokes it. Errors generated by HTTP or REST requests are not visible in the integration’s Activity log. If you want to view or test the errors generated by HTTP or REST requests, when you configure the API Provider or the webhook step, check the Include error message in the return body option (checked by default). Then, you can verify whether the error message is included in the response by checking the HTTP or REST header in the response to the caller. You can also check the integration pod’s log file for INFO
messages.
Additional resources
- To obtain additional information between any two steps, you can add a log step to the integration. A log step provides information about each message it receives and can provide custom text that you specify. If you add a log step, then it appears as one of the integration’s steps when you expand the integration execution that you want to view activity information for. You view Fuse Online information for a log step in the same way that you view Fuse Online information for any other step. See Logging information about integration execution.
8.4.3. Viewing metrics for a particular integration
Fuse Online provides the following metrics for each integration:
- Total Errors indicates the number of runtime errors that all executions of this integration encountered during the past 30 days.
- Last Processed displays the most recent date and time that this integration processed a message. The message might have been successfully processed or there might have been an error.
- Total Messages is the number of messages that all executions of this integration processed in the last 30 days. This includes message failures.
- Uptime indicates when this integration started running and how long it has been running without an error.
Prerequisite
The integration that you want to view metrics for is running or has been running.
Procedure
- In the left panel, click Integrations.
- At the right of the entry for the integration for which you want to view metrics, click View.
- In the integration’s summary page, click Metrics.
8.4.4. Viewing metrics for a Fuse Online environment
Metrics for your Fuse Online environment appear on the Fuse Online home page.
Procedure
In the left panel, click Home.
Results
Fuse Online updates the following metrics every 5 seconds:
- The number of integrations that are defined in this environment as well as the number of integrations that are running, the number of integrations that are stopped, and the number of integrations that are pending. Fuse Online is either stopping or starting pending integrations. A red cross indicates any integrations that were running but that encountered an error that suspended execution.
- The number of connections that are defined in this environment.
- Total number of messages that have been processed by integrations in this environment in the last 30 days. This includes messages that were processed by integrations that might no longer be running or that might have been deleted from this environment.
- Uptime indicates how long there has been at least one integration that is running. The date and time when uptime started appears as well.
8.5. Testing integrations
After you create an integration and it is running correctly in a Fuse Online development environment, you might want to run it in a different Fuse Online environment to test it.
Prerequisite
- You have a Fuse Online development environment and a Fuse Online test environment.
- You have an integration that is running correctly in your Fuse Online development environment.
Procedure
- Learn about copying an integration to another environment.
- Export the integration from the development environment. See Exporting an integration.
- Import the integration into the test environment. See Importing an integration.
8.6. Tips for troubleshooting integration execution
If an integration stops working, check its activity and history details. See Viewing integration activity information and Viewing integration history.
Insufficient memory for integrations
If the Fuse Online Operator logs shows that an integration’s status is not ready
or if an integration’s pod events report insufficient memory, you might need to edit the integration’s deployment configuration as described in Adjusting the memory and CPU configuration attributes for an integration.
Connection to an application that uses OAuth
For a connection to an application that uses OAuth, you might see an error message that indicates that the access token for the application has expired. Sometimes, you might get a less explicit 403 - Access denied
message. The information in the message depends on the application that the integration is connecting to. In this situation, try reconnecting to the application and then republishing the integration:
- In the left panel, click Integrations.
- In the list of integrations, at the right of the entry for the integration that stopped running, click View.
In the integration’s summary page, in the flow visualization, click the icon for the application that you want to reconnect to.
If this is an API provider integration, then in the integration’s summary page, click its flow icon to display the operations list. Then click the operation whose path contains the connection that is failing and then click the failing connection in the operation’s path visualization.
- In the connection’s details page, click Reconnect.
Respond to that application’s OAuth workflow prompts.
Fuse Online displays a message to indicate that its access to that application has been authorized. For some applications, this takes a few seconds but it can take longer for other applications.
- After reconnecting to the application, start the integration.
If reconnection is not successful, try this:
- Re-register Fuse Online as a client of the application. See General procedure for obtaining authorization.
- Create a new connection.
Edit each integration that was using the old connection:
- Remove the old connection.
- Replace it with the new connection.
- Publish each updated integration.
8.7. Updating integrations
After you create an integration, you might need to update it to add, edit or remove a step.
Prerequisite
In your Fuse Online environment, there is a version of the integration that you want to update.
Procedure
- In the left Fuse Online panel, click Integrations.
- In the list of integrations, click View for the integration that you want to update.
On the integration’s summary page, in the upper right corner, click Edit Integration.
If this is a simple integration, Fuse Online displays the integration’s flow. If this is an API provider integration, Fuse Online displays the operations list. To update the flow for a particular operation, click Edit flow on the right of that operation to display its flow.
Update the flow as needed:
- To add a step, in the flow visualization, click the plus sign that is where you want to add the step. Then click the card that represents the step that you want to add.
- To delete a step, in the flow visualization, click on the step that you want to delete.
- To change the configuration of a step, in the flow visualization, click Configure on the step that you want to update. In the configuration page, update the parameter settings as needed.
8.8. Adjusting the memory and CPU configuration attributes for an integration
You can specify custom values for a specific integration’s CPU and memory by editing the integration’s deployment configuration object. You might want to adjust the memory and CPU configuration attributes for an integration, for example, if the integration requires more memory than its default allocation.
Prerequisite
-
The Red Hat OpenShift
oc
client tool is installed and it is connected to the OCP cluster in which Fuse Online is installed. -
A user with cluster administration permissions gave you
admin
permission for the project that contains the integration that you want to configure.
Procedure
Log in to OpenShift with an account that has
admin
permission for the OpenShift project that contains the Fuse Online integration. For example:oc login -u admin -p admin
Switch to the project that contains the Fuse Online integration. For example:
oc project my-fuse-online-project
Edit the integration’s deployment configuration object:
Enter the following command, which typically opens the resource in an editor:
oc edit deploymentconfig <i-integration-name>
For example, if the integration’s name is
my-integration
, type this command:oc edit deploymentconfig i-my-integration
Edit the configuration by setting
spec.containers.resources
to specify values for CPU and memory as shown in the following example:spec: containers: resources: limits: cpu: 350m requests: memory: 350Mi
- Save the configuration.
Results
After you save your changes, the integration’s pod restarts and the new pod runs with the new values. For example, if you run the oc describe <intergration-pod-name>
command (where you replace <intergration-pod-name> with the name of the integration pod, for example i-my-integration
), the command returns the new values, such as:
resources: limits: cpu: 350m requests: cpu: 350m memory: 350Mi
These values persist even after you publish a new version of the integration.
Additional resources
To set the default value for all integration’s CPU and memory attributes, an OpenShift cluster administrator can update the Fuse Online custom resource as described in Descriptions of custom resource attributes that configure Fuse Online in {NameOfFuseOnlineOnOCP}.
8.9. Deleting integrations
After you delete an integration, Fuse Online still has the history of that integration. If you import a version of the deleted integration, then Fuse Online associates the history of the deleted integration with the imported integration.
Procedure
- In the left Fuse Online panel, click Integrations.
- In the list of integrations, at the right of the entry for the integration that you want to delete, click and select Delete.
- In the popup, click OK to confirm that you want to delete the integration.
8.10. Copying an integration to another environment
To run integrations across development, staging and production environments, you can export and import integrations. The environments can all be on a single OpenShift cluster, or they can be spread out across multiple OpenShift clusters.
The procedures described here instruct you to export and import integrations in the Fuse Online console.
If you are running Fuse Online on OpenShift Container Platform on-site, you might have Continuous Integration/Continuous Deployment (CI/CD) pipelines that need to export and import certain integrations. For information about doing that, see Using external tools to export/import integrations for CI/CD.
See the following topics:
8.10.1. About copying integrations
Each Fuse Online installation is an environment from which you can export an integration. Exporting an integration downloads a zip file that contains the information needed to recreate the integration in a different Fuse Online environment.
In an environment, each integration can have only one Draft version.
The result of importing an integration depends on:
- Whether the integration was previously imported
- Whether a connection that the integration uses was previously imported
Fuse Online uses an internal identifier for each integration and each connection to determine whether it already exists in the environment that it is being imported into. If you change the name of an integration or connection, Fuse Online recognizes it as the same integration or connection, which just has a different name.
The following table describes the possible results of importing an integration:
In the importing environment: | What the import operation does: |
---|---|
The integration has not been previously imported. | Creates the integration. The integration is in the Draft state. |
The integration has been previously imported. | Fuse Online updates the integration. The updated integration is in the Draft state. If there was a Draft version of this integration, it is lost. |
The imported integration uses a connection that did not exist in the environment before the import operation. | Fuse Online creates a connection that has the same settings except for secrets. You must review each new connection. If a connection is not completely configured for its new environment then you must add the missing settings. For example, you might need to obtain secret settings by registering this Fuse Online environment as a client of the application that this connection accesses. |
8.10.2. Exporting integrations
When Fuse Online exports an integration it downloads a zip file to your local Downloads
folder. This zip file contains the information needed to recreate the integration in a different Fuse Online environment.
Exporting an integration is also a way to have a backup of the integration. However, Fuse Online maintains the versions of an integration so exporting an integration is not required for having a backup copy.
Procedure
- In the left panel of Fuse Online, click Integrations.
- In the list of integrations, identify the entry for the integration that you want to export.
- At the right of the entry, click and select Export.
Next step
To import the integration into another Fuse Online environment, open that environment and import the exported zip file.
8.10.3. Importing integrations
In a Fuse Online environment, you can import an integration that was exported from another Fuse Online environment. Exporting an integration downloads the zip file that you upload to import the integration.
Prerequisites
- You have a zip file that contains an integration that was exported from another Fuse Online environment.
Procedure
- Open the Fuse Online environment that you want to import the integration into.
- In the left panel, click Integrations.
- In the upper right, click Import.
Drag and drop one or more exported integration zip files, or navigate to a zip file that contains an exported integration and select it.
Fuse Online imports the file(s) and display a message when importing is successful.
- In the left panel, click Integrations.
- In the list of integrations, on the entry for the integration that you just imported, click View.
- In the integration summary, if there is a notification that configuration is required, in the upper right, click Edit integration.
For each connection that requires configuration:
- Click its Configure button to display its details.
- Enter or change connection details as needed. It is possible that every field on this page is correct and that only security configuration is required.
- Click Next.
In the left panel, click Settings.
The Settings page displays entries for applications that use the OAuth protocol.
For each connection that requires configuration and that accesses an application that uses the OAuth protocol, register your Fuse Online environment with the application. The steps vary for each application. See the appropriate topic:
- In the left panel, click Connections and confirm that there are no longer any connections that require configuration.
- In the left panel, click Integrations. In the list of integrations, imported integrations have a green triangle in the upper left corner of their entries.
- In the list of integrations, at the right of the entry for the integration that you imported, click and select Edit.
- In the upper right, click Save or, if you want to start running the imported integration, click Publish. Regardless of whether you save the integration as a draft or you publish the integration, Fuse Online updates the integration to use the updated connections.