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.

Database Mapper Remote Agents

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.

Remote Agent Overview


What is a remote agent?

A remote agent is a service that runs in the background on a machine within your environment, and is responsible for generating the snapshots and documentation for the solutions configured within Database Mapper. It feeds the snapshot and documentation back to Database Mapper Cloud. This agent service needs to be installed on a machine that has access and permissions to the environments configured to be documented. See the System Requirements article for more details.

Where should a remote agent be installed?

The remote agent may be installed on any on-premises machine that meets the system requirements, including access to all the resources (i.e. a SQL Server) it must connect to in order to create documentation. Keep in mind that since it runs as a Windows service in the background, it can only perform the work while the machine is running. A machine that is shut down overnight will not be able to generate documentation or take snapshots during that time.

How many remote agents are needed?

In general, you should start with a single remote agent. Situations where you may need more than one remote agent include:

  • You require numerous or large snapshots and they are taking longer than acceptable to complete with a single agent
  • Your network environment is locked down in such a way that not one machine has access to all the resources you are trying to document. In this case, you might need to install a remote agent on Machine1 to access SQLServer1, and a remote agent on Machine2 to access SQLServer2.

What is a remote agent pool?

A remote agent pool is a grouping of remote agents in your Database Mapper environment. Database Mapper automatically creates a default system-generated remote agent pool that you can't change. When you register any remote agent, your remote agent goes into the system-generated pool by default. If you have multiple remote agents, and want to control what work they can pick up, you can group them into pools. When a snapshot is requested for a solution item, it allocates that work to any of the available agents within the pool that's associated with the solution item. 

For example, you could create remote agent pools with remote agents that document only:

  • your production server
  • your development server
  • SSIS packages

Managing Remote Agents

Manage the remote agents assigned to Database Mapper. In Database Mapper, select to open the Remote Agents management page. Starting with Version 2022.3, Remote Agents are displayed on the top and Remote Agents Pools are displayed on the bottom of the same page for streamlined management.

Database Mapper Web Portal Remote Agents > Manage Remote Agents

Remote Agents details

Database Mapper Remote Agents page

Metadata Description
Machine Name The name of the machine where the Remote agent is installed.
Date Registered The day and time that the Remote agent was registered with Database Mapper.
Description A user entered description about the Remote agent.
Remote Agent Pool The Remote agent pool to which the remote agent is assigned.
Last Signal received The last time a successful connection was made to the remote agent.
Version The software version number of the remote agent. Note:  Database Mapper displays an Upgrade button by your Remote Agent if an update is available. Select Update to update your remote agent remotely. 

Managing Remote Agents page buttons

Button Description
Database Mapper Web Portal Edit description button Select the Edit description button to edit the description column for the selected remote agent. Enter your desired description, and then select to save your changes. 
Database Mapper Web Portal Change pool assignment button Select the Change pool assignment button to open the Change pool assignment window. Select the desired remote agent pool from the drop-down list, and then select Saveto save your changes.
Database Mapper Web Portal Check Connectivity button Select the Check connectivity button for a remote agent to open the Check remote agent connectivity window. Select Start connectivity check to verify the connection.
Database Mapper Web Portal Task History button Select the Task History button for a remote agent to open the Task History page for the remote agent. 
Database Mapper Remote Agents Software Update History button Select the Software Update History button to open the Software history window for the selected remote agent.
Database Mapper Web Portal Manage License button Note:  This is no longer an option or requirement in versions 2021.3 and later.

Select the Manage License button to open the Manage License window. 
Database Mapper Show Running Tasks button Select the Show Running Tasks button to open the running tasks window for the selected remote agent. 
Database Mapper Show Available Providers button Select the Show Available Providers button to open the Available Providers window for the selected remote agent.
Database Mapper Web Portal Delete button Select the Delete button to open the Delete Remote agent window. Select Delete Remote agent to delete the selected remote agent from the Remote Agents page.

Updating a Remote Agent

Note: 

  • When using Database Mapper (the cloud version at document.sentryone.com), you will see the Update option next to the remote agent to upgrade them via the Database Mapper web interface when updates are available.
    • Selecting Update also updates any other remote agents from the same installation directory.
  • When using Database Mapper Software (the on-premises, self-hosted version), you must download the latest Database Mapper Remote Agent software from my.sentryone.com, then run through the installer.
    • This updates all remote agents that are part of this installation.
  • There's no need to stop the remote agent services before upgrading them.
    • We don't recommend upgrading them while they are performing work (e.g. generating documentation or a snapshot).

Update your remote agent to the newest software version on the Remote Agents page. 

1. Select the Update option next to an out-of-date remote agent to open the Update prompt.Database Mapper Remote Agents Update Remote Agent

2. Select Ok to update the selected remote agent remotely. 
Database Mapper Remote Agents Update Remote Agent Prompt

Deleting a Remote Agent

You can delete any unused remote agents in your Database Mapper environment by completing the following:

1. Open Windows Services, then select the remote agent you want to delete. Right click the remote agent, then select Stop to stop the service from running.Database Mapper Open Services and Stop Remote Agent

Note:  Stopping the Database Mapper Remote Agent Service makes the uninstall process easier and does not require you to restart your machine.

2. Select the Windows button, then navigate to the SolarWinds folder. Right click the Database Mapper Solution Configuration Tool, and select Uninstall to open the Control Panel.
Database Mapper Solution Config Tool select Uninstall

3. Right click the Database Mapper Remote Agent that you want to uninstall, then select Uninstall to uninstall the service. Select Yes to confirm your selection.

Database Mapper Remote Agent Uninstall from Control panel

Viewing a Remote Agent Log

If your remote agent encounters any issues or failures, you can select the Task History button for the desired remote agent. On the Task History page for the remote agent, you can view or download log output that details the issue. 

Note:  For a more detailed log, you can view the log output for your on premises installation at the following path:

C:\Program Files (x86)\SentryOne\SentryOne Document Remote Agent\SentryOne.Document.RemoteAgent.exe.config

Logging is set to record any error by default. If you want your log to record more detailed data, you can change this configuration to debug.

Managing Remote Agent Pools Details

Starting with Version 2022.3, Remote Agent Pools are located under the Remote Agents Options on the Remote Agents page. Database Mapper Remote Agent Pool Settings

Note:  Database Mapper automatically creates a default system-generated remote agent pool that you can't change. When you register a remote agent, your remote agent goes into that pool by default.

Create custom pools, and move agents around between them. If you have multiple remote agents, and want to control what work they can pick up, you can group them into pools. When a snapshot is requested for a solution item, it allocates that work to any of the available agents within the pool that is associated with that solution item.

Creating a new pool

Create a new remote agent pool in the Manage Remote Agents pools page by completing the following steps:

  1. Select to open the New Remote Agent Pool window.Database Mapper Web Portal Manage Remote Agent Pools New Pool
  2. Enter a Pool name, and then select Save to create your remote agent pool.
    Database Mapper Web Portal Create New Pool window

Success: Your remote agent pool is ready to use!
 Database Mapper Web Portal Manage Remote Agent Pools New pool available

Managing remote agent pool page details

Metadata Description
Pool name The name of the remote agent pool.
Agents Assigned The number of remote agents assigned to the pool.

Managing remote agent pool buttons

Button Description
Database Mapper Remote Agent Pools Add button Select the button to open the New Remote Agent Pool window.
Database Mapper Web Portal Manage Remote Agent Pools Edit name button Select the Edit Remote agent pool name button to open the Edit Remote Agent Pool window. Enter the desired changes, and then select Update to save your changes.
Database Mapper Web Portal Manage Remote Agent Pools Delete pool button Select the Delete button to open the Delete Remote Agent pool window. Select Confirm Delete to delete the selected remote agent pool.

Deleting a Remote Agent Pool

Important:  Before deleting a selected remote agent pool, you must reassign all the existing remote agents, solutions, and solution items within the pool to another pool.

Delete a selected remote agent pool from Database Mapper by completing the following:

1. Reassign any remote agents, solutions, or solution items that are assigned to the pool you want to delete. In this example, we reassign a remote agent to a different pool. 

2. Select the Delete button for the remote agent pool you want to delete, then select Confirm Delete to complete the process.

Database Mapper Web Portal Delete Remote Agent Pool Confirm Delete

Success: The remote agent pool has been deleted from your Database Mapper environment.
Database Mapper Web Portal Remote Agent Pool deleted