Unable to render {include} The included page could not be found.

Preparing for a BMC Digital Workplace upgrade

Complete the following tasks:   

TaskActionAdditional information

Review the system requirements

Make sure that you meet the system requirements for this release.
2Review the known and corrected issues
3Complete the upgrade worksheetsBefore you start installing the products, you must gather information about the parameters that the installer requires for each product. The planning spreadsheet provided in this section helps you gather these parameter values. To avoid installation errors, refer to this spreadsheet when you run the installation.
4Downloading the BMC Digital Workplace installation filesThis topic explains how to obtain the files that you need for the upgrade from the BMC Electronic Product Distribution (EPD) site.

Apply patch 1 for BMC Remedy AR System 9.1.04

This patch enables cognitive service management.

Prepare your relational database by estimating the space (and time) required to copy the social and notification data stored in the MongoDB database to your RDBMS.


Run the upgrade on at least one environment to get the social data migration utility.

Before migrating your social data, you must estimate the space you will need on your relational database. The space required on your relational database, and time needed for the upgrade can vary according to how much notification data you keep, determined by the setting described below.


The MongoDB database contains a lot of data that will not be moved to your relational database. In some cases the vast majority will not need to be copied over because it is redundant or not needed for . So, the current size of your MongoDB database does not indicate the space you will need in the relational database after the migration.

  • The retention period for notifications will have a direct impact on the space and time required.
    For instance, 1 month of data requires ~500 MB and takes ~15 minutes to transfer
  • Use the historical data consumption values on your MongoDB as a reference to calculate the free space required on your relational database.
    For instance, if the space required for 1 month is 500 MB, you need to factor in a proportional increase in capacity to accommodate the data.
 Click here to view the procedure for estimating the size of your notification data on MongoDB
  1. Navigate to the social data migration utility
    1. <DigitalWorkplaceHome>\DWP\social2-migration\migration-scripts\scripts\windows (Windows)
    2. /opt/bmc/DWP/social2-migration/migration-scripts/scripts/linux (Linux)
  2. Stop all the social services that communicate with the MongoDB
  3. Edit the setenv.bat or setenv.sh file to provide the following details for your environment:

    set MONGO_DB_CONNECTION_URL=mongodb://<MongoDB_database_server>:<port_number>/<database_name>
    set CONSULT_MIGRATION_NOTIFICATIONS_PERIOD_1_IN_DAYS=<First period for which you want to estimate the data size. Default is 30>
    set CONSULT_MIGRATION_NOTIFICATIONS_PERIOD_2_IN_DAYS=<Second period for which you want to estimate the data size. Default is 90>
    set CONSULT_MIGRATION_NOTIFICATIONS_PERIOD_3_IN_DAYS=<Third period for which you want to estimate the data size. Default is 365>
    set SOCIAL2_MIGRATION_LOG_LEVEL=<The log level>
    set SOCIAL2_MIGRATION_LOG_FILE=<Name and location of the log file>
    set SOCIAL2_MIGRATION_LOG_FILE_MAX_SIZE=<The size to limit the log file>
  4. Run the following script to receive an estimate on the number of notifications and size required for the same.


    The default estimation periods are set to 30, 90, and 365 days. Edit the set_env file to change the default estimation periods.

    1. migrationNotificationConsult.bat (Windows)

    2. migrationNotificationConsult.sh (Linux)
Example output of the migrationNotificationConsult script
│Period in days     │Number           of│Estimated migration│Estimated DB  size│
│                   │notifications   not│time (secs)        │required (MB)     │
│                   │older than period  │                   │                  │
│30                 │0                  │0                  │0                 │
│90                 │1                  │0                  │0                 │
│365                │5357346            │8928               │7663              │
│All                │5663115            │9438               │8101              │


(optional) Estimate the size of the attachments on your existing BMC Digital Workplace installation and decide if you want to only move attachments larger than 5 MB.

Before migrating your BMC Digital Workplace data, you may check for and move attachments that are larger than 5 MB, and choose to not migrate these attachments.


This step is optional. You must use the utility provided with your current version of BMC Digital Workplace to identify large attachments. The utility provided with version 18.05 will not work with older versions of BMC Digital Workplace.

 Click here to view the procedure for estimating the size of the attachments on BMC Digital Workplace

The pre-export tool provides the following information:

  • The number of records and total size of attachments in the ATTACHMENT and SOCIAL_ATTACHMENT tables.
  • The first 20 attachments in the database that are larger than 5 MB from each table.
  • The heap size required for the data transfer. Set the JAVA_OPTS parameter in the set_env.bat before exporting.
    • For example, if you need 15GB, set JAVA_OPTS="-Xmx15G”

To run the pre-export

  1. Open set_env.bat and fill in all required fields.
  2. Modify .\connection\<database_type>.connection.properties  and provide your current BMC Digital Workplace database information.
  3. Type "run_pre_export.bat" from the console.

To run the export

  1. Open set_env.bat and fill in all required fields.
  2. Modify .\connection\<database_type>.connection.properties  and specify required DB information there.
  3. Type "run_export.bat" from the console.

Use the "--overwrite" option with the run_export.bat to overwrite the output_file_path file.

To run the data_dump

  1. Open set_env.bat and fill in all required fields.
  2. Export the data from the database and save it to a zip file
    1. For Windows, run data_dump.bat
    2. For Linux, run data_dump.sh

    Attachment count
    table size
    Max heap
    Max heap
    1618 MB9.513610.612
    20005.5 GB9.721810.316.5
    49008.8 GB10.725313.728.3


    The above values depict the time required on various test environments, however the actual time required will depend on your environment and network factors such as latency.


If you are upgrading from the versions 3.3.02-3.5 or 18.05, you must Install the ITSM integration patch.

Before you upgrade BMC Digital Workplace, you must install the ITSM integration patch. This patch enables  BMC Remedy IT Service Management (BMC Remedy ITSM) to work with BMC Digital Workplace. Without this patch, timelines, email notifications, and social features do not work in BMC Digital Workplace. The installation applies required BMC Remedy ITSM patches.


This patch replaces the User Experience patch that was provided with previous releases of BMC Digital Workplace.

9Upgrade to 64-bit Java Runtime Environment (JRE) 8.

Upgrade to JRE 8 on all the servers where you have BMC Digital Workplace installed.


Take a backup of BMC Remedy AR server database, MongoDB database, and BMC Digital Workplacedatabase.

To recover from any unexpected upgrade failure and resume upgrade from the last executed stage, take a back up of the following databases:

  • BMC Remedy AR Server
  • MongoDB
  • BMC Digital Workplace

Was this page helpful? Yes No Submitting... Thank you


  1. Raghuram Guggilam

    We followed this step "Skip this step only if you are upgrading from BMC Digital Workplace 18.02, and have installed the User Experience Version 18.02.00 patch for Remedy ITSM.", But after Upgrading 18.05 it has been removed few forms which starts with "MYIT:*".

    Then, we tried to install Integration Patch which resolves the issue. I hope, this sentence need to be corrected. For upgrade, we must need to install integration patch irrespective of UX patch.

    Could you please check once and update accordingly.

    Jan 13, 2020 01:07
    1. Olha Horbachuk

      Thanks for your attentiveness, Raghuram Guggilam. The changes will be available after publishing.

      Jan 13, 2020 04:14