DOC xPress to SentryOne Document Migration

Introduction

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

Note:  The Import option only appears if you have the latest version (2020.10+) of the SentryOne Document configuration tool and are connected to a SentryOne Document endpoint that supports the import functionality.

Import Process

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

1. Open the SentryOne Document configuration tool

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

  1. On the Welcome to SentryOne Document! 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 http://localhost:44322.
  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 SentryOne Document, 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 SentryOne Document 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 SentryOne Document.
    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 SentryOne Document. 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 SentryOne Document 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 SentryOne Document. 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.
    Uploading data...
    Preparation completed successfully
    Note:  If your import fails, see the Failures section at the end of this article.
  7. Open the SentryOne Document portal in a browser. You'll see that the solution has a status of Importing... while SentryOne Document 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 SentryOne Document does. SentryOne Document 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 SentryOne Document 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).

Importing Status Popup

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.

Example of import progress in Task History. The list of commands can vary from import to 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 SentryOne Document features available with your licensing for that solution.

Once the import completes, the SentryOne Document feature options are available for the solution

Success: You have migrated from DOC xPress to SentryOne Document! Check out the Using SentryOne Document 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 SentryOne Document configuration tool, select the solution you have canceled, then select Delete.
    Select the cancelled solution, then choose Delete
    Note:  A cancelled import will show a solution in an Import Cancelled status in the web portal. The data deletion in the SentryOne Document 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 SentryOne Document.Example of a cancelled solution Example of cancelled solution details
  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 SentryOne Document Troubleshooting article.