Process Definition Processor

[MrHinsh]

This discussion is for questions, feedback, and community support related to the Process Definition Processor.

Quick Reference

• Class Name: ProcessDefinitionProcessor
• Friendly Name: Process Definition
• Documentation: Process Definition Processor

How to Use This Discussion

• Ask Questions: If you need help configuring or using this component
• Share Examples: Post your configuration examples or use cases
• Report Issues: Describe any problems you encounter (though bugs should be reported as GitHub Issues)
• Request Features: Suggest improvements or new features

Related Documentation

Please refer to the official documentation for detailed configuration options and examples.

[AnaMariaChi]

The ProcessDefinitionProcessor appears to have compatibility issues with the current endpoint implementations.

The error I keep getting:
Processor::EnsureConfigured
[16:12:48 DBG] [16.2.9] Loading model for [Source].
[16:12:48 DBG] [16.2.9] Loading model for [Target].
[16:12:48 ERR] [16.2.9] Failed to synchronize processes.
System.ArgumentNullException: Value cannot be null.
Parameter name: uriString
at System.Uri..ctor(String uriString, UriKind uriKind)
at System.UriBuilder..ctor(String uri)
at MigrationTools.Endpoints.AzureDevOpsEndpoint.GetUriBuilderBasedOnEndpointAndType[DefinitionType](String[] routeParameters) in D:\a\azure-devops-migration-tools\azure-devops-migration-tools\src\MigrationTools.Clients.AzureDevops.Rest\Endpoints\AzureDevOpsEndpoint.cs:line 113
at MigrationTools.Endpoints.AzureDevOpsEndpoint.GetHttpClient[DefinitionType](String[] routeParams) in D:\a\azure-devops-migration-tools\azure-devops-migration-tools\src\MigrationTools.Clients.AzureDevops.Rest\Endpoints\AzureDevOpsEndpoint.cs:line 68

My config file:

{
"Serilog": {
"MinimumLevel": "debug"
},
"MigrationTools": {
"Version": "16.2.9",
"Endpoints": {
"Source": {
"EndpointType": "AzureDevOpsEndpoint",
"Collection": "https://dev.azure.com/***/",
"Project": "Process Template Sync",
"Authentication": {
"AuthenticationMode": "AccessToken",
"AccessToken": ""
}
},
"Target": {
"EndpointType": "AzureDevOpsEndpoint",
"Collection": "https://dev.azure.com/***/",
"Project": "Test Process Sync",
"Authentication": {
"AuthenticationMode": "AccessToken",
"AccessToken": ""
}
}
},
"Processors": [

        {
            "ProcessorType": "ProcessDefinitionProcessor",
            "Enabled": true,
            "ProcessMaps": {"Basic - sync test": "Basic - Sync Test"},
            "Processes": {"Basic - sync test":["Epic"]},
            "UpdateProcessDetails": true,
            "MaxDegreeOfParallelism": 0,
            "SourceName": "Source",
            "TargetName": "Target"
          }
    
  ]
}

}

I tried changing to TfsTeamProjectEndpoint but it doesn't accept it:

Unable to cast object of type 'MigrationTools.Clients.TfsTeamProjectEndpoint' to type 'MigrationTools.Endpoints.AzureDevOpsEndpoint'.

Is there something I am missing or is this a bug?

[MrHinsh]

You should be using TfsTeamProjectEndpoint and not AzureDevOpsEndpoint

UPDATE: Im fairly sure AzureDevOpsEndpoint is correct... the opposite error form the usage through me off.

[AnaMariaChi]

I tried that too but it seems not to accept it. It errors with:
"Unable to cast object of type 'MigrationTools.Clients.TfsTeamProjectEndpoint' to type 'MigrationTools.Endpoints.AzureDevOpsEndpoint'. etc"

[MrHinsh]

What baout if you use AzureDevOpsEndpoint like you have above?

[AnaMariaChi]

I get this error:
System.ArgumentNullException: Value cannot be null.
Parameter name: uriString
migration-errors20250722.log

[MortenVest]

I have project copying and query copying working.
I can not get process copying working.
Trying to copy from one organization (Azure DevOps) to another. Tried multiple versions of endpoint to make it work.
Can anyone provide a working sample? Or a hint on what is wrong in my configuration

{

  "Serilog": {
    "MinimumLevel": "Debug"
  },
  "MigrationTools": {
    "Version": "16.3",
    "Endpoints": {
      "Source": {
        "EndpointType": "AzureDevOpsEndpoint",
        "Organisation": "https://dev.azure.com/Source/",
        "Collection": "https://dev.azure.com/Source/",
        "Project": "Test",
        "AuthenticationMode": "AccessToken",
        "AccessToken": "****" ,
        "Authentication": {             
          "AuthenticationMode": "AccessToken",
          "AccessToken": "*****" 
        },
        "ReflectedWorkItemIdField": "Custom.ReflectedWorkItemId"
      },

      "Target": {
        "EndpointType": "AzureDevOpsEndpoint",
        "Organisation": "https://dev.azure.com/Target/",
        "Collection": "https://dev.azure.com/Target/",
        "Project": "TargetTest",
        "AuthenticationMode": "AccessToken",
        "AccessToken": "*****",
        "Authentication": {          
          "AuthenticationMode": "AccessToken",
          "AccessToken": "*****",
        },
	"ReflectedWorkItemIdField": "Custom.ReflectedWorkItemId"
      }
    },
    "Processors": [
          {
            "ProcessorType": "ProcessDefinitionProcessor",
            "Enabled": true,
            "UpdateProcessDetails": true,
            "MaxDegreeOfParallelism": 0,
            "SourceName": "Source",
            "TargetName": "Target"
          }
    ]
  }
}

the "doubling" of connectionstrings, is to facilitate easier test with different endpoint options.
Logs:

[09:48:33 INF] [16.3.1] Azure DevOps Migration Tools [Object Model]
[09:48:33 INF] [16.3.1] 16.3.1
[09:48:33 INF] [16.3.1] naked Agility with Martin Hinshelwood
[09:48:33 INF] [16.3.1] ===============================================================================
[09:48:33 INF] [16.3.1] --------------------------------------
[09:48:33 INF] [16.3.1] Telemetry Note:
[09:48:33 INF] [16.3.1] We use Application Insights to collect usage and error information in order to improve the quality of the tools.
[09:48:33 INF] [16.3.1] Currently we collect the following anonymous data:
[09:48:33 INF] [16.3.1] -Event data: application version, client city/country, hosting type, item count, error count, warning count, elapsed time.
[09:48:33 INF] [16.3.1] -Exceptions: application errors and warnings.
[09:48:33 INF] [16.3.1] -Dependencies: REST/ObjectModel calls to Azure DevOps to help us understand performance issues.
[09:48:33 INF] [16.3.1] This data is tied to a session ID that is generated on each run of the application and shown in the logs. This can help with debugging. If you want to disable telemetry you can run the tool with '--disableTelemetry' on the command prompt.
[09:48:33 INF] [16.3.1] Note: Exception data cannot be 100% guaranteed to not leak production data
[09:48:33 INF] [16.3.1] --------------------------------------
[09:48:33 INF] [16.3.1] Start Time: "2025-10-06T09:48:33.7132765+02:00"
[09:48:33 INF] [16.3.1] Running with settings: {"ConfigFile":".\ProcessMigration.json","DisableTelemetry":false,"DebugTrace":false,"skipVersionCheck":false,"$type":"ExecuteMigrationCommandSettings"}
[09:48:33 INF] [16.3.1] OSVersion: Microsoft Windows NT 6.2.9200.0
[09:48:33 INF] [16.3.1] Version (Assembly): 16.3.1
[09:48:33 INF] [16.3.1] Logpath: C:\Users\movs\AppData\Local\Microsoft\WinGet\Packages\nkdAgility.AzureDevOpsMigrationTools_Microsoft.Winget.Source_8wekyb3d8bbwe\logs\20251006094832
[09:48:33 DBG] [16.3.1] DetectOnlineService::IsOnline
[09:48:34 DBG] [16.3.1] IsPackageManagerInstalled: true
[09:48:34 DBG] [16.3.1] Searching for package!
[09:48:37 DBG] [16.3.1] Found package with id nkdAgility.AzureDevOpsMigrationTools
[09:48:37 DBG] [16.3.1] IsPackageInstalled: true
[09:48:37 DBG] [16.3.1] IsUpdateAvailable: false
[09:48:37 DBG] [16.3.1] IsNewLocalVersionAvailable: false
[09:48:37 DBG] [16.3.1] IsRunningInDebug: false
[09:48:37 INF] [16.3.1] Verion Info:
[09:48:37 INF] [16.3.1] Running: 16.3.1.0
[09:48:37 INF] [16.3.1] Installed: 16.3.1
[09:48:37 INF] [16.3.1] Available: 16.3.1
[09:48:38 DBG] [16.3.1] ===================================
[09:48:38 DBG] [16.3.1] Configuring 'MigrationTools:Processors:0:Enrichers'
[09:48:38 DBG] [16.3.1] ===================================
[09:48:38 INF] [16.3.1] No validator found for processor type ProcessDefinitionProcessorOptions
[09:48:38 INF] [16.3.1] Creating Migration Engine 414db9dd-ecc3-481a-b736-4d28ba3b53c5
[09:48:38 INF] [16.3.1] ProcessorContainer: Of 1 configured Processors only 1 are enabled
[09:48:38 INF] [16.3.1] ProcessorContainer: Adding Processor ProcessDefinitionProcessor
[09:48:38 DBG] [16.3.1] Constructor found: IOptions1, CommonTools, ProcessorEnricherContainer, IServiceProvider, ITelemetryLogger, ILogger1
[09:48:38 DBG] [16.3.1] Attempting to pass parameters: OptionsWrapper`1
[09:48:38 DBG] [16.3.1] ===================================
[09:48:38 DBG] [16.3.1] Configuring 'MigrationTools:CommonTools:FieldMappingTool:FieldMaps'
[09:48:38 DBG] [16.3.1] ===================================
[09:48:38 INF] [16.3.1] Logging has been configured and is set to: unknown.
[09:48:38 INF] [16.3.1] Max Logfile: Verbose.
[09:48:38 INF] [16.3.1] Max Console: Debug.
[09:48:38 INF] [16.3.1] Max Application Insights: Error.
[09:48:38 INF] [16.3.1] The Max log levels above show where to go look for extra info. e.g. Even if you set the log level to Verbose you will only see that info in the Log File, however everything up to Debug will be in the Console.
[09:48:38 INF] [16.3.1] Beginning run of 1 processors
[09:48:38 INF] [16.3.1] Processor: ProcessDefinitionProcessor
[09:48:38 INF] [16.3.1] Migration Context Start: ProcessDefinitionProcessor
[09:48:38 INF] [16.3.1] Processor::InternalExecute::Start
[09:48:38 INF] [16.3.1] Processor::EnsureConfigured
[09:48:41 FTL] [16.3.1] Error while running ProcessDefinitionProcessor
System.NullReferenceException: Objektreferencen er ikke indstillet til en forekomst af et objekt.
ved MigrationTools.Processors.ProcessDefinitionProcessor.EnsureConfigured() i D:\a\azure-devops-migration-tools\azure-devops-migration-tools\src\MigrationTools.Clients.AzureDevops.Rest\Processors\ProcessDefinitionProcessor.cs:linje 112
ved MigrationTools.Processors.ProcessDefinitionProcessor.InternalExecute() i D:\a\azure-devops-migration-tools\azure-devops-migration-tools\src\MigrationTools.Clients.AzureDevops.Rest\Processors\ProcessDefinitionProcessor.cs:linje 90
ved MigrationTools.Processors.Infrastructure.Processor.Execute() i D:\a\azure-devops-migration-tools\azure-devops-migration-tools\src\MigrationTools\Processors\Infrastructure\Processor.cs:linje 99
[09:48:42 INF] [16.3.1] ProcessDefinitionProcessor completed in 00:00:00
[09:48:42 ERR] [16.3.1] ProcessDefinitionProcessor The Processor MigrationEngine entered the failed state...stopping run
[09:48:42 INF] [16.3.1] Command ExecuteMigrationCommand completed in "00:00:09.3625540"
[09:48:42 INF] [16.3.1] Check the logs for errors: C:\Users\movs\AppData\Local\Microsoft\WinGet\Packages\nkdAgility.AzureDevOpsMigrationTools_Microsoft.Winget.Source_8wekyb3d8bbwe\logs\20251006094832

{"Timestamp":"2025-10-06T09:48:41.0380483+02:00","Level":"Fatal","MessageTemplate":"Error while running {MigrationContextname}","TraceId":"c929e365e5dcc78974e7ee800ff59c93","SpanId":"2c6bb356e804e90d","Exception":"System.NullReferenceException: Objektreferencen er ikke indstillet til en forekomst af et objekt.\r\n ved MigrationTools.Processors.ProcessDefinitionProcessor.EnsureConfigured() i D:\a\azure-devops-migration-tools\azure-devops-migration-tools\src\MigrationTools.Clients.AzureDevops.Rest\Processors\ProcessDefinitionProcessor.cs:linje 112\r\n ved MigrationTools.Processors.ProcessDefinitionProcessor.InternalExecute() i D:\a\azure-devops-migration-tools\azure-devops-migration-tools\src\MigrationTools.Clients.AzureDevops.Rest\Processors\ProcessDefinitionProcessor.cs:linje 90\r\n ved MigrationTools.Processors.Infrastructure.Processor.Execute() i D:\a\azure-devops-migration-tools\azure-devops-migration-tools\src\MigrationTools\Processors\Infrastructure\Processor.cs:linje 99","Properties":{"MigrationContextname":"ProcessDefinitionProcessor","SourceContext":"MigrationTools.Processors.Infrastructure.Processor","versionString":"16.3.1","ProcessId":2592}}
{"Timestamp":"2025-10-06T09:48:42.9777274+02:00","Level":"Error","MessageTemplate":"{Context} The Processor {ProcessorName} entered the failed state...stopping run","TraceId":"c929e365e5dcc78974e7ee800ff59c93","SpanId":"194de0c037074552","Properties":{"Context":"ProcessDefinitionProcessor","ProcessorName":"MigrationEngine","SourceContext":"MigrationTools.MigrationEngine","versionString":"16.3.1","ProcessId":2592}}

[MrHinsh]

Why do you have both?

  "Organisation": "https://dev.azure.com/Target/",
        "Collection": "https://dev.azure.com/Target/",

[MortenVest]

I have been experimenting using different endpoints to make this work. Left in the definitions to ease switching.

[MortenVest]

A simpler (standard) version
{

"Serilog": {
"MinimumLevel": "Debug"
},
"MigrationTools": {
"Version": "16.3",
"Endpoints": {
"Source": {
"EndpointType": "AzureDevOpsEndpoint",
"Organisation": "https://dev.azure.com/Source/",
"Project": "Test",
"AuthenticationMode": "AccessToken",
"AccessToken": "*****",
"ReflectedWorkItemIdField": "Custom.ReflectedWorkItemId"
},

  "Target": {
    "EndpointType": "AzureDevOpsEndpoint",
    "Organisation": "https://dev.azure.com/Target/",
    "Project": "TargetTest",
    "AuthenticationMode": "AccessToken",
    "AccessToken": "****",
    "ReflectedWorkItemIdField": "Custom.ReflectedWorkItemId"
  }
},
"Processors": [
      {
        "ProcessorType": "ProcessDefinitionProcessor",
        "Enabled": true,
        "UpdateProcessDetails": true,
        "MaxDegreeOfParallelism": 0,
        "SourceName": "Source",
        "TargetName": "Target"
      }
]

}
}

Provides these results:

[13:05:11 INF] [16.3.1] Azure DevOps Migration Tools [Object Model]
[13:05:11 INF] [16.3.1] 16.3.1
[13:05:11 INF] [16.3.1] naked Agility with Martin Hinshelwood
[13:05:11 INF] [16.3.1] ===============================================================================
[13:05:11 INF] [16.3.1] --------------------------------------
[13:05:11 INF] [16.3.1] Telemetry Note:
[13:05:11 INF] [16.3.1] We use Application Insights to collect usage and error information in order to improve the quality of the tools.
[13:05:11 INF] [16.3.1] Currently we collect the following anonymous data:
[13:05:11 INF] [16.3.1] -Event data: application version, client city/country, hosting type, item count, error count, warning count, elapsed time.
[13:05:11 INF] [16.3.1] -Exceptions: application errors and warnings.
[13:05:11 INF] [16.3.1] -Dependencies: REST/ObjectModel calls to Azure DevOps to help us understand performance issues.
[13:05:11 INF] [16.3.1] This data is tied to a session ID that is generated on each run of the application and shown in the logs. This can help with debugging. If you want to disable telemetry you can run the tool with '--disableTelemetry' on the command prompt.
[13:05:11 INF] [16.3.1] Note: Exception data cannot be 100% guaranteed to not leak production data
[13:05:11 INF] [16.3.1] --------------------------------------
[13:05:11 INF] [16.3.1] Start Time: "2025-10-09T13:05:11.6344745+02:00"
[13:05:11 INF] [16.3.1] Running with settings: {"ConfigFile":".\DefaultProcessMigration.json","DisableTelemetry":false,"DebugTrace":false,"skipVersionCheck":false,"$type":"ExecuteMigrationCommandSettings"}
[13:05:11 INF] [16.3.1] OSVersion: Microsoft Windows NT 6.2.9200.0
[13:05:11 INF] [16.3.1] Version (Assembly): 16.3.1
[13:05:11 INF] [16.3.1] Logpath: C:\Users\movs\AppData\Local\Microsoft\WinGet\Packages\nkdAgility.AzureDevOpsMigrationTools_Microsoft.Winget.Source_8wekyb3d8bbwe\logs\20251009130510
[13:05:11 DBG] [16.3.1] DetectOnlineService::IsOnline
[13:05:11 DBG] [16.3.1] IsPackageManagerInstalled: true
[13:05:12 DBG] [16.3.1] Searching for package!
[13:05:30 DBG] [16.3.1] Found package with id nkdAgility.AzureDevOpsMigrationTools
[13:05:30 DBG] [16.3.1] IsPackageInstalled: true
[13:05:30 DBG] [16.3.1] IsUpdateAvailable: false
[13:05:30 DBG] [16.3.1] IsNewLocalVersionAvailable: false
[13:05:30 DBG] [16.3.1] IsRunningInDebug: false
[13:05:30 INF] [16.3.1] Verion Info:
[13:05:30 INF] [16.3.1] Running: 16.3.1.0
[13:05:30 INF] [16.3.1] Installed: 16.3.1
[13:05:30 INF] [16.3.1] Available: 16.3.1
[13:05:31 DBG] [16.3.1] ===================================
[13:05:31 DBG] [16.3.1] Configuring 'MigrationTools:Processors:0:Enrichers'
[13:05:31 DBG] [16.3.1] ===================================
[13:05:31 INF] [16.3.1] No validator found for processor type ProcessDefinitionProcessorOptions
[13:05:31 INF] [16.3.1] Creating Migration Engine d613c60d-80f3-4a3d-8f67-869f3ae6e9dd
[13:05:31 INF] [16.3.1] ProcessorContainer: Of 1 configured Processors only 1 are enabled
[13:05:31 INF] [16.3.1] ProcessorContainer: Adding Processor ProcessDefinitionProcessor
[13:05:31 DBG] [16.3.1] Constructor found: IOptions1, CommonTools, ProcessorEnricherContainer, IServiceProvider, ITelemetryLogger, ILogger1
[13:05:31 DBG] [16.3.1] Attempting to pass parameters: OptionsWrapper`1
[13:05:31 DBG] [16.3.1] ===================================
[13:05:31 DBG] [16.3.1] Configuring 'MigrationTools:CommonTools:FieldMappingTool:FieldMaps'
[13:05:31 DBG] [16.3.1] ===================================
[13:05:31 INF] [16.3.1] Logging has been configured and is set to: unknown.
[13:05:31 INF] [16.3.1] Max Logfile: Verbose.
[13:05:31 INF] [16.3.1] Max Console: Debug.
[13:05:31 INF] [16.3.1] Max Application Insights: Error.
[13:05:31 INF] [16.3.1] The Max log levels above show where to go look for extra info. e.g. Even if you set the log level to Verbose you will only see that info in the Log File, however everything up to Debug will be in the Console.
[13:05:31 INF] [16.3.1] Beginning run of 1 processors
[13:05:31 INF] [16.3.1] Processor: ProcessDefinitionProcessor
[13:05:31 INF] [16.3.1] Migration Context Start: ProcessDefinitionProcessor
[13:05:31 INF] [16.3.1] Processor::InternalExecute::Start
[13:05:31 INF] [16.3.1] Processor::EnsureConfigured
[13:05:33 FTL] [16.3.1] Error while running ProcessDefinitionProcessor
System.NullReferenceException: Objektreferencen er ikke indstillet til en forekomst af et objekt.
ved MigrationTools.Processors.ProcessDefinitionProcessor.EnsureConfigured() i D:\a\azure-devops-migration-tools\azure-devops-migration-tools\src\MigrationTools.Clients.AzureDevops.Rest\Processors\ProcessDefinitionProcessor.cs:linje 112
ved MigrationTools.Processors.ProcessDefinitionProcessor.InternalExecute() i D:\a\azure-devops-migration-tools\azure-devops-migration-tools\src\MigrationTools.Clients.AzureDevops.Rest\Processors\ProcessDefinitionProcessor.cs:linje 90
ved MigrationTools.Processors.Infrastructure.Processor.Execute() i D:\a\azure-devops-migration-tools\azure-devops-migration-tools\src\MigrationTools\Processors\Infrastructure\Processor.cs:linje 99
[13:05:35 INF] [16.3.1] ProcessDefinitionProcessor completed in 00:00:00
[13:05:35 ERR] [16.3.1] ProcessDefinitionProcessor The Processor MigrationEngine entered the failed state...stopping run
[13:05:35 INF] [16.3.1] Command ExecuteMigrationCommand completed in "00:00:23.9300147"
[13:05:35 INF] [16.3.1] Check the logs for errors: C:\Users\movs\AppData\Local\Microsoft\WinGet\Packages\nkdAgility.AzureDevOpsMigrationTools_Microsoft.Winget.Source_8wekyb3d8bbwe\logs\20251009130510

{"Timestamp":"2025-10-09T13:05:33.5586214+02:00","Level":"Fatal","MessageTemplate":"Error while running {MigrationContextname}","TraceId":"849d2e0a45153ee1e740ca49665b47e1","SpanId":"f221530a795bb89a","Exception":"System.NullReferenceException: Objektreferencen er ikke indstillet til en forekomst af et objekt.\r\n ved MigrationTools.Processors.ProcessDefinitionProcessor.EnsureConfigured() i D:\a\azure-devops-migration-tools\azure-devops-migration-tools\src\MigrationTools.Clients.AzureDevops.Rest\Processors\ProcessDefinitionProcessor.cs:linje 112\r\n ved MigrationTools.Processors.ProcessDefinitionProcessor.InternalExecute() i D:\a\azure-devops-migration-tools\azure-devops-migration-tools\src\MigrationTools.Clients.AzureDevops.Rest\Processors\ProcessDefinitionProcessor.cs:linje 90\r\n ved MigrationTools.Processors.Infrastructure.Processor.Execute() i D:\a\azure-devops-migration-tools\azure-devops-migration-tools\src\MigrationTools\Processors\Infrastructure\Processor.cs:linje 99","Properties":{"MigrationContextname":"ProcessDefinitionProcessor","SourceContext":"MigrationTools.Processors.Infrastructure.Processor","versionString":"16.3.1","ProcessId":26916}}
{"Timestamp":"2025-10-09T13:05:35.4611387+02:00","Level":"Error","MessageTemplate":"{Context} The Processor {ProcessorName} entered the failed state...stopping run","TraceId":"849d2e0a45153ee1e740ca49665b47e1","SpanId":"ed13a173d3508ace","Properties":{"Context":"ProcessDefinitionProcessor","ProcessorName":"MigrationEngine","SourceContext":"MigrationTools.MigrationEngine","versionString":"16.3.1","ProcessId":26916}}