Library > Articles >

IBM i packaging and deployment

Ash Hariharan and Kevin Doyle, Rational Team Concert Enterprise Extensions
Last updated: May 31, 2013
Build basis: Rational Team Concert 4.0

This article explains how to use the IBM i packaging and deployment capabilities of Rational Team Concert 4.0.

Overview

“Packaging” refers to archiving IBM i objects to a save file so that you can deploy them to test or production systems. You must create package definitions that define package properties, like where to find the objects you want to package. You can run package definitions through a build engine on the build system (much like requesting a build) to archive these deployable objects to a save file, based on the properties you specify in the package definition.

“Deployment” refers to taking a package you have created, loading it to a deployment system, and then deploying the package on that system. You must create deployment definitions to define deployment properties, like the libraries where you deploy the objects. You can run deployment definitions through a build engine on the deployment system to load and deploy the contents to that system.

For instructions on how to set up a project area that contains the IBM i sample mailing list application, a Rational Build Agent, and an IBM i dependency build definition, see: IBM i sample application: Maillist version 4.0

Prerequisites

  • Rational Team Concert Eclipse client downloaded and installed.
  • Access to a compatible version of a Rational Team Concert server running on a supported platform.
  • A compatible version of the Build System Toolkit running on your IBM i build system with the Rational Build Agent and, optionally, the Build System Toolkit and the Rational Build Agent on another IBM i system to which you want to deploy.

Build System Toolkit requirements

  • You must use the user ID you specify for the Build System Toolkit to connect to the server when you build.
  • The build user ID must belong to the “JazzUsers” group and have a Rational Team Concert – Developer for IBM Enterprise Platforms license. (We use TestJazzAdmin1 as the user ID to develop this article.)
  • If you run an FTP deployment, make sure you have the Build System Toolkit running on the system where your package will be deployed.

Contents

Creating a package definition

  1. In the Rational Team Concert Eclipse client, go to the Team Artifacts view and expand your project area, then expand the Enterprise Extensions node. Right-click the Packages node, then select New Package Definition.

  2. The New Package Definition wizard opens. Select Create a new package and click Next.

  3. Specify the following information on the General Information page of the New Package Definition wizard:
    • In the ID field, enter an ID for your package definition.
    • Optional: In the Description field, enter a brief description of the package definition.
    • In the Package File Systems section, select the appropriate file system for the objects you are packaging. In this case, you are packaging resources for an IBM i RPG application, which is built into library-based objects (*PGMs and *SRVPGMs), so select IBM i and click Next.
  4. Accept the defaults for Additional Configuration and click Finish.

Your new package definition opens to the Overview page of the editor.

Back to top

Configuring the package definition

Configure your package definition by adding details to four tabs on the package definition editor:

  1. Overview tab: In the Supporting Build Engines section, click Edit. In the Edit Build Engines dialog, select the build engine that is running on the build system and click OK.
    Note: Select the same build engine that you used with your IBM i dependency build definition to package the output objects created during the build.
  2. Properties tab: By default, the properties tab contains no properties. You can add properties that will be used when the packaging or deployment runs or to override fields in the package and deployment definitions.
  3. Ant tab: Contains the default scripts for the package to run.
  4. IBM i Packaging tab: Specifies the properties of the packaging definition.

    Select the Package section on the IBM i Packaging tab:

    • Select the IBM i dependency build definition you created previously. .
    • Specify the package root directory where you want the package to be stored.
    • Specify the IBM i intermediate save file library.
    • Click Add, Edit, or Delete to select the contents of the include and exclude ship list. (See creating Ship list section.)

    Open the Option section on the IBM i Packaging tab:
    Note: All the properties on this tab are optional.

    • Click Add, Edit, or Delete to specify the libraries packaged and the libraries to be mapped to during deployment. (Refer to Restore mapping section)
    • Select Auto clean to enable the automatic cleanup of packages from the package root directory. The auto clean option deletes the packaging results from the package root directory. You must wait 30 minutes after you delete a package result, and then create a package, before auto clean occurs. You can change timing by modifying the “Build Result Pruner Task Fixed Delay (seconds)” property on the server on the Change and Configuration Management Advanced Properties page.
    • Select any of the publishing options to make those files available on the Downloads tab of the package results. Note that the manifest file displays the list of all the objects being packaged. When you select the publish package option, your new .savf file is attached to the downloads tab.

Back to top

Create and edit the ship list filter

The ship list file lists the objects that are saved to a package. A ship list filter file is a file that lists generic or specific object specifiers to determine the objects in your libraries that you want to save to or exclude from the package. Add object specifiers to the include and exclude tables on the Package tab of the IBM i packaging tab to create a ship list filter.

Complete the following steps to create a ship list file:

  1. On the package section of the IBM i Packaging tab, click Add next to the Include table. The the Ship List Manager dialog opens.
  2. The “Select specific objects” option is the default. Add values in the Library, Object, and Type fields and click Run to run a query against all the built objects from the build definition associated with this package definition.
    Option: Instead of adding specific objects, you can also use the “Add generic filter” option to add a filter that uses wildcard characters. For example, you can specify all objects that start with “M” of type “*PGM” by using this wildcard filter: Library: LIBRARYNAME, Object: M*, and Type: *PGM.
  3. From the generated list, select the objects you want to add to the package.
  4. Click OK to add objects to the Include table.
  5. Click Add next to the Exclude table. The the Ship List Manager dialog opens.
  6. The “Select specific objects” option is the default. Add values in the Library, Object, and Type fields and click Run to run a query against all the built objects from the build definition associated with this package definition.
    Option: As with the Include list example above, you can use the “Add generic filter” option to add a filter that uses wildcard characters.
  7. From the generated list, select the objects you want to exclude from the package.
  8. Click OK to add your objects to the Exclude table.

Note: If you do not select a build definition in the package definition, the “Select Specific objects” option is disabled. Back to top

Restore mapping section

In the Options section of the IBM i Packaging tab, you can override the default library where your package will ultimately be deployed. By default, the packaging and deployment process deploys IBM i objects to the library on the target system that corresponds to the library on the original system. If you want to deploy to a different library on the target system, add the original and target library names to the restore mapping table. When you run your package, the packaging process generates a restore mapping file that will indicate where the objects are packaged from (the “From Library” column on the table) and where the objects will be deployed (the “To Library” column).

You can create the restore mapping file by making specifications in the From library and To library fields and clicking Add in the restore mapping table.

Note: If you specify a mapping for a library, then you must specify a mapping for all libraries in your package or the deployment will fail.

Back to top

Creating a package

There are two ways to specify the objects you want to package:

  • Work item packaging packages the built output objects from change sets associated with the work items you select.
  • Ship list packaging uses include and exclude ship list filters to specify which files from the build you want to archive to the package. Choose a time stamp to package only those files that have been built or changed since the time stamp.
    Note: With ship list packaging, you can use the timestamp option to package only the files that have been built or changed after the time stamp that you list in the ship list packaging wizard.
    Skip to ship list packaging steps.

Complete the following steps to create a work item package:

  1. In the Team Artifacts view, expand your project area, then Enterprise Extensions, then Packages. Right-click your package definition and select Create Package. The Create Package wizard opens.

  2. On the Packaging Type Selection page of the Create Package wizard, choose Work item packaging. Click Next.
  3. On the Work Item Selection page, select the work items you want to package. Click Next.

  4. The Work Item Summary page gives a summary of the work items you select, and the output objects you want to package. Click Next.

  5. In the Library Mapping Selection page, specify any changes for the restore mapping table. Click Next.

    Note: This is an optional page. Any changes you make here will override the library mapping tables from the package definition, and will affect only the package you create in this instance.
  6. On the Include Ship List Selection page, specify any changes you want to make to the Include Ship List Selection. Click Next.

    Note: This is an optional page. Any changes you make here will override the Include Ship list table from the package definition, and will affect only the package you create in this instance.
  7. In the Exclude Ship List Selection page, specify any changes you want to make to the Exclude Ship list table. Click Finish.

    Note: This is an optional page. Any changes you make here will override the Exclude Ship list table from the package definition, and will affect only the package you create in this instance.

Complete the following steps to create a ship list package:

  1. In the Team Artifacts view, expand your project area, then Enterprise Extensions, then Packages. Right-click your package definition and select Create Package. The Create Package wizard opens.

  2. On the Packaging Type Selection page of the Create Package wizard, choose Ship list packaging. Click Next.

  3. In the Library Mapping Selection page, specify any changes for the restore mapping table. Click Next.

    Note: This is an optional page. Any changes you make here will override the library mapping tables from the package definition, and will affect only the package you create in this instance.
  4. On the Include Ship List Selection page, specify any changes you want to make to the Include Ship List Selection. Click Next.

    Note: This is an optional page. Any changes you make here will override the Include Ship list table from the package definition, and will affect only the package you create in this instance.
  5. In the Exclude Ship List Selection page, specify any changes you want to make to the Exclude Ship list table. Click Finish.

    Note: This is an optional page. Any changes you make here will override the Exclude Ship list table from the package definition, and will affect only the package you create in this instance.
Back to top

Checking packaging results

Open the package results by double-clicking the package result from the Builds view.

  1. The number of objects you packaged is specified on the Overview tab, along with a link to the summary work item in the Reported Work Items section.
  2. If you selected any publishing options in the package definition, those files will be available On the Downloads tab.
    Note: The manifest file displays a list of all the objects being packaged. Select the publish package option to attach the save files to the Downloads tab.
  3. The Activities tab contains information about all the activities that occur while the package is created. Use this tab to monitor the progress of your package.
  4. The Package Summary tab contains information about all the packaged objects.
  5. Verify that you created a new package in the package root directory that you specified in the packaging definition. You can find the exact location where the new package is stored on the Package Summary tab.
Back to top

Alternate ways to request a package

You can create a package directly from a work item to package the output objects from the associated change sets.

  1. Select Package Work items to open the work item selection page of the Create Package wizard.
  2. Select a package definition and click Next. This opens the Work Item Summary page. Now perform the corresponding steps described in the “Creating a package” section of this article.
Back to top

Show all packages

  1. In the Team Artifacts view, expand your project area, then Enterprise Extensions, then Packages.
  2. Right-click your package definition and select Show All Packages.
  3. A list of all of the packages that are available to be deployed from that package definition is displayed in the Queried Results view.
Back to top

Creating a deployment definition

Go to the Team Artifacts view and expand your project area, then the Enterprise Extensions node.

  1. Right-click the Deployment node, and select New Deployment Definition. The New Deployment Definition wizard displays.
  2. Select Create a new deployment then click Next.
  3. On the General Information page of the New Deployment Definition wizard, do the following:
    • In the ID field, enter an ID for your deployment definition.
    • In the Description field, optionally enter a brief description of the deployment definition.
    • In the Deploy File Systems section, select the appropriate file system for the packages you are deploying; for example, if you are deploying packages to an IBM i system, select IBM i.
  4. Click Next and accept the defaults for Additional Configuration, then click Finish.
Back to top

Deployment definition properties

The deployment definition editor contains the following four tabs:

  1. On the Overview tab, select a supporting build engine and click Edit. The Edit Build Engines dialog displays. Select the build engine that is running on the deploy system, then click OK.

  2. Note: If you want to run an FTP deployment, make sure there is a Build System Toolkit running on the deploy system.
    • By default, the Properties tab contains no properties.
    • The Ant tab specifies the default scripts for the deployment to run.
    • The IBM i Deployment tab specifies the properties for the deployment.
  3. Select the Load Tab from the IBM i deployment tab.
    • Specify the package definition associated with the packages you want to deploy.
    • Select a load method: FTP or Copy. If you select FTP, you must indicate which system the package is saved on.

    • Note: If you select FTP, you must specify a host name, user ID, and password file for the system where the package is saved. The host name is the name of the system where the package exists. The password file must be stored in the deploy system.
    • Specify the deployed package root directory. This is where the package will be loaded to. Also specify the original package root directory. This is where the package is saved on the package or build system.
    • Specify the intermediate save file library
    • You also have the option of specifying pre- and post-load commands.
  5. Open the Deploy tab and specify the following:
    • Optional: Click Add, Edit, or Delete to specify the libraries packaged and the libraries to be mapped to.

    • Note: Any changes you make here override the restore mapping entries from the package definition.
    • You also have the option of specifying pre- and post-deploy commands, and rollback commands.
  7. Open the Publish tab and specify the following:
    • Optionally, select any of the publishing choices. If you select these options, the published files will be available on the Downloads tab of the deployment result.

    Note: If you select Publish delta deploy manifest, a list of the objects deployed in the current deployment is recorded in a .xml file. If you select Publish cumulative deploy manifest, a list of all the objects deployed during all the deployments for the specific deployment definition is recorded in a .xml file. If you select Publish rollback manifest, a list of all the objects that will be rolled back is recorded in a .xml file.
Back to top

Run the deployment definition

In the Team Artifacts view, expand your project area, the Enterprise Extensions node, then Deployments. Select your deployment definition.

  1. Right-click and select Request Deployment. The Request Deployment dialog box opens.

  2. Note: You can change deployment properties for this request by expanding the Deployment Options section.
  3. Select a deployment type. There are four ways of requesting a deployment: Load and Deploy, Load, Deploy, and Rollback.

  4. Note: Load and Deploy  Loads and deploys the selected package to the deploy system. Load  Only loads the selected package to the deploy system. Deploy  Deploys a previously loaded package on the deploy system from the deployed package root directory to the target libraries. Rollback  Rolls back the package to a previously deployed state.
    Note: If you select Load and Deploy or Deploy, the deployed package is deleted from the load space, whether ot not the deployment is successful. If the deployment fails, you must load the package to the deploy system again.
    Note: To deploy the package to a personal location, select the Personal Deploy option and specify the From Library and To Library.
  5. By default, the last package you created is selected. To select a different package to deploy, click Select. This opens the Select Package dialog. Select a package and click OK.
    Note: More information about the selected packaged is displayed in the Package Details section.
  6. Click Submit to submit the deployment request.
Back to top

Checking the deployment results

After the request is processed, you should see either a green check mark (successful deployment) or a red circle with an X (failed deployment). Double-click the Deployment result to open the Deployment Results editor.

  1. On the Overview tab, in the Reported Work Items section, a link to the summary work item is provided. You should also see a link to the log file that resulted from the deployment request.
  2. Open the Activities tab for additional information about all the activities that occur while the deployment runs.
  3. On the Downloads tab, if you selected the publishing options in the deployment definition, those files will be available on the Downloads page.

    Note: If you select Publish delta deploy manifest, a list of the objects deployed is recorded in a .xml file. If ou select Publish cumulative deploy manifest, a list of all the objects deployed during the total number of deployments is recorded in a .xml file. If you select Publish rollback manifest, a list of all the objects that will be rolled back is recorded in a .xml file.
  4. Open the Deployment Summary tab for additional information about all the objects you deployed.
    Note: If you roll back, this tab is called the Rollback Summary tab. If you perform just a Load, it is called the Load Summary tab.
Back to top Alternate ways to request a deployment
  • If you know the package you want to deploy, right-click a package definition result in the Builds view and select Load and Deploy, or select Load and Deploy from the package result editor.
  • Specify the deployment definition to use and the Request Deployment dialog opens.
Back to top

Querying deployed packages

If you need to know which packages have been deployed on a system, or what systems a certain package was deployed to, use the Query Deployed Packages tool.

  1. To use it, right-click on a deployment definition or the Deployments node then specify a deployment definition, package definition, build agent, or package, then click OK.

If you list a specific deployment definition, package definition, and build agent, and use a wildcard character (*) for the package, the query result will show all of the packages that are deployed to the system using the specified build agent, package definition and deployment definition. Another query example is to use a wildcard character for each field except the package, and list a specific package. The query results will list all the deployments for that package. Then you can determine which systems the package was deployed to based on the build agent.

For more information

Copyright © 2013 IBM Corporation

Dashboards and work items are no longer publicly available, so some links may be invalid. We now provide similar information through other means. Learn more here.
Feedback
Was this information helpful? Yes No 1 person rated this as helpful.