Automating Rational Software Architect Design Management imports from Rational Team Concert (Part 2): Rational Team Concert-driven integration
This article uses a scenario-based approach to explain how to extend your Rational Team Concert integration by automating an import process from Rational Software Architect Design Management at the end of a Rational Team Concert build cycle.
After publishing Automating RSA Design Manager Imports from Rational Team Concert article in 2011, customers commented that the solution was Design Management-driven. As a result of this focus, organizations had to schedule imports through a Rational Software Architect import definition and maintain separate Ant scripts that were called by a Rational Software Architect import engine to get content from the Rational Team Concert server.
Customers with existing scheduled Rational Team Concert builds and Ant scripts do not want the additional overhead of maintaining separate scheduling mechanisms and Ant scripts for a Rational Software Architect Design Management import. This article defines a solution to address these concerns.
Scenario
The following scenario uses the JKE Banking example that is also used in the Automating RSA Design Manager Imports from Rational Team Concert article. In this scenario, a company called JKE Bank has two Rational Software Architect modeling projects, JKE Banking and JKE Banking Profile, both under source control in a Rational Team Concert repository, as shown in the following diagram.
Preferred method for importing profiles
Before Rational Software Architect Design Management 4.0, it was only possible to import Rational Software Architect profiles into instance project areas.
With Design Management 4.0 and later, you should import Rational Software Architect profiles into the Domains project area as described in the Design Management help. In Design Management 4.0 and later, you can still import Rational Software Architect profiles into instance project areas as described in the JKE Banking example, however, it is no longer the preferred method.
In this example, the goal is to have both projects available in Design Management so that the model stakeholders can review the content online. Because the models are evolving, JKE Bank requires the latest committed versions to be placed into Design Management daily.
The following diagram describes the high-level Rational Team Concert-driven import ecosystem and processes.
The following steps describe the process for the Rational Team Concert-driven import:
- Software architects create and update model content using a stand-alone instance of Rational Software Architect. The software architects deliver changes to the Rational Team Concert server.
- The user named RTC builder requests a Rational Team Concert build on a regular basis (the build request can be started either manually or by schedule).
- The Rational Team Concert server passes the build request to the Rational Team Concert build system toolkit.
- The Rational Team Concert build system toolkit executes the Rational Team Concert build Ant script.
- The Rational Team Concert build Ant script issues a teamFetch request to the Rational Team Concert server to get the latest model content in the local workspace directory.
- The Rational Team Concert server exports the latest model content in the local workspace directory.
- The Rational Team Concert build Ant script issues a start import request to the Design Management Server.
- The Design Management Server requests an import of the latest model content to the server via the import engine.
- The import engine collects the latest model content from the local workspace directory.
- The import engine sends the latest model content to the Design Management Server. The Design Management Server receives the content, processes it, and places it on the server.
- The model reviewers view the latest model content online.
Note: In the Rational Team Concert-driven integration scenario, the Rational Team Concert build engine drives the Rational Team Concert build and Rational Software Architect import. In the Design Management-driven integration, the Rational Software Architect import engine drives the Rational Team Concert build and Rational Software Architect import.
Environment and setup
In a Rational Team Concert-driven integration, JKE Bank dedicates three physical machines to the import process. The following diagram describes the servers with the following configurations completed.
The following procedures describe the setup of each of the three machines:
Machine 1 (Design Management Server)
- The Design Management Server is started and running.
- A new Project Area called Banking Model Project has been created.
- A new workspace called Banking Model Workspace has been created. This is the workspace that the model content will be imported into.
- A user ID named dm_import has been created and has an Administrator process role in the Design Management project area named Banking Model Project.
Machine 2 (Rational Team Concert server)
- The Rational Team Concert Server is started and running.
- A project area named Banking Project, which contains a stream named Banking Stream, has been created. A component Banking Component has been defined for Banking Stream, with the two modeling projects added (JKE Banking and JKE Banking Profile) that were created in Rational Software Architect.
- A public repository workspace called dm_import Repository Workspace, which contains the component named Banking Component, has been created. The dm_import Repository Workspace is the workspace that is used for model content extraction.
- The Rational Team Concert user account named rtc_builder has been created with sufficient privileges to execute the Rational Team Concert build Ant script.
Machine 3 (Rational Team Concert build system toolkit and Rational Software Architect import engine)
- The Rational Team Concert build engine is installed, configured, and running.
- The Rational Software Architect import engine is installed, configured, and running.
- A local workspace directory, for example, C:rtc_tmpbanking, is created and is dedicated to the extracted model projects from the Rational Team Concert repository.
- An encrypted password file for the Rational Team Concert user named rtc_builder has been created. The file is located at C:Documents and Settingsrtc_builderrtc_builder_pass.txt.
- An encrypted password file for the Design Management user named dm_import has been created. The file is located at C:Documents and Settingsdm_importdm_import_pass.txt.
Note: To generate a password file, see Using JBE to create an encrypted password file.
Implementation
Configure and start the Rational Software Architect import engine
To handle import requests from Design Management Server, the Rational Software Architect import engine must be configured and initiated.
The following screen capture shows the Rational Software Architect import engine configuration dialog box. The Design Management user named dm_import is required to configure the import engine before starting it.
Note: For the Rational Team Concert-driven integration, the Rational Software Architect import engine does not launch Eclipse to execute the Ant script; therefore, it is no longer necessary to set the Eclipse installation directory to Rational Team Concert build system toolkit’s Eclipse directory.
In the Design Management Server interface, there are two options for importing models onto the server: import an entire workspace or import individual projects. If you import an entire workspace, the target Eclipse instance specified by the import engine configuration must have the import engine hook plug-in installed. To import individual projects, the default Eclipse installation directory will work.
Create an import definition
For each Design Management workspace, a single import definition defines the resources to import. Each import definition assigns an import engine and provides options for automation. The import definition is created on the Design Management Server with the Design Management web client.
On the Import Definition page, the Design Management user named dm_import is required to specify the following items:
- The name of the import engine to initiate the import process. The name specified must match the name that is entered in the import engine configuration dialog box: DM_Build_Import_Engine.
- The paths and names of the Rational Software Architect projects to import. The workspace path must match the location of the local workspace directory from which the Ant script extracts the Rational Software Architect projects, for example, C:tmprtc_tmpbanking.
Note: For the Rational Team Concert-driven integration, both the Ant Script Path and Schedule sections should be empty. These sections are only required for the Design Management-driven integration where Design Management specifies the Ant script to execute and when to start the import process. For the Rational Team Concert-driven integration, this information is specified by the Rational Team Concert build definition.
After the required configurations are created, the import request places or updates the JKE Banking Project and JKE Banking Profile in the Design Management project area named Banking Model Project.
The following image shows the projects that are mapped between the Rational Team Concert server and the Design Management Server:
Configure and start the Jazz Build Engine
Jazz Build Engine is a component of the Rational Team Concert build system toolkit. To handle requests for the Rational Team Concert build, the Jazz Build Engine must be configured and started. From the command line on Machine 3 where the Jazz Build Engine resides, start the build engine with the following configurations:
<RTCBuildSystemToolkitInstallationDirectory>/jazz/buildsystem/buildengine/eclipse/jbe -repository https://machine2:9443/ccm -userId rtc_builder -passwordFile "C:Documents and settingsdm_importrtc_builder_pass.txt"-engineId Banking_RTC_Build_Engine
The Jazz Build Engine starts and is ready to receive and send requests.
Create a Rational Team Concert build definition
It is possible to create the Rational Team Concert build definitions based on various build templates, such as Ant, command line, or Maven. In the following example shows how to create an Ant build definition.
In Rational Team Concert, the build definition controls the build process. The build definition defines build tasks, assigns the build engine, and provides options for scheduling and automation. The build definition is created on the Rational Team Concert server via the Rational Team Concert Eclipse client.
On the Overview page of the build definition, the user named rtc_builder must specify build engines to run the build. In this example, there is only one build engine. The value must match the -engineId parameter value of the JBE command: Banking_RTC_Build_Engine.
On the Schedule page of the build definition, the user named rtc_builder can set up scheduled builds.
On the Ant page of the build definition, the user named rtc_builder must specify the path to the Ant build file. In this example, the location of <RTC_Build_Ant_Script>. In addition, the rtc_builder user must select the Include the Jazz build toolkit tasks on the Ant library path check box. This option is required because <RTC_Build_Ant_Script> uses the Rational Team Concert build teamFetch Ant task.
After the build definition is configured and saved, you must deploy the com.ibm.xtools.rmps.rtc.extension_1.0.0.jar plug-in to enable the startRSADMImport task.
Deploy the com.ibm.xtools.rmps.rtc.extension_1.0.0.jar plug-in
It is important to deploy the com.ibm.xtools.rmps.rtc.extension_1.0.0.jar plug-in into the <RTCBuildSystemToolkitInstallationDirectory>/jazz/buildsystem/buildtoolkit directory.
The plug-in contributes a custom Ant task named startRSADMImport to the Rational Team Concert build system toolkit. The task communicates with the remote Design Management Server to start the Rational Software Architect import process.
Valid attributes of the startRSADMImport task are as follows:
- userId: The user account.
- pass: The password (or passwordFile: the password file).
- repositoryAddress: The URL of the Design Management Server. For example: https://hostname:port/dm.
- projectName: The name of the project area
- workspaceName: The name of the workspace that contains the import definition
- reimport (optional): Set to true to delete existing content and import again from scratch. Set to false to import a delta of the changes. The default is set to false.
- snapshotName (optional): If specified, a snapshot is created automatically at the end of the import process.
- snapshotDescription (optional): A description of the snapshot. This option is only available if a snapshot name is specified.
After the com.ibm.xtools.rmps.rtc.extension_1.0.0.jar plug-in is deployed, it can handle custom scripts and the build Ant script can be configured.
Rational Team Concert build Ant script
The Rational Team Concert build Ant script extracts the model projects from Rational Team Concert into a local workspace directory and issues an import request to the Design Management Server to start the import process.
The Rational Team Concert build Ant script requires Ant tasks, provided by the Rational Team Concert build system toolkit, to accept the latest changes into the Design Management workspaces (teamAccept) and then extract the workspaces to the local file system (teamFetch).
For example:
<teamAccept repository=”${rtcRepository}” userId=”${rtcUserId}” passwordFile=”${rtcPasswordFile}” workspaceName=”${rtcWorkspaceName}” verbose=”true” /> <teamFetch repository=”${rtcRepository}” userId=”${rtcUserId}” passwordFile=”${rtcPasswordFile}” workspaceName=”${rtcWorkspaceName}” verbose=”true” destination=”${targetdir}” />
After the latest model content is in the local file system, the script issues an import request to the Design Management Server to start the Rational Software Architect import process.
For example:
<startRSADMImport userId=”${dmUserId}” passwordFile=”${dmPasswordFile}” repositoryAddress=”${dmRepository}” projectName=”${dmProjectName}” workspaceName=”${dmWorkspace}” reimport=”${dmReImport}” snapshotName=”${dmSnapshotName}” snapshotDescription=”${dmSnapshotDescription}”/>
A complete sample script is attached in the attachment section. Before using it, change the values in the property tasks to the appropriate values.
The following diagram shows the Rational Team Concert build Ant script after modifying the values of the property tasks:
Request a build using Rational Team Concert Eclipse client
To test the script or manually start the build process, in the Rational Team Concert Eclipse client, on the Team Artifacts page, right-click Banking_RTC_Build_Definition; then click Request Build.
For more information
- Rational Software Architect extension for Design Management infocenter
- Rational Team Concert infocenter
- Rational Team Concert Jazz Build System Toolkit inforcenter
Sample Script
A copy of a completed sample script and JAR are available to use as a starting point.
About the author
Tao Weng is a software developer on the Jazz Platform Reporting team. Before that, he worked on Rational Software Architect Design Management since the Design Management 3.0 release. Tao works for IBM Canada in Ottawa, Canada. He can be contacted at tweng@ca.ibm.com.
Corey Syrnyk is the project lead for Design Management User Technologies. Corey works for IBM Canada in Ottawa, Canada. He can be contacted at csyrnyk@ca.ibm.com.
Copyright © 2013 IBM Corporation