Work Item customization: HTTPConector and OAuth in RTC 4.0 for OSLC

Starting as of Rational Team Concert 3.0.1.1 a new feature was introduced called “Data Source Value Set Providers”, this cool feature allowed us to expose in our RTC work item attributes information gathered from external sources by the means of calling an external service and parsing the XML response. The details of how this feature works can be found here.

Taking borrowed the image from the Jazz wiki, the basic mechanism is as follows:

Along with that extensible feature, the product offered an implementation of a HTTP Value Set provider, that allows fetching data from a HTTP call (REST service call). The feature was available in the attribute customization wizard (in the project area Process Configuration navigating to Configuration Data > Work Items > Attribute Customization):

Once defined your new HTTP Value Set, a menu is presented offering you the parameters to configure the URL of the service to be called, the XML response parsing details and authentication information mainly:

Note you also had the option create a script implementing the call and parsing of the service response. As these configurations are extensively covered in the jazz.net wiki article, I will rather focus on what were some interesting questions I got working with customers with the features available at that time (3.0.1.1), and what benefits the new OAuth option can offer:

  1. Can “Remote Server” be my RTC Server? I want to expose work items attributes values as a list of values in another work items from a OSLC call.
  2. How can I access protected services in RTC and my systems?

To try to query RTC information using OSLC services using this provider is not really a big challenge once you understand the basics of this services and you get used to the vocabularies involved. For example, a dummy configuration that would allow me to expose the id of the work items in my system to pick up on of them as an attribute value would use the following parameters:

 url: https://<yourServer>/ccm/oslc/contexts/<projectAreaUUID>/workitems
 xpath: //Collection/ChangeRequest
 columnXpaths: ./identifier
 columnIds: id

This parametrization works with the features available in 3.0.1.1, but you have to also take into account that the services are protected, thus we need to provide information to allow the service call to authenticate against the Jazz Team Server. A little understanding of how the Jazz Team Server performs the authentication will be useful. For the needed configuration you can find an example in the referred wiki article (look for “Example accessing jazz.net”), but briefly, for 3.0.1.1 you would need to fill the following parameters:

 Authentication method: Form Based Authentication
 URL for authentication: https://<yourServer>/ccm/authenticated/j_security_check
 User name parameter name: j_username
 Password parameter name: j_password
 Credential identifier: rtcserver

We are almost there but now, what are “j_username” and “j_password” values? This discussion leads to an interesting point related with the second question: the authentication mechanisms available to querying services at that time were not all the fancy that we would like to. The protected services (in our example of Jazz, but generally speaking can be any service you want to interact with using this mechanism), will be accessed using credentials manually configured, whether written in our connector configuration parameters, the configuration side for a custom script or in the server’s Advanced Properties using the Authentication Service.

In addition to the administration concerns to configure security in such a way, the service queried will always use this “hardcoded” credentials, which in many cases is not the desired due to security policies or for information retrieval, for example if you want the value returned from OSLC to be scoped to your actual logged-in user credentials.

Now we have introduced the basic configuration for these use cases, it is time to present the new feature we can use as of Rational Team Concert 4.0. One of the main improvements that the new version offers is the ability to use OAuth as the authentication method for the HTTP Value Set:

This improvement has a great impact on these use cases: the service call will be challenged using the OAuth credentials of the logged-in user to try to access the data, therefore we will achieve this benefits:

Credentials management: the credentials will be automatically managed. No more need of manually setting the user and password (whether in the Attribute Customization area or in the server Advanced Properties).

Information scope: as we are querying with the logged-in user credentials, any returned information will be based on the visibility of the user, not of the hardcoded credentials anymore.

That way, we have a clean option to query our own RTC services and expose values in work items attributes.

OK, is that all? Well, this mechanism could be used for your in-house applications  working on some modifications to allow their services to participate in this OAuth challenge process. A real good topic to review is covered in this wiki page: Becoming an OAuth Consumer, but I fear that will be another (kind of big) topic.

I wanted to update this post I wrote some time ago and add a little script that will retrieve the same information as I described before in this same post: retrieve the ID of work items from an OSLC query.  The following script will retrieve this information by means of a Scripted Value Set Provider using OAuth.

dojo.provide("net.jazz.example.scripted.oslc.wiids.ValueSetProvider"); 

dojo.require("com.ibm.team.workitem.api.common.connectors.HttpConnectorParameters"); 

(function() { 
    dojo.declare("net.jazz.example.scripted.oslc.wiids.ValueSetProvider", null, { 

        getValueSet: function(attributeId, workItem, context){ 

        var params= new com.ibm.team.workitem.api.common.connectors.HttpConnectorParameters(); 
        params.url="<Server>/ccm/oslc/contexts/<PAreaUUID>/workitems"; 
        params.xpath= "//Collection/ChangeRequest"; 
        params.columnXpaths= ["./identifier"]; 
        params.columnIds= ["wid"]; 
        params.ignoreInvalidCertificates=true; 
        params.useOAuth=true; 

        var connector= context.getDataConnector("HttpConnector"); 
        var values= connector.get(params); 
        var result= []; 

        while(values.hasNext()){ 
            var entry= values.next(); 
            var wiIDs= entry.getById("wid"); 
            result.push(wiIDs); 
        } 

        return result; 
    } 
   }); 
})();

Note that in the previous script, you have to modify the URL parameter to use your server and project area UUID. This sample script can serve as basis if you need to perform some computation for the actual list of values the user will be presented with.

Our lawyers reminded me to state that the code samples in this blog are governed by this license, which basically means you can use it for internal usage, but not sell. Remember that this code comes with the usual lack of promise or guarantee. Enjoy!

Advertisements

7 thoughts on “Work Item customization: HTTPConector and OAuth in RTC 4.0 for OSLC

  1. This is a nice article. Thank you.

    But I have one case that I can’t handle:
    We have an RRC project where we want to retrieve artifact values in RTC wokritem attributes. So we are using RRC REST Api. Everything is ok. We retrieve the desired values.

    If I use Oath authentication, users who are able to see that specific RRC project area will only retrieve values from that project. In case they are not added to this project area, they will have nothing in the attribute 🙂 But that’s not a case because it’s a “library” project for whole company. But there are some confidential infomation that no everybody should access 🙂

    So we wanted to have an admin user where we will use Form Based Authentication so this particular user will fetch data from RRC and fill RTC’s attribute.

    But we couldnt understand what parameters to pass Form Based Authentication. URL and Credential Identifier for RRC.

    I assume I need “https://rrcserver:9443/jts/authenticated/j_security_check for URl but what shoudl I use for credential Identifier

    • Hi Canberk,

      glad to see you find it useful. Regarding your question, yes, that has to be the credentials url as the value for “URL for authentication” parameter (assuming your Jazz Team Server is placed at “rrcserver:9443”)
      For the Credential Identifier parameter, you have to create one in your RTC server. You can follow these steps:

      1. Go to https://server/ccm/admin#action=com.ibm.team.repository.admin.configureAdvanced

      2. Look for the the property called “Login Credentials for Data Connectors”

      3. Create an entry following the format “credentialsID|||username|||password”

      That “credentialsID” you define in Advanced Properties is what you will use in the connector parameters

  2. Let’s assume I will use “https://canberk-pc:9443/rm/publish/resources?typeName=Document&projectURI=_xL4U0JnZEeGuQJ5gMK2nZw” as REST service in order to extract the Document type artifacts list on workitem attribute.

    Then shouldn’t I enter that “credentialsID|||username|||password” to RRC’s Advanced properties? There’s no such record for RRC. I found it in ccm and added the same parametes.

    I should also write: https://canberk-pc:9443/jts/authenticated/j_security_check for “URL for Authentication” in HTTP Filtered Value to authenticate RRC. am I right?

    • Hi CanBerk,

      the Credentials ID as you point out is in CCM Advanced Properties. Take into account that the HTTP Value Set provider you are to use is a RTC feature, so you are providing the credentials information that you want to use in that feature, whether is going to interact with RRC (as your case) or other application.
      Regarding the “URL for Authentication”, yes you are right. The Jazz Team Server is the one that manages the auth in your CLM deployment, and that is the URL in which the auth form is presented.

  3. I have placed my xml file under tomcat ROOT dir “apache-tomcat-7.0.65\webapps\ROOT\example_data”. I can access the xml file thru browser with the URL http://localhost:8888/example_data/makers.xml. But while creating value set it could not retrieve the xml and throws error as – Problems accessing ‘http://localhost:8888/example_data/makers.xml’: Connection to http://localhost:8888 refused

    Could you please let me know what can be the issue here ?

    Thanks
    Akshay P

      • Hi Jorge,

        I tried to map localhost to domain name but I could not do that because I don’t have access to amend Windows host file. Any other alternative you may have ??

        Thank you
        Akshay Panchakshari

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s