Working with community connectors

To browse the community connectors, or create or download a community connector, complete the relevant step:

• To browse the community connectors and download a connector, complete these steps:
  1. From the Catalog page in App Connect Designer, scroll to the end of the connector list and then click the Browse the community connectors link.
     
     IBM Automation Explorer opens with the Discover tab on display. This tab initially displays a featured subset of the connectors and templates that are available.
  2. If you are not logged in, use your IBMid to sign in to IBM Automation Explorer.
  3. Look for the community connector that you want and then download it.
     1. Click View all connectors to see the full list of connectors.
        Note:

        • Community connectors are depicted with an App Connect notation and a Community connector icon .
          
        • You also see App Connect connectors that are developed by IBM, and which you can use to sign up for a trial of IBM App Connect Enterprise as a Service (which is hosted on AWS). Other connectors, which you can use in IBM Event Automation, are also displayed.
     2. Browse to locate the community connector that you need, or use the search box or filters.
     3. Click the community connector's tile to view its details, including any actions. and then click Download connector.

     The file is downloaded as a .car file, which you can then import into your Designer instance.

• To create a community connector, complete the following steps:
  1. From the Catalog page in App Connect Designer, scroll to the end of the connector list and then click the Connector Development Kit link.
     The Connector Development Kit opens.
  2. If you are not logged in, use your IBMid to sign in.
  3. Create the connector that you require and then submit a publishing request to make the connector available for sharing.

     For more information, see Overview of the IBM Connector Development Kit.

     After the connector is published, you can download it as a .car file, which you can then import into your Designer instance.

Complete these steps to import a community connector into App Connect Designer:

1. From the Catalog page, click the Add connector or API icon [+] (or click Import connector or API in a 12.0.10.0-r1 or earlier Designer instance).
   

   In some versions of Designer, you can also scroll to the end of the connector list and then click Import.

   

2. Complete the Add a connector or API panel as follows. (In a 12.0.10.0-r1 or earlier Designer instance, you see the Import connector or API panel.)
   1. Applicable to a 12.0.10.0-r2 or later Designer instance only: From the Import or discover view, select Import a connector file or API document, and click Next.
      
   2. From the Import document view, select Community connector from the Document type list.
   3. Specify the .car file that you want to import. You can either drag the file from its location in an open file browser into the Import box, or click within the box to open a file browser and locate the file. The file name is displayed in the Import field, as shown in the following example.
      
   4. Click Next.
   5. From the Review properties view, complete the fields as follows:
      • Name: The connector name in the imported file is displayed and you cannot change it. Your connector is identified by this name on the Catalog page or within the flow editor.
      • Description: Summarize the function of the connector. The description from the imported file is displayed if provided, but you can update this field as required. Up to 250 characters are allowed.

      You can expand the imported objects to view the defined operations, which are displayed as actions.

      
3. Click Import connector. Your community connector is displayed on the Catalog page with a Not connected status.
   

About this task

Typical scenarios for an update are as follows:

• If you have breaking changes in a community connector, you can choose to upgrade or downgrade the major version of the connector in App Connect.
• When you make additive or non-breaking changes to a community connector, you can upgrade the minor version of the connector in App Connect.
• When you make changes that are compatible with an earlier version of a community connector or fix bugs in the connector, you can upgrade the patch version of the connector in App Connect.

The following image shows an example of a community connector that was imported into the catalog with an initial version of 1.0.0.

To add an updated version of an imported community connector from the Catalog page, complete the following steps:

• For a major version update, complete the following steps:
  1. Follow the steps to import the downloaded .car file for a community connector into the App Connect Designer Catalog page. The following example shows the .car file for a major version of a community connector that you want to import.
     
  2. When you get to the Review properties view, choose either of these options:
     • Click Create a new connector to create a different major version of the connector in the catalog without replacing the existing connector.
     • Click Replace existing connector to replace the existing version of the connector with the new version.

     
  3. Click Import connector.

     If you chose to create a new version, the existing community connector and newly imported connector are both displayed on the Catalog page.

     

     If you chose to replace the existing community connector, the existing connector is overwritten with the newly imported connector on the Catalog page.

     
  Tip: The version of a community connector is displayed on the Catalog page only if the version is 2.0.0 or later. When you add an action for a community connector to a flow, the version is always displayed in the flow editor regardless of the number.
• For a minor or patch version update, complete the following steps:
  1. Follow the steps to import the downloaded .car file for a community connector into the App Connect Designer Catalog page. The following example shows the .car file for a minor version of a community connector that you want to import.
     
  2. When you get to the Review properties view, review the warning message that tells you which version your existing community connector is going to be replaced with.
     
  3. Click Import connector.

     The existing connector is overwritten with the newly imported connector on the Catalog page and the version is displayed only if it is 2.0.0 or later. When you add an action for the updated connector to a flow, you can also see the updated version in the flow editor.

     

To use the imported community connector in your flows, you need to establish a connection to the associated API by setting up one or more accounts with the required credentials. The values that are required to connect App Connect to the API depend on the authorization types that are configured for the community connector and the connection properties (or fields) that are defined for each authorization type. If more than one authorization type is defined, you need to first select a preferred authorization type before you provide the connection details.

To add account details from the Catalog page, complete the following steps:

1. From the navigation pane, click the Catalog icon to open the Catalog page.
2. Locate and click the imported connector.
3. If no accounts are created for this connector, click the Connect button, and then go to step 5.
4. If an account exists for this connector and you want to add another account, click the Account drop-down list and click Add a new account. Then, go to step 5.
   
5. Complete the fields for connecting to the associated API.
   1. If only one authorization type is defined for the connector, enter the account credentials in the connection fields that are displayed. If multiple authorization types are defined, select your preferred authorization type and then complete the connection fields. Depending on the connection properties that are configured for the community connector in the Connector Development Kit (with settings such as Hidden, Required, or Secret), you might see a combination of fields:
      • Default fields that are specific to each authorization type
      • Custom fields that allow data to be passed in a request header, cookie, or query
      • Standard fields that are common to all authorization types, and which can be used to allow self-signed certificates or to override the URL for the API server

      If standard fields are included in the connection properties for the community connector, you can complete these fields as follows:

      • If you want to be able to accept self-signed certificates that are trusted and used only in a non-production environment, set the Allow self-signed certificates field to true. The default is false.
      • If you want to override the URL for the API server, which makes runtime calls, with a URL that points to a publicly available endpoint, complete the Override server URL or Override the host name and port of the API server field. Specify an override value for the host and port in the format http://host:port or https://host:port. (Leave the Private network connection field blank.) When you create and run a flow, the API server's host and port are overwritten. This setting enables you (or multiple users of the Designer instance) to use the same flow to call different or custom endpoints for the API by setting up multiple accounts with different override URLs.
      • If you want to override the URL of the API server with a URL that points to an endpoint in a private network (for example, behind a firewall in an on-premises location), you'll need to set up a private network connection that App Connect will use to securely access the endpoint. To connect to an endpoint in a private network, you must complete these fields:
        • Override server URL or Override the host name and port of the API server: Specify the protocol, host name or IP address, and the port number of the protected endpoint in the format http://host:port or https://host:port. When you create and run a flow, the API server URL is overwritten with a destination host and port that enables the API request to be routed through the private network connection, to the protected endpoint.
        • Private network connection: Select the name of a private network connection that App Connect uses to connect to your private network. This list is populated with the names of private network connections that are created from the Private network connections page in the Designer instance. You see this field only if a switch server is configured for this Designer instance. For information about creating and configuring private network connections, see Connecting to a private network from App Connect Designer. (In App Connect Designer 12.0.10.0-r1 or earlier instances that include this field, the display name is shown as Agent name.)

      If no authentication and no override values are required for connecting to or calling the API, you can leave all the fields blank.

   2. Click Connect.

   A default name (typically Account n) is assigned to the account, where n is a number that starts from 1 and increments for each account that you add. Before you use the account, you might find it useful to rename the account to something more meaningful. To do so, select the account in the Account drop-down list, open its options menu (⋮), and then click Rename Account.

If no longer needed, you can delete a community connector from the Catalog page.