Enable CORS on WSO2 Data Services Server (DSS)

CORS enable/disable feature does not come as an out of the box feature from WSO2 DSS. But this can be achieve by adding a cors filter. We can use the method described in cors filter installation document in DSS as well because DSS uses a tomcat server.

Step 1 : add necessary libraries to DSS

Download and copy cors-filter-2.4.jar and java-property-utils-1.9.1.jar files to the <dss_home>/repository/components/lib folder. Latest libraries can be found in this site.

Step 2 : Add CORS configuration to tomcat web.xml

Open  <dss_home>/repository/conf/tomcat/web.xml file and add CORS Filter declaration and mapping.

<filter>
   <filter-name>CORS</filter-name>
   <filter-class>com.thetransactioncompany.cors.CORSFilter</filter-class>
</filter>

<filter-mapping>
   <filter-name>CORS</filter-name>
   <url-pattern>/*</url-pattern>
</filter-mapping>

Step 3 : Restart the server

Customizing API Manager – Adding Workflow Extension

API Manager comes with capability to add custom workflows to user signup, application creation, registration and subscription. By default API manager comes with two workflows. Simple Workflow Executor and WS Workflow Executor. Simple workflow executor is the simplest one and it is enabled by default and it executes the default flow.

In WSO2 API Manager documentation, you will find a post regarding creating a custom workflow. In this post I’ll try to show in more details how this workflow process happens. Once you understand the process you could use this feature much more effectively in your own environment.

Workflows can be used to add extra steps in to the processes like self signup, application creation, etc. For example we can use a workflow for user self signup in the store and add extra steps to approve this user before giving him the permission to access the store. (the default process just create the user and grant him the rights to access the store). WS Workflow Executor has implemented this feature. The sample executor in the api manager documentation sends an email during the workflow. So we can do whatever we want. At the moment workflows can be used for only user signup, application creation, registration and subscription.

Following image describes the steps. Knowing the steps would make it easier to implement a custom workflow

When an action occurs (ex user signup, etc) API manager selects the executor to execute for that action. This is defined in the registry workflow-extension.xml file (refer https://docs.wso2.com/display/AM180/Adding+Workflow+Extensions)

Then it execute the execute() method first (please refer to the code example in https://docs.wso2.com/display/AM180/Customizing+a+Workflow+Extension). This method is called by the previous mentioned action. WorkflowDTO object is passed to this method which contains a unique reference id for that workflow (externalWorkflowReference) this reference needs to be there all the time to complete the execution.
All the custom executors should extend the base class WorkflowExecutor.
By calling the parent execute() method, an entry related to this workflow is added to the database with 'Created' as the status.
super.execute(workflowDTO);

Inside this method we could do our additional work. (sending email, etc). WS Workflow Executor which comes with API manager as one of the default executors sends a request to external business process server (WSO2 BPS) for an approval process.

We can also call the complete() method from the execute() method. This way we can finish the workflow from there (Simple Workflow Executor and the sample executor in the documentation use this method).

NOTE: some processes need to change their states in the complete stage. For example in application creation workflow you have to set the status of that application to ‘REJECTED’ or APPROVED in the complete() method (before the execute() method the application state is in ON_HOLD ).

Do not forget to call parent method at the end of the complete method
super.complete(workflowDTO);
API manager has deployed a web service to handle the situations where we call external applications (step 2 and 3). A web service'WorkflowCallbackService' is hosted to accept external requests related to workflows and call the complete() method.

The service endpoint is http://127.0.0.1:8280/services/WorkflowCallbackService and the wsdl file can be viewed using http://127.0.0.1:8280/services/WorkflowCallbackService?wsdl

The reference id I mentioned in the execute() method needs to be sent as workflowReference and status should be APPROVED, REJECTED or REGISTERED

WS Workflow Executor

WS Workflow Executor is one of the default executors in API manager. This can be used to add an approval/rejection process. WSO2 Busines Process Server is used as an external server to handle the approval process. The process is defined in BPL and deployed in WSO2 BPS. Following is the overall picture of how it is used. You could understand it with the previous information

Customizing API Manager – Adding custom handlers

API Manager comes with a built in ESB. It acts as the gateway and handles all the api calls. API creator can manipulate the requests before they are sent back to the actual back end by configuring the api gateway. Handlers can be used to achieve this task.

There are some default handlers added to an api once it is created. To check this first create and publish an api by login in to API manager publisher and then go to the <AM_HOME>/repository/deployment/server/synapse-configs/default/api location. If the api is created successfully, there will be an xml file with the name of the api in this location (creator_name_version.xmlwould be the exact name ). Under the <hanlders> element, all the default handlers are defined. These handlers execute (in the order) first once a request hits the api before sending it to the back end.

These handlers handle different tasks related to the api call. First handler handles the authentication part of the request. For example, to call an published api, we need to use an access token ( adding it to the Authorization header of the request). APIAuthenticationHandler handler is used to validate the token and reject invalid requests.

Adding a custom handler to an existing api

api creator may need to add his own processing. (for example validate some other headers) . He can develop a custom handler and plug it in to the api. Tutorial on creating a custom handler can be found in the Api manager documentation. After creating the handler, put it in to the<AM_HOME>/repository/components/lib folder and insert an entry inside the <handlers> element

<handler class="org.wso2.customhandlers.testhandler"/>

Note: To build the custom handler you need the have the synapse libraries in the class path. You can point to<AM_HOME>/repository/components/plugins folder for this.

Adding a custom handler to all the apis.

If this handler needs to be added to every new api, then it is not practical to add it manually once the api is created. API manager provides templates to define the structure of the api and we can modify this to have the custom handler as a default handler. This way every api will have the custom handler inside the<handlers> element

For this we need to modify the velocity_template.xml file in the<AM_HOME>/repository/resources/api_templates/ location. Open it and find the location '<handlers>'

Add the custom handler inside the <handlers> element after the #end tag. This will add the custom handler after the default handlers.

Self signup for tenants – API manager 1.8

Api manager comes with user signup feature for user store by accessing API store application. One limitation  in Api Manager 1.7 was that users were able to  signup only to super user’s API store. Tenant users were added through the management console. Api Manager 1.8 comes with the self signup feature for tenant store as well.

To enable self signup in AM 1.7, admin has to modify following configuration in the api-manager.xml file in <AM_HOME>/repository/conf

This is removed from api-manager.xml configuration file and moved to registry location. For each tenant doman there is a sign-up-config.xml configuration file. Tenant admin can log in to the management console and edit this configuration. This way each tenant domain can have different configurations for self signup.

The configuration file related to self signup in Api Manager 1.8. this can be found in the ‘/_system/governance/apimgt/applicationdata/sign-up-config.xml‘ registry location. Login to http://localhost:9443/carbon by using tenant admin credentials

following is the configuration file

To enable self signup for tenant API store <EnableSingup> element needs to be ‘true’. Otherwise the self signup option would not be visible in the tenant store. This is ‘true’ by default for super tenant.

AM 1.8 provides option to set the user storage to store these users.<SignUpDomain> defines this. PRIMARY refers to the primary user store. This can be pointed to secondary user store as well. More on creating user stores can be found in API manager documentation related to configuring secondary user stores . The Domain name used for that user store can be used in <SignUpDomain>

<SignUpRoles> defines the roles that are assigned to the users. AM 1.8 provides facility to assign more than one role for the user by adding <SignUpRole> element inside the <SignUpRoles> element.

NOTE: These roles are not created automatically so these roles needed to be created by the admin user. See more on how to create user roles and assigning permission.

IMPORTANT: At least one role has to have ‘subscriber’ permission. Otherwise user won’t be able to login to the tenant store.

After configuring this, you will be able to see the self signup button in the tenant API store

This feature can be extended by enabling user signup in workflow extension . This will enable an approval process for newly Signed up users. More information on this can be found in Api Manager documentation

Optimize the OS to handle large number of concurrent requests

Theoretically Node.js can handle huge number of concurrent requests without blocking the application. This means server created using Node.js can handle concurrent requests without any problem unlike thread based server applications such as Apache servers.

I had to create a server application using Node.js to handle high level of concurrent requests. During the testing for higher level of concurrency one error I got was connect EMFILE . 

This error means that the OS is not allowing your program to open more files or sockets. So to handle higher levels of requests, you need to optimize the OS. We can do this by changeing the maximum number of files that can be open. To check the current limit in Linux system type

ulimit -n

For a Linux based system, this can be done using following instructions

One method is reset the limit for your current shell. This can be done easily by typing ulimit -n 4096. 4096 is the new maximum limit

The other way is by editing /etc/security/limits.conf file. open it using your favorite editor.

sudo gedit /etc/security/limits.conf

Add following two lines before the end of file

* soft nofile 4096

* hard nofile 65535

soft limit is the current value. Hard limit is the maximum limit. The soft value cannot exceed the hard value.Then logout and re login to your system. you can check the limit by  ulimit -n

Set up your Raspberry Pi

Have you ever used this cool piece of hardware called ‘Raspberry Pi’. If not your should try it out. It is cheap credit-card-sized computer. You can google it for more info.

I recently acquired one of this for my final year project work. I went straight away to set this up. I read many number of posts to figure out how to do this. If you do not like to read lengthy posts, then this is the place. I will try to keep things simple.

You need to have a SD card (probably 2GB minimum ), power supply (5V , around 700mA) , a USB key board and a RCA cable. There is a HDMI port which can be used to take the video out as well. If you do not have a RCA cable and a USB key board with you (I didn’t) you can still use this using a network cable. More on that later. If you cannot find a power source for this but you have a USB-to-microUSB cable (normally comes with android devices) you can power up by plugging it to the USB port. 

Download the OS

you can download the OS from http://www.raspberrypi.org/downloads . if you are planning to install JVM, then you should use the ‘Soft-float Debian “wheezy”‘ version. If not the Raspbian version is enough for any beginner. (At the time of writing thisOracle released a Developer Preview of JDK 8 runtime for Linux ARM hardfloat and with JavaFX which supports the Raspbian version).

Install the OS

Format the SD card. if you are using windows or Mac you can use SD Card Association’s SD Formatter to do it easily. Then download the OS and extract it and use Win32DiskImager (Windows users) or dd (for Unix) to write the image to the SD card.

That’s it. Power up the Raspberry Pi (no power switch to switch it on. just connect the power.).  When you start for the first time, you will get a window to configure the system. you can just skip this or access this late by typing sudo raspi-config . When you exit the configuration. you will be asked to enter user name and password.

Default login :  Username: pi     Password: raspberry

You can work on the terminal or can access the GUI by typing startx. 

Configure 

There are some configurations you might need to do. You can read more about the configuration from here. Some of them are

• expand_rootfs – If you are using a SD card larger than 2GB, you should do this. this expands the initial image to fill the unused parts in the SD card
• change_pass –  change the password
• memory_split – This can be used to configure how much memory to share for GPU. If you are not using much video processing, you can reduce this to a minimum value.