Managing analysis projects

Scan and manage analysis projects by using the Z Understand container.

1. Create a project.
   1. Navigate to the Z Understand container folder in the Terminal by running the following command:

      cd /opt/wca4z-understand

   2. Optional: Run the cli.sh script without any parameters or with the --help parameter to see all the possible project-related actions and their syntax.

          -c [ --create ] arg                        create project, where <arg> is a project configuration file name located in the 'config/projects' folder
          -d [ --delete ]                            delete project
          --delete-forced                            force delete project in case of read locks
          -r [ --rename ] arg                        rename project <project_name> where <arg> is the new name of the project
          -b [ --build-project ]                     build the project
          -m [ --make ]                              make the project
          --build-selection arg                      build selection on the project, where <arg> is a project configuration file name located in the 'config/projects' folder
          -s [ --set-property ] arg                  update a specific property(key) from the project settings, where arg is: <key_to_update> <new_value>
          --list-properties                          list all the current project properties
          -u [ --update-config ] arg                 update project configuration properties, where arg is the full path to the .ini input file.
          -l [ --log-level ] arg                     specify a log level such as D,I,W,E (or Debug, Info, Warning, Error)
          --ls                                       list all the existing projects
          --pj-upgrade                               project repository upgrade
          --update-pj-def                            update project definition in database (project type and project properties)
          -si -api-key <api_key>                     run semantic indexing (required only for CPD environment)
          -si -m code -api-key <api_key>             run semantic indexing in code mode (required only for CPD environment)
          -si -m explain -api-key <api_key>          run semantic indexing in explain mode (required only for CPD environment)
          -si-brd -api-key <api_key> <project_name>  run BRD indexing (required only for CPD environment)
          -doc -api-key <api_key> -watsonx-url <url> run Doc Generation tool for the whole project
               -watsonx-api-key <key> -watsonx-project-id <id> <project_name>        

   3. Prepare the configuration file for the project creation. A list of sample files is provided in the config/projects/samples folder. Open the folder and list the available sample files by running the following command:

      cd config/projects/
      ls samples

   4. Clone the sample file that corresponds to the type of relational database server that you configured. For more information, see 4.d in the configuration instructions.
      For example, clone the sample file for Microsoft SQL Server by entering the following command:

      cp samples/new_proj_sql.ini .

   5. Open the cloned sample file by running the following command:

      vi new_proj_sql.ini

   6. Modify the file as follows:
      1. Press the i key on the keyboard to enable keyboard input in the editor.
      2. Replace the line comments, which represent the properties in the file, with actual values.

      Note: If you are creating an analysis project from a migrated Windows project, see Migrating analysis projects from the Windows server.
   7. Press the Escape key on the keyboard to exit insert mode. Then, save the file to disk and exit the editor by typing :wq and pressing the Enter key.
   8. Create a project by running the following command:

      cd ..
      ./cli.sh -c new_proj_sql.ini <PROJECT_NAME>

   A project folder is created under the projects/<PROJECT_NAME> folder.
2. Add files to the project.

   Creating the project also creates a specific folder structure that is named and organized by object type. Add the source files to be analyzed to the appropriate project folders. The list of project folders can differ according to the chosen settings during the project creation. For information about each folder type, see The project folder types.

3. Scan the project.
   To do so, run the following command:

   ./cli.sh -b <PROJECT_NAME>

   The progress of the operation is displayed in the Terminal.

4. Index the source code of the new project to improve the AI Chat answers. To do so, run the indexing commands from the Terminal. These commands are required for a Cloud Pak for Data (CPD) environment. Two types of indexing commands are available:
   1. The semantic indexing, which uses AI to generate explanations for every paragraph in the application. Run the semantic indexing for a new project or if the source code of a project has changed.
      To run the semantic indexer, enter the following command:

      ./cli.sh -si -api-key <API_KEY> <PROJECT_NAME>

      2.7.20+ You can use the explain parameter to improve the quality of the explanations. With this parameter, the semantic indexer generates explanations for the source code by using the AI model and indexes the explanations. This index has better quality for the purpose of retrieval. However, indexing takes more time as the explanations are generated first. If you want to use this parameter, enter the following command:

      ./cli.sh -si -m explain -api-key <API_KEY> <PROJECT_NAME>

      2.7.20+ You can use the mode parameter to reduce the indexing time. With this parameter, the semantic indexer indexes the code itself without involving the AI model. If you want to use this parameter, enter the following command:

      ./cli.sh -si -m code -api-key <API_KEY> <PROJECT_NAME>

   2. 2.7.20+ The business rules indexing, which indexes the stored business rules. Run it for a new project or if business rules have been added to a project.
      To index the business rules, enter the following command:

      ./cli.sh -si-brd -api-key <API_KEY> <PROJECT_NAME>

   Note: In all the commands, <API_KEY> is an IBM Cloud® API key.
5. Optional: 2.8.0+Run the Doc generation tool to automatically create accurate, easy-to-navigate program and application documentation. For more information, see Generating documentation with the Z Understand Linux container.