OpenSocial Gadget Development for IBM RTC
The IBM Rational Team Concert (RTC) support widgets of two type's iWidgets and OpenSocial Gadgets. The Advantages of developing Widgets as OpenSocial Gadgets for IBM RTC are
- It requires only the knowledge on HTML, CSS, and JavaScript to get most of the things out of the box during development.
- Adding the OpenSocial Gadget do not require any additional permission for the end user, it can be directly added to the users “Mini Dashboard” area.
To use an OpenSocial Gadget in IBM RTC
- The OpenSocial Gadget has to be hosted in a webserver
- The URL of the page (OpenSocial Gadget xml file which will be discussed in Part 2) has to be added in the “Add OpenSocial Gadget” area of IBM RTC Server
The web server to host the OpenSocial Gadget is up to the user preference like NGINX, Apache, WAMP, IIS and so on. The most import aspect to consider before choosing a web server is to check if the web server supports HTTPS hosting.
IBM RTC Server works under HTTPS, if the OpenSocial Gadget is hosted as HTTP site, the gadget will be blocked from rendering with issue as Mixed-Content. Majority of the browsers does not support mixed-content.
If the web server which you choose is intended only for the purpose of OpenSocial Gadget, then your best choice can be NGINX which is very light weighted. In the below post we have explained how to configure and use NGINX for OpenSocial Gadgets
Part 1 - NGINX Setup
Installing NGINX on Windows
- Download the latest version of NGINX/Windows zip from http://nginx.org/en/download.html. The stable version during the time of this blog was NGINX 1.12.0
- Unzip the zip to a location in your system and run the nginx.exe
- Open your browser and navigate to the link http://localhost/. If you are seeing a message as “Welcome to nginx” it means your ngnix webserver is up and running.
If you are receiving message as site cannot be reached, it means NGINX is not running. You can check the logs folder to find the exact reason. One common cause would be another application running in your systems uses the same port as NGINX. The default port of NGINX is 80 which can be changed through nginx.conf file located inside conf folder.
Configuring NGINX for IBM RTC OpenSocial Gadget
The two major configuration which has to carried out for the OpenSocial Gadget to work under NGINX are
- HTTPS Configuration and
- Cross Origin Support
All the configuration changes are carried out in the nginx.conf file located under conf folder. We can use text editors like notepad, notepad++, sublime, etc… to make changes to the nginx.conf file.
HTTPS Configuration
- Open the nginx.conf file and search for the text “# HTTPS Server”, # is treated as comment in nginx conf file.
- Uncomment the server { listen 443 ssl;} region below the line # HTTPS Server.
- HTTPS configuration does not work without an SSL certificate. Either you can use the SSL certificate attached at <<Link>> or generate your own SSL certificate.
- You can follow the link https://www.digitalocean.com/community/tutorials/openssl-essentials-working-with-ssl-certificates-private-keys-and-csrs to generate your own SSL certificate.
- Once you have the valid SSL Certificate and Key, place it in your preferred location and provide its path to the “ssl_certificate” and “ssl_certificate_key” under the server {} region.
Cross Origin Support
Why we need cross origin support? Creating all the required form data under one page will cause the page appearance to look bad and it is hard for the developers to manage the code. In order to avoid this, we often tend to create multiple views/page and render it under single page based on the requirement. To achieve this we will be sending Ajax requests from JavaScript code to fetch the resource or page from our NGINX Server.
When widget is hosted as OpenSocial Gadget in IBM RTC, the widget will be executed under the scope of IBM RTC, in other words OpenSocial gadget code will be treated as its own server code by IBM RTC. Since our code will be running under the scope of IBM RTC, any request to fetch a resource from our NGINX server will be treated as cross-origin request.
Our NGINX Server should be enabled to support cross-origin requests and below is the steps to achieve it.
Search for the location / {} region under the HTTPS Server region and add the below two lines
add_header 'Access-Control-Allow-Origin' '*';
add_header 'Access-Control-Allow-Methods' 'GET, POST, OPTIONS';
The final nginx.conf file will look like the image shown below. Now we are all set for the Development and Hosting of OpenSocial Gadget. Restart the NGINX Server for the changes to reflect. You can use the command nginx.exe –s reload to restart the server.
To verify the cross-origin support, navigate to the page https://localhost and check for the response headers which was added is getting displayed.
Part 2 - OpenSocial Gadget Development
Almost all the operations which works on REST API calls in IBM RTC like creating work items, duplicating work items, retrieving project areas and so can be developed as an OpenSocial gadget.
It is good to go ahead with Angular JS for gadget development which provides clear separation of code as MVC (Model View Controller). The above configuration is fully compatible with Angular JS 1. If you wish to go with Angular JS 2/4, the NGINX configuration has to be modified accordingly.
The OpenSocial Gadget can also be developed using plain JavaScript and jQuery. One such sample code for example is provided in GitHub. The project repository can be cloned using the URL https://github.com/kaarthikin/opensocial-ibm-rtc-project-areas
We provide a self hosted service to directly run our OpenSocial Gadget to get all available project areas in your IBM RTC Server. You can add the link https://opensocial.craftedforeveryone.com/AllProjectAreas/widget.xml as external widget in IBM RTC to run the gadget. The details on how to add an OpenSocial gadget is available at Jazz.net
You can refer to the Gadget API documentation to get basic understanding on writing a simple Hello World! Gadget API, and later which can be added as External Widget in IBM RTC.
