Customizing promotion settings

Use the Promotion Definition editor to set up and change the settings for promoting artifacts in the development-test-production hierarchy.


  1. In the Team Artifacts view, expand the project folder.
  2. Expand the Enterprise Extensions node, expand Promotions, right-click a promotion definition, and select Open Promotion Definition.
  3. In the Promotion Definition editor, click the Overview tab.
    1. Optional: In the General Information section, in the Description field, briefly describe the build definition.
    2. Optional: Select the Ignore warnings when computing overall status check box.
    3. Optional: In the Supporting Build Engines field, click Add to add a build engine, or click Create to create one.
    4. Optional: In the Pruning Policy section, select the Prune build results check box, and then set the number of successful and failed builds to save.
  4. Optional: For z/OS® only: Click the Job Output Publishing tab, and then select the Publish job output logs check box so that the output files that are generated by compilers are attached to the build results. You can also select the Publish only when an error occurred check box to reduce the attached job output logs.
  5. Optional: Click the Schedule tab to set up builds.
    1. Optional: Select the Enabled check box, and then click Add to add a build to run, or click Remove to cancel a build.
    2. Optional: In the Build time field, click either Continuous interval in minutes, and then indicate that interval; or click At, and choose an hour at which to run an automatic build.
    3. Optional: In the Build days field, choose the days of the week on which to run the build.
  6. Optional: Click the E-mail Notification tab to add, remove, or edit notification criteria.
  7. Optional: Click the Properties tab to add, remove, or edit promotion definition properties.
    You can specify the following properties:
    Specify the amount of time to allow for the finalize build map step in seconds. Specify -1 to wait infinitely. The timeout override is useful if your promotion involves many files and long build times to generate and publish target build maps.
    Specify true or false.
    If a build definition has multiple build engines that are associated with it, promotion builds might run concurrently, which might produce undesirable results. There are two ways to avoid promotion builds from running concurrently:
    • Associate only one build engine with the promotion definition.
    • Specify false for team.enterprise.promotion.allowConcurrentBuilds to disable concurrent promotion builds. If two promotions are running concurrently from the same build definition, the second promotion fails with the message Found a promotion build build currently running. Running concurrent promotion builds is disallowed. This situation is true for simulation promotions.
      Note: If either of the concurrent promotions is a preview promotion or a work item source only promotion, the second build does not fail.
    Specify true or false. This option applies to component promotion only. Specify true if you do not need a target build after the promotion completes.
    User ID used during scheduled component promotions to promote source and update the summary work item. You can use this property to specify the user ID that runs the promotion. The default user ID for promotions is ADMIN.
    Engineering Workflow Management publishes all build maps that are promoted in the build result by default. For performance reasons, you can use this property to prevent the build map links from being published in the build result.
    At the end of the work item promotion, Engineering Workflow Management displays the build result view with the promotion builds. You can specify various values to customize the display.
    • If you specify PromotionBuild, the build result of the promotion build is displayed, as it is by default.
    • If you specify TargetBuild, the build result of the target build is displayed. It is useful if you have set the follow-up action to run the target build after a promotion.
    • If you specify None, nothing is displayed. It is useful for source-only promotion.
  8. Click the Enterprise Promotion tab.
    1. In the Scope section, make sure that the information is correct for the source and target build definitions.
    2. In the Promotion Type section, select the types of promotions to be available for this promotion definition.
    3. To record the current state of the components before they are promoted, select the Create a snapshot of the target stream before promoting source check box in the Advanced Options section. By default, the option to create snapshots is not selected.
    4. In the Destination directory field of the Toolkit Configuration section, specify where to place intermediate build files. The intermediate files are temporary files that are stored while promotion builds are running.
    5. Optional: For IBM® i only: Enter IBM i commands in the Pre-command or Post-command fields to run before and after promotion.
      Note: The pre-build and post-build command options are available for IBM i promotion definitions. However, adding pre-build and post-build UNIX commands and Ant scripts is not a common practice for IBM i builds. You cannot use the pre-build and post-build command options for IBM i commands.
    6. Required: For z/OS only: Specify the path of the ISPF gateway script in the z/OS ISPF gateway script field of the Toolkit Configuration section.
    7. By default, the Skip time stamp check when promoting build outputs check box in the Advanced Options section is not selected. The time stamp check verifies that the built objects that you are promoting match the objects that are specified in the build map. If you know that the built objects changed and you want to promote anyway, select the Skip timestamp check when promoting build outputs option.
    8. Decide whether to publish or suppress build map links in the Advanced Options section. In version 4.0.6 and later, to improve build processing speeds, the build map links are not published by default. Select the Publish build map links check box to make build map links available.
      Build map links are included in the promotionReport.xml file on the Links tab in a readable display or on the Downloads tab in plain XML format.
      • Promotion definitions that were created with Rational® Team Concert® client versions earlier than 4.0.6 publish build map links by default.
      • If you use a build system toolkit version 4.0.5 or earlier, the promotion report is not created. So, by default, build map links are not published in the build result. For links to the build maps to be available, select Publish build map links.
    9. Optional: For IBM i only: In the Rules for promoting physical files section, select the option for how physical files are handled during promotion:
      • Overwrite physical file objects with source objects: Copy the source physical files to the target library.
      • Keep existing data in physical files: Move the physical file content when it exists in the target library and when it contains one or more data records.
      • Keep existing data in physical files using specified command: Promote physical file content by typing a command in the field. The command does not have syntax checking and can contain substitution variables, such as CALL PGM(MYLIB/MIGRATEPF) PARM(&S &D &N &T &A &W). You can also use these variables in the command:
        • &S: source library
        • &D: destination library
        • &N: object name
        • &T: object type
        • &A: object attribute
        • &W: temporary object name
      Note: The existing physical file in the target library is backed up as a temporary resource in case of failure. After a successful migration, the temporary object is removed. When the failure occurs while content is being restored, the original target physical files can be found in the target library with temporary names with the format of EEP#######. The temporary files are also tagged with a TEXT description that includes the original physical file name. To restore the target library to its original state, delete the promoted versions of these physical files, and rename the temporary files to their original names.
    10. In the Build File and Targets section, select either Generate build file or Use an existing build file. Click Generate build file to generate a build file that copies artifacts to the target location. Click Use an existing build file to specify a custom build file and build targets.
  9. Optional: For z/OS only: Click the Pre-Build Command Line tab and the Post-Build Command Line tabs to configure a build that uses UNIX commands or Ant scripts. Reference any properties that use this format: ${propertyName}. In the Command fields, specify a command to start before or after you build. In the Working directory field, indicate the working directory for the started command process to use. In the Connection Time Out field, indicate after how many seconds the connection times out.
  10. In the Ant Configuration section, specify any configuration details, including the following:
    • Ant home
    • Ant arguments. The default is -verbose.
    • Working directory
    • Java™ home
    • Java VM arguments. The default is -Xquickstart.
    • Properties file
  11. Depending on which types of promotions you selected in the Promotion Type section of the Promotion tab, select the check box of the promotion type and enter the necessary information.
    1. Select the Component Promotion check box. Select components from the source build definition workspace to promote, or remove components that you do not need to promote.
    2. Select the Work Item Promotion check box. Select the artifacts to promote. If the artifact selection is to be selected at the time of the promotion request, select Specify the following radio button options during work item promotion. For the options to include the children of selected work items, consider ignored changes, and include impacted outputs, select whether to Enable these options for any promotions using this definition. To have the options selected at the time of the promotion request, select Specify during work item promotion.
  12. Click Save.

What to do next