Documentation forDatabase Mapper
Effective February 28, 2024, Database Mapper has reached its end of life and is no longer available or supported. If you liked Database Mapper, consider trying another SolarWinds product.

DOC xPress to Database Mapper Migration

EOL: An end of life announcement has been made for Database Mapper on February 28, 2023. See the Solarwinds End of Life Policy for more information.

Introduction

SolarWinds Database Mapper replaces the DOC xPress product. The Import option in the Database Mapper configuration tool is designed to migrate a DOC xPress metabase to Database Mapper (the cloud or on-premises software version).

Note:  The Import option only appears if you have a compatible version of the Database Mapper configuration tool and are connected to a Database Mapper endpoint that supports the import functionality. This is not available by default for cloud.

Import Process

Before you can migrate your data from DOC xPress to Database Mapper, you must install and configure a version of Database Mapper (cloud or on-premises). The import process uses the installed Database Mapper configuration tool to perform the migration.

1. Open the Database Mapper configuration tool

The Database Mapper configuration tool is installed on-premises for both the cloud and self-hosted versions of Database Mapper. The instructions for the import are essentially the same for either, but you will have different server endpoints.

  1. On the Welcome to Database Mapper! screen you'll need to enter your Server URL.
    Note:  The Server value defaults to the cloud server (https://document.sentryone.com). If you are using the self-hosted version, you'll need to use your hosted server URL. In these instructions, we're using the self-hosted version with a Server value of .
  2. Select Validate to test the connection. A Server validated successfully message appears.
  3. Select Connect to open the Solutions screen.

2. Import

The Import allows you to choose a DOC xPress metabase to migrate to Database Mapper, as well as how much of the snapshot history you would like to include. Data is prepared on the machine running the configuration tool, then it is sent to the server hosting Database Mapper for additional processing.

  1. Select the Import button on the Solutions screen to get started.
  2. On the Import screen, enter the Server name for your existing DOC xPress database, select a Security mode for the connection, select a Database, and then select Connect to DOC xPress Metabase to continue.

    Note:  The default database is typically named DOCxPress.

    If you select something that is not a DOC xPress metabase you will see a Could Not Connect popup error.

  3. On the Select solutions to import screen you will see a list of the available solutions and solution items from your DOC xPress database. Select the solutions that you would like to import by checking the boxes next to them. Select Next to continue.
    Note:  By default, selecting a solution will select all the associated solution items listed, however, you can deselect any items that you do not want to import into Database Mapper.
    Note:  The Import checks your licensing to verify how many data sources you are licensed for. If you select more data sources than you are licensed for, you will receive a Target Limit Exceeded popup message.
  4. On the Configure data range for import screen, make a selection for the time range that you want to import snapshots into Database Mapper. Only snapshots from the time range you select will be imported.
    Note:  There's also an option called None to import only the the configuration. This provides a fresh start with the solution to start taking snapshots in Database Mapper without importing the historical data.
    Important:  Depending on how much history you have in your DOC xPress metabase, the Full option could take a significant amount of time to migrate.
  5. Select Start to begin the migration. A screen appears to show you the progress of the data as it is prepared for the transfer. 
  6. A green check mark and Preparation completed successfully message indicates that the data has been taken from DOC xPress and the files have been generated and uploaded to Database Mapper. When the preparation step completes, you have the option to Save Log (save a file of the messages from the preparation process) or Close the screen.
    Note:  If your import fails, see the Failures section at the end of this article.
  7. Open Database Mapper in a browser. You'll see that the solution has a status of Importing... while Database mapper processes the data that has been uploaded. You may need to hit refresh.

3. Import Status

While DOC xPress maintains a history of the snapshots, it does not maintain a history of the documentation at each of those points in time the way Database Mapper does. Database Mapper needs to generate all the documentation at each point in time from the data that is being migrated, as well as generate lineage if the licensing level allows for it.

Within the Database Mapper web portal, you can select the Importing... status to view a high-level summary about the status (e.g. when the import was created, who requested it, the current status, and total file size).

You can also select the Task History button to view additional details. Task History will display all the steps that have been completed and all the steps that have yet to complete. There's also a Cancel option available on the Task History screen if you would like to cancel the import.

Note: 

  • The Generate lineage for solution and Finalize lineage for solution steps will only display if your licensing level includes lineage analysis.
  • These lineage steps require at least one remote agent running in the default agent pool. The lineage steps above will not complete until you have a remote agent running.

4. Import Complete

Once the import process is complete, you will have all the Database Mapper features available with your licensing for that solution.

Success: You have migrated from DOC xPress to Database Mapper! Check out the Using Database Mapper articles to start exploring all the features.

Cancelling an Import

If you changed your mind about what you are importing while it is in progress (i.e. you selected more history than you need and the migration is taking longer than expected):

  1. Select Cancel from the Task History page.
  2. Go to the Database Mapper configuration tool, select the solution you have canceled, then select Delete.
     
    Note:  A cancelled import will show a solution in an Import Cancelled status in the web portal. The data deletion in the Database Mapper web portal is asynchronous and will be deleted in the background. There is no status displayed for this process. Attempting to import again right away may cause an error if the solution has not been fully deleted from Database Mapper.
  3. You can set up the import again by following the Import process instructions, if needed.

Previously imported solutions

To prevent importing the same solution multiple times, you will see solutions listed under the Previously imported solutions section in the Solution Configuration Tool if you open it again after doing an import.

Troubleshooting

Failures

If an import fails during the Solution Configuration Tool Preparation (step 6 from Import), you will see:

If this happens, select Save Log to view the log output.

If an import fails after the preparation and file upload (step 6 from Import completed successfully), you will see an Import Failed status message next to the solution.

Select Import Failed to see more details in the popup.

Select Task History to see which steps failed.

Refresh the solutions list in the Solution Configuration Tool to check for the the Import Failed status.

View the log files for more information, particularly the API.log file, as described in the Database Mapper Troubleshooting article.