Phase 4: Build your service desk from scratch or migrate existing data

On this page

Introduction

With planning complete, it’s time to execute your migration. Follow your migration plan to ensure minimal disruption. Leverage SolarWinds support and documentation to guide the process, test key functionalities, and validate data integrity before going live.

This page describes the tasks for migrating your existing data from Web Help Desk. Before you begin migration tasks, be sure you have completed the first three phases in the process:

• Phase 1: Assess your organization's needs and Service Desk
• Phase 2: Plan your migration
• Phase 3: Prepare for your migration

After completing Phases 1-3, you decided on the best transition approach for your organization.

• If you decided to build from scratch, see Build from scratch tasks.
• If you decided to migrate existing data, see Migrate existing data from Web Help Desk.

See the PDF version of this Migration Guide.

Build from scratch tasks

You've already assessed your organization's needs, planned for the transition to Service Desk, and completed the preparation process.

1. It's time to Begin initial setup by building the foundational building blocks of your service desk.

2. Set up and design your service portal. The service portal is for the customers of the services your service desk provides. See Service Portal overview.

3. Review the contents of the Administrator Setup Guide and set up the features you identified in the assessment, planning, and preparation processes.

4. When setting up your Service Desk from scratch, it is still possible to migrate over some data using CSV imports. See CSV file imports, updates, and exports.

Migrate existing data from Web Help Desk

Migration prerequisites

1. Back up your Web Help Desk database. Instructions are available on the Prepare your Web Help Desk database page under Back up the PostreSQL database.

2. Restore the backup on a Web Help Desk-equivalent production/test server. Be aware that the migration utility:

   • Is not compatible with legacy Web Help Desk. It supports Web Help Desk 12.7.7 and later versions.

   • Is not compatible with legacy MSSQL Server 2008. Your database backup needs to be restored on MSSQL Server 2012+.

   • Is not compatible with legacy PostgreSql 9. Your database backup needs to be restored on PostgreSql 13.

3. Ensure:

   • Your Service Desk account is on the Advanced or Premier plan.

   • You have access to your Service Desk account with Account Owner privileges.

   • You have access to Web Help Desk Database using the same login as the one configured in the Web Help Desk application.

   • You have collected the following information about your instance of Web Help Desk Database: database name, username, password, IP address, and port number. You will need the information during the configuration process.

Common configurations for all operating systems

Create/Update Ticket/Incident status and Asset status:

Ticket and asset statuses differ between Web Help Desk and Service Desk. If the ticket/incident does not match, it will be updated based on the available/configurable status. If the asset status does not match, it will be adjusted to Operational.

1. In Service Desk, navigate to Setup > Global Settings > Custom States.

2. To see the custom states related to incidents, click the Incidents tab.

   

3. Create a Custom State for assets by clicking + Custom State.

Set up allowed domains:

1. In Service Desk, navigate to Setup > Global Settings > Service Portal.

2. Scroll down to Allowed Domains.

3. Remove all domains from the text field and click Update.

   

Disable Service Desk notifications:

1. In Service Desk, navigate to Setup > Service Desk > Notifications.

2. Disable all notifications from the Send to column to stop alerts during migration.

   

Two options are available for migrating data

If your server OS is Windows or Mac, you can use the migration tool embedded with Web Help Desk v 12.8.8. For any other OS, follow the Migration steps for Linux servers or External Utilities.

Use the migration UI tool embedded with Web Help Desk if your OS is Windows or Mac

1. Launch the migration utility.

   1. Go to the Web Help Desk server machine and login into the Web Help Desk application with an admin user account.

   2. Go to Setup -> General -> Migrate Your Data. Scroll down to the bottom and click Start Migration.

      

   3. From the confirmation alert popup, click OK.

      

      The utility tool launches after confirmation.

      

2. Configure Service Desk account and JWT token.

   1. In Service Desk, navigate to Setup > Account > Account Summary and copy the Account URL from that page.

      

   2. Go to the utility tool and add your account URL. Be sure to add https:// before the URL.

   3. In Service Desk, navigate to Setup > Users & Groups > Users.

   4. In the Name column, select the user account (with Administrator role) that was used to set up your Service Desk account.

   5. Click Actions, and from dropdown select Generate JSON Web Token.

      Directly under the Default Landing Page field, the JSON Web Token field expands to show the new token.

      

   6. Click Copy.

   7. In the utility tool, paste the Web Token and click Test Connection to validate the URL and token.

3. Optional configuration.

   

   • Configuration settings to migrate data for specific time ranges:

     • Ticket filter fromDate - If you want to migrate data for the last 3-6 months or the last half year, set the fromDate in Ticket filter to fromDate field. Example: Default fromDate value: 01-Jan-2001

     • Ticket filter toDate - If you want to migrate data up to a specific date, set the toDate in Ticket filter to toDate field. Example: Default toDate value: CURRENT_TIMESTAMP

   • Migrate Assets as non-chargeable - The utility tool moves all assets based on their categorization and whether they are chargeable. If this setting is disabled, all assets are moved to the Other_Assets category and IP address information is stored in the Description details.

   • Migrate Asset name with numbers - The utility adds Asset: as a prefix to the asset name, resulting in the asset name Asset: + AssetNumber. If this setting is enabled, the asset name becomes only AssetNumber.

4. Click Next to move to the next screen, Progress Dashboard.

   

5. Familiarize yourself with the data migration screens.

   

   The tabular data shows the total count of the data available in Web Help Desk and success / failure count of migrated data.

   • Download Migration Details: downloads respective entity success and failed json files of migrated data in the specified directory.

   • Download Complete Logs: downloads a zip file of the log folder in the specified directory.

   • Download Current Logs: downloads the latest log file in the specified directory.

   The tabs for migrating Web Help Desk data.

   • Metadata - Migrates all metadata (Locations/Sites, Departments, Categories, Custom Fields, Tech, Clients and User Groups) from Web Help Desk to Service Desk.

     *The Metadata option is mandatory.

     

   • Ticket

     

     • Parent Tickets - Migrates all parent incidents data from Web Help Desk to Service Desk.

     • Child Tickets - Migrates all child incidents data from Web Help Desk to Service Desk.

     • Ticket Notes - Migrates all client/tech notes data from Web Help Desk to Service Desk.

     • Ticket Attachments - Migrates all Ticket and Notes attachments data from Web Help Desk to Service Desk.

     • Ticket Status Update - Updates all migrated Ticket status from Web Help Desk to Service Desk.

   • FAQ

     

     • FAQ - Migrates all FAQ data from Web Help Desk to Service Desk.

     • FAQ Attachments - Migrates all FAQ Attachments data from Web Help Desk to Service Desk.

   • Assets

     

     • Vendors - Migrates all Vendors data from Web Help Desk to Service Desk.

     • Purchase Order - Migrates all Purchase Order data from Web Help Desk to Service Desk.

     • Purchase Order Attachments - Migrates all Purchase Order Attachments from Web Help Desk to Service Desk.

     • Assets – Migrates all Assets data from Web Help Desk to Service Desk.

     • Assets Attachments - Migrates all Assets attachment data from Web Help Desk to Service Desk.

   • Delete WHD Mapping - Deletes all mapping records from Migration utility - Use this option if you have cleared up the Service Desk data and want to perform the migration activity again with the same database.

     The options below are not required for your first data migration.

     

   • Delete Service Desk Data - Deletes all Service Desk data based on your Input. You can pick and choose what specific data to delete.

     

Migration steps for Linux servers or External Utilities

Two external tools are available:

• UI Migration tool
• CLI Migration tool

UI Migration tool

The UI Migration tool can be executed from different machines for Linux server users or any machine. It is the same as embedded tools with these exceptions:

1. Database Configuration: Copy the .whd.properties file from the <webhelpdesk>/conf directory and paste it into the <migration utility home directory>/conf folder.

   • For Windows: Go to the migration directory and execute the create shortcut to run migration for window file. This creates shortcut file with name start_migration_tool_in_window to execute the migration utility for Windows OS.

     Execute start_migration_tool_in_window file to start migration utility.

     

   • For Mac: Open Terminal and locate the migration utility folder, then execute the command below

     sudo sh ./bin/mac_migration.sh

2. Migrate Approval due_date: If you are using Web Help Desk - 12.8.3 or later, enable this flag.

   

CLI Migration tool

You can rund the CLI Migration tool on a Linux server.

Migration Step 1: Download and install the Web Help Desk migration tool

1. Contact your Service Desk sales rep or account rep for the most up-to-date link to the Migration Tool.

2. Download the whd-migration-swsd.zip file and extract it to a Web Help Desk-equivalent production/test server. The file contains:

   • Data folder
   • Resources folder
   • whd-migration-swsd-0.0.1-SNAPSHOT.jar
   • application.properties
   • window_migration.bat

3. Install Microsoft-JDK 17 on the production and test server if it is not already installed. Use the link below to download and install Microsoft-JDK 17.

   • For Windows

     In a browser, open https://learn.microsoft.com/en-us/java/openjdk/download#openjdk-17 and then download and install microsoft-jdk-17.0.12-windows-x64.msi.

   • For Ubuntu/Debian

     sudo apt update
     sudo apt install openjdk-17-jdk

   • For CentOS/RHEL

     sudo yum install java-17-openjdk

   • For Fedora

     sudo dnf install java-17-openjdk

4. Verify OpenJDK 17 is correctly installed by running:

   Java -version

5. Set up JAVA environment variables if not set up.

Migration Step 2: Configure the Web Help Desk Database

Configuration settings

1. Copy the .whd.properties file from the <webhelpdesk>/conf directory and paste it into the migration utility folder where the utility jar file is located, usually in WebHelpDesk/conf.

   If whd.properties is not available, configure the database details in the application.properties file.

2. Open the application.properties file in a text editor and configure the details for the three types of connections below:

   PostgreSQL properties

   
   spring.datasource.url=jdbc:postgresql://IP_Address:Port/database_name
   spring.datasource.username=username
   spring.datasource.password=password
   spring.datasource.driver-class-name=org.postgresql.Driver
   spring.jpa.hibernate.ddl-auto=update
   spring.jpa.show-sql=false
   spring.jpa.properties.hibernate.dialect=org.hibernate.dialect.PostgreSQLDialect

   MSSQL properties

   spring.datasource.url=jdbc:sqlserver://IP_Address:Port;databaseName=
   WHD_DATABASE;encrypt=true;trustServerCertificate=true
   spring.datasource.username=username
   spring.datasource.password=password
   spring.jpa.hibernate.ddl-auto=update
   spring.jpa.show-sql=false
   spring.datasource.driver-class-name=com.microsoft.sqlserver.jdbc.SQLServerDriver
   spring.jpa.properties.hibernate.dialect=org.hibernate.dialect.SQLServerDialect

   MySQL properties

   spring.datasource.url=jdbc:mysql://IP_ADDRESS:PORT/DATABASE_NAME
   spring.datasource.username=USERNAME
   spring.datasource.password=PASSWORD
   spring.jpa.hibernate.ddl-auto=update
   spring.jpa.show-sql=false
   spring.jpa.properties.hibernate.dialect=org.hibernate.dialect.MySQLDialect
   spring.datasource.driver-class-name=com.mysql.cj.jdbc.Driver

Miscellaneous configuration settings

1. For Linux OS only: If you are running migration utility in Linux OS, set the popup flag to True and the Service Desk account URL and JSON web token:

   #Default: false
   swsd.showpopup.flag=true
   swsd.account.url=<SERVICE_DESK_ACCOUNT_URL>
   swsd.json-web-token=<JSON_WEB_TOKEN>

2. If the category flag is set to True, the utility tool will move all assets based on their categorization and whether it is chargeable. If it is False, all assets will be moved to the Other_Assets category and IP address information will be stored in the Description details.

   #Default: true
   asset.categoryFlag=false

3. If the AssetName flag is set to false, the utility will add Asset: as a prefix to the asset name, resulting in the asset name Asset: +AssetNumber. If the AssetName flag is set to true, the asset name will be only AssetNumber.

   #Default: false
   asset.assetname=false

Migration Step 3: Run the utility on your deployment machine

Navigate to the migration utility folder, locate the file proper file (see below), and then double-click it to run it.

• Windows OS: window_migration.bat

  If window_migration.bat does not work, use a command prompt to run the migration utility.

• Linux/Mac OS: java -jar -Xms5368M -Xmx8589M whd-migration-swsd-0.0.1-SNAPSHOT.jar -spring.config.location=application.properties
  

Migration Step 4: Configure your Service Desk account

Instructions for Windows and Mac OS

1. When the utility starts, the popup below displays.

   

2. Click Configure Service Desk Account.

3. In Service Desk, navigate to Setup > Account >Account Summary. You need the Account URL from that page.

   

4. In the utility tool, add your account URL with https:// before the URL.

   

5. When you see the message that the URL is reachable, click OK.

   

6. In Service Desk, navigate to Setup > Users & Groups > Users.

   1. In the Name column, select the user account (with Administrator role) you used to set up your Service Desk account.

   2. Click Actions, and from dropdown select Generate JSON Web Token.

      Directly under the Default Landing Page field, the JSON Web Token field expands to show the new token.

      

   3. Click Copy.

   4. In the utility tool, paste the Web Token.

      

   5. When the successful connection message displays, click OK.

      

      The Command Prompt window will display.

7. Familiarize yourself with the data migration options.

   

   Option descriptions
   1. Metadata *	Migrates all metadata (Locations/Sites, Departments, Categories, Custom Fields, Tech, Clients and User Groups) from Web Help Desk to Service Desk. *The Metadata option is mandatory.
   2. Parent Ticket/Incidents	Migrates all parent incidents data from Web Help Desk to Service Desk.
   3. Child Ticket/Incidents	Migrates all child incidents data from Web Help Desk to Service Desk.
   4. Client/Tech Notes	Migrates all client/tech notes data from Web Help Desk to Service Desk.
   5. Attachments	Migrates all Ticket and Notes attachments data from Web Help Desk to Service Desk.
   6. Ticket/Incident Status Update	Updates all migrated Ticket status from Web Help Desk to Service Desk.
   7. FAQ	Migrates all FAQ data from Web Help Desk to Service Desk.
   8. FAQ Attachment	Migrates all FAQ attachments data from Web Help Desk to Service Desk.
   9. Vendors	Migrates all Vendors data from Web Help Desk to Service Desk.
   10. Purchase Order	Migrates all Purchase Order data from Web Help Desk to Service Desk.
   11. Purchase Order Attachment	Migrates all Purchase Order attachment data from Web Help Desk to Service Desk.
   12. Assets	Migrates all Assets data from Web Help Desk to Service Desk.
   13. Assets Attachment	Migrates all Assets attachment data from Web Help Desk to Service Desk.
   The options below are not required for your first data migration.
   14. Delete Mapping Records	Deletes all mapping records from Web Help Desk database newly created tables. Use this option if you have cleared the Service Desk data and want to perform the migration activity again with the same database.
   15. Delete Service Desk Data	Deletes all Service Desk data based on your Input. You can pick and choose what specific data to delete.
   0. Exit	Stops the migration utility.

8. Migrate data using the steps in a-d below.

   As you migrate data, monitor progress on Console.

   

   1. Use Option 1. Metadata * to start the metadata migration process.

      All metadata is migrated from Web Help Desk to Service Desk. Imported metadata will include location, departments, categories, custom fields, users (tech and client), and User Groups.

      1. Check the progress of the metadata migration on console and see if you see any exceptional failure.

         If you receive an "Operation Complete" message, you can ignore the progress percentage in the console, even if it shows less than 100%.

      2. If you see any failed site/department/category/user/custom field, create it manually in Service Desk and be sure to use the same name when you create it.

      3. Reconcile all the migrated metadata between Web Help Desk and Service Desk.

      4. If all looks good, move on to migrating Web Help Desk tickets.

   2. Use Options 2-6 to start the ticket migration process.

      This step lifts and shifts the ticket, comments, and attachments

   3. Use Options 7-8 to start the FAQ migration process.

      This step lifts and shifts the FAQ and FAQ attachment.

   4. Use Options 9-13 to start the Assets migration process

      This step lifts and shifts the Vendors, Purchase Orders, Assets, and Assets Attachments.

If at any point during the data migration process you receive a PKIX certificate error message, refer to Migration Step 5: .

Next phase

Phase 5: Launch your Service Desk