Implement a Ballerina Connector

Ballerina is a general purpose, concurrent and strongly typed programming language with both textual and graphical syntaxes, optimized for integration by WSO2.

What is a Connector?

A connector allows to interact with third party application functionality and data through APIs in the existing integration flow. For example if I want to read mails, create labels, delete drafts in Gmail, I could wrap up this functionalities appropriately, call it as Gmail Connector and that connector can be imported and used as needed.

Image source — http://srijicomputers.com/wp-content/uploads/2016/02/Power-cord_icon.png

Scenario

To implement a Ballerina connector I have chosen Cisco Spark APIs which is an app-centric, cloud-based service that provides space for teams to collaborate and work together

Following functionalities will be included in the Cisco Spark Connector which will interact with Cisco Spark APIs related to Teams.

  • Retreive all Teams
  • Create a new Team
  • Retrieve a team by team identifier
  • Edit a team name
  • Delete a team

Lets implement the Cisco Spark Connector

using Ballerina v0.92

I followed the existing WSO2 Ballerina Connectors project structure and created a new file named ciscoSparkConnector.bal.

Initially import the OAuth2 client connector.

import org.wso2.ballerina.connectors.oauth2;

Imported oauth2 connector handles the authentication flow with oauth2 authentication. This can be used in implementing cisco spark connector since it also uses OAuth2 authentication. Basically when we provide the required arguments when creating an instance of this connector, it handles the authentication flow.

Create an instance of oauth2 by providing relevant arguments. For this scenario I worked only with the access token. So when creating an instance of oauth2, I sent the access token and base URL of cisco spark API as parameters and for the rest I sent null of string type. Refer oauth2 connector for the expected parameters when creating an instance of oauth2. The name of the instance I created is ciscoSparkEP using which I can invoke the actions of the oauth2 package.

package org.wso2.ballerina.connectors.ciscospark;
import org.wso2.ballerina.connectors.oauth2;
connector ClientConnector (string accessToken) {
string baseUrl = "https://api.ciscospark.com/v1";

oauth2:ClientConnector ciscoSparkEP = create oauth2:ClientConnector(baseUrl, accessToken, "null", "null", "null", "null");
}

Then create an action called createTeam which is a unit of behavior. What this actions does is, it creates a team for the given team name as the name of the action implies.

In the above code snippet,

  1. The action createTeam will take the name of the team to be created as a parameter.
  2. Return type is of message type.
  3. Resource path to create team is in createTeamPath string variable.
  4. Payload to be sent in body is in createTeamPayload json variable.
  5. JSON payload is set to the request body.
  6. Header of Content-Type: application/json is set to the request header.
  7. Post action in oauth2 connector is invoked using the created oauth2 instance ciscoSparkEP.
  8. Response object is returned.

I used the Source View in Ballerina composer for coding, instead of that you can use the Design View as well. This is a cool feature in Ballerina, when we code in source view, the sequence diagram is auto generated and when we work on design view, the source code is auto generated.

The generated sequence diagram or the design view for Cisco Spark Connector including createTeam action looks like below,

Design View of Cisco Spark Connector — createTeam action

I implemented four more actions to edit a team, delete a team, view a specific team and view all teams. You can also try implementing few more actions.

Use the Implemented Connector

To use the implemented connector we need a valid access token. I created a Cisco Spark developer account and an application which provided me with an access token. For further information on creating an application and generating credentials (client id, client secret, access token, refresh token) refer cisco spark authentication.

After having a valid access token, create a separate file with the main function to invoke the createTeam action and to print the details of the created team by invoking the getTeam action of the connector.

function main (string[] args) {
string accessToken = "access-token";
ciscospark:ClientConnector ciscoSpark = create ciscospark:ClientConnector(accessToken);
message createTeamRespone = ciscoSpark.createTeam("DevX");
json createTeamJSONRespone = messages:getJsonPayload(createTeamRespone);

if (http:getStatusCode(createTeamRespone) != 200) {
system:println(jsons:toString(createTeamJSONRespone));
return;
}

string teamId = jsons:toString(createTeamJSONRespone.id);
message getTeamResponse = ciscoSpark.getTeam(teamId);
json getTeamJSONResponse = messages:getJsonPayload(getTeamResponse);
system:println(jsons:toString(getTeamJSONResponse));
}

After implementing the function, run it to see the output in the Ballerina console. Output which I got when I run the above main function looks like below,

Ouput of the main function in Ballerina console

I’ll be working with this connector in future to enhance its capabilities by adding more actions to interact with the Cisco Spark API. I will also be working with Testerina for this connector. Anyone interested please feel free to contribute.

GitHub Repository: https://github.com/saadsahibjan/cisco-spark-connector