Connector Developer Program

Create from a Swagger Definition

Creating Connector from a Swagger Definition

Swagger is a set of open-source tools built around the OpenAPI Specification that can help you design, build, document, and consume REST APIs.

Swagger allows you to describe the structure of your APIs so that your machines can read them. Swagger does this by asking your API to return a YAML or JSON that contains a detailed description of your entire APIs.

This tutorial helps you to create a Connector for petstore swagger, define the predefined operations, and test them for a RESTful API using the webMethods platform.

Below is the video tutorial for Creating Connector from a Swagger Definition:

Creating Connector Project

  1. Launch Software AG Designer and change the perspective to CloudStreams Development
    In Software AG Designer, go to Window > Perspective > Open Perspective > CloudStreams Development

    CloudStreams Development Perspective

  2. Open CloudStreams Providers view

  3. Configure the Integration Server(IS) if not configured

  4. Right-click on the Integration Server Name(Default) and select Cloudstreams Provider Project

    CloudStreams Development Perspective

  5. Enter the Project name and choose Connector Type as REST
    Example: DemoPetStoreProvider
    CloudStreams Development Perspective

  6. Enter the Connector Details for Petstore
    Example:
    Name: Petstore
    ID: com.softwareag.cloudstreams.petstore_v2
    Group: Petstore
    Import Swagger specification file: checked
    File/URL: https://petstore.swagger.io/v2/swagger.json

CloudStreams Development Perspective

7. Click the Finish button. All the resource definitions which are part of the Swagger file are generated as part of the Connector as shown in the below screenshot:

CloudStreams Development Perspective

Adding Authentication

Note:- Petstore Swagger supports API Key, OAuth2, and also works without authentication. This example demonstrates the authentication mechanism in the Connector when you choose the authentication type as Credentials.

  1. In Designer, expand the project name and double-click the Connector name Petstore to show the overview of the Connector

    CloudStreams Development Perspective
  2. On the Connection screen select the Authentication tab and choose the Authentication Type as Credentials and save the changes

    CloudStreams Development Perspective

For your reference, click here to download the sample Connector project created using the above steps. To know how to import the Connector project into Designer CloudStreams Development, go to Appendix.

Publishing Connector

Finally, let us publish the Connector after all the resources are generated for the CRUD operations.

To create the Connector project as IS package you need to publish it to the target server(IS).
Follow the below steps to publish the Connector:

  1. Right-click the Connector project in the CloudStreams Providers view and click Publish

    CloudStreams Development Perspective
  2. Ensure that the Connector project is selected and click Next

    CloudStreams Development Perspective
  3. Select the Target Server(IS) and click the Finish button

    CloudStreams Development Perspective

For your reference, click here to download the sample IS package for the Connector.

Creating Predefined Operations

Each application has the most commonly used objects and their related REST resources/operations.
Predefined operations enable end-users to directly consume these most widely used operations.
Example: Create a ticket in ServiceNow

Follow the below steps to create predefined operations:

  1. Create a connection for the published Connector. You can follow the below steps to create a Connection:
  • Go to Integration Server Administrator page > Solutions > CloudStreams > Providers > Petstore
    Click the connector name Petstore from the Connectors List and select Configure New Connection

  • Provide the Connection Details such as Package, Folder name, Connection name, Credentials, and Authorization Type
    Example:
    Package: Default
    Folder Name: CloudConnections
    Connection Name: PetstoreConnection
    Username: demo
    Password: demo
    Authorization Type: basic

    CloudStreams Development Perspective

  • Save the Connection details and enable the Connection

    Create Connection

  1. Create a folder structure under the DemoPetStoreProvider package for creating Predefined operations under them. In Software AG Designer, go to Service Development perspective > Expand the Package(DemoPetStoreProvider) > Right-click the package and create the folder structure as shown below:

    CloudStreams Development Perspective
  2. Create a Cloud Connector Service (CCS) with the name findPetsByStatus
    In Software AG Designer, go to Service Development perspective > Expand the Package > Right-click the triggers folder and perform the action as shown below:

    CloudStreams Development Perspective
  3. Choose Finds Pets by status Resource

    CloudStreams Development Perspective
  4. Create an empty folder findPetsByStatus with the same name as CCS

  5. Create an empty FlowService findPetsByStatus with the same name as CCS within the created folder as shown below:

    CloudStreams Development Perspective

  6. Open the empty FlowService and click the Tree tab and then drag and drop the CCS on the canvas

    CloudStreams Development Perspective

  7. Click the Input/Output tab of the FlowService

    CloudStreams Development Perspective

  8. Open CCS, go to the Input/Output tab and copy the entire Input parameters from the CCS's Input tab and paste them into the FlowService's Input tab

    CloudStreams Development Perspective

  9. Similarly, copy entire Output parameters from CCS's Output tab and paste them into the FlowService's Output tab

    CloudStreams Development Perspective

  10. Open the FlowService, click the Tree tab, and select the dropped CCS on the canvas.
    In the below Pipeline tab, check if the variables are correctly mapped, if not then manually map the variables

    CloudStreams Development Perspective

The predefined operation is now ready and you can run the created FlowService. Repeat the above steps starting from Step 3 to add more predefined operations.

For your reference, click here to download the Connector IS Package with the created predefined operations.

Testing Connector

To test the predefined operations created using the Connector package, follow the below steps.

  1. To test a Connector either use the above-created Connector package or download the Connector package from here

  2. Create a test package(DemoPetStoreProviderTest) that encloses the connections and testing artifacts as shown below:

    Test Package

Test Package

  1. Create a folder inside the package with the same name(DemoPetStoreProviderTest) to avoid any namespace conflicts

Test Folder

Test Folder

  1. Right-click the folder DemoPetStoreProviderTest and create folder connections to keep all your connections to the SaaS backend

connections Folder

  1. Create a connection similar to Creating Predefined Operations (Step 3) in the DemoPetStoreProviderTest package under connections folder. Provide the connection folder name as DemoPetStoreProviderTest.connections

Create Connection

Create Connection

Create Connection

  1. Copy the connection name as shown in the below image which will be used as input to test the Predefined operation

copy connection

  1. Create folder services for all FlowServices that you will create to test the predefined operations

service Folder

  1. Create a FlowService findAvailablePets, drag and drop the predefined operation findPetsByStatus from the Connector package as shown below, and save the changes

    FlowService

FlowService

FlowService

  1. Select the dropped predefined operation in the FlowService and click the Pipeline to show the parameters and $connectionAlias

Pipeline

  1. Copy the entire Service In input parameters as shown below:

Pipeline

  1. Click the Input/Output tab of the FlowService and paste the input parameters.
    Repeat the same for the output parameters

Pipeline

  1. Right-click the FlowService findAvailablePets and run the service as shown below:

Run

  1. Provide the inputs for parameters as below and click OK
    status: available
    $connectionAlias: value copied from Testing Connector (Step 6)

Run

The HTTP call is made and the response from Petstore is shown in the Results tab.
Here, you can verify the status and response of the executed operation.
Ensure that all the required fields are present as per the signature of the created Predefined Operation.

Run

Congratulations! You have successfully created the Connector.

To download the source code of the Petstore Connector from GitHub, click here.

Connector Submission to Software AG

Now that you have the Connector ready, you might want to submit the Connector package to Software AG. Software AG will review the Connector, and if it meets the certification criteria, then it will be published to webMethods.io Integration Platform.
Go to Connector Certification page to submit.