Creating an integration server to run your BAR file resources

The BAR file for your exported flow contains all the resources that are needed to deploy an integration that exposes the integration and its operations. To run this integration, you’ll need to create an integration server to run the BAR file resources.

To create an integration server, complete the following steps:

1. Applicable to Cloud Pak for Integration only: From your cluster, launch the App Connect Dashboard:
   1. Obtain the name of the App Connect Dashboard instance from your administrator.
   2. If not already logged in, log in to the Platform Navigator for your cluster.
   3. From the Capabilities tab, click the name of the App Connect Dashboard instance for your dashboard.
      Tip: You can also open the App Connect Dashboard instance from the IBM Cloud Pak menu in the Platform Navigator.
2. Applicable to App Connect Enterprise certified container only: To access your App Connect Dashboard instance, open a browser window and enter the URL that your administrator provided for the App Connect Dashboard instance.
3. Enter your login credentials to log in to your App Connect Dashboard.

   The Home page for the App Connect Dashboard is displayed. You can click the tiles on this page to view any deployed integration servers from the Servers tile, and their underlying integrations from the Integrations tile. You can also create an integration server from the Create a server tile, and view the documentation from the Learn more tile. (If you had previously logged in, your last location in App Connect Dashboard is remembered.)

   
4. Complete either of the following steps depending on your location:
   • From the Home page, click the Create a server tile.
   • From the navigation pane, click the Dashboard icon to open the Servers page. Any existing integration servers in the namespace are displayed as tiles on this page.

     Click Create server.

     
5. From the Type panel on the Create an App Connect Integration Server page, click Quick start designer integration to deploy an integration that you obtained from any of these environments:
   • A BAR file that you exported from an App Connect Designer instance in your cluster or from an App Connect on IBM Cloud service instance
   • A BAR file that you developed as a hybrid by using both App Connect Designer (or App Connect on IBM Cloud) and IBM App Connect Enterprise Toolkit
   
6. Click Next to proceed to the next stage.
7. From the Integrations panel, complete any of these steps to add the BAR file that you want to deploy. (This example uses a BAR file that was exported for an API flow.)
   • Drag and drop the file from its location in an open file browser into the boxed area.
   • Click within the boxed area to open a file browser and locate the BAR file.
   • From the drop-down list, select an existing BAR file that was previously uploaded to the content server. (This option is useful if you want to create more than one integration server from the same BAR file to manage your workloads.)
   
8. Click Next.
9. From the Configuration panel, select or create one or more configurations that you want to apply to the integration server.
   • If these configurations have previously been created, select the required entries in the configurations table by clicking the check boxes.
   • If you need to create configurations, click Create configuration to open the Create configuration panel, select the configuration type, and then complete the details. When you click Create, the configuration is added to the table, and is selected by default.
   Note:

   • For a Designer integration (BAR file) that you exported from an App Connect Designer or App Connect on IBM Cloud instance, only the following configuration types are relevant.
     • Accounts: If you want to use local connectors to run one or more operations in the integration server, you'll require the account details for these connectors. Only one configuration of type Accounts can be selected for the integration server, but this configuration can contain account details for multiple connectors. You can configure account details by clicking Create configuration, selecting Accounts from the Type field, and then completing the details. For more information, see Accounts type.

       If the BAR file was exported for an event-driven flow, you must create a local account for the application that is used to trigger the flow because only local accounts are supported for events.

     • Agentx: If your App Connect Dashboard instance has been configured to use a switch server for callable flow capability, and a Callable flow node was configured in the exported flow, you'll require an Agentx file that enables connection to the switch server. A preconfigured default-agentx entry is available in the configurations table by default, and will be automatically selected for use with the integration server. This entry represents the configuration for a locally deployed switch server. Clear this check box only if you would prefer to use an external switch server. Only one configuration of type Agentx can be selected for the integration server. For information about creating a configuration for an external switch server, see Agentx type. You must select this new configuration entry for the integration server before you create the server.

       An AgentA configuration object is also created by default for the switch server, and is presented as a default-agenta entry is in the configurations table.

       Note that only one agent configuration is permitted per integration server. If you select both default-agentx and default-agenta, an error message will be generated when you try to create the server.

     • setdbparms.txt: If you want to use cloud-managed (App Connect on IBM Cloud) connectors to run one or more operations in the integration server, you'll need to specify an IBM Cloud API key that your deployed integration can use to authenticate to your App Connect on IBM Cloud instance, in order to connect to the connectors and accounts that were referenced in the exported flow. You can specify this key by clicking Create configuration, selecting setdbparms.txt from the Type field, and then completing the details. For more information, see setdbparms.txt type.
   • For a Designer integration (BAR file) that you developed as a hybrid, you can select or create multiple valid configurations that apply for your BAR file definition. For more information, see Configuration types for integration servers.

   

   Note: If an App Connect Designer instance is created in the same namespace as your App Connect Dashboard instance, the configurations table will include configurations that were automatically created when the Designer instance was created. These configurations will be prefixed with the name of the Designer instance. For example, if the Designer instance is named des-quickstart, you'll see configurations of various types that are named in the format des-quickstart-designer-xxx, where xxx represents an abbreviation of the configuration type. Do not delete these configurations.
10. Click Next.
11. From the Server panel, define details about the integration server and install the BAR file resources:
    1. Complete the fields:
       • Name: Enter a short distinctive name that uniquely identifies this integration server.
       • Designer flows mode: Specify what type of connectors you want to use:
         • all: Select this option to use any combination of cloud-managed or local connectors. This option will extend the functionality of each pod by deploying sidecar containers, which are needed to run flows that are authored in App Connect Designer, and local connectors. (You’ll need to have a secret that contains an IBM Cloud API key and account credentials.)

           If you select this option, a local connector will be used if a successful connection can be established with the supplied credentials. If the connection fails or if local credentials were not supplied, the cloud-managed connector will be used. The operation will fail if the connection to the cloud-managed connector also fails.

         • local : Select this option to use local connectors only. This option will extend the functionality of each pod by deploying sidecar containers, which are needed to run flows that are authored in App Connect Designer, and local connectors. (You’ll need to have a secret that contains account credentials.)

           If you select this option, a local connector will be used if a successful connection can be established with the supplied credentials. Otherwise, the operation will fail.

       • Designer flows type: Specify what type of flows are supported:
         • api-flows: Select this option to enable support for API flows only.
         • event-driven-or-api-flows: Select this option to enable support for both event-driven and API flows. You must select this option if your exported BAR file contains an event-driven flow, but it can also be used if deploying an API flow. Note that the resource requirements are higher for this option.
         Note: The Designer flows type field is not supported for version 11.0.0.10-r2 or earlier, so if you select a value for Designer flows type, you must ensure that a supported value is selected in the Version field. If required, you can clear the Designer flows type field by clicking the x next to the selected value.
       • Replicas: Specify the number of replica pods to run for this deployment.
       • The type of transport used by the integration endpoint: Select a protocol that will determine whether the endpoint of the deployed integration is secured. You can choose either http or https.
       • Enable Operations Dashboard tracing: Set this switch to on to enable transaction tracing, which will push trace data to the IBM Cloud Pak for Integration Operations Dashboard to aid with problem investigation and troubleshooting. An Operations Dashboard instance must be available to process the required registration approval for tracing, as described in the About this task section.
       • Operations Dashboard namespace: Specify the namespace where the Operations Dashboard was deployed. This field is displayed only when Enable Operations Dashboard tracing is set to on.
       • Version: Select an App Connect product version that the integration server is based on. You can select a channel or a fully qualified version. If you select a channel, you must ensure that the license aligns with the latest available version of the IBM App Connect Operator. For more information, see spec.version values and Licensing reference for IBM App Connect Operator.
         Note: If you select a fully qualified version of 11.0.0.10-r2 or earlier, or select a channel that resolves to 11.0.0.10-r2 or earlier, you must ensure that the Designer flows type field is clear because it is not supported for these versions.

       
    2. Optional: Display advanced settings by switching Advanced settings to on, and then populate any of the additional fields that are displayed.
    3. Click YAML editor to switch to code view for a more advanced configuration of fields that are not exposed in the Common settings view.
       • You can manually change the values of the parameters, which represent the fields in the Common settings view. Any changes that you make will be reflected in the Common settings view.
       • Notice that the YAML editor displays some default parameters, such as licence settings, which are not shown in the Common settings view. Ensure that spec.license.license and spec.license.use contain the values that you require. For licensing information, see Licensing reference for IBM App Connect Operator.
       • To see the full set of parameters that you can specify, go to App Connect Integration Server reference: Custom resource values.

       
    4. Click Create to create the integration server.
       The integration server is displayed as a tile on the Servers page of the dashboard, with an initial status of Unavailable (), which then changes to Started when the deployment completes. (Refresh the page to see the change in status.)

       

       You can click the integration server tile to view the deployed integration. (For an API flow, this includes a single API and other resources that are defined in the uploaded BAR file.) From the Servers page, you can also view the integrations for all listed integration servers by clicking Integrations to open the Integrations page.

       
    Tip:

    • If required, you can deploy the same BAR file more than once to accommodate your workloads. A unique integration server must be created each time, typically with the same configurations. Different API endpoints will be generated for each integration server.
    • From the Servers page of the dashboard, you can use the Share REST APIs feature to push (or export) the deployed API to IBM API Connect to take advantage of its advanced API management capabilities. For more information, see Pushing REST APIs to IBM API Connect by using the web user interface.