Continuous delivery with Rational Team Concert and UrbanCode Deploy

Part 3. How to use extensions to the Ant build.xml file

Comments

Content series:

This content is part # of # in the series: Continuous delivery with Rational Team Concert and UrbanCode Deploy

Stay tuned for additional content in this series.

This content is part of the series:Continuous delivery with Rational Team Concert and UrbanCode Deploy

Stay tuned for additional content in this series.

This series of articles presents two mechanisms for integrating IBM(R) Rational Team Concert(TM) and IBM(R) UrbanCode Deploy to create a continuous delivery process. Part 1 showed you a packaged out-of-the-box implementation that is easy to set up. The second approach, presented in Part 2 and Part 3, uses extensions to the Ant build.xml file.

The Initiation of a deployment from a build process

Phase 5. Initiating a deployment

The initiation of an UrbanCode deployment can require a large amount of data to be supplied regarding the deployment process to use, the environment that is to receive the deployment and the versions of the components being deployed. As a result the udclient command line function receives a JSON format file containing the information that it needs to perform the deployment.

To view the format of the JSON data required run the deployment request command line with a –t option as shown in Listing 1.

Listing 1. Deployment request command -t
udclient -weburl https://rational-srv-02:8443 -authtoken <my-auth-token> requestApplicationProcess –t

The result shown after you run the command is the format of JSON data to be supplied.

Properties

Listing 2 shows the additional required properties. Add these properties at the top of the build.xml file. Set up specific values for the application, environment and process for your environment.

Listing 2. New properties to support the deployment operation
<property name="Deploy_DeploymentJSONFile" value="Deploy_application_deploy.JSON" /> 
<property name="Deploy_ApplicationName" value="Deploy Sample Application" />
<property name="Deploy_ApplicationProcess" value="Deploy to Tomcat" />
<property name="Deploy_Environment" value="Development" />
<property name="DeployDeploymentLog" value="${workingDir}/DeployDeploymentLog.log" /> 
<property name="DeployRequestIDFile" value="${workingDir}/DeployRequestIDFile.txt"/>
<property name="DeploymentRequestJSONTitle" value="requestId"/>

Deployment request: Step 1

Use the StartBuildActivity build command shown in Listing 3 as the first step to create the deployment request.

Listing 3. StartBuildActivity build command
<startBuildActivity activityIdProperty="Deploy" label="Deploy objects with Deploy"
    autoComplete="true" buildResultUUID="${buildResultUUID}"
repositoryAddress="${repositoryAddress}"
userId="${userId}" passwordFile="${passwordFile}" />

Deployment request: Step 2

Use the echo command to write the required content into the JSON file.

Note:
If using multiple components, their names and version identifiers should also be added in here using repeated blocks of the versions element in the section of JSON content shown in Listing 4.

Listing 4. JSON file creation process
<echo file="${workingDir}/${Deploy_DeploymentJSONFile}" append="false">{
    "application": ${Deploy_ApplicationName},
    "applicationProcess": ${Deploy_ApplicationProcess},
    "environment": ${Deploy_Environment},
"versions": [
{
"version": ${buildLabel},
"component": &quot;${Deploy_Component}&quot;,
}
],
}
</echo>

Deployment request: Step 3

In the third step, the udclient command runs the deployment. The first arguments of the command are the same as the login command. Further arguments are shown in Listing 5. These include the requestApplicationProcess command and the identifier of the JSON file.

Listing 5. Deployment request build command
<exec executable="cmd" dir="${workingDir}" output="${DeployDeploymentLog}">
    <arg value="/c"/>
    <arg value="udclient"/>
<arg value="-authtoken"/>
    <arg value="${Deploy_AuthToken}"/>
    <arg value="-weburl"/>
    <arg value="${Deploy_WebURL}"/>
    <arg value="requestApplicationProcess"/>
 <arg value="${Deploy_DeploymentJSONFile}"/> 
</exec> 

The ID for the deployment request, as shown in Listing 6, is in the output file that results from executing the deployment.

Listing 6. Deployment request response from UrbanCode
{
    "requestId": "6e0d5a7d-d371-4665-8cc5-f99cb4b11856"
}

Get the deployment request ID

You can extract the deployment request ID from the JSON format output result of the requestApplicationProcess command (shown in Listing 6) the same way that you previously extracted the component version ID. The Java application that was used in phase 3 of article 2 is invoked from within the build script to process the output of the requestApplicationProcess command and extract the ID.

Listing 7 shows the section of xml required to run the java application with the required properties.

Listing 7. Invoking the Java application to get properties from JSON file
<java jar="${getJSONPropertyValue}" output="${getJSONPropertyValue-Log}" fork="true">
<classpath refid="getJSONPropertyValuePaths" />
    <arg value="inputFile=${DeployDeploymentLog}" />
    <arg value="Title=${DeploymentRequestJSONTitle}" />
    <arg value="outputFile=${DeployRequestIDFile}" />
</java> 

The output file containing the deployment request identifier shown in Listing 8 is created after the execution of the command shown in listing 7.

Listing 8. Deployment request identifier
6e0d5a7d-d371-4665-8cc5-f99cb4b11856

Listing 9 contains:

  • Command to load the file into a property
  • Echo command to show the ID in the build log file
Listing 9. Build command to read the content of the deploy request file
<loadfile property="DeployRequestID"
srcFile="${DeployRequestIDFile}"/>  
<echo message="ID of Deployment request = ${DeployRequestID}" />  

Publish a link to the deployment request in the build record

You can use the link publisher command in Rational Team Concert to publish a URL constructed from a header URL defined as a property at the top of the build.xml file and the ID extracted from the file by the commands in listing 7 and shown as an example in listing 8. Use the code in Listing 10 to add the header URL property to the build.xml file.

Listing 10. Property to add to build.xml for the deploy process request ID
<property name="DeployRequestDeploymentLinkHeader" 
value="${Deploy_WebURL}/#applicationProcessRequest/"/>

Listing 11 is the command to publish the link.

Listing 11. Build.xml command to publish a link to the deployment record
<linkPublisher label="UrbanCode Deploy Application Deployment '${Deploy_ApplicationName}'"
url="${DeployRequestDeploymentLinkHeader}${DeployRequestID}"
componentName="Application Deployment" buildResultUUID="${buildResultUUID}"
repositoryAddress="${repositoryAddress}" userId="${userId}"
    passwordFile="${passwordFile}" failOnError="false" /> 

Phase 5. Summary

In phase 5 you completed the steps to make the continuous delivery process initiate a deployment of the new component version to a specific environment defined in UrbanCode Deploy. You also created a link on the build record to the deployment record in UrbanCode Deploy.

Phase 6. Tracking the end of the deployment

The solution provided in phase 5 has a slight issue tracking the deployment process through the Rational Team Concert build process. Listing 12 shows the deployment request command in the Ant build.xml format.

Listing 12. Build.xml command to invoke the deployment
<exec executable="cmd" dir="${workingDir}" output="${DeployDeploymentLog}">
    <arg value="/c"/>
    <arg value="udclient"/>
<arg value="-authtoken"/>
    <arg value="${Deploy_AuthToken}"/>
    <arg value="-weburl"/>
    <arg value="${Deploy_WebURL}"/>
    <arg value="requestApplicationProcess"/>
 <arg value="${Deploy_DeploymentJSONFile}"/> 
</exec> 

Listing 12 translates to a command line execution of the command.

Listing 13. The command line equivalent of the command in listing 12
udclient –weburl https://<web-server > -authtoken <my auth token> 
requestApplicationProcess <JSON file name>

The UrbanCode command line client processes a request for a deployment initiation and completes the command shown in Listing 13 and returns the user to the command prompt as soon as UrbanCode Deploy accepts the request. This does not mean that the deployment has ended and this command cannot track the progress of a deployment.

The result is that the deployment process, as invoked by the Rational Team Concert build, appears to take just three seconds to run. This is shown by the activity tracking report of the build record in Figure 1.

Figure 1. Build activity record
Build activity showing a short deployment time
Build activity showing a short deployment time

As shown in Figure 2, the actual deployment by UrbanCode Deploy took 22 seconds.

Figure 2. UrbanCode Deploy record of build activity
Record of deployment showing it took 22 sec
Record of deployment showing it took 22 sec

The unlinked timing of the build and deployment operations is shown in Figure 3.

Figure 3. Build and deploy operations end at different times
Build process ends before the deploy process
Build process ends before the deploy process

Ideally the Rational Team Concert build process should wait for the deployment to complete before moving on to the next task or to the completion of the build. It is also necessary to wait for the deployment to end if the success of failure of the deployment process is to be used as an indicator of the success of failure of the build process too.

There are a number of pause-check-act mechanisms bayou can use for this process. The approach taken here is to have the Ant build process poll periodically for the presence of a specific marker file . UrbanCode Deploy writes the marker file as the final step of the deployment process, as shown in Figure 4. A small discrepancy in time between the deployment process finishing (and creating the marker file) and the Ant build script running inside Rational Team Concert is shown in Figure 4. The discrepancy is between the deployment process completing (and creating the marker file) in UrbanCode Deploy and the Ant build script running (polling and finding that the marker file has been created) inside Rational Team Concert. The maximum period that this will be is given by the poll period of the Ant task shown in the following section with the setting of checkevery="5000". This indicates that the Ant process will look for the file every 5 seconds. In this example the maximum discrepancy could be 5 seconds, however the value for the checkevery parameter can be set to whatever is appropriate for your environment.

Figure 4. Build and deploy operations end at different times
Build process ends before the deploy process
Build process ends before the deploy process

Build process steps

To perform the polling for the end of the deployment you need to add steps to the build. Listing 14 is the first step. It is the startBuildActivity command and is important at this part of the deployment. It lets you track the deployment within UrbanCode Deploy. You can also follow the link to the running deployment and watch the steps run. At times a deployment can take several minutes and it is important to keep the user informed.

Listing 14. Track the deployment
<startBuildActivity activityIdProperty="Deploy" label="Polling for Depoy to end"
autoComplete="true" buildResultUUID="${buildResultUUID}"
repositoryAddress="${repositoryAddress}"
userId="${userId}" passwordFile="${passwordFile}" /> 

A new property definition is required for the marker file, which is shown in listing 15. It must match the filename and location that UrbanCode Deploy creates at the end of the deployment.

Listing 15. The build.xml property to identify the marker file
<property name="DeploymentEndMarkerFile" value="c:\\WorkingDir\\${buildLabel}.txt" />

The waitfor function in Ant allows the system to periodically poll for the presence of a particular file indicated by ${DeploymentEndMarkerFile}. In Listing 16, the waitfor command is configured to wait for a maximum of 30 minutes. The presence of the marker file is checked for every 5 seconds. More frequent checking will likely have a negative impact on the performance of the system.

Listing 16. The command to cause Ant to wait for the presence of a file.
<waitfor maxwait="30" maxwaitunit="minute" checkevery="5000">
    <available file="${DeploymentEndMarkerFile}"/>
</waitfor>

Use logPublisher, shown in Listing 17, to publish the deployment log file.

Listing 17. logPublisher
<logPublisher filePath="${DeployDeploymentLog}" label="Deploy Deployment Log"
    buildResultUUID="${buildResultUUID}" repositoryAddress="${repositoryAddress}" 
userId="${userId}" passwordFile="${passwordFile}" verbose="true"  />

Mark the end of the deployment process

The UrbanCode Deploy process that is invoked at the end of the deployment process to indicate the completion of the deployment is shown in Figure 5. The deployment process steps are:

  1. Check that the directory to hold the marker file exists
  2. If the marker directory does not exist (as indicated by the switch) then create the marker directory.
  3. Use the Create File process step to create the marker file.
Figure 5. UrbanCode Deploy end of deployment process
Process steps that create the marker file
Process steps that create the marker file

For this process to function as required and give the indication to Rational Team Concert that the deployment has completed it is necessary for the deployment to reach this process and so the application process should be constructed accordingly.

Closeout steps

The final step is to logout of the session of UrbanCode Deploy and to remove the marker file created by UrbanCode Deploy as shown in Figure 5. Listing 18 contains the instructions to add to the build.xml file.

Listing 18. Logout of UrbanCode and delete the temporary marker file
<exec executable="cmd" dir="${workingDir}">
    <arg value="/c"/>
    <arg value="udclient"/>
    <arg value="logout" />
    <arg value="-weburl"/>
    <arg value="${Deploy_WebURL}"/>
</exec>  
<exec executable="cmd" dir="${workingDir}">
    <arg value="/c"/>
    <arg value="del"/>
    <arg value="${DeploymentEndMarkerFile}" />
</exec> 

Phase 6. Summary

The continuous delivery process is now complete. The deployment process is monitored by the build process. The build ends when the deployment is complete.

Summary

This series of articles presented two different mechanisms for the integration of the Rational Team Concert Build process with UrbanCode Deploy for automated deployment. The center of any DevOps solution is the close working of the development and operations teams. That close relationship relies on a continuous delivery process operating between the build and deployment solutions. The first solution, Part 1. An out-of-the-box implementation, will work fine for many scenarios. Users are recommended to use this solution where possible. However, when teams have complex build processes and generate content to be included in multiple UrbanCode components, use the second solution presented in parts 2 and 3. Titles and links.


Downloadable resources


Related topics


Comments

Sign in or register to add and subscribe to comments.

static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=DevOps, Rational
ArticleID=996992
ArticleTitle=Continuous delivery with Rational Team Concert and UrbanCode Deploy: Part 3. How to use extensions to the Ant build.xml file
publish-date=02062015