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

Performing the BMC Digital Workplace upgrade

This topic describes how to use the GUI wizard installer to upgrade BMC Digital Workplace on a single server. Other options for running the installer are described in Performing the BMC Digital Workplace installation.

Before you begin

Complete the tasks described in Preparing for a BMC Digital Workplace upgrade. Version 18.05 introduces architecture changes, such as a change from MongoDB to the RDBMS. This upgrade includes new preparation tasks to prepare for these changes.

Be aware of the following changes introduced in version 18.05:

  • The installer will only upgrade BMC Digital Workplace. If you are using BMC Digital Workplace and Smart IT, you must upgrade BMC Digital Workplace before upgrading Smart IT. For information on upgrading Smart IT (after you upgrade BMC Digital Workplace), see Performing the Smart IT upgrade .
  • You must move your social data from MongoDB to the RDBMS that you use for installing BMC Digital Workplace. You can choose to migrate your data along with the upgrade or use the migration utility provided with the installer for moving your data.
  • Users who have never logged in to BMC Digital Workplace will not be considered as valid users, and will not be migrated to BMC Digital Workplace 18.05.
  • User profile images are stored separately for Smart IT and BMC Digital Workplace. The modifications made in either products will be independent of the other.
  • Broadcast messages sent by BMC Digital Workplace administrators will not be received by Smart IT users.
  • BMC Digital Workplace locations and assets will not be available to agents while creating work orders or incidents using Smart IT.
  • The Smart IT Active Users Report will not be available in the BMC Digital Workplace Admin console if Smart IT was upgraded to version 18.05.

To upgrade BMC Digital Workplace on a single server

Best practice

Do not use Xming to install the BMC Digital Workplace server, because it might not perform reliably during installation. Instead, use VNC, MobaXterm, or any other client.

  1. Unzip the suite installer (for example, DigitalWorkplaceV.V.V.windows.zip or DigitalWorkplaceV.V.V.linux.tar.gz where VV.VV.VV and V.V.V indicates the version number of BMC Digital Workplace).
  2. Navigate to the Disk 1 folder.
  3. Start the installer:
    • For Windows, run setup.exe.
    • For UNIX, run setup.bin.

  4. On the Welcome panel, click Next.
  5. Review the license agreement, click I agree to the terms of license agreement, and then click Next.
  6. Review the details of this upgrade and decide if you want to perform the upgrade now or later:
    • The use of MongoDB is discontinued, and your social data will be migrated to your BMC Digital Workplace RDBMS. You can choose to migrate your data along with the upgrade or use the migration utility for moving your data after the upgrade is complete.
    • You will be allowed to select a new database schema for the MongoDB data or use the BMC Digital Workplace database schema.
    • The installer will only upgrade BMC Digital Workplace. If you were using BMC Digital Workplace and Smart IT, your BMC Digital Workplace data will be copied to a new database schema.
      • Smart IT will continue to work without being upgraded. If you choose to upgrade Smart IT, you must do it AFTER upgrading BMC Digital Workplace. For information on upgrading Smart IT, see  Performing the Smart IT upgrade .
  7. Enter the values from the Upgrade worksheets.
    After you have entered the required information, the installer validates your input.
  8. Select the directory.
  9. BMC recommends that you back up the following databases before performing an upgrade in your production environment: 
    • BMC Digital Workplace database 
    • BMC Remedy AR System database
    • MongoDB database

    In case of upgrade errors related to database schemas or AR System workflow, you can use the backups to restore the databases and resume the upgrade from the last successful step.
  10. If you have BMC Digital Workplace Catalog installed, select the checkbox if you want to switch to using BMC Digital Workplace.
  11. Select one of the following options depending on your existing set up:
    1. I use Smart IT and Digital Workplace
      You will be asked to enter database information for a new schema to use as the database for Digital Workplace.The Digital Workplace data will be moved to the new database or schema. Smart IT will continue to work after the upgrade completes, and will continue to use the database or schema it is currently using. Also, you should first run the pre-export utility in the Data Migration Tool to find out whether you should choose the third option below to run data migration separately after install. 
      Select this option to migrate the BMC Digital Workplace data to a new database. This will allow Smart IT to continue working using the existing database, however you must upgrade Smart IT to use the integration between Smart IT and BMC Digital Workplace.

    2. I am not using Smart IT

      BMC Digital Workplace will continue to use the existing database or schema.

      Select this option if you are NOT using Smart IT and only using BMC Digital Workplace.

    3. I use SmartIT and Digital Workplace, and I need to run the data migration separately after install

      You will be asked to enter database information for a new schema to use as the database for Digital Workplace. The new schema and tables will be created, but no data will not copied to the new schema or database during this install. Use this option if you ran the pre-export utility in the Data Migration Tool and the results indicated that you need to run the data migration separately from the install so you can adjust parameters to deal with large attachments.

  12. Select the following option if you are upgrading a POC (Proof of concept) or test environment that has limited amount of social data on your MongoDB. If you do not choose to migrate your social data as part of the upgrade, you must use the migration utility to migrate the social data before you can use BMC Digital Workplace. Use the utility to estimate the size of data based on when it was created, instead of migrating all the data.

    Run the Digital Workplace migration of Social and Notifications data now

    This will copy needed data from MongoDB to a new RDBMS schema. If this option is cleared, Digital Workplace will not work properly after upgrade until you run the separate migration utility manually.

  13. Decide if you want to create a new database or use a pre-created database and provide the required details.
  14. Review the list of services stopped by the installer and make sure to start the services that are required after the upgrade is complete.
  15. After post-upgrade cleanup, a summary of the installation appears.
  16. From the installation summary, review the information and any instructions. For example, if there was a database update failure, you can recover and run the upgrade again if you have a backup of your database and perform the recovery steps:
    1. Restore the database by using the backup created in step 6.
    2. View the installation log files to find and correct the cause of failure. For example, review any SEVERE error messages or warnings in the product installer log. See whether errors are due to network, host, or other environment-related issues. You can view a log file of the installation: 
      • C:\Users\Administrator\AppData\Local\Temp\digital_workplace_install_log.txt (Windows) 
      • /tmp/digital_workplace_install_log.txt (Linux)
    3. Run the installer again. The upgrade will resume from the last successful step.
  17. Click Done to exit the installer.


    When the DWP Application service starts for the first time after the upgrade, the total processor utilization across all cores will increase for the first few minutes. The increase in total processor utilization will depend on your server configuration and other applications running on the same server.

To update configuration details in a secure application server environment

If you configured SSL for the Tomcat server, you must update the following files. These configuration steps add a dedicated HTTP connector to Tomcat, that is available from only from the localhost (not available from outside), and configures the social server to use that connector.

  1. Navigate to <Tomcat_Home>/conf/server.xml, and add the following details for the HTTP connector. 

     <Connector address="" connectionTimeout="20000"
                     server=" "/>
  2. Navigate to <Tomcat_Home>/external-conf/connect-dwp.properties, and update the port number for the social server.

    # Social connection settings
    social.server.protocol = http
    social.server.host = localhost
    social.server.port = 9001
    social.user.autocreate = false

To migrate your social data and update the database location

Starting with version 18.05, BMC Digital Workplace no longer uses MongoDB. Follow the procedure below if you did NOT migrate the social data as part of the upgrade process.


Contact BMC Support to obtain an improved version of the migration utility.

  1. Navigate to the social data migration utility:
    • <DigitalWorkplaceHome>\DWP\social2-migration\migration-scripts\scripts\windows (Windows)
    • /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 DWP_DB_JDBC_CONNECTION_URL=jdbc:oracle:thin:@<DWP_database_server>:<port_number>:<database_name>
    set DAYS_BEFORE=<The period for which you want to transfer the notification and social data For example, 30>
    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. If you did not estimate the number of notifications and size required for the migration, as a part of Preparing for a BMC Digital Workplace upgrade, 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.

    • migrationNotificationConsult.bat (Windows)

    • 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              │

  5. Run the following script to migrate data from the MongoDB database to your BMC Digital Workplace relational database.


    Edit the DAYS_BEFORE parameter in theset_env file to customize the period (in number of days) for which you want to transfer data.

    • migrationAll.bat (Windows)

    • migrationAll.sh (Linux)
  6. Follow the steps given below if you are using BMC Digital Workplace in a cluster.

     Click here to expand and view the steps...
    1. Navigate to <Tomcat dir>/conf/Catalina/localhost
    2. Update the social.xml file with details for the new database.

      <Parameter name="spring.datasource.url" value="jdbc:oracle:thin:@<database_server>:<database_port>:<database_name>"/>
      <Parameter name="spring.datasource.username" value="<user_name>"/>
      <Parameter name="spring.datasource.password" value="<password>"/>
  7. Start the DWP Application service.


    When the DWP Application service starts for the first time after the upgrade, the total processor utilization across all cores will increase for the first few minutes. The increase in total processor utilization will depend on your server configuration and other applications running on the same server.

  8. After the social data is successfully migrated, social data such as posts, pictures, and thumbnails will be available.

To troubleshoot issues with data migration

  1. In case of a migration failure or error, navigate to the social migration log to debug:


    Set the logging level to INFO to collect INFO, WARNING, and ERROR events.

    • <Digital_Workplace_Home>\social2-migration\logs\social.log (Windows)

    • <Digital_Workplace_Home>/social2-migration\logs\social.log (Linux)

  2. After debugging the issue, run the following command before retrying the migration

    • migrationClean.bat (Windows)

    • migrationClean.sh (Linux)

To upgrade BMC Digital Workplace in a cluster

  1. Upgrade BMC Digital Workplace on the first server, as described in To upgrade BMC Digital Workplace on a single server earlier in this topic.
    You can run the first upgrade on the primary server, or on any of the secondary servers.
  2. Upgrade BMC Digital Workplace on each of the other servers in the cluster.
    For each of these additional upgrades, the application is upgraded on the applicable server. However, the AR System server and database are not updated, because they are updated when you run the upgrade on the first server.


    You can save time by upgrading the other servers in parallel. However, you should start the additional upgrades only after completing the upgrade for the first server.

Where to go from here

Verifying the BMC Digital Workplace installation

Install Patch 1 for version 18.05.00, which includes a clean up utility

If you do not install the patch, verify the BMC Digital Workplace installation, and manually clean up your server

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


  1. Tomã¡s Almida miguel

    Hi, I execute "MigrationAll.bat (Windows)" but I observe in the logs that the data is not migrated by the following error:

    WARN 4992 --- [main] c.b.d.d.s.n.m.s.parser.ParserMigration

    java.text.ParseException: Unparseable date:

    I can't find anything about this error either in the communitys or in online documentation, how can I solve this error?

    Oct 22, 2019 02:23
    1. Ravee Panjwani

      Thanks for your comment, Tomã¡s Almida miguel.

      I am looking into this, and will get back to you with an update.

      In the meanwhile, can you please confirm the version of BMC Digital Workplace from which you are upgrading to version 18.05?

      Also, please review the troubleshooting information available on this page → Troubleshooting installation and upgrade issues in BMC Digital Workplace.


      Oct 23, 2019 12:29
  2. Tomã¡s Almida miguel

    Hi,thanks for you comment Ravee,

    I am updating from version 3.3.02. I have followed BMC online documentation at all times, this point would be:


    My goal is to go up to 19.08, I have also tried to go up to 18.05 patch1 and from there to 19.08 but the manual migration shows me the same error. I have an open incidence of support for BMC (00778065). However, I will look at the URL you provided. Thanks and best regards.

    Oct 24, 2019 01:41
    1. Ravee Panjwani

      Thanks again for letting us know, Tomã¡s Almida miguel. I hope the URL has information that will help you troubleshoot the issue.

      I consulted with my team, and they recommended you continue working with BMC Support.


      Oct 25, 2019 01:29
  3. Dalwinder Singh

    Can we have a sample setenv.bat file ... have tried every possible way to trigger but seems i missed somethig.

    May 25, 2020 11:12
    1. Ravee Panjwani

      Thanks for your comment, Dalwinder. This file is packaged with the installer, and we will need more information to be able to help you troubleshoot. Please let me know if you had a chance to speak with the Customer Support team. 


      Jun 02, 2020 08:54