Process Version Migration Utility v3 0 6

This is an update of the "process instance version migration utility" originally created by NeilM and subsequently modified by Jacob Behrnes and Steve H.
The version 3.0.4 contains the following changes:
-Check if Data Fields are compatible between the 2 versions before the migration. If a version is used in the filter, the drop down list of destination version is filtered on only the compatible one.
-Allow if all Data Fields are in the same order and same type but with new Data Fields before/after/between.
-When a Data Field issue is found, display the details of Data Field per version.
-Add check-box to check status of Data Fields during initial display of process instances.
-During migration, check Data Field status (Error or not) before and after if the check-box is ticked.
-You can use keyboard to tick the current selected process instance: Space button for tick check-box. Your selection can be in any columns.
-After select rows (very first small column) you can use the new button "Toggle Select" to Tick/Untick the corresponding rows.
-In the report, display the status of migration (not only error message).
-Update height and width of the main process instance table when the form is resized.
-Display the Original version number in the main table
-Adapt the width of the columns Status to fill all the free space.
-In the conf file: Ability to have a default environment setup
-Now it's possible to set default filter values in the config file like this:
       <DefaultProcess Status="Active" ItemLimit="50"/>
        <DefaultProcess ProcessName="K2ProjectMigrationTestProcessMig" Activity="DefaultActivity"  Version="23" Status="Active" ItemLimit="50"/>
       When ProcessName is setup a search will be done automatically
       <DefaultProcess ProcessName="K2ProjectMigrationTestProcessMig" Activity=""  Version="" Status="" ItemLimit="50"/>
-Fix issue if double click on a row (index out of range)
This version was tested with K2 4.6.11.
If you find any bugs, please let me know.
Version 3.0.5 (September 2018):
This version has been tested with 4.6.11 and K2 Five.
-Add management of known issue with K2 Five: With new K2 Five designer, according our test, the migration work only if no Client Event action has been performed. No issue detected with K2 Studio.
  Display column "Number of client event" in the table: Only records with 0 client event will be migrated without error.
  Add check-box "Force the migration in spite of potential K2 Five issue detected" 
  Issue logged to K2 development team. For more information see comment of "*personal details removed*:30 PM".
  In all cases, this tool is not supported by K2 Support. If you want to use it, we strongly advise to do test on other environment before migration on production.
-Display the DisplayName of the Activity. If process instance is stopped, don't try to re-stop it.
-Change icon to green in order to avoid display issue  when windows task bar is black
-Add button "Open selected process instance details." 
Version 3.0.6 (May 2019):
-Don't display warning message since fix compatibility issue with K2 Five 5.2 FP27.
-Add Folio and Process instance id as filter
-Display a clearer error message when the database settings are not correct or ProcessInstanceVersionMigrator.exe.config is not found.
-Increase the width of Process name
-Fix issue about filter of version, status, activity and order by not took into account in some cases.
-Display in the windows title the version of the tool and the K2 version.
-For Datafield check: Fix issue if some version didn't have any Datafield (Variable)
Improve management of errors. Replace destination version column from a green color to a blue one and add in the header 'Current destination'.
Version (September 2019):
Fix issue of message display about compatibilty even if we are in 5.2 Cumulative update.
Hi Olivier,

Thanks for uploading this utility, it is very helpful 🙂

However, sometimes we need to connect to K2 using AAD credentials. Is there some way you can add "Security Label Name" to the Connection String properties in the .config file? So we can connect using different Security Labels?

And would this also affect how we connect to the SQL server? Can we connect to the SQL server through the K2 server for example, so we don't need to run this utility as the K2 Service Account?

Thanks and kind regards,
Hi Olivier, another request, can you please include logging into your utility? A customer recently ran into an issue where the only error message was "Object reference not set to an instance of an object" which is very vague, and some detailed / verbose logging would be helpful in this case. Thanks!

Has anyone tried if this will work with K2Five?

Thanks for taking over this utility, Olivier.  Does this now work better with K2 4.7?  Has it been tested with K2 Five?

Steve_H, Knudsend
Warning: when I use Process Version Migration on a K2 Five (5.1 FP13), I saw two issues:
   - The more important/blocking one: When you add new Task on the workflow, if you try to migrate, the process instance will be stopped you will have error "Error while migrating to new version:Object reference not set to an instance of an object.".
   At this state, it's not possible to do the migration to the previous version and we can't remove this instance (same error message): Very dangerous.
The only case where the migration work is when there are no Client event with an action done.
More details:
Issue with K2 Five new workflow designer (FP20 at least).
If we deploy twice the workflow: version 3 and 4 are exactly the same.
Start 2 instances with version 3.
Approve the first instance only to go to Task 2. The second instance is still in first step.
Do the migration of the instances from 3 to 4: only no issue with the second instance (in first step : CODE is always "Task").
Other issue found:
Start 1 instance with version 3.
Approve the first task only to go to Task 2.
Do GoToActivity of the first instance (Version is 3 and current task "First task")
Do the migration of the instances from 3 to 4: Issue: seems to be linked to the first action done.
Test with First task as Timer and SmartObject: no issue. First issue is when we perform a client event (Certainly linked to table [ServerLog].[ActInstSlot])
No issue with K2 Studio and K2 Five

I opened a ticket with this title "Migration of instance generate a blocking state with  "Object reference not set to an instance of an object.". Please contact support team.
  - No very important and not blocking: The Datafields seems to be duplicated after each migration of workflow instance in the reports Process Overview/Process instance Detail/Data Audit. In the K2 database the information is not realy duplicated: it's only one data in table [ServerLog].[ProcInstData] .
I opened ticket with this title: "Migration of K2 workflow generate duplicated datafield in the process overview". Please contact support team.
Best regards,

Where is the download link for this version?



As it explained in this url:


The Market Solution files are temporarily unavailable from the Community, while we transition to the new format.
As per this post to the Community News board, you should email one of the Community Administrators, and specify which project you are looking for. 


The new Market is under development, and coming soon.


We apologize for the inconvenience.


Thanks, and regards,


K2 will not accept any liability for any issues arising from actions taken in respect of the information provided by any forum member.





Currently the K2 Five issue raised in ticket 152011 is not fixed.

But you can vote to the following idea:


Best regards,




I believe the object reference error when using process migration if a client event was completed is resolved in FP27:

The tool's filtering isn't working for activity and version. e.g. I selected to filter on v11 but v12 shows up. With FP27 I migrated a few dozen then encountered 1 item with this error. A database error occurred : Object reference not set to an instance of an object. Compared ProcId and ExecutingProcID and they were the same. Just needed to Restarted the work item from a stopped state.
Olivier, Is this tool meant for installations with 4.7 to K2 Five so it uses SourceCode.Workflow.Management API's SetProcessInstanceVersion(procInstId, NewVersionNumber) ? Does it work also with fresh K2 Five install? If we wanted to migrate a specific procinstId we can just use the API? It seems K2 did not update SetProcessInstanceVersion API to work properly in: 4.7 processes running in K2 Five? K2 Five processes running in K2 Five? (based on the issues/conditions stated in CheckIfK2fiveVersionIsCompatible()) Anyone tried it on K2 Five 5.3?

Hi Pyao,

I didn't work on this tools since K2 five 5.0. But I can say that this tool (not originally created by me) use the 

SetProcessInstanceVersion(procInstId, NewVersionNumber) 


Today, according ticket 152011  the corresponding TFS is not officialy fixed.

If you want to use this tool, I advise to do a backup of database before because, if the bug is still here, your process instances will be definitively broked.


Best regards,


Hi Pyao,


I generated the version 3.0.6: After some tests, the issue of "Object reference not set to an instance of an object." has been fixed with 5.2 FP27 (Reproduced with FP26). We don't have the issue too with 5.3 (No FP).

Thanks to Celine for the test!


Remember: In all cases, this tool is not supported by K2 Support. If you want to use it, we strongly advise to do test on other environment before migration on production.


See details of version 3.0.6 in the main comment in the top of this page.


Best regards,


Oliver, on FP27 using 3.0.6, why are some items in the same process getting 24129 A database error occurred : Object reference not set to an instance of an object. Is there more detail to the error?

Hi Olivier,

first of all: thank you for the good work, the tool looks very useful and the new features are a great improvement on the original version.

However, it does not work for us. We get a couple of errors ("Could not retrieve process set ID for selected process", "Error during retrieve of instance: the input string was not in the correct format"). So I was wondering if the source code is available somewhere (as it was for the previous version) so we can debug these errors?

kind regards,


I thought I saw source code to this tool at one point. I couldn't edit my last comment, but I am still encountering this bug where the instance becomes Stopped. On 5.2 FP27 using 3.0.6, some items in the same process gets 24129 A database error occurred : Object reference not set to an instance of an object. So this tool does not other database updates other than calling the SetProcessInstanceVersion(procInstId, NewVersionNumber) API which in turn calls a K2 stored proc in the database, and it's this K2 stored proc that's buggy?



I put the source code attached. Generally the issue "Could not retrieve process set ID for selected process" could appears if the database not correspond to the K2 server (Dev/Production).



 What is the context of the error? If you are able to reproduce, I think that the best thing is to open a support ticket base on the use of SetProcessInstanceVersion(procInstId, NewVersionNumber) API. In the Source of this tool, you have a very simple tool "SimpleUseOfSetProcessInstanceVersion" that you can provide as test for labs.


Best regards,


Oliver, it failed on SetProcessInstanceVersion. Tried StopProcessInstance first also. I removed the SourceCode DLL (seems for 4.x) that came with the zip and just let it use the one installed by K2 on test server. Exception thrown: 'ClientException' in SourceCode.HostClientAPI.dll Additional information: 24129 A database error occurred : Object reference not set to an instance of an object. Thanks for the source upload, can clean up the files in in and obj folders and delete SourceCode*.dll.


I known that when we try to use the tool on an instance already badly migrated (because migrated before 5.2 FP27) the issue will still here even if you upgrade to 5.2 FP27. Are you in this configuration? Do you reproduce the issue on the new instance (Old version) of the workflow?

If yes, in the Source of this tool, you have a very simple tool "SimpleUseOfSetProcessInstanceVersion" that you can provide as test for labs.  Please reproduce the issue on this tool and open a Support Ticket that will be acceptable by labs.


Best regards,


Hi Guys,

Has anyone been able to use this on a K2 CLOUD environment?
If so, what did you modify to make it work?




This tools is currently note available for cloud as it need a direct access to the K2 server and a SQL access to the corresponding database.

If it's only the solution that you needed, maybe open a ticket support asking to use this tool to do the migration, but I'm not sure that it will be accepted as support.


You can vote to the following idea:


Best regards,


3.0.6 has an issue with checking for compatibility if your 5.2 has updated to use the CU. You'll get this error: "Known issue with K2 Five version: Impossible to migrate without error." Current code checks for version.IndexOf("fp"); (version.StartsWith("k2 five (5.2") && fpNb<27) _IsK2FiveVersionWithIssue = true; K2 Five (5.2) May 2019 CU Fixpack 04 K2 Five (5.2) May 2019 Cumulative Update K2 Five (5.2) FP27


I fixed this issue with version

Best regards,



Fantastic tool. I am bewildered that I am the first to give it kudos.


Thank you!

Dear all,


In this tool, we can use the behavior "Go To Activity":  

Warning:  we have encountered a problem and are in discussion with the Project managers:

Following the use of the go to activity inside a Split/Merge the workflow stops at the “Merge” step next. Issue appears with Go To Activty from Management site with K2 Five new designer (Split and merge was not possible in K2 Studio). The issue appears too with Process Version Migration Utility.


At the same time, I asked to an impacted customer to create 2 K2 Ideas created in order to maximize the chances of having actions taken on this subject which can be blocking.


I therefore invite you to vote on these K2 ideas:

Fix issue: after go to activity, the workflow stop at the next merge step.

Add warning message in case of use of Go to activity from Management site to avoid important issue with split branches.


Best regards,



Version history
Revision #:
1 of 1
Last update:
‎08-23-2017 04:55 AM
Updated by: