Configuring an IBM i deployment definition

After you create a deployment definition, you can configure it by modifying or adding deployment definition properties.

Procedure

  1. Expand the Enterprise Extensions node, then the Deployments node. Right-click the deployment definition that you want to configure and select Open Deployment Definition.
  2. In the Deployment Definition editor, go to the Overview tab.
    1. In the General Information Description field, briefly describe your deployment definition.
    2. Optional: Select Ignore warnings when computing overall status.
    3. In the Supporting Build Engines field, click Create to create a build engine, or select an existing build engine by clicking Add, selecting the build engine, then clicking OK. You must associate a build engine with your package definition. For more information, see Creating build engines.
    4. Optional: In the Pruning Policy field, select Prune build results, and then set the number of successful and failed builds to save.
  3. Optional: Go to the Properties tab. From the Properties table, you can highlight an existing property that you want to edit. Click Edit and enter a value in the Value field. You can also click Add or Remove to add or remove properties.
  4. On the IBM i Deployment > Load tab, add details for your project and choose the following options:
    1. Required: For the Package definition field, click Select to choose a package definition to deploy.
    2. In the Load Method field, select either Copy or FTP.
      FTP
      Deploys the package to the load space by using FTP.
      If you select FTP, you must specify the following details:
      Host name
      The host name of the system that contains your package.
      User ID
      Your user ID on the system that contains your package.
      Password file
      The location of the password file (by using the Jazz® Build Engine and the -createPasswordFile flag) on the system where your deployment is running. The encrypted password is the password for the user ID on the system that contains your package. For more information about creating an encrypted password file, see Creating encrypted password files.
      Copy
      The package that you deploy is transferred by copying it to the load space (for mounted drives). When you select Copy, you do not have to specify a Host Name, User ID, or Password File.
    3. Required: In the Deployed package root directory field, specify the directory where you want your package to be loaded.
      Note: It is advised to avoid using blanks or $ in the path as these characters (or their national language equivalents) can cause inconsistent results.
    4. Required: In the Original package root directory field, specify the directory where the package was created. This directory should be the same as the Package Root Directory in the associated package definition.
      Note: It is advised to avoid using blanks or $ in the path as these characters (or their national language equivalents) can cause inconsistent results.
    5. Optional: In the Load pre-command or Load post-command fields, specify commands to run on the deployment system before or after loading.
    6. Required: In the IBM i intermediate save file library field, specify a working library on the IBM® i server to temporarily store objects.
  5. On the IBM i Deployment > Deploy tab, add details for your project and choose the following options:
    1. In the mapping table, click Add, Edit, or Remove to specify the libraries you packaged and where you want to deploy them.
    2. Optional: In the Deploy pre-command or Deploy post-command fields, specify commands to run on the deployment system before or after the deployment process runs.
    3. Optional: In the Rollback pre-command or Rollback post-command fields, specify commands to run on the deployment system before or after the rollback process runs.
    4. Optional: Select Allow multiple rollbacks and indicate how many packages that you want saved.
      Selecting this option allows your team to roll back any saved package that was successfully deployed.
      Notes:
      • This option is available only with version 5.0.1 or later. With earlier versions, you can only roll back the last package that was successfully deployed to its previously deployed state.
      • If the value for Maximum number of rollbacks to keep is set to 0, all rollback archives are saved on the deployment server. To free up space on the server, you must delete obsolete rollback archives manually or by using a scheduled cleanup program.
    5. On the Rules for deploying physical files section, choose one of the following options to specify how physical files are handled during deployment.
      Overwrite physical files with packaged objects
      This option is the default for deployment definitions that are created with version 4.0.6 and earlier versions. With this option, all objects from the package that is deployed replace existing objects.
      Copy existing data to physical files while deploying
      This option is the default for deployment definitions that are created in version 5.0 and later versions. With this option selected, a backup copy of the files is created and the data in that backup is copied to the deployed object. The backup is deleted after the package is deployed successfully.
      Note: If the deployment fails, any physical files that were copied to the deployed object before the failure have backup copies that are available in the target library. Check the deployment build log or search for *FILE objects with file names that include QJX*. The backup file text descriptions list the original file names. To restore the original files, delete the deployed versions of the physical files and rename the temporary files with the original file names.
      User-defined command to deploy each physical file
      Select this option if you have physical files that must be deployed in a specific way. Add a CL command similar to the following example:
      CALL PGM(UTILLIB/MIGRATEPF) PARM(&S &R &W &N &T &A)
      You can use the following substitution variables with your information. As the deployment process iterates through the physical files, these variables will be substituted with your values:
      • &S: This variable is replaced with the original saved library name. (For example, this variable is used for the RSTOBJ SAVLIB parameter). This variable is also the name of the save file in the intermediate save file library.
      • &R: This variable is replaced with the target library where the package will be deployed. (For example, this variable is used for the RSTOBJ RSTLIB parameter.)
      • &W: This variable is replaced with the intermediate save file library name that is defined in the deployment definition.
      • &N: This variable is replaced with the name of the object that is being deployed.
      • &T: This variable is replaced with the type of object that is being deployed. (For example, *FILE.)
      • &A: This variable is replaced with the attribute type of the object that is being deployed. (For example, PF-DTA.)
      This user-defined command is called many times during the deployment process:
      • One time for each physical file that already exists and has data records in the target library.
      • One time after the logical files are deployed to the target library, which allows time to clean up temporary files for migration. In this special case, &N is assigned *END and &A is assigned LF.

      Any physical files that are new or empty are replaced by the deployment process without calling the user-defined program. After physical files are deployed, the logical files will be deployed, and then all other file types and object types from the package are deployed. If your package is being deployed to more than one library, the deployment process iterates through this cycle (physical files, logical files, and then other objects) for each library.

    6. Select Save physical files in rollback archive before deployment to save a backup of your physical files in case errors occur during the deployment process. This option is selected by default.
      If an error occurs, the original objects can be restored by requesting a rollback.
      Notes:
      • Backing up large database files uses time and space during the deployment.
      • If you do not choose Save physical files in rollback archive before deployment, physical files are not backed up, but all other object types are.
      • If you do not select Save physical files in rollback archive before deployment, make sure that you have a backup copy of your physical files. If you decide to roll back the deployment, first you must restore your backup of the physical files to the target libraries before you begin the rollback process.
  6. On the IBM i Deployment > Publish tab, specify one or more of the following options.
    • Select Publish delta deploy manifest if you want the delta deployment manifest file included in the deployment result.
    • Select Publish cumulative deploy manifest if you want the cumulative deployment manifest file included in the deployment result.
    • Select Publish rollback manifest if you want the rollback manifest file included in the deployment result.
  7. Optional: Go to the Ant tab.
    1. In the Build File and Targets section, specify the Ant build file and targets you want your definition to start. Reference properties by using this format: ${propertyName}.
    2. In the Ant Configuration section, select Include the Jazz build toolkit tasks on the Ant library path if you want to add the -lib Ant argument with the path to the Jazz buildtoolkit directory.
    3. Specify any other configuration details, including the following options:
      • Ant home
      • Ant arguments. The default is -verbose.
      • Working directory
      • Java™ home
      • Java VM arguments. The default is -Xquickstart.
      • Properties file
  8. Click Save to save your deployment definition.