This is the third in a series of articles about the use of IBM® Rational Team Concert™ for System z® at the enterprise level. It explains the integration between Rational Team Concert for System z and external host-based software configuration management (SCM) products.
Rational Team Concert for System z provides the collaboration and governance support not provided by existing host-based SCM solutions. Being able to use these features while still using the existing host-based SCM brings immediate value to your organization, without having to change the existing development tools and build processes. In Part 1, we provided an overview to the features of Rational Team Concert for System z (see "View more content in this series"). With this article, we dive into new functions provided with Version 2 for simplified integration.
The System z Jazz Gateway, which is new with Version 2, makes it possible to access information about Jazz work items from an existing client that is running a mainframe, regardless of the system the Jazz server is running on. This article provides the details behind how the System z Jazz Gateway works with existing mainframe software configuration management systems, such as the IBM® Software Configuration and Library Manager (SCLM), to control the editing and promotion of development artifacts.
Extracting Jazz information from z/OS
The System z Jazz Gateway that is included with Rational Team Concert for System z provides a set of services to query your Jazz server from the host, where your existing system is running. You can visualize the System z Jazz Gateway as a server companion that is waiting for mainframe tool requests regarding work item attributes stored in your Jazz server. The purpose of this gateway is to leverage existing tools: a host software configuration management system, such as IBM SCLM, CA Endevor, Serena ChangeMan, or any other z/OS tool that you use for your software development.
Figure 1 gives an overview of the System z Jazz Gateway and shows the workflow, which comprises six steps to retrieve information from the server.
Figure 1. Overview of the gateway
These are the six steps for using the System z Jazz Gateway:
- Test the REXX or SCLM user exit setup parameters to pass to the REXX gateway client.
- The REXX client passes specified parameters to the gateway server and waits for a response.
- The IBM System z Jazz Gateway performs authentication, sets up REST URI, and sends a request to the Jazz server.
- The Rational Team Concert for System z server returns the work item XML code for the requested REST URI.
- The System z Jazz Gateway extracts the status and returns the complete XML back to the REXX client.
- The REXX client returns the status or the XML to the calling program.
The gateway can accept many connections from clients. It always answers, regardless of the status of the Rational Team Concert for System z server, so that these clients can adopt a strategy based on the answer.
Because most development processes in Rational Team Concert for System z are handled through work items, one common use scenario for the gateway is to enable or disable activities of your mainframe tool according to the value of a work item attribute. This scenario can help you align all of your multiplatform development, whether it is completely managed by Rational Team Concert for System z or still partially managed by your existing development tools that run on the mainframe.
Figure 2 shows an example of a work item status that can be returned to a terminal and used by your z/OS infrastructure.
Figure 2. Example of a work item status extraction on z/OS
Prepare the System z Jazz Gateway infrastructure
The rest of this article walks you through two sample scenarios that illustrate how to integrate Rational Team Concert for System z with SCLM by using the System z Jazz Gateway. These scenarios use two System z Jazz Gateway API services that help retrieve information about Jazz work items from a z/OS system:
- Get the full XML content of a work item, from which you can get the value of a specific attribute that you are interested in.
- Get the status of a work item directly.
Prepare your environment
To follow along with the examples in this article, ensure that you have completed all of these steps first:
- Install the Rational Team Concert for System z Server.
- Install the System z Jazz Gateway on your mainframe.
- Configure and test the System z Jazz Gateway.
- Ensure that you have followed all of the steps required to set up and use SCLM with the System z Jazz Gateway server.
For more information about these installation and configuration steps, see the Rational Team Concert for System z documentation.
Install the sample code
After you have prepared your environment, get the two REXX scripts,
BLZSCLM2, from the Download section of this article. To install them on your z/OS machine, follow these steps:
- Create a subdirectory (folder) on your workstation, and unzip the contents of the zipped file that you downloaded into that folder. The extracted files are all in text format.
- Use your mainframe file transfer protocol to upload the text files. You must use the following attributes:
FB, LRECL=80, BLKSIZE=3120.
- Copy the
GETSUMMfile into a library that is in the
SYSEXEC DDallocations. The
GETSUMMfile is an ISPF edit macro and, as such, must be part of the
SYSEXEC DDallocation for it to function as an edit macro. You can rename it to any name that conforms to your site standards. Be sure to use the new name when you call the macro.
- Copy the
BLZSCLM2file to a library that is referenced by your SCLM project definition or that the SCLM user exits that are invoked by the project definition exit points. This file is a replacement for the
BLZSCLM1file that was included with Rational Team Concert for System z, Version 18.104.22.168.
- Follow the instructions for
BLZSCLM1in the chapter about Setting up the System z Jazz Gateway to control SCLM workflow in the Rational Team Concert for System z documentation.
Customize SCLM automated process
An easy way to extend the behavior of SCLM is by using the user exit points provided by the tool to add your own process to the standard ones provided. SCLM user exit points can use the information returned by the System z Jazz Gateway Server. For more information on user exits, see the SCLM Library. Select the ISPF SCLM Guide and Reference that corresponds to your version of z/OS, and look for the user exits chapter.
Scenario 1. Automatic code annotation
In any complex development environment, it is important not only to keep track of changes made to code, but also to explain why the changes are made. This scenario shows how to automatically add comments to source code by using information from a Rational Team Concert work item. It uses the ISPF edit macro functionality to add the number and description of a work item at edit time and to generate a hyperlink to the work item inside the source code.
If you are new to ISPF edit macros, read the documentation cited in the Resources section at the end of this article.
Figure 3 provides an example of an automated comment added in the source code by using the macro. The first line of the comment indicates the date of the update (17/09/09) and the associated work item number (
Work item 18). The second and third lines show the complete summary of the work item.
Figure 3. An automated comment in the source code
Create an ISPF edit macro to add code change comments
The first thing to do is to create an edit macro by using the sample code provided and described below. Edit macros must be created as a member in a library that is allocated to either the
SYSEXEC DD in the ISPF allocations. You can call the member whatever you like. In this example, the member is called
The edit macro sample is split into several procedures, which are illustrated in code listings 1 through 4 and described in detail in the following sections. The REXX macro main script is shown in Listing 1. The
ISREDIT MACRO command indicates to ISPF that this is an edit macro and enables the ISPF edit macro. Next, the script obtains the work item number that the comment is to be created for. If the macro is called from within an edit session in SCLM, then the work item number is retrieved from the ISPF variable where SCLM stores the change code number entered on the SCLM edit panel. To use this macro outside of an SCLM context, a work item number can be passed to the macro as a parameter.
The macro then calls the
getSummary procedure to retrieve the work item information from the Jazz repository, and, if no error is returned, then calls the
insertComment procedures. The next sections of this article describe each of these procedures in a more detail.
Listing 1. Get work item summary macro
/* Rexx */ "ISREDIT MACRO (Workitem)" If Workitem = '' Then Do /* Assume this macro is being run from SCLM to get the */ /* SCLM entered change code that is being used. */ Address ISPEXEC "VGET (NCCDE) P?OFILE" Workitem = NCCDE End Call getSummary If WI_rc = 0 Then Call buildComment If WI_rc = 0 Then Call insertComment Exit
Invoke the System z Jazz Gateway through the getSummary procedure
getSummary procedure shown in Listing 2 calls the System z Jazz Gateway to query a work item and extract its summary from the XML returned by the System z Jazz Gateway.
Although this procedure contains a hard-coded, specific
password to provide a quick procedure to test, it can be modified to meet the security demands of a production system. You can, for example, use an encrypted file that contains your password. For more information about the security aspects of the gateway, read the chapter about Creating an encrypted password file for the System z Jazz Gateway in the Rational Team Concert for System z documentation.
One of the services provided by the gateway is to return the full content of a work item in XML format. This information is presented as
title in the returned XML.
getSummary procedure performs the following steps to add the work item information to the source code:
- Definition of the local variables
- The first three lines of the procedure define local variables for credentials to be used by the Gateway to access the Jazz server.
- Construction of the query parameter string
parm = Server' 'Userid' 'Password' 'Workitem
- This line creates the query parameter string that will be passed to the gateway to retrieve the work item content. It does not set a state in the query parameter in order to get the full content of the work item returned by the gateway.
- Allocation of the XML returned by the gateway
Address TSO "ALLOC F(XMLRESP) UNIT(VIO) NEW " ||, "RECFM(V B) LRECL(32657) SP(1 5) TR"
- To be able to parse the XML that is returned by the gateway, the procedure uses a TSO command to allocate a transient file, named
XMLRESP, that will be filled with the work item content.
- Invoke the System z Jazz Gateway
Address ISPEXEC "SELECT CMD(EX 'BLZ.SBLZSAMP(BLZGWCLI)' '"parm"') NEST"
- This line defines the gateway invocation that will query the work item according to the parameter string
parm. The command executed launches the gateway client JCL, called
- Parse the XML returned to get the work item summary
Address TSO "execio * diskr XMLRESP (stem xmlin. finis" parse var xmlin.1 . '<dc:title>' title '</dc:title>'
- Next, the procedure reads the XML returned by the Gateway in the
XMLRESPfile. It parses the file content for the summary associated with the
- Free XML file
Address TSO 'FREE F(XMLRESP)'
- Now that the work item summary is ready to be added to the source comment, the procedure frees the
- The procedure writes a completion message to the terminal.
Listing 2. Get work item summary
getSummary: Server = "<your_server_address>"" /* RTCz server */ Userid = "your_userid" Password = "your_password" parm = Server' 'Userid' 'Password' 'Workitem /* Allocate new XML output file to VIO */ Address TSO "ALLOC F(XMLRESP) UNIT(VIO) NEW " ||, "RECFM(V B) LRECL(32657) SP(1 5) TR" /* Invoke System z Jazz Gateway client to query workitem */ Address ISPEXEC "SELECT CMD(EX 'BLZ.SBLZSAMP(BLZGWCLI)' '"parm"') NEST" WI_rc = rc Address TSO "execio * diskr XMLRESP (stem xmlin. finis" parse var xmlin.1 . '<dc:title>' title '</dc:title>' . /* Free XML output file */ Address TSO 'FREE F(XMLRESP)' /* Write completion message to terminal */ If WI_rc <> 0 Then Say 'Problem with Work item retrieval' Return
Build the comment to be inserted using the buildComment procedure
Listing 3 shows how the comment is formatted for insertion into the code. This procedure varies according to the software language that you are using and the way that you want to present your comment. This example formats two different lines for the header and the summary. The header of the comment, which is printed in the first element of a REXX stem variable
cmline.1, is straightforward: a simple concatenation of the current date of the update followed by the work item number. The work item summary is split and stored into the subsequent elements of the REXX stem variable, named
Listing 3. Build comment
buildComment: /* This procedure takes the summary line and splits it into */ /* COBOL comment lines that fit the complete comment. */ cmline.1 = ' *** 'Date('E')' Workitem ' ||, Left(Workitem,40,' ')'***' Do i = 2 by 1 while (length(strip(title,T)) > 49) n = Words(Substr(title,1,49)) p = Wordindex(Substr(title,1,49),n) comment = Substr(title,1,p-1) cmline.i = ' *** 'Left(comment,49,' ')'*** ' title = Substr(title,p) End cmline.i = ' *** 'Left(title,49,' ')'*** ' Return
Insert the comment into the COBOL program by using the insertComment procedure
The final procedure inserts all of the lines stored in the REXX stem variable into the source code where the comment block is placed. The procedure uses the standard ISPF edit macro commands to achieve this, as shown in Listing 4. This example assumes that there is a comment block in the COBOL program that begins with the literal
"*** Change activities:".
Listing 4. Insert comment
insertComment: /* This procedure looks for the existing comment block and */ /* inserts the work item comment after the last comment. */ Address ISPEXEC "ISREDIT FIND '*** Change activities:' First" "ISREDIT FIND '*** ' Next" "ISREDIT (LINE,COL) = CURSOR" Do j = 1 to i NEWDATA = cmline.j "ISREDIT LINE_BEFORE "LINE" = (NEWDATA)"? "ISREDIT (LINE,COL) = CURSOR" End "ISREDIT RESET" Return
Try this yourself to experience this newly created link between the that code you maintain on z/OS and your collaboration platform, from which you can now guide all of your development.
Scenario 2. Promote approved code
Enforcing approval of work items
The second scenario shows how to use Rational Team Concert for System z to drive your mainframe SCM workflow and automate the promotion of your code to production level when a specific work item has received all of the approvals that it needs to be closed.
Although this example uses the Bugzilla workflow provided with some Rational Team Concert for System z project templates, it can easily be adapted to your own workflow, because it does not rely on any aspect that is specific to this workflow.
Rational Team Concert lets you easily request approvals, reviews, or verifications by using work items and the underlying process engine. To make these requests, you open the work item editor on the Approvals page and define the type of approval that you need, the users whose approval you want, and a due date. After you have defined an approval for the work item for your code promotions, your work item Approvals page should look similar to the one shown in Figure 4.
Figure 4. Work item approvals page
You can also configure approvals for the exact type and number of approvers you want and for controlling the workflow of a work item according to whether the approval has been accepted or rejected. The example in this scenario uses the latter configuration: controlling the process workflow to ensure that none of the new or updated code is put into production unless it is approved by a specific user, the product owner.
To force all work items to be closed automatically when approved, you need to configure approval trackings. Open the project editor Configuration view and navigate to Project Configuration > Configuration Data > Work Items (Advanced) > Approval Trackings, as illustrated in Figure 5.
Figure 5. Work item approval trackings
In this example, there are currently no workflow actions set for the Approval and Review approval types. With the current settings, no automatic action is triggered by the Jazz process when a work item has been completely approved or reviewed. You can change these settings so that a work item is automatically closed when it is approved. SCLM, in turn, can check the state of the work item to allow or disallow the code promotion. To select this new behavior, change the value of the Approved status to force the Close action to be triggered. After changing the workflow action, the Approval Tracking settings should be similar those shown in Figure 6. Notice that no other workflow behavior is changed other than the one needed for this scenario.
Figure 6. Work item closed when approved
Driving the source code promotion
After the Jazz process has been configured, you can change the way that the SCM follows the newly defined workflow when you try to promote code. Before changing any code used by Rational Team Concert for System z and SCLM on the mainframe, be sure to consider what can be returned to the REXX client by the System z Jazz Gateway.
The Bugzilla workflow, which is used in this scenario, makes the states presented in Listing 5, available for the Task and Defect work items managed in the project. This scenario uses the work item status to enable or disable code promotion.
Listing 5. Work item status
WIState.0 = 'XML Returned' WIState.1 = 'New' WIState.2 = 'In Progress' WIState.3 = 'Resolved' WIState.4 = 'Verified' WIState.5 = 'Closed' WIState.6 = 'Reopened' WIState.7 = 'Triaged' WIState.8 = 'Unknown'
Along with the work item status goes the resolution. Listing 6 shows the resolutions that can be expected for a work item in a Bugzilla workflow. The resolution attribute can be used to indicate if there is any code to be promoted or not.
Listing 6. Work item resolution
WIResolution.1 = "Fixed" WIResolution.2 = "Duplicate" WIResolution.3 = "Won't Fix" WIResolution.4 = "Works for me" WIResolution.5 = "Invalid" WIResolution.7 = "Later" WIResolution.8 = "Fixed Upstream"
Listing 7 shows how to check whether code can be promoted from Development to Test status. The rule applied here to allow promotion is to admit code to the next level only if the work item status is Resolved. In no other case is code allowed to be promoted to the Test level.
Listing 7. The Promote to Test script
When (WIState_rc < 3) | (WIState_rc > 5) Then Do Say 'Workitem number 'Strip(CCODE)' is in ' ||, WILiteral.WIState_rc 'status.' Say 'This is not a valid status for promotion.' Exit 8 End
Because the workflow process was configured in Rational Team Concert for System z to automatically change the work item status to Closed as soon as the work item change was reported as Approved or Reviewed, the work item status can be used to determine if the code can be promoted from Test to Production. To avoid updating the Production line for no good reason, and just replace the code with the same one instead, you can also check whether anything was actually fixed. Listing 8 illustrates how to check the Resolution attribute to see if something has been fixed or not.
Listing 8. Promote to Production script
When (WIState_rc = 5) Then Do If WIResolution_rc <> 1 Then Do Say 'The workitem resolution must be "Fixed" ' ||, 'to promote. The resolution is currently ' ||, WIResolution.WIResolutiom_rc Say 'This is not a valid resolution for promotion.' Exit 8 End End
Both code promotions on the mainframe SCM (from Development to Test and from Test to Promotion) are now allowed, according to the content of a work item following the process defined in the Rational Team Concert for System z project. Now you have reached the point at which you can test your code promotion, based on the samples installed. Figure 7 displays the result from SCLM when the code promotion is allowed and executed. Figure 8 displays the result when the work item does not meet the requirement for promotion.
Figure 7. Example of a code promotion on z/OS
Figure 8. Example of a code promotion stopped on z/OS
This part of the "Using IBM Rational Team Concert for System z and the Jazz platform" series provides the base knowledge to help you start integrating your host SCMs with Rational Team Concert for System z, thus solving some coexistence and migration challenges. By using two different scenarios, this article shows you not only how to get started with team collaboration across the various development organizations and platforms, from distributed to z/OS, but also some of the benefits of doing so.
The subsequent articles in this series will cover details of the new System z Scrum template, how to configure the components and streams within Rational Team Concert for System z, and integration with Rational Developer for System z and integrating Rational Team Concert for System z with your IBM® Rational® Build Forge® environment. Each article focusing on a different aspect of new functions provided with Rational Team Concert for System z V2.
|REXX scripts for this article||RTCzArticleSamples.zip||4KB|
- IBM Rational Team Concert for System z
- Resource-Oriented Work Item API 2.0
- IBM REXX Family documentation
- z/OS V1R7.0 ISPF Edit and Edit Macros
Get products and technologies
- Download IBM Rational Team Concert for System z.
Dig deeper into Open source on developerWorks
Get samples, articles, product docs, and community resources to help build, deploy, and manage your cloud apps.
Experiment with new directions in software development.
Software development in the cloud. Register today to create a project.
Evaluate IBM software and solutions, and transform challenges into opportunities.