This documentation supports an earlier version of BMC Helix IT Service Management on-premises deployment. To view the documentation for the latest version, select 23.3.04 from the Product version picker.


Replicating configurations and data from a source environment to a target environment

Replicate configurations and data from one environment to another by using the database refresh pipeline.

Related topics

Performing-the-BMC-Helix-IT-Service-Management-installation

Important

You can use the database refresh pipeline only for PostgreSQL databases.

The following scenarios describe the use case for replicating environment configurations and data:

Scenario 1

Apex Global wants to implement BMC Helix Service Management to address its business needs. The company plans to set up BMC Helix Service Management in both its non-production and production environments.

A system administrator at Apex Global installs BMC Helix Service Management  in both the non-production and production environments. The administrator then configures the nonproduction environment with the required configurations. To replicate the configurations in the production environment, the system administrator uses the database refresh pipeline.

Scenario 2

A new feature has been added to BMC Helix Service Management in a recent hotfix. Apex Global is interested in using this feature and wants to test it before implementing it in their production environment.

A system administrator at Apex Global replicates the production environment configurations in the QA environment by using the database refresh pipeline. The system administrator tests the feature in the QA environment and then implements it in the production environment.

Use the database refresh pipeline to replicate the following Foundation data, application data, and application configurations from a source environment to a target environment:

  • BMC Helix Innovation Suite configurations
  • BMC Helix ITSM: Smart Reporting configurations
  • BMC Helix Single Sign-On OAuth configurations
  • BMC Digital Workplace Catalog connectors configurations
  • BMC Digital Workplace configurations
  • Cognitive and BMC Helix Chatbot configurations
  • BMC Helix ITSM users
  • Web services filters

Important

You can run the database refresh pipeline on BMC Deployment Engine, that is the Jenkins server, on the source environment or target environment.


The following image shows the replication process:

Backup and restore process.png

Before you begin

  • Make sure that the source and target environments are using the same BMC Helix Service Management version.

  • Make sure that the PostgreSQL client such as psql version on your BMC Deployment Engine where you plan to run the pipeline and the PostgreSQL client version on your target database are the same.


  • Make sure that your BMC Helix Service Management target environment is licensed and that the number of licenses on the target environment and source environment are the same.
  • Make sure that you copy the source and target configuration repositories.

To copy the source and target configuration repositories

  1. In the source environment, copy the CUSTOMER_CONFIGS repository located in the directory that contains all the Git repositories in BMC Deployment Engine. Rename it to SOURCE_CUSTOMER_CONFIGS.
  2. In the target environment, copy the CUSTOMER_CONFIGS repository located in the directory that contains all the Git repositories in BMC Deployment Engine. Rename it to TARGET_CUSTOMER_CONFIGS.
  3. Copy the SOURCE_CUSTOMER_CONFIGS and TARGET_CUSTOMER_CONFIGS repositories to the environment where you want to run the database refresh pipeline.
    For example, to run the database refresh pipeline in the target environment, make sure that the following repositories are present in the git repository of the target environment:
    • SOURCE_CUSTOMER_CONFIGS
    • TARGET_CUSTOMER_CONFIGS
    • DB_REFRESH_REPO

Database refresh pipeline modes and parameters

Use the database refresh pipeline, HELIX_DB_REFRESH, to replicate configurations from one environment to another. 

The database refresh pipeline, HELIX_DB_REFRESH, provides the following modes:

  • BACKUP_CONFIGURATION—In this mode, the HELIX_DB_REFRESH pipeline backs up the configurations of the target environment.
  • RESTORE_CONFIGURATION—In this mode, the HELIX_DB_REFRESH pipeline restores configurations from one environment to another.

Important

  • You must run the HELIX_DB_REFRESH pipeline separately to backup and restore configurations. First, run the pipeline in BACKUP_CONFIGURATION mode and then in the RESTORE_CONFIGURATION mode.You cannot perform backup and restore in a single pipeline run.
  • Before running the HELIX_DB_REFRESH pipeline, make sure that all the platform and application pods are in a healthy state.

The database refresh pipeline, HELIX_DB_REFRESH, contains the following input parameters:

Parameter

Description

RERUN

Select this check box to rerun the pipeline from where it failed in the last run.

BACKUP_CONFIGURATION

Select this check box to back up configurations in the target environment.

RESTORE_CONFIGURATION

Select this check box to restore source database backup configurations to the target environment.

LOCATION

Specify the temporary working directory location of the pipeline.

Example: /home/git/workspace

REPO_PATH

Specify the repository path name where the SOURCE_CUSOTMER_CONFIGS, TARGET_CUSTOMER_CONFIGS, and DB_REFRESH_REPO repositories are located.

Example: ssh://<Jenkins server host name>/home/git/git_repo

SOURCE_CUSTOMER_NAME

Specify the CUSTOMER_NAME parameter value that you provided in the HELIX_ONPREM_DEPLOYMENT Jenkins pipeline during the installation of BMC Helix Service Management on the source environment.

SOURCE_CUSTOMER_SERVICE

Specify the CUSTOMER_SERVICE parameter value that you provided in the HELIX_ONPREM_DEPLOYMENT Jenkins pipeline during the installation of BMC Helix Service Management on the source environment.

SOURCE_ENVIRONMENT

Specify the ENVIRONMENT parameter value that you provided in the HELIX_ONPREM_DEPLOYMENT Jenkins pipeline during the installation of BMC Helix Service Managementthe source environment.

The HELIX_DB_REFRESH pipeline uses the SOURCE_CUSTOMER_NAME, SOURCE_CUSTOMER_SERVICE, and SOURCE_ENVIRONMENT parameters to identify the Deployment Input Configuration file location in the source environment.

TARGET_CUSTOMER_NAME

Specify the CUSTOMER_NAME parameter value that you provided in the HELIX_ONPREM_DEPLOYMENT Jenkins pipeline during the installation of BMC Helix Service Management on the target environment.

TARGET_CUSTOMER_SERVICE

Specify the CUSTOMER_SERVICE parameter value that you provided in the HELIX_ONPREM_DEPLOYMENT Jenkins pipeline during the installation of BMC Helix Service Management on the target environment.

TARGET_ENVIRONMENT

Specify the ENVIRONMENT parameter value that you provided in the HELIX_ONPREM_DEPLOYMENT Jenkins pipeline during the installation of BMC Helix Service Management on the target environment.

The HELIX_DB_REFRESH pipeline uses the TARGET_CUSTOMER_NAME, TARGET_CUSTOMER_SERVICE, and TARGET_ENVIRONMENT parameters to identify Deployment Input Configuration file location in the target environment.

TARGET_EXT_IP

Specify the PLATFORM_ADMIN_PLATFORM_EXTERNAL_IPS parameter value that you provided in the HELIX_ONPREM_DEPLOYMENT pipeline during the installation of BMC Helix Service Management on the target environment.
See Performing-the-BMC-Helix-IT-Service-Management-installation.

IS_DB

Select this check box to back up and restore BMC Helix Service Management configurations.

SMART_REPORTING

Select this check box to back up and restore BMC Helix ITSM: Smart Reporting configurations.

Task 1: To back up the source and target environment

Take a complete backup of your source and target databases.
Use your preferred method to back up the databases.

Task 2:  To back up configurations of the target environment

  1. Log in to the Jenkins server by using the following URL:
    http://<Jenkins server host name>:8080
  2. On the Jenkins server, select the HELIX_DB_REFRESH pipeline.
  3. Select the BACKUP_CONFIGURATION check box and clear the RESTORE_CONFIGURATION check box.
  4. Specify the values for the LOCATION and REPO_PATH parameters.
  5. Specify the values for the SOURCE_CUSTOMER_NAME, SOURCE_CUSTOMER_SERVICE, and SOURCE_ENVIRONMENT parameters.
  6. Specify the values for the TARGET_CUSTOMER_NAME, TARGET_CUSTOMER_SERVICE, and TARGET_ENVIRONMENT parameters.
  7. Specify the value for the TARGET_EXT_IP parameter.
  8. Select the IS_DB check box to back up BMC Helix Service Management configurations.
  9. Select the SMART_REPORTING check box to back up BMC Helix ITSM: Smart Reporting configurations.
  10. Click Rebuild.

The HELIX_DB_REFRESH pipeline runs in the BACKUP_CONFIGURATION mode. It creates a backup of the configurations and scales down all the application pods.

The pipeline creates the backup files and folders at the custom workspace location <LOCATION>\HELIX_DB_REFRESH\<Source_DB_Name>.

Task 3: To restore the source database backup to the target environment

After the database refresh pipeline is completed successfully in the BACKUP_CONFIGURATION mode, restore the source database backup to the target database.

Use your preferred method to restore the database backup.

After you restore the backup, the target database contains the source environment configurations and source environment data.

Task 4: To restore configurations to the target environment

  1. Log in to the Jenkins server on the environment where you want to run the pipeline by using the following URL:
    http://<Jenkins server host name>:8080
  2. On the Jenkins server, select the HELIX_DB_REFRESH pipeline.
  3. In the Build History, select the latest build and click Rebuild.
  4. Clear the BACKUP_CONFIGURATION check box.

  5. Select the RESTORE_CONFIGURATION check box.

    Important

    Do not modify other parameter values.

  6. Click Rebuild.

The pipeline runs in the RESTORE_CONFIGURATION mode. It restores the configurations and scales up all the application pods.

After you restore the configurations, the target database contains the target environment configurations and source environment data.

Important

  • The HELIX_DB_REFRESH pipeline checks the status of all pods every two minutes and has a timeout of 60 minutes. If a pod fails to start during the Check Pod Status stage, restore the pod to a normal state before the timeout.
    When all the pods are up and running, the pipeline proceeds automatically.
  • If the clamav pod fails to start during the Check Pod Status stage, scale down the pod by using the following command:
    kubectl scale deployment clamav --replicas=0 -n <Target environment namespace>After the pipeline execution is completed, scale up the clamav pod by using the following command:
    kubectl scale deployment clamav --replicas=<replica count> -n <Target environment namespace>

To rerun the HELIX_DB_REFRESH pipeline

If you encounter a failure in BACKUP_CONFIGURATION or RESTORE_CONFIGURATION mode while you are running the  HELIX_DB_REFRESH pipeline, use the RERUN option to rerun the pipeline.

  1. On the Jenkins UI, navigate to the HELIX_DB_REFRESH pipeline where the failure occurred.
  2. In the Build History pane of the pipeline where the failure occurred, select the latest build, and click Console Output.
  3. On the Console Output page, go through the logs to identify the reason for the failure.
  4. Debug and fix the issue.
  5. Rerun the HELIX_DB_REFRESH pipeline.
    1. Navigate to the pipeline where the failure occurred.
    2. In the Build History pane of the failed pipeline, select the latest build, and click Rebuild.
    3. On the Rebuild page, select the RERUN check box , and click Rebuild.
      The pipeline starts running from the stage where it stopped due to the failure.

 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*