Installation

This guide walks you through installing Cartographer into your Dataverse environment. Install it from the AppSource listing on the Microsoft Marketplace, which sets up VerseBlocks Core and Cartographer together, in the right order. A fresh install in an empty environment took about five minutes.

Get it free on AppSource

Prerequisites

Before installing, make sure you have the following:

  • A Microsoft Dataverse environment (Power Apps, Dynamics 365, or standalone Dataverse)
  • System Administrator security role in the target environment
  • Permission to install solutions (some organizations restrict this via tenant settings)
  • A modern browser — Edge, Chrome, Firefox, or Safari
  • Browser access to cdn.jsdelivr.net, which the Automation Map uses to load its diagram library
Cartographer installs as a managed solution. It does not modify any existing tables, forms, or views in your environment. Uninstalling removes all Cartographer components cleanly.

What Gets Installed

Cartographer consists of two managed solutions that install into your environment. The AppSource listing installs both, in the right order.

VerseBlocks Core

Required

Required by Cartographer. Must be installed first when you import the files yourself.

VBCore — v1.2.4.0

Cartographer

Main App

The full Cartographer product: Component Dashboard, Summaries, Semantic Search, Automation Map, Compass, User Guides, and Best Practice Analysis. It is about 21 MB because it bundles the small open-source embedding model that powers Semantic Search.

Cartographer — v1.2.4.0
VerseBlocks Core must be installed before Cartographer. Cartographer depends on components in VBCore. Attempting to install Cartographer first will fail with a missing dependency error.

Installation Steps

Cartographer is live on Microsoft AppSource, and that is the primary way to install it. The listing installs VerseBlocks Core and Cartographer together, in the right order, so there is no dependency to manage. Open the listing, install it into the environment you want to document, then skip to step 5.

Get it free on AppSource

To import the files yourself, or if your organization restricts AppSource, follow steps 1 to 4. They download both managed solutions from the downloads page and import them.

  1. 1

    Download the solution files

    For manual installation, visit the VerseBlocks downloads page and download both managed solutions — VerseBlocks Core (install first) and Cartographer, currently version 1.2.4.0.

    Go to Downloads
  2. 2

    Import VerseBlocks Core first

    Go to make.powerapps.com, select your environment, and navigate to Solutions.

    1. Click Import solution in the command bar
    2. Click Browse and select the VerseBlocks Core managed solution file
    3. Click Next
    4. Click Import
    5. Wait for the import to complete — you will see a success notification
    Solution import dialog in Power Apps
  3. 3

    Import Cartographer

    After VBCore completes successfully, repeat the import process:

    1. Click Import solution
    2. Browse and select the Cartographer managed solution file
    3. Click Next, then Import
    4. Wait for completion
    Do NOT import Cartographer before VerseBlocks Core. The import will fail with a missing dependency error. Always install VBCore first, verify it completed successfully, and then import Cartographer.
  4. 4

    Publish all customizations

    After both solutions are imported, click Publish all customizations in the Solutions area. This ensures all components are active and visible in the environment.

  5. 5

    Open the Cartographer app

    Navigate to Apps in the left navigation. Find the Cartographer model-driven app and click to open it. You'll see a sidebar with all pages: Solution Manager, Component Dashboard, Automation Map, Compass, Best Practices, and Activation.

Enable Scheduled Crawling

Cartographer ships two cloud flows and the connection reference they use, so crawl configurations can run automatically on their configured schedule. Only you can supply a connection, so both flows ship switched off and the connection reference ships unbound. That means one manual step stands between a fresh install and working schedules.

This step is easy to miss. If you skip it, a crawl frequency you set on a solution does not run, though Crawl Now still works. If a solution never crawls on the schedule you set, this is the first thing to check. Once you have activated, the Scheduled Crawling section of the Activation page shows whether the connection and both flows are done.
  1. In Solutions, open the Cartographer solution and find its connection references.
  2. Open Cartographer Dataverse Connection and bind it to a Dataverse connection (create a new one if you don't already have one).
  3. Still inside the Cartographer solution, find its cloud flows and turn on both Cartographer - Scheduled Crawl Processor and Cartographer - On-Demand Crawl.
The scheduled flow polls every 30 minutes and checks each crawl configuration's own frequency and last-completed time — 30 minutes is how often it checks, not how often a given solution actually crawls. See crawl configuration frequency for the available schedules. Scheduled crawls update the documentation. The search index is updated from Solution Manager, so the next Crawl Now indexes anything a scheduled crawl found.

Post-Install Setup

With both solutions installed, finish setup inside the app, signed in as a System Administrator or System Customizer. To give other people access afterwards, see Security Roles for what each role grants.

  1. 1

    Activate

    Open the Activation page in the sidebar. Do this first, because most actions in the app need an activated install.

    • Enter your name, company name and email address
    • Click Activate
    That is the entire flow. There is no licence key to enter and no plan to choose. Cartographer is free and every feature is unlimited. Activating sends your name, company, email address, organisation ID and environment URL to VerseBlocks, which registers a free licence for you. You never see or need the licence key. Cartographer also sends VerseBlocks usage reports, and there is no switch to turn them off. The names, metadata and documentation of your components never leave your environment. The privacy policy has the full list. See the Activation guide for more detail.
  2. 2

    Add your first crawl configuration

    Open Solution Manager in the sidebar. At the foot of Configured Solutions, pick the solution you want to document and a crawl frequency, then click Add Solution. The crawl starts when you click Crawl Now on its row, so you don't need to wait for the schedule. Keep the page open while it runs, because Crawl Now also indexes components for search from your browser.

  3. 3

    Explore your documentation

    After the crawl completes, open the Component Dashboard to see every discovered component, each carrying a plain-English summary that Cartographer writes from a template at crawl time. Click any component to view its details. Once Crawl Now has finished indexing, a Search section appears in Solution Manager. Ask it a question such as "who is allowed to read records" and it ranks components by meaning, using a small open-source embedding model bundled in the solution. See Semantic Search for how it works.

Upgrading Cartographer

When a new version of Cartographer is released, you can upgrade without losing any data.

Download the latest managed solution files from our downloads page and import them into your environment using the same process as the initial installation. Power Platform will detect the existing solution and perform an upgrade automatically.

After you upgrade, open Solution Manager and choose Rebuild everything from the More actions menu on each solution. A normal crawl skips components that have not changed, so only Rebuild everything brings existing summaries up to the new wording, and it also rebuilds the search index. It does not regenerate user guides, so use Regenerate on any guide you want refreshed.

Data is always preserved. Upgrading imports a newer version of the managed solution over the existing one. All your crawl data, summaries, user guides, and configuration settings are retained.

Uninstalling

To remove Cartographer from your environment:

  1. Go to Solutions in Power Apps
  2. Select Cartographer and click Delete
  3. After Cartographer is removed, select VerseBlocks Core and click Delete
Uninstalling Cartographer permanently deletes all crawl data, summaries, user guides, and configuration. Export any data you need before uninstalling. Uninstall Cartographer before VerseBlocks Core — Core cannot be removed while Cartographer depends on it.

Troubleshooting Installation

"Missing dependency" error during import

This means VerseBlocks Core was not installed, or the installation failed silently. Go to Solutions, verify that VBCore appears in the list with a "Managed" status, then try importing Cartographer again.

Cartographer does not appear in the Apps list

Make sure you have a security role that grants access to the Cartographer app. System Administrator and System Customizer have access by default. For other users, assign the Cartographer Admin or Cartographer Reader security role, then add that role to the app: in make.powerapps.com, open Apps, select Cartographer, click Share, and add the role. See Security Roles.

"You are not authorized" error when opening the app

This indicates a missing security role. Ask your System Administrator to assign the Cartographer Reader or Cartographer Admin security role to your user account. The role must also be added to the app: in make.powerapps.com, open Apps, select Cartographer, click Share, and add the role.

A crawl configuration's schedule never runs

A crawl schedule needs the two Cartographer cloud flows turned on and the connection reference bound. This is a one-time step every fresh install needs. The Scheduled Crawling section of the Activation page shows which part is still missing. See Enable Scheduled Crawling above.

Next Steps

Cartographer is installed and ready. Review your crawl configurations and security roles, or head straight to crawling.

Configuration GuideCrawling Solutions