v1 to v2 migration guide

Version 2 of OrgFlow brings a handful of new features and breaking changes. This guide will take you through the process of updating from version 1 to version 2.

Output formats

The most impactful breaking change is to the way that you specify the output format of commands. Version 1 had an --output argument on every command which allowed you to specify on output format of Pretty, Flat, or JSON. The Flat output format was not frequently used, and it added maintentance overhead (especially as we continued to add new features and commands).

Version 2 of OrgFlow removes the Flat output format and the --output argument, and continues to default to Pretty output format unless the new --json switch is specified (which changes the output to JSON). We feel that this new switch simplifies the control of output format as well as reducing our maintenance overhead. The migration steps required are as follows:

Anywhere where you ommitted the --output argument will continue to work as before.
Anywhere where you specified --output=pretty will need to be updated so that this argument is removed.
Anywhere where you specified --output=flat will need to be updated. There is no equivalent to the flat output in version 2, so you will need to decide whether to switch to pretty or JSON output in these cases.
Anywhere where you specified --output=json will need to be updated to --json.

Source tracking

OrgFlow builds on the Source Tracking features in Salesforce to add two powerful new features in version2: Clobber detection and Partial Retrieve. OrgFlow automatically detects whether or not source tracking is available for your Salesforce orgs and Environment, and it can fall back to maintain functionality should source tracking not be available.

You do not need to do anything in OrgFlow to enable source tracking support, but you may want to ensure that source tracking is enabled in your Salesforce orgs so that you get the best OrgFlow experience. OrgFlow will automatically enable source tracking support after the first Flow In with version 2 from an org with source tracking enabled.

Clobber detection

Clobber detection can warn you before you deploy changes that would overwrite changes in the Salesforce org. Version 1 of OrgFlow would simply continue with this deployment wihtout producing any warnings. You may need to update any workflows that will now fail if clobber is detected. The affected commands are env:flowout and env:flowmerge, and the new behavior in version 2 of OrgFlow could mean that scripts including either of these two commands could now fail if OrgFlow detects clobber.

If you want to maintain the version 1 functionality (of always deploying regardless of clobber), you need to add the --clobber=accept argument to scripts with the affected commands. However, we'd recommend that you take advantage of OrgFlow's new clobber detection and decide the best way to proceed on a case-by-case basis for each of your scripts and environments. The clobber documentation can help you understand the different options available, and how to implement them.

Partial retrieves

Partial Retrieve is powered by source tracking, and can significantly reduce the time it takes to retrieve changes from Salesforce. Version 2 of OrgFlow will automatically opt you in to partial retrieves for environments where source tracking is available, but you can opt out of this by specifying:

--retrieveMode=full for env:flowin
--sourceInRetrieveMode=full or --targetInRetrieveMode=full for env:flowmerge

Selective inbound flows

The --excludeUndeployable, --interactiveExclude and --exclude arguments have been removed from the env:flowin command. These arguments allowed you to do 'selective inbound flows', but excluding components during inbound flows prevented us from being able to rely on source tracking data from Salesforce. This feature required a large amount of maintenance and testing which slowed down delivery of other features, and it contributed a relatively large percentage of the overall download size.