Integration

 View Only

Using the Connector Development Kit: Create a custom connector from an openAPI document - Part 3

By Siddalinga Swamy Mathad posted Fri April 07, 2023 08:17 AM

  

Authored by @Siddalinga Swamy Mathad and @RAMKUMAR RAMALINGAM

Part 1: Using the Connector Development Kit: Create, Customize & Contribute your own Connectors
Part 2: Using the Connector Development Kit: Create a custom connector from scratch

IBM Connector Development Kit is a UI-based development kit that allows you to create a connector in your browser without code. CDK provides an intuitive and guided user experience to build and test your connector. You can learn more about IBM CDK in Part 1 of this series.

In this, Part 2 of this series, you learnt how to create a custom connector from scratch using IBM CDK, in this article you will learn how to build a custom connector by importing an OpenAPI document in IBM CDK, this approach accelerates your connector development process as CDK auto populates most of the details required by the connector from your Open API document.

Prerequisites

Before your begin ensure you have completed following steps

  • Identify the SaaS application to which you want to build a custom connector and ensure that the application provides an OpenAPI document that can be downloaded.
  • Ensure that you have procured an account for the application and the account has authorisation access to invoke the APIs.
  • Create a IBM ID if you have not created already. IBM ID is mandatory to create a custom connector and to download an existing community connector from IBM Automation Explorer.
  • After you log in with your IBM ID, please review and accept the user terms to allow IBM to use your connector and log within IBM App Connect.

In this article, we will try to create a connector for the IBM Watson Natural Language Understanding service. The IBM Watson NLU helps you to extract the meaning and metadata from the unstructured text data.
Before you continue, complete the following steps to get access to IBM Watson NLU APIs.

  •  Provision IBM Watson Natural Language Understanding service from IBM Cloud here. It offers Free Lite plan that can be used for development of the connector.
  • As with all IBM Watson service, the IBM Watson NLU also offers OpenAPI specification document that you can download easily.  When you are in the API docs page of the service, you can download the OpenAPI documentation by clicking on the hamburger menu option available on the top left corner of the page. 
  • Once you provision the service, you will be provided with a API key. Note down the "API Key" and also instance URL of your service. 

    Lets begin developing connector using CDK

Step 1: Create a connector

Create your first custom connector by clicking on the “Create a connector” button.


You do not need to provide connector name and description as these are auto populated by the OpenAPI document. 

Provide the OpenAPI documentation downloaded into the "OpenAPI document" field by clicking on the import link. This will populate the connector name and description automatically. Review connector name and description, you can edit if you are not happy with them. 

Provide an icon if you have it. Currently Connector Development kit accepts only svg image files. 



Step 2: Verify authentication type

CDK supports multiple authentication types like Basic, Bearer Token, API Key, OAuth2 Authorization Code, OAuth2 Password, OAuth2 Implicit, and OAuth2 Client.

IBM Watson Natural Language Understanding service supports API Key authentication. You have already noted down the API Key in the previous step.  There is nothing to do in this step.

Step 3: Add or remove actions

You notice that the Connector Development Kit has created several actions for you using the OpenAPI document you have provided.
By default CDK creates 10 actions, you can click on the Add or remove actions to add additional actions or remove actions that are not applicable for the connector. All the actions that are visible on the pallet will be the available actions of your connector. 

To keep the connector simple, lets remove all actions from the pallet and retain only Analyze group of actions. 

You will have only Analyze Text (GET) and Analyze Text actions as part of the connector actions.



Analyze Text operation helps you analyze raw text, html or a website. We will use the operation to analyze the emotional quotient of a text to test the connector action later.

Step 4: Configure actions

In this step you will configure both the actions for further improvements. If you notice, the "Anlayze text (GET)" action is marked incomplete.  We will make it complete first. 

Configure action details


Select the display name field on the action details tab, you will notice that CDK is throwing an error. CDK does not allow non alphanumeric characters in the display name. Lets change the display name value to "Analyze text GET".  Now, change the action type to "Retrieve" as this is simple GET operation and returns a single record. The action shall be marked complete now.  You can further format the action description if you are not happy with the text.

Configure Request and Response properties


Navigate to the Request tab to configure the request properties for the action. As this a Retrieve action, you need to configure request query parameters. You can keep all of the query parameters as is or you can remove some of them to make connector precise and concise. Click on "Add or remove" on Query parameters to unselect of the parameters from the actions.

You can now go to other action "Analyze text" and modify display name and description if required.  Navigate to Request tab, you can configure the request properties for your action. Click on "Add or remove" on Properties section to remove properties that are not relevant for the connector. 


After removing unwanted properties you can now set the display order of these properties. You can move important and required properties to the top of the request set and less important properties to the bottom. This helps connector users to configure the connector action quickly when used in an integration flow.

Similar to request tab, you can configure the response properties. But, you can't change the display order of the response properties.

Your connector is complete and ready for testing.

Step 4: Testing actions

CDK has in-built test runtime that helps you quickly test the connector without moving to App Connect. Click on Test tab to test your connector actions. It is mandatory to provide connection details before testing your actions.  Click on connect button to create a connection. 
In order to connect to IBM Watson NLU service you need to provide API key you noted down previously. 

The IBM Watson NLU service expects you to pass API Key in the Authorization header as BASIC Authentication type. For that you need to generate the Base64 encoded string of 'apikey:<apikey_value>'. You can easily generate Base64 encoded string through internet.  Read more about how to authenticate to a Watson Service here

In the connection screen provider following values 
Provide API key field with the value Basic <Base64encoded string>
Provide the instance URL of your IBM Watson NLU service instance that you noted down in the prerequisite section in the 'Override server URL' field.


Once you connected successfully to the service, you can now see all your actions in the Test tab. Lets try testing "Analyze text GET" action.

Lets try to analyze a text for emotional quotient using the action you have just developed. Here are values you need to fill in for the request parameters in the test tab and click on Submit. You will get back the emotion rating for the text you provided to the action. 
The current IBM Watson NLU version is '2022-04-07'


The successful test results indicate that the connector is able to successful connect to your NLU service and invoke the operation on it. 

Step 5: Download connector

Now that your connector is complete and tested, you can download it as a private connector to use it in IBM App Connect. You can use the connector in both App Connect on AWS cloud and CP4I. 
Click on download connector option to download the connector. 


You will be able to download the connector archive file called Natural Language Understanding - Connector.car on to your local file system. 
You also have the option to publish this connector to make it available to the community. In that case, you can click on publish option to follow the instructions displayed on the screen. 
If you want to continue to use connector privately then you can upload the connector archive file you just downloaded to your App Connect instance.

Step 6: Deploying your connector in IBM App Connect 

The steps in the section are similar to the steps mentioned in the Step 7 of Part 2 

To import the connector to your IBM App Connect instance, click on '+' icon in the catalog page from your Designer instance. This will open up a wizard to guide you to import a connector.  



Drag and drop your connector Natural Language Understanding - Connector.car  and select community connector option from the drop down. 



Click next to preview the connector metadata 


Click on import connector to import your connector. 

Create the account for your connector and start using its actions in the integration flow. 

Summary

In this article, you are able to build a custom connector using OpenAPI document in very quick time by just following 5 steps. You also learnt how to use the connector as a private connector in your App Connect instance. Hope this article will help you to get started with IBM CDK. 

If you have any feedback or suggestion for improvements for IBM CDK and Automation Explorer, feel free to post your questions to community forum. Look forward your active engagement.



0 comments
58 views

Permalink