Skip to content

How to use Wagonmaster Manifest ​

Script version 1.2.1. Last updated 2026-11-12. Download this page as a Word document.

What it does ​

Wagonmaster Manifest is the script Export-WagonmasterManifest.ps1. It reads everything an Azure Migrate project exposes through Azure APIs and writes each dataset twice: a flattened CSV for Excel or Power BI, and a JSON file with the full structure. It is read only and never changes anything in Azure.

AreaWhat you get
DiscoverySites, vCenters, Hyper-V hosts and clusters, discovered machines, SQL Server instances, databases and availability groups, IIS and Tomcat web servers and apps
Software (optional)Installed software per machine, with -IncludeSoftwareInventory
AssessmentsAzure VM, AVS, SQL and web app assessments, with per machine results
Business caseBusiness cases and their evaluated machines and workloads
MigrationReplication and migration items from linked vaults
Resource GraphEvery project record in the MigrateResources table

Not included: agentless dependency data. Export it from the portal under Manage Dependencies, then Export dependencies. Azure keeps that data for 30 days, so export it on a regular schedule.

Before you start ​

You need PowerShell 7 and Reader access to the project's resource group. Everything else installs itself.

  • PowerShell 7 or later (pwsh). Windows PowerShell 5.1 is refused with a clear error.
  • Modules: Az.Accounts, Az.Resources, Az.ResourceGraph, and powershell-yaml when a config file is used. Missing modules are installed for the current user from the PowerShell Gallery.
  • Access: the Reader role on the resource group that holds the Azure Migrate project. See Security and access for details.
  • Files: clone or download the repository. The script and its config folder live in src/manifest. Keep them together.
  • If Windows blocks the script because it was downloaded, run Unblock-File .\Export-WagonmasterManifest.ps1 once.

Status: this script has been reviewed but not yet run against a live project. Run it with -DryRun first.

Quick start ​

Run the script with no parameters and answer the prompts. No IDs are needed.

  1. Open PowerShell 7 and change to the src/manifest folder.

  2. Run a dry run first:

    powershell
    .\Export-WagonmasterManifest.ps1 -DryRun
  3. Choose Interactive when asked how to sign in, then sign in through the browser.

  4. Pick the subscription and the Azure Migrate project from the numbered lists.

  5. Press Enter to accept the default output folder, or type another one.

  6. Check the list of resources the dry run prints. Then run the same command without -DryRun.

  7. Open _Summary.csv in the new output folder to see what was exported.

  8. Optional: build a dashboard from the export with Wagonmaster Waypoint.

To skip the prompts next time, pass the values:

powershell
.\Export-WagonmasterManifest.ps1 -AuthMethod Interactive -SubscriptionId <subscription-id> `
    -ResourceGroupName <resource-group> -ProjectName <project-name>

How values are resolved ​

Each setting is taken from the first place that has a value:

  1. A parameter on the command line
  2. The config file, config\wagonmaster-manifest.yml by default, or the file named with -ConfigPath
  3. An environment variable
  4. A prompt, only when a person is at the keyboard

In pipelines, Azure Automation, scheduled tasks, or with -NonInteractive, step 4 is skipped. A missing value stops the run with an error that names the parameter, config key and environment variable to set.

ParameterConfig keyEnvironment variable
-AuthMethodauth_methodWAGONMASTER_AUTH_METHOD
-TenantIdtenant_idAZURE_TENANT_ID
-SubscriptionIdsubscription_idAZURE_SUBSCRIPTION_ID
-ResourceGroupNameresource_group_nameWAGONMASTER_RESOURCE_GROUP
-ProjectNameproject_nameWAGONMASTER_PROJECT_NAME
-OutputPathoutput_pathWAGONMASTER_OUTPUT_PATH
-ClientIdclient_idAZURE_CLIENT_ID
-ClientSecretNot allowedAZURE_CLIENT_SECRET
-CertificateThumbprintcertificate_thumbprintAZURE_CLIENT_CERTIFICATE_THUMBPRINT
-ManagedIdentityClientIdmanaged_identity_client_idWAGONMASTER_MI_CLIENT_ID

To use a config file, copy config\wagonmaster-manifest.example.yml to config\wagonmaster-manifest.yml and fill in the values. Keep the real file out of source control.

Switches ​

SwitchWhat it does
-DryRunSigns in, finds the project, lists what would be exported, then stops. Writes no files.
-IncludeSoftwareInventoryAdds installed software for every machine. One call per machine, so it is slow on large estates.
-SkipResourceGraphSkips the Resource Graph MigrateResources query.
-SkipMigrationStatusSkips replication and migration status from linked vaults.
-UseDeviceCodeInteractive sign in with a device code instead of a browser.
-NonInteractiveNever prompts. A missing value is an error.
-ConfigPath <file>Uses a specific config file. If it does not exist, it is created from the example and the run stops.

-AuthMethod accepts Interactive, ManagedIdentity or ServicePrincipal.

Unattended runs ​

Unattended runs never prompt, so supply every value by parameter, config file or environment variable. Identity setup is in Security and access.

Managed identity (Azure VM, Automation account, Arc enabled server):

powershell
.\Export-WagonmasterManifest.ps1 -AuthMethod ManagedIdentity -ConfigPath .\config\wagonmaster-manifest.yml

Add -ManagedIdentityClientId <client-id> for a user assigned identity.

Service principal with a certificate:

powershell
.\Export-WagonmasterManifest.ps1 -AuthMethod ServicePrincipal -TenantId <tenant-id> `
    -ClientId <client-id> -CertificateThumbprint <thumbprint> `
    -SubscriptionId <subscription-id> -ResourceGroupName <resource-group> -ProjectName <project-name>

Service principal with a secret: set AZURE_CLIENT_SECRET from your secret store in the same session, then run the same command without -CertificateThumbprint. The secret is never read from the config file.

Pipeline that has already signed in (Azure PowerShell task with a service connection):

powershell
.\Export-WagonmasterManifest.ps1 -AuthMethod Interactive -NonInteractive `
    -SubscriptionId <subscription-id> -ResourceGroupName <resource-group> -ProjectName <project-name>

This reuses the existing Azure session. If there is none, the run stops with an error.

Understanding the output ​

Each run creates a new timestamped folder, so earlier exports are never overwritten.

text
WagonmasterManifest\
  <project>-<yyyyMMdd-HHmmss>\
    _Summary.csv      one row per dataset: record count and status
    _CallLog.csv      one row per API call
    _Manifest.json    who ran it, when, against what, API versions
    export.log        full run log
    csv\              one flattened CSV per dataset
    json\             one JSON file per dataset, full structure

Start with _Summary.csv. The Status column means:

StatusMeaning
OKData was returned
NotAvailableThe project does not use that feature, or the API does not offer it
ErrorThe call failed. The Errors column says why.
PartialSome calls for that dataset worked and some failed

Reading the CSV files:

  • Columns that start with an underscore, such as _Project, _Site and _Assessment, say where the row came from. Use them to join files.
  • Nested values become dotted column names. Lists of simple values are joined with a semicolon. Lists of objects stay as JSON in one cell.
  • Cells longer than 32,000 characters are cut off with a note. The JSON file has the full value.
  • Text that starts with =, +, - or @ gets a leading apostrophe so Excel cannot run it as a formula. The JSON file keeps the raw value.
  • Files are UTF-8 with a byte order mark, so Excel opens them correctly.

Known limits and troubleshooting ​

A failed dataset never stops the run. Check _Summary.csv first, then export.log.

SymptomLikely causeWhat to do
"Cannot read Azure Migrate project"Wrong project or resource group name, or no Reader accessCheck the names. Confirm the Reader assignment on the resource group.
"Missing required value"An unattended run has no value for that settingSet the parameter, config key or environment variable the error names.
"No existing Azure session to reuse"Interactive was chosen where no one can sign inSign in first, or use ManagedIdentity or ServicePrincipal.
Web app assessment or business case shows ErrorThose use preview API versions that Microsoft can changeUpdate the version in the $ApiVersions block at the top of the script.
SQL or web app datasets are emptyNot discovered, or the appliance lacks credentialsFix discovery in the Azure Migrate portal, then export again.
Assessment numbers look oldAssessments are point in time snapshotsRecalculate the assessment in the portal, then export again.
Device code sign in is refusedConditional Access blocks device code flowRun without -UseDeviceCode.
More data than expectedSeveral projects share one resource group and the fallback collected all of themFilter on the _Site column, or keep one project per resource group.
Module install failsThe PowerShell Gallery is blockedInstall the Az modules from your internal repository first.

Other limits:

  • Dependency data is not exported. Use the portal.
  • Software inventory makes one call per machine. Expect a long run on estates with thousands of servers.
  • The replication job dataset for the newer replication vault type uses an unverified API path. It may show NotAvailable.
  • Exports contain server names, IP addresses and software lists. Treat the output folder as confidential. See Security and access.

Released under the MIT License.