Configuring the project

This topic describes how to configure a project:

Before you begin

Perform the procedures described in the following topics:

• Preparing for a project 
• Creating a project

To configure a project

Use the following procedure to configure the project to migrate schema changes and validate schema standards in Db2 for z/OS environment.

1. From the Dashboard in the Jenkins web user interface:
   1. Select the project you want to configure.
   2. Click Configure. 
2. Select the General tab.
   1. (Optional) Enter a project description.
   2. (Optional) To use parameters in the project:
      1. Select the This project is parameterized check box.
      2. Click Add Parameter .

      3. From the list, select the type of parameter.

         Important

         Boolean Parameter, String Parameter, and Password Parameter are the typical parameter types for the variables you might use when working with the product.

         Examples

         • AMIDevOpsDebugOn is a Boolean Parameter.
         • Job_ID is a String Parameter.
         • MF_PW is a Password Parameter. This parameter type provides encryption for passwords.
      4. For the new parameter, enter values for the following fields:

         1. Name

            Important

            • (BMC.DB2.SPE2110) String parameters with spaces in the name are not supported. You can include an underscore in the string parameter names.

            • A double dollar sign can be used to produce a character string starting with, or containing, a dollar sign. That is, $$ yields $.

         2. Default Value
         3. Description
3. Select the Build tab to add and configure the build steps as follows:

   1. Click Add build step.

      Important

      BMC AMI DevOps has five main build steps and three supporting build steps.

      The five main build steps are:

      • BMC AMI DevOps Common - File Transmission
      • BMC AMI DevOps Schema Mgmt for Db2 - Schema Change Migration
      • BMC AMI DevOps Schema Mgmt for Db2 - Schema Standards (BMC.DB2.SPE2110)
      • BMC AMI DevOps Schema Mgmt for Db2 - Output Transmission
      • BMC AMI DevOps Common - JCL Execution

      The three supporting build steps are:

      Best practice

      Select one of the Common - Authentication build steps based on your Jenkins configuration.

      • BMC AMI DevOps Common - Authentication
      • BMC AMI DevOps Common - Authentication (Credential Store) (BMC.DB2.SPE2204)
      • BMC AMI DevOps Common -  Clean Up

      (BMC.DB2.SPE2204) We offer the BMC AMI DevOps Common - Authentication (Credential Store) build step. This build step has the Login Credentials field that provides credentials saved in Jenkins Credential Store. For more information, see BMC AMI DevOps Common - Authentication (Credential Store).

      When configuring projects, if you add one or more main build steps, you must also add the supporting build steps. You must add BMC AMI DevOps Common - Authentication or BMC AMI DevOps Common - Authentication (Credential Store) as the first build step and BMC AMI DevOps Common - Clean Up as the last build step. For more information, see Examples of how to add build steps during project configuration.

   2. Add build steps and enter values for the fields:

      Important

      • You can run any or all build steps in Debug mode. For more information, see To run build steps in Debug mode.
      • When building the project, you can disable processing for one or more build steps except:
        • BMC AMI DevOps Common - Authentication
        • BMC AMI DevOps Common - Authentication (Credential Store)
        • BMC AMI DevOps Common -  Clean Up
        For example, you can disable the BMC AMI DevOps Common - File Transmission build step when you are performing a comparison between two local catalogs. To enable this feature, select the Disable Build Step check box.
      • To enter your mainframe password when building the project:
        1. Select the Provide Password via Build Parameter check box.
        2. Specify a parameter-based variable as the value of the Mainframe Password via Build Parameter field. For example, specify ${MF_PW}, where MF_PW is a Password Parameter variable, as the value of this field.
      • To generate JCL but not execute it, you can select the Generate JCL Only check box in the BMC AMI DevOps Schema Mgmt for Db2 - Schema Change Migration and the BMC AMI DevOps Schema Mgmt for Db2 - Schema Standards build steps. For example, you can use this feature to validate the JCL before submitting it. The generated JCL is saved to the project workspace folder. If you select this option, you must also disable the subsequent build steps.

      • For any of the following fields, if you do not enter any path or enter the relative path, BMC AMI DevOps considers the default path of the workspace project folder.

        Build step	Field
        BMC AMI DevOps Common - Authentication	Plug-in Variables File Path
        BMC AMI DevOps Common - File Transmission	Source PDS or Directory Name
        BMC AMI DevOps Common - File Transmission	Destination PDS or Directory Name
        BMC AMI DevOps Schema Mgmt for Db2 - Output Transmission	Destination Directory Name
        BMC AMI DevOps Common - JCL Execution	Execution JCL PDS or Directory Name

        For more information about the default path, see Default path for Jenkins projects when the relative path is specified for a field.

      1. BMC AMI DevOps Common - Authentication

          Click here for information about configuring this build step

         To configure the BMC AMI DevOps Common - Authentication build step

         Enter values for the following fields:

         1. Mainframe (host name or IP address)

            Important

            Ensure that you enter the corresponding mainframe IP address or host name of the LPAR in the SYSPLEX on which z/OSMF is running.

         2. Port Number

            Important

            Ensure that you enter the corresponding port number of the LPAR in the SYSPLEX on which z/OSMF is running on the mainframe.

         3. Mainframe User ID
         4. Provide Password via Build Parameter
            Select this check box if you want to enter your mainframe password when building the project. If you select this check box, you must enter a parameter as the value for the the Mainframe Password via Build Parameter field.

         5. Mainframe Password

            If you do not select the Provide Password via Build Parameter check box, enter your mainframe password in this field.

            Important

            The plug-in uses 256-bit encryption scheme and requires one of the following:
            

            • Java JDK 8 version 8u161 or later must be installed.
              

            • For older version of JDK/JRE 8, the  Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy file (jce_policy-8.zip) must be downloaded from the Oracle website and placed in the security folder under the Java home directory.

         6. Plug-in Variables File Path

            Important

            You can also enter a String Parameter variable in the Plug-in Variables File Path field. You can specify any of the following values for the variable:

            • The full plug-in variables file path, including the file name
            • Part of the plug-in variables file path
            • The plug-in variables file name

            See the following examples:

            Example 1

            When configuring the project, you have added a String Parameter variable with the following field values:

            Field	Value
            Name	VARPROP
            Default Value	/var/lib/AMA_Properties/AMA_DevOps.properties
            Description	The value of this variable is the full plug-in variables file path, including the file name.

            You can then enter ${VARPROP} in the Plug-in Variables File Path field.

            Example 2

            When configuring the project, you have added a String Parameter variable with the following field values:

            Field	Value
            Name	VARPATH
            Default Value	/var/lib/AMA_Properties
            Description	The value of this variable is part of the plug-in variables file path and does not include the file name.

            You can then enter ${VARPATH}/AMI_DevOps.properties in the Plug-in Variables File Path field.

            Example 3

            When configuring the project, you have added a String Parameter variable with the following field values:

            Field	Value
            Name	VARFILE
            Default Value	AMI_DevOps.properties
            Description	The value of this variable is the plug-in variables file name and does not include the file path.

            You can then enter /var/lib/AMA_Properties/${VARFILE} in the Plug-in Variables File Path field.

            Important

            AMI_DevOps.properties is the default name of the plug-in variables file. Your plug-in variables file can have any name but it must be a .properties file.

            
            

      2. BMC AMI DevOps Common - Authentication (Credential Store) (BMC.DB2.SPE2204)

      3.  Click here for information about configuring this build step

         To configure the BMC AMI DevOps Common - Authentication (Credential Store) build step

         Enter values for the following fields:

         1. Mainframe (host name or IP address)

            Important

            Ensure that you enter the corresponding mainframe IP address or host name of the LPAR in the SYSPLEX on which z/OSMF is running.

         2. Port Number

            Important

            Ensure that you enter the corresponding port number of the LPAR in the SYSPLEX on which z/OSMF is running on the mainframe.

         3. Login Credentials

            Important

            In the Jenkins Credentials Provider: Jenkins >  Add Credentials, we only support the Username with Password option in the Kind field.

         4. Plug-in Variables File Path

            Important

            You can also enter a String Parameter variable in the Plug-in Variables File Path field. You can specify any of the following values for the variable:

            • The full plug-in variables file path, including the file name
            • Part of the plug-in variables file path
            • The plug-in variables file name

            See the following examples:

            Example 1

            When configuring the project, you have added a String Parameter variable with the following field values:

            Field	Value
            Name	VARPROP
            Default Value	/var/lib/AMA_Properties/AMA_DevOps.properties
            Description	The value of this variable is the full plug-in variables file path, including the file name.

            You can then enter ${VARPROP} in the Plug-in Variables File Path field.

            Example 2

            When configuring the project, you have added a String Parameter variable with the following field values:

            Field	Value
            Name	VARPATH
            Default Value	/var/lib/AMA_Properties
            Description	The value of this variable is part of the plug-in variables file path and does not include the file name.

            You can then enter ${VARPATH}/AMI_DevOps.properties in the Plug-in Variables File Path field.

            Example 3

            When configuring the project, you have added a String Parameter variable with the following field values:

            Field	Value
            Name	VARFILE
            Default Value	AMI_DevOps.properties
            Description	The value of this variable is the plug-in variables file name and does not include the file path.

            You can then enter /var/lib/AMA_Properties/${VARFILE} in the Plug-in Variables File Path field.

            Important

            AMI_DevOps.properties is the default name of the plug-in variables file. Your plug-in variables file can have any name but it must be a .properties file.

            
            

      4. BMC AMI DevOps Common - File Transmission

          Click here for information about configuring this build step

         To configure the BMC AMI DevOps Common - File Transmission build step

         Enter values for the following fields:

         1. Direction of File Transfer
            Select one of the following options:
            
            • Send file to mainframe
            • Receive file from mainframe
         2. Source PDS or Directory Name
         3. Source Member or File Name
         4. Destination PDS or Directory Name
         5. Destination Member or File Name

      5. BMC AMI DevOps Schema Mgmt for Db2 - Schema Change Migration

          Click here for information about configuring this build step

         To configure the BMC AMI DevOps Schema Mgmt for Db2 - Schema Change Migration build step

         Use the following procedure:

         1. In the General Input Fields section, enter values for the following fields:
            1. SSID
            2. Work ID Owner
            3. Work ID Name
            4. ( SPE2107 ) (Optional) If you select the Add comment to Work ID check box, enter a value for the Work ID comment text field.
         2. In the Compare section, if you have not selected the Skip Comparison check box, enter values for the following fields:
            1. Comparison Type
               Select one of the following options:
               
               • Local Catalog to DDL File with DDL File as Scope
               • Local Catalog to Migrate Worklist with Worklist as Scope
               • Local Catalog to Baseline
               • Local Catalog to Local Catalog with Objects as Scope
               • Local Catalog to Local Catalog with Baseline Profile as Scope
               • Local Catalog to Local Catalog with Outbound Migrate Profile as Scope
               • Local Catalog to Remote Catalog with Objects as Scope
               • Local Catalog to Remote Catalog with Baseline Profile as Scope
               • Local Catalog to Remote Catalog with Outbound Migrate Profile as Scope
               For more information about the types of comparisons that you can perform using the BMC AMI Change Manager for Db2 product, see the  BMC AMI Change Manager for Db2 .
            2. Enter values for the fields in the following sections. Depending on the comparison type you selected, some of the fields are optional. If you do not enter values for the required fields, a warning is displayed.

               • Compare1 Input Fields
                 

                 Important

                 If you selected a comparison type that has objects as the scope, select one of the following values in the Object Type (applies to Compare1 and Compare2) field:

                 Object type value	Definition
                 SG	Storage group
                 DB	Database
                 TS	Table space
                 TB	Table
                 IX	Index
                 VW	View
                 SY	Synonym
                 AL	Alias
                 SP	Stored procedure

                 1. Object Name Part 1 for Compare1
                 2. Object Name Part 2 for Compare1
                 3. Object Name Part 3 for Compare1
                    
                 4. Compare1 DDL PDS and Member Name
                    
                 5. Compare1 Baseline Name
                    
                 6. Compare1 Baseline Profile (SCOPE1)
                    
                 7. Compare1 Outbound Migrate Profile (SCOPE1)
               • Compare2 Input Fields
                 1. Compare2 Catalog (SSID)
                 2. Object Name Part 1 for Compare2
                    
                 3. Object Name Part 2 for Compare2
                    
                 4. Object Name Part 3 for Compare2
                    
                 5. Compare2 DDL/Worklist PDS and Member Name ( SPE2107 )
                    
                 6. Compare2 Baseline Name
                    
                 7. Compare2 Baseline Profile (SCOPE2)
                    
                 8. Compare2 Outbound Migrate Profile (SCOPE2)
                 9. If you select the Use Outbound Migrate Profile (applied before comparison) check box, enter a value for the Outbound Migrate Profile (applied before comparison) field.
                 10. ( SPE2107 ) (Optional) If you select the Add comment to Compare output check box, enter a value for the Compare comment text field.
               • Post Compare
                 If you select the Use Outbound Migrate Profile (applied after comparison) check box, enter a value for the Outbound Migrate Profile (applied after comparison) field.
         3. In the Import Input Fields section, enter values for the following fields:
            
            1. CDL PDS and Member Name
            2. If you select the Use Inbound Migrate Profile check box, enter a value for the Inbound Migrate Profile field.

         4. In the Analysis Input Fields section, enter values for the following fields:

            1. Worklist PDS and Member Name

            2. (Optional) Impact Report PDS and Member Name
         5. In the Execution JCL Generation Input Fields section, enter values for the following fields:
            1. Execution JCL PDS and Member Name
            2. Enter values for the fields in the following sections:
               • Before Making Schema Changes
                 Select one of the following options in the Select Baseline Type Before Execution field:
                 • None
                 • Pre-Execution baseline
                 • Full Recovery baseline
                 For more information about baselines, see the BMC AMI Change Manager for Db2 .
                 If you are creating a Pre-Execution or full-recovery baseline, enter values for the following fields:
                 1. Baseline Profile Name (before execution)
                 2. Baseline Name (before execution)
               • Rollback Compare
                 If you select the Generate CDL to Rollback Schema Changes check box, enter a value for the Rollback PDS and Member Name (CDL) field.
               • After Making Schema Changes
                 If you select the Create Baseline After Execution check box, enter values for the following fields:
                 1. Baseline Profile Name (after execution)
                 2. Baseline Name (after execution)

         6. In the Job Information section, enter values for the following fields:

            1. Job Card
            2. JCL
            The product generates values for the following fields based on your input for the Comparison Type and Object Type fields and the fields in the Import Input Fields, Analysis Input Fields and Execution JCL Generation Input Fields sections.
            
            1. Compare Input Stream
            2. Import Input Stream
            3. Analysis Input Stream
            4. JCL Generation Input Stream
         7. In the Advanced Settings section, enter values for the following fields:
            1. Acceptable Return Code
            2. Maximum Job Wait Time

         Important

         • You can select one of the following check boxes to apply change rules from a migrate profile:

           • Use Outbound Migrate Profile (applied after comparison) in the Post Compare section. The migrate profile is applied to the CDL file after comparison.
           • Use Inbound Migrate Profile in the Import Input Fields section. The migrate profile is applied to the CDL data during import to an ALTER work ID.
         • You can only select the Generate CDL to Rollback Schema Changes check box if you have selected the Create Baseline Before Execution check box.
         • BMC AMI DevOps lets you roll back the schema changes implemented by the current project build. For more information about rolling back schema changes, see Rolling back implemented schema changes in Jenkins.

         
         

      6. BMC AMI DevOps Schema Mgmt for Db2 - Schema Standards  (BMC.DB2.SPE2110)

          Click here for information about configuring this build step

         To configure the BMC AMI DevOps Schema Mgmt for Db2 - Schema Standards build step

         Use the following procedure:

         1. In the General Input Fields section, enter values for the following fields:
            1. SSID

            2. Schema Standards Rule Set name

               Important

               The Schema Standards rule sets and rules are defined and managed via the BMC AMI Command Center for Db2 product. For more information, see Managing schema rule sets .

            3. Violation Response
               
         2. In the Schema to Analyze section, enter values for the following fields:
            
            1. Source of Schema
               Select one of the following options:
               
               • DDL
               • CDL
               • Migrate Worklist
               • Catalog using Migrate Profile as scope
               • Catalog using Baseline Profile as scope (BMC.DB2.SPE2201)

            2. Input for Schema Source

               Important

               The value for the Input for Schema Source depends on the source of the schema you select:

               • If you select DDL, CDL, or Migrate Worklist in the Source of Schema field, enter the partitioned data set (PDS) name and member which contain the DDL, CDL, or Migrate Worklist that Schema Standards analyzes.
               • (BMC.DB2.SPE2201) If you select Catalog using Migrate Profile or Baseline Profile as scope in the Source of Schema field, enter the two-part name (owner. name) of the profile that contains the scope rules to identify the objects in the Db2 catalog that Schema Standards analyzes.
         3. In the Post Schema Analysis section, enter the values for the following fields:
            • (Optional) If you select the Use Outbound Migrate Profile (applied after objects are read) check box, enter a value for the Outbound Migrate Profile (applied after objects are read) field.

         4. In the Job Information section, enter values for the following fields:

            1. Job Card
            2. Schema Standards Input Stream
               
            3. Debug Input Stream
               
            4. JCL
               
         5. In the Advanced Settings section, enter a value for the Maximum Job Wait Time field.

      7. BMC AMI DevOps Schema Mgmt for Db2 - Output Transmission

          Click here for information about configuring this build step

         To configure the BMC AMI DevOps Schema Mgmt for Db2 - Output Transmission build step

         Enter values for the following fields:

         Important

         The BMC AMI DevOps Schema Mgmt for Db2 - Output Transmission build step lets you download any or all of the generated artifacts (CDL file, worklist, impact report, and execution JCL) to the destination directory. To download an artifact, enter its respective source PDS name.

         You must enter the source PDS name for at least one artifact.

         1. Source PDS Name (CDL)
         2. Source PDS Name (WORKLIST)

         3. Source PDS Name (EXEC_JCL)

         4. Source PDS Name (IMPACT REPORT)

         5. Source Member Name

         6. Destination Directory Name

         7. Destination File Name

      8. BMC AMI DevOps Common - JCL Execution

          Click here for information about configuring this build step

         To configure the BMC AMI DevOps Common - JCL Execution build step

         Enter values for the following fields:

         1. Run Step regardless of previous Compare results check box ( SPE2107 )
            

         2. Source of JCL ( SPE2107 )

            Important

            ( SPE2107 ) You can select any one of the following options in the Source of JCL field:

            • (Default) Submit JCL from file or member uses the JCL defined in the following fields:
              • Execution JCL PDS or Directory Name
              • Execution JCL Member or File Name
            • Submit free-form JCL defined below uses the JCL statement defined in the Free-form JCL field.
         3. Execute JCL from Mainframe PDS check box

         4. Execution JCL PDS or Directory Name

         5. Execution JCL Member or File Name
         6. Free-form JCL ( SPE2107 )
            
         7. Acceptable Return Code
         8. Maximum Job Wait Time

         Tip

         In some application or database environments (for example, QA, System Test or Production environments), you might need to review the impact and accountability of your project or pipeline. You can do this by reviewing the generated artifacts (impact report, worklist, and execution JCL) before running the BMC AMI DevOps Common - JCL Execution build step to apply the schema changes.

         You can verify the changes to your schema in the worklist and review the execution JCL before executing it as follows:

         1. Configure the project.
         2. Disable the BMC AMI DevOps Common - JCL Execution build step.
         3. Build the project. For more information, see To build a project.
         4. After your project is built successfully, review the worklist and execution JCL. For more information, see To review the output of a project.
         5. Run only the execution JCL by following these steps:
            
            1. Open the existing project for configuration.
            2. Disable all the build steps except BMC AMI DevOps Common - JCL Execution.
            3. We recommend you to use Run Step regardless of previous Compare results check box appropriately.
            4. Build the project. For the Job_ID parameter, enter the same value that you used in the build that generated the worklist and execution JCL.

         You can also include a prompt for approval to your automated process workflow to allow for review when using BMC AMI DevOps for Db2 along with other plug-ins as part of a Jenkins pipeline.

         For more information, view the following Quick Courses: BMC AMI DevOps for Db2 - Building a Pipeline - Part 1: Illustrates how to configure projects to compare databases and generate rollback artifacts without including the BMC AMI DevOps Common - JCL Execution build step BMC AMI DevOps for Db2 - Building a Pipeline - Part 2: Illustrates how to use BMC AMI DevOps as part of a pipeline Important This example also illustrates how to configure your pipeline script to send an email with the results of the comparison to an approver. Alternatively, you can configure the pipeline script to send an email to the approver before building the project that creates rollback artifacts. This would enable the approver to review the artifacts for impact and accountability before the pipeline continues running and implements the schema changes.

      9. BMC AMI DevOps Common -  Clean Up
         Add BMC AMI DevOps Common -  Clean Up as the last build step in your project to delete the workfile.properties file after processing all the other build steps.
   3. Click Apply to save the project, or Save to save and close the project.

Examples of how to add build steps during project configuration

The following examples illustrate how to add build steps to the project configuration.

For information about configuring the fields in each build step, see step 3 of the procedure to configure the project.

To use the configuration provided in the sample project

BMC has provided you with a ready-made sample project for your reference and convenience. The sample project folder contains the config.xml file for the project. You can customize the configuration available in the sample project instead of configuring a new project.

For more information, view the Quick Course BMC AMI DevOps for Db2 - Defining Sample Projects to Jenkins.

Follow this procedure to use the sample project:

1. Copy the project folder to the following directory:

    Click here if you are using Jenkins on Windows

   installationDirectory\Jenkins\jobs
   In this path, the installationDirectory variable represents the directory on the system on which Jenkins is installed.

    Click here if you are using Jenkins on Linux

   /installationDirectory/jenkins/jobs

   In this path, the installationDirectory variable represents the directory on the system on which Jenkins is installed.

2. Restart the Jenkins server and log in to Jenkins.
   The sample project appears on the Dashboard in the Jenkins web user interface.
3. Open the project for configuration.
4. Update the values of the fields based on your requirements. For more information, see To configure a project.

For the full list of sample values that you can configure for the different fields in the project, see Sample projects for Schema Change Migration and Sample projects for Schema Standards.

To run build steps in Debug mode

To view additional diagnostic information, you can run any or all the build steps in the Debug mode. To enable this feature, do one of the following:

• To run any build step in Debug mode, when configuring the build step, select the Run Step in Debug Mode check box.
• To run all the build steps in Debug mode:
  

  1. When configuring the project, add a Boolean parameter with the following field values:

     Field	Value	Notes
     Name	AMIDevOpsDebugOn	You must enter only this value for this field. However, this name is not case-sensitive.
     Default Value		Clear this check box.
     Description	Select this check box to run all the build steps in Debug mode.

     For more information about configuring parameters, see step 2.b of the procedure to configure a project.

  2. When building the project, select the AMIDevOpsDebugOn check box.

     Important

     Selecting the AMIDevOpsDebugOn check box runs all the build steps in Debug mode even if you have not selected the Run Step in Debug Mode check box when configuring any of the build steps.