Brief Idea of WSO2 ESB Connectors

What is connector?

Connectors allow you to connect and interact with services which are provided by outside parties. A connector is a collection of templates which define set of operations which are given by outside party. Connectors are used to wrap the API of an external service. For writing a connector, we should research the API provided by the service. Then we have to decide which API we are going to use to write our connector. After that we can implement the operations which are provided by the API. Most of outside parties offer two services such as REST and SOAP in their APIs.

Why Connector?

I am pretty sure that most of the people think why we need to use connector. There are many external parties providing API to use their methods and tables. Most of us know about Google Blog API which is providing many methods such as getting get Blog, get comment, get post and etc. If you want to use those functions in your software, then you have to implement all those functions in your software. But in a connector already the methods are implemented. By using connector in your code you could save your time by recreating it. As all you know WSO2 products are open source, you can download the connectors and can use it.

Writing ESB Connector

You can clone ESB connectors from the following git hub link "https://github.com/wso2/esb-connectors".

$ git clone https://github.com/wso2/esb-connectors

After you clone there are lot of connectors you can get. They can be SOAP connector or REST connector or Java connector. So you can select one of the connector according your task and modify it. 

Open a connector according to your API in IntelliJ. You can see below structure. 

Here you can see some folder structure.

• Repository: Here you have to put your WSO2 ESB which you downloaded.
• Resources: Here you have to implement your API methods. Some outside party can provide set of grouped methods. So that set methods must come in one folder. 
• config: This folder contains init.xml and component.xml.
• init.xml: Initialize the connector environment. Here we specify username, password, API url, Access token and etc which are related to initialize the API.
• component.xml: This file is included in every module (like folder). This defines available methods in the module. In this folder we define init.xml and its desvription. component.xml will be like this.
  

  <component name="config" type="synapse/template"> 

        <subComponents> 

            <component name="init"> 

                 <file>init.xml</file> 

                 <description>Configuration.</description> 

             </component> 

       </subComponents>

   </component>

•  icon: Here you have to put API's icons.
  
  After that you can create own folder structure and within the folder you can create your synapse template like below.
  

  <template name="method" xmlns="http://ws.apache.org/ns/synapse"> 

     <parameter name="param" description="The parameter which needs to give to API./>    
       <sequence> 

          <property name="uri.var.param" expression="$func:param"/>
            <call> 

               <endpoint> 

                    <http method="GET" uri-template="{uri.var.URL}"/> 

               </endpoint> 

           </call> 

      </sequence> 

  </template>

• connector.xml: This defines connector name and dependent modules.
  

  <?xml version="1.0" encoding="UTF-8"?>

  <connector> 

     <component name="compo" package="org.wso2.carbon.connector"> 

           <dependency component="config"/>        
          <description>WSO2 Connector for API.</description> 

    </component> 

  </connector>

• pom.xml: Contains the required dependencies for connector core libraries and relevant synapse libraries as well as maven repositories for a specific connector.
  
  In my next blog I will cover Integration Test using TestNG. :)

Working with Import Set API in Service Now

What is ServiceNow?

ServiceNow is a software platform that supports IT service management and automates common business processes. This software as a service (SaaS) platform contains a number of modular applications that can vary by instance and user.

ServiceNow has two types of APIs such as SOAP and REST API. Most functions are same in those two APIs. ServiceNow offers three types of REST APIs such as Table API, Aggregate API and Import set API. There are some methods and tables in those APIs.

Accessing Import Set API differ from other APIs because we cannot directly access the records in import set tables. We have to give ACL permission for that. This blog illustrates about Import Set API.

What is Import Set API?

The ServiceNow Import Set API provides a REST interface for import set tables. The API transforms incoming data based on associated transform maps. The import set API supports synchronous transforms. Access to tables via the REST API is restricted by BasicAuth and the rest_service ACL

Import Set API provides two methods such as POST record and GET record by sys_id. When you create an instance four tables will be provided such as imp_computer, imp_location, imp_notification and imp_user. You can create your own tables also. The user should have rest_service role to access above two methods.

In this blog, I am discussing about how to give access to the table imp_computer and  create an exclusive ACL for rest_service role.

Giving Application Access to the records in the table

1. Go to the link "https://instancename.service-now.com/imp_computer_list.do " Here you have to specify your own instance name. After that below page will be displayed.

 

2. Then Right Click->Configure->Table

3. Then  a window like below will ,appear. In this window you can check the check box "can create", "can read", "can update" and "can delete" according to your requirement.

Create an exclusive ACL for rest_service role, giving access to the table

Before creating ACL for rest_service role, we have to create rest_service role for the user.

1. Elevating to a privileged role: For this type as "roles" in your filter of the instance. Then click on the Roles which appear in the list (left panel). Following window will appear. 

Then make Elevated privilege as true to security_admin

 After that click on a lock icon which appears next to the user's name in the header.

 Then a pop up window will appear. In that window you have to tick security_admin.

2. Navigate to System Security > Access Control (ACL) in your instance. Following window will appear.

3. Click New.
4.Define the object the ACL rule secures and the permissions required to access the object. Put a read ACL for rest_service role- you should have security_admin role to create new ACLs: Incident.none and Incident.*

Now you have given ACL permission for that record. Then you can access Get Record by specifying sys_id method can be accessed.

The sys_id that is returned during a POST call to an import set table is not the sys_id of the record in the import set table.  It is the sys_id in the target table(where the record was transformed to)

To get the sys_id, as an admin, you have a multitude of options

Option 1: Navigate to the record (https://instancename.service-now.com/imp_computer_list.do) in a list, right click and copy sys_id.

Option 2: Open the record in a new window, without the frames.  The URL will contain the sys_id

Option 3: While in the record, right click on the header, select show XML, and find sys_id in there.

After getting the sys_id go to REST API Explorer by typing "rest" in the filter in your instance.

Then specify the table name as "imp_computer" and your copied sys_id and click send.

The Response message will like below.