This document is posted to help you gain knowledge. Please leave a comment to let me know what you think about it! Share it to your friends and learn new things together.
Transcript
Get to know Open Services for LifecycleCollaboration Change ManagementHow to use OSLC delegated Web dialogs
This article highlights some of the key features of the new OSLC ChangeManagement 1.0 specification (OSLC-CM), which is part of the OSLC group ofspecifications. The authors use a simple HTML + Javascript interface to illustrate howyou can take advantage of these features quickly and easily.
Introduction
A growing community focused on Application Lifecycle Management (ALM)interoperability is forming at Open-Services.net. This initiative, referred to as theOpen Services for Lifecycle Collaboration (OSLC), brings together communitymembers to define interoperability specifications that are based on key scenarios.The initial working group focused on change management integration scenarios.These specifications provide the guidance needed for service providers (the ALMtools that receive the requests) to be invoked by a variety of consumers (the ALMtools that generate the requests).
IBM® Rational® software provides many service provider implementations inproducts such as IBM® Rational® Team Concert™, IBM® Rational® ClearQuest®,
IBM® Rational® Change, and IBM® Rational® Change Management Express. Also,there are quite a few IBM products that use these services, such as IBM® Rational®Quality Manager, IBM® Rational® Requirements Composer, and IBM® Rational®Asset Manager.
What this article covers
In this article, we use a sample application that is available in the Download sectionto illustrate how you can leverage several aspects of the OSLC ChangeManagement (OSLC-CM) Version 1.0 specification:
• Service discovery
• Delegated resource creation
• Delegated resource selection
• Presentation of resources – HTML
We cover many key areas of the specifications here, although there is much more toexplore. In particular, the variety authentication models and technology choices forleveraging these services deserve your attention.
This article does not cover these specification items:
• Query
• Resource (defect, bug) property retrieval
• Resource creation and modification
Nonetheless, this article gives you with a good starting point for taking advantage ofthese services quickly, with minimal effort.
Sample application setup
This article features a sample OSLC Change Management consumer that is writtenentirely in Javascript, using the Dojo Javascript Toolkit. The sample helps readersconnect to an OSLC Change Management provider and create or find changerequests.
Server proxies in Jazz-based softwareThe same-origin policy in browsers can pose problems whenbuilding real-world integrations between Web applications. Theserestrictions protect users from a host of cross-site scripting exploits,but Web applications from different domains often legitimately needto communicate. The OSLC-CM specifications offer a solution for
delegated Web UIs, which is discussed in the IFrameCommunication section here. Web developers who need to performservice discovery tasks still need to wrestle with this problem,however.
IBM® Jazz™ technology-based products, such as Rational TeamConcert and Rational Quality Manager, solve this problem by usingserver proxies. Requests flow through the origin server but areforwarded to the CM-provider server. See "Interacting with RemoteData" on Jazz.net for more details (see Resources).
In this sample, the Javascript client connects directly with the OSLC-CM provider.Browsers typically restrict Javascript HTTP requests to the source domain of thedocument. This is known as the same-origin policy (see sidebar). Therefore, to runthe sample, you must work around this issue in one of two ways:
1. Extract the files to your local file system, and open the oslc.html file in abrowser that permits local HTML files to access the Internet throughXMLHttpRequest. (Of the major browsers, only the Apple Safari Version4.0 browser allows this.)
2. Deploy the files to the same Web server as the CM provider. Consult yourCM provider's application server documentation for appropriate location.
• On an IBM® WebSphere® Application server, place the files in thehtdocs directory.
• On an Apache Tomcat server, place the files in the webappsdirectory
After you have loaded the sample page into your browser, simply enter the baseREST URI into the Service URL text field, and click Go!
For Rational Team Concert, this is typically the path to enter (where <bracketInfo> isa variable for your location):
To access protected data in a change management system such as Rational TeamConcert, you typically must furnish a user name and password. OSLC takes a "justenough" approach to integrations, by reusing existing standards where it makessense. Authentication is no exception, and the OSLC-CM 1.0 REST APIspecification states that providers should support Basic HTTP Authentication andOAuth (see Change Management REST API: Security and Authentication).
Therefore, for simplicity, we've assumed here that the change management provideris configured for Basic HTTP Authentication. This lets the browser take care of anylogin prompts for you, making it transparent in the Javascript sample client (seeFigure 1).
Figure 1. A basic HTTP authentication dialog
IBM Rational Team Concert, Rational ClearQuest, and Rational Change can all beconfigured for Basic HTTP Authentication of their OSLC services. For the examplesin this article, we use Rational Team Concert Version 2.0 configured for Basic HTTPAuthentication.
Note:It is also possible to enable this sample to work with other authenticationapproaches. For example, you can simply log into the CM provider's Web userinterface first so that the browser will establish the necessary authenticationprerequisites, and then subsequent requests will be successful.
The OSLC-CM 1.0 service discovery model offers the flexibility that you need forvarious change management providers by using a nesting structure for serviceprovider catalogs. From these catalogs, you can locate further information regardingadditional catalogs or documents that describe the completed configuration, whichare known as service description documents. Figure 2 shows an example fromRational Team Concert that provides a single service provider catalog that hasentries for each of its projects, which in turn reference a service descriptiondocument for each project hosted by that server.
Figure 2. Sample of service discovery using Rational Team Concert
The service provider catalog is an optional part of the service discovery process.The catalog provides references to additional catalogs or entries for servicedescription documents. The service description document provides the discoveryend point.
The sample included in the Download section here starts with a URL for either aservice provider catalog or a service description document, as shown in Figure 3.
If you are new to Dojo and Javascript, this may not be obvious. The code in Listing 1is simply performing an HTTP GET operation on the URL provided, requesting theacceptable content types of either a PROVIDER_CATALOG orSERVICE_DESCRIPTION.
The response has been altered a bit for this article, but it illustrates the key elementsof the catalog. There are two <oslc_disc:entry> elements, and each has a<oslc_disc:ServiceProvider> element. Knowing that these are references toservice provider's service description documents, we know that we are close. Itwould also be possible to have more catalogs as entries, which the attached samplecode does handle. From the catalog, we see that is has a title of Project Areas,which can be used as a label for a selection list. Likewise, each service providerentry has a <dc:title> element, which can be used as an entry to the selectionlist. Figure 4 shows JUnit Project and Test Automation as options in the drop-downmenu for the Rational Team Concert Project Areas selection.
The Javascript used to parse and present the choices simply parses the catalog tolocate the needed elements, then instantiates the appropriate controls.
After a selection is made from the sample, the sample makes another request(Listing 4) in a similar way, although this time the expected response is a servicedescription document.
Listing 4. HTTP request for service description document
GET https://localhost:9443/jazz/oslc/contexts/1/workitems/services.xmlAccept: application/x-oslc-disc-service-provider-catalog+xml,
application/x-oslc-cm-service-description+xml
At this point, you can use the <oslc_disc:services> to determine the URL torequest the document. Listings 5 and 6 show the responses.
Listing 5. Response of service description document (contributor fragment)
Content-Type: application/x-oslc-cm-service-description+xml<?xml version="1.0" encoding="UTF-8"?><oslc_cm:ServiceDescriptorxmlns:dc="http://purl.org/dc/terms/"xmlns:oslc_cm="http://open-services.net/xmlns/cm/1.0/"xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"rdf:about="https://localhost:9443/jazz/oslc/contexts/1/workitems/services.xml"><dc:title>JUnit Project</dc:title><dc:description>IBM Rational Team Concert OSLC CM Service Description for Project'JUnit Project'</dc:description><dc:contributor>
<dc:title>IBM Rational Team Concert Work Items</dc:title><dc:identifier>com.ibm.team.workitem</dc:identifier><oslc_cm:icon>https://localhost:9443/jazz/web/RationalTeamConcert.ico</oslc_cm:icon>
</dc:contributor>…
The <dc:contributor> fragment in Listing 5 provides information about the
service provider tool and vendor for informational purposes. There is furtherconfiguration information in the <oslc_cm:changeRequests> section of thedocument that indicates URLs used later in this article for creating and selectingchange requests. See Listing 6.
Listing 6. Response of service description document (changeRequestfragment)
</oslc_cm:creationDialog><oslc_cm:creationDialog oslc_cm:hintWidth="740px" oslc_cm:hintHeight="510px"><dc:title>New Plan Item</dc:title><oslc_cm:url>https://localhost:9443/jazz/WICreation?project=1;dc%3Atype=story</oslc_cm:url>
</oslc_cm:selectionDialog><oslc_cm:factory oslc_cm:default="true"><dc:title>Default location for creation of change requests</dc:title><oslc_cm:url>https://localhost:9443/jazz/oslc/contexts/1/workitems</oslc_cm:url>
</oslc_cm:factory><oslc_cm:simpleQuery><dc:title>CQL based change request queries</dc:title><oslc_cm:url>https://localhost:9443/jazz/oslc/contexts/1/workitems</oslc_cm:url>
</oslc_cm:simpleQuery></oslc_cm:changeRequests>
</oslc_cm:ServiceDescriptor>
The key elements for this article are from this discovery document:
• <oslc_cm:creationDialog>
• <oslc_cm:selectionDialog>
These elements provide the information that you need to create an IFrame that canbe used to host these Web page fragments. The following sections will explain, indetail, how this information is used to present these dialogs, with code examples.
Figure 5 shows the sample application after service discovery has been completed.Service discovery is considered complete when a service description document hasbeen obtained.
OSLC Change Management providers offer more than just REST APIs for accessingdata programmatically. They also give you a way to embed change managementdialogs inside of your applications. These delegated Web UIs are a key aspect ofmany OSLC integrations.
This approach enables developers to build loosely coupled, seamless integrationsbetween ALM tools. You can display feature-rich dialogs from the changemanagement application with minimal knowledge about the application. Additionally,different change management providers can be swapped with virtually no codeimpact to the change management consumer.
You can use creation dialogs to submit new change requests. The changemanagement provider renders the content of these dialogs and, thus, controls bothlayout and validation. An OSLC Change Management consumer can then display afully functioning Submit dialog without duplicating all of the business logic behind thedialog.
Figure 6. Creating a new change request
Figure 7. Resulting link to the new change request
Imagine that Sue, a tester, is working in a quality management application, such asRational Quality Manager. She finds a bug in the product she tests and needs to filea defect. Ideally, she should be able to create the defect record directly from withinthe quality management application and then store a link in the test execution recordto the newly created defect report. By using OSLC delegated Web UIs, she can dothis and do all of her work within one application.
A provider's creation dialogs are listed as creationDialog elements in the servicedescription XML document, as highlighted in previous sections on service discovery.
Resource selection
What if Sue knows that there is already a defect record for a bug, which is blockingher testing? This time, she uses a delegated selection dialog to link her testexecution record to an existing defect. She can launch this dialog from the sampleby clicking the Find Change Request button, which launches the contributedRational Team Concert window.
Again, the change management provider controls the content of this dialog.Therefore, Sue can use any search and query capabilities of the changemanagement application to find the defect record that she is looking for. When shefinds the defect, she adds it as a link in her test execution record, never leaving thequality management tool.
A CM provider's selection dialogs are listed as selectionDialog elements in theservice description document.
IFrame communication
So how does all of this work?
OSLC delegated Web UIs are designed to work across domains, where the changemanagement provider is located on a server different from the host application. Forsecurity reasons, modern Web browsers prohibit HTTP requests to differentdomains. However, OSLC delegated Web UIs are embedded in HTML IFrameelements (see Figure 10). This means that they appear directly within a hostapplication even when the two applications are on entirely different servers indifferent domains. (See the diagram in Figure 10.)
Figure 10. An ALM tool embeds a change management dialog in an IFrame
Embedded dialogs send messages back to the host application in one of two ways:by using either the Post Message protocol or the Window Name protocol. The hostapplication determines which protocol to use, based on the browser's capabilities.Listing 7 shows Javascript code to test to see which mode to use and how to createan iFrame from using the results of this test.
Listing 7. Choosing an IFrame protocol
// Tests to see if this browser supports window.postMessageOslcCmConsumer.prototype.isPostMessageSupported = function () {
// Older versions of IE define a method window.postMessage() that does// something else, so we can't simply test for typeof (window.postMessage).if (dojo.isIE && dojo.isIE < 8) {
return false;}
return typeof window.postMessage == 'function';};
// Creates an IFrame to show a Delegated Web UI.OslcCmConsumer.prototype.createIFrame = function (url, container) {
// Determine which IFrame protocol to use.if (this.isPostMessageSupported()) {
this.postMessage(url, container);} else {
this.windowName(url, container);}
};
In Listing 7 there was a function referenced postMessage(), which is a localfunction defined in Listing 8. This function uses the Post Message protocol andworks in the latest versions of most browsers and is preferable. It uses thewindow.postMessage() function in HTML 5 to send events to the observing hostapplication.
// Display the IFrame.this.styleIFrame(iframe);container.appendChild(iframe);
};
To display a dialog by using the Post Message protocol, you must complete thesesteps:
1. Tell the OSLC-CM provider to use the Post Message protocol byappending this to the dialog URL:#oslc-postMessage-1.0
2. Add an event listener for window message events. The listener tests tosee whether the message content begins with the oslc-response:header, which indicates that this is an OSLC message.
3. Create an IFrame element, and set the IFrame src to the dialog URL.
4. When the window message event is received, remove the event listener,and handle the message that is returned.
The Window Name protocol is more involved, but it must be used in older browsersthat do not support window.postMessage(). As Listing 9 shows, it works aroundcross-site scripting restrictions by passing the OSLC results message as one of thecontent window properties of the IFrame, which the host application can read.
Listing 9. Window Name example
OslcCmConsumer.prototype.windowName = function (url, container) {// Step 1url += '#oslc-windowName-1.0';
var iframe = document.createElement('iframe');var frameState = 0;iframe.onload = dojo.hitch(this, function () {
var data;if (!frameState) {
// Step 5try {
// May throw an exception if the IFrame's location is// still a different origindata = iframe.contentWindow.name;if (data != this.returnLocation) {
frameState = 1; // we are done nowif (data) {
this.handleMessage(data);}
}} catch(e) {
// ignore: access exception when trying to access window name}
}});
// Step 3// Set iframe.name to a URL of a blank page on the observer's domain.iframe.name = this.returnLocation;// Step 4iframe.src = url;this.styleIFrame(iframe);container.appendChild(iframe);
};
To display a dialog by using the Window Name protocol, you must follow thesesteps:
1. Tell the OSLC-CM provider to use the Window Name protocol byappending this to the dialog URL:#oslc-windowName-1.0
2. Create an IFrame element and assign a listener for onload events.
3. Set the IFrame's Name property to a blank page on the host application'sdomain. (When the dialog has been closed, the OSLC-CM provider willset the IFrame src to this URL so that the observer can read propertiesof the IFrame.)
4. Set the IFrame src to the dialog URL.
5. In the onload event handler, read the IFrame's contentWindow.nameproperty, which now contains the OSLC response message. The client'sonload event handler is invoked when the CM provider sets the IFramesrc to the return URL.
Unfortunately, working with IFrames in Microsoft® Internet Explorer has a fewquirks. This example omits Internet Explorer workarounds for clarity. See theattached code sample for details (in the Download section).
The OSLC response message is a Javascript Object Notation (JSON) object thatcontains an oslc_cm:message property, indicating what operation was performed,and an oslc_cm:results property, an array of resources. Each resource is aJSON object with two properties: oslc_cm:label property, which defines a simpledisplay label, and the rdf:resource property, which is the URI of the resourcebeing referenced.
Listing 10. Handling an OSLC response message
var response = dojo.fromJson(message);var messageType = response['oslc_cm:message']; // "oslc_cm:create" or "oslc_cm:select"dojo.forEach(response['oslc_cm:results'], function (next) {
var label = next['oslc_cm:label'];var uri = next['rdf:resource'];// ...
});
A little bit about the final resource URL
After a change request has been created or selected from the previous examples,the result is a URL of a change request resource that can be used to retrieve,update or even delete that change request. Because this article focused onbrowser-based access to these services, it would be natural to expect an HTMLversion of the change request that can be used as a presentation form of the changerequest. As the OSLC-CM specification indicates, other formats can be requested,such as XML or JSON variants. This article highlights only the HTML format byallowing a clickable hyperlink within the sample page. See the Resources section foradditional information.
Summary
This article has taken you through a simple process that starts with a URL anddiscovers the services available by using the Rational Team Concert OSLC-CMprovider. A working sample is included (see Download) that you can use to get abetter understanding of OSLC-CM, to help validate your own provider, or to jumpstart your own consumer implementation. From the service descriptor, you could usedelegated Web user interfaces for creating and selecting change request resources.This discovery and delegation provides a quick and powerful method for achieving aloosely coupled integration. There are many other features in the OSLC-CMspecification, including resource manipulation, query capabilities, other creationmodels, and more.
• See Interact with Remote Data for more details (requires Jazz.net registration).
• Check the latest developments of OSLC by visiting the Open-Services.net Website.
• Learn more about the Rational software mentioned in this article:
• IBM Rational Asset Manager helps you catalog, organize, use, reuse,manage, and report on any type of asset – business, technology orsoftware – across your enterprise
• IBM Rational Change integrated, Web-based, enterprise changemanagement
• IBM Rational Change Management Express, which is included in RationalTeam Concert, with integrated work item tracking
• IBM Rational ClearQuest provides change tracking, process automation,reporting and traceability for better visibility and control
• IBM Rational Quality Manager offers a Web-based, centralized testmanagement environment that provides a collaborative and customizablesolution for test planning, workflow control, tracking, and metrics reporting
• IBM Rational Requirements Composer for collaborative requirementsdefinition and updates for fast-paced projects with high stakeholderinvolvement
• IBM Rational Team Concert provides work item, change management,and build management for real-time collaboration that makes softwareteams more productive and processes more transparent
• Learn about other applications in the IBM Rational Software Delivery Platform,including collaboration tools for parallel development and geographicallydispersed teams, plus specialized software for architecture management, assetmanagement, change and release management, integrated requirementsmanagement, process and portfolio management, and quality management.You can find product manuals, installation guides, and other documentation inthe IBM Rational Online Documentation Center.
• Visit the Rational software area on developerWorks for technical resources andbest practices for Rational Software Delivery Platform products.
• Explore Rational computer-based, Web-based, and instructor-led onlinecourses. Hone your skills and learn more about Rational tools with thesecourses, which range from introductory to advanced. The courses on this
catalog are available for purchase through computer-based training orWeb-based training. Some of the "Getting Started" courses are available free ofcharge.
• Subscribe to the IBM developerWorks newsletter, a weekly update on the bestof developerWorks tutorials, articles, downloads, community activities, webcastsand events.
Get products and technologies
• Download trial versions of other IBM Rational software.
• Download IBM product evaluation versions and get your hands on applicationdevelopment tools and middleware products from DB2®, Lotus®, Tivoli®, andWebSphere®.
Discuss
• Check out developerWorks blogs and get involved in the developerWorkscommunity.
About the authors
Steve SpeicherSteve Speicher, an IBM senior software engineer, focuses on Rational changemanagement solutions and integrations. He is the lead for the Open Services forLifecycle Collaboration (OSLC) Change Management topic area, which delivers openREST-based specifications, as well as implementations within the Rational changemanagement products. Steve formerly worked in emerging standardization efforts inhealthcare and compound documents (W3C).
Sam PadgettSam Padgett is an IBM advisory software engineer who works within the RationalTeam Concert and Rational ClearQuest development teams on Web-basedtechnologies, OSLC Change Management (OSLC-CM), and Application LifecycleManagement (ALM) product integrations.
Trademarks
Trademarked terms commonly used in developerWorks content are attributed on the