AppOps DX Plugin

Overview 

Scratch orgs, like development sandboxes, don’t include data when created. Because scratch orgs are typically created and dissolved on a daily basis, quickly and easily adding data to and deploying data from scratch orgs is critical for developer productivity. Prodly provides a Salesforce DX plugin so Salesforce developers can easily seed their scratch orgs with data and/or deploy data to and from any Salesforce environment directly using the sfdx command line interface.

The plugin allows you to deploy data between these environment types for any environment you have credentials to access:

  • From a developer hub (dev hub) org to a scratch org.
  • From any environment to a scratch org.
  • From a scratch org to any environment, except a dev hub org.
  • From any non-scratch org to any non-scratch org.

Some example use cases:

  • Copy a subset of data from an existing production environment to a scratch org for testing purposes.
  • After developing and testing an application using scratch orgs, deploy the changes to a centralized sandbox.
  • Mimic the typical environment-to-environment deployment you do from the AppOps Release user interface.
  • Many other possibilities…

Setup 

To properly set up your environment for using the plugin:

  1. Follow the instructions in the Salesforce DX Setup Guide to enable the Salesforce Developer Hub (dev hub) in your production or business environment.
  2. Follow the instructions in the Install the Managed Package topic of Prodly AppOps Release to install the Prodly AppOps managed package in your dev hub org. The dev hub org must be the AppOps control environment.
  3. Download the Prodly AppOps Salesforce DX plugin from https://github.com/prodly/appopsdxcli or https://www.npmjs.com/package/appopsdxcli and install the plugin in your dev hub org.
  4. Use the Salesforce DX command-line interface (CLI) to authorize your dev hub org.
  5. Use the Salesforce DX (sfdx) CLI to create your scratch orgs.
  6. Optionally, use this command to set a default dev hub username:$ sfdx force:config:set defaultdevhubusername=<devhubusername_or_alias> –global
  7. Optionally, use this command to set a default scratch org username:$ sfdx force:config:set defaultusername=<username_or_alias> –global
  8. Before accessing each environment (from production to full sandbox to scratch org) relevant to your use case for the very first time, either add the environment on the Environments page in the UI or use the appops:manage -m command to connect AppOps Release to the environment from the command.
  • If you encounter errors deploying to a scratch org either after initial creation or after your session times out, run this command:$ sfdx force:org:open – u

Usage 

Prodly’s Salesforce DX plugin consists of these commands:

  • appops:checkin – saves data from a Salesforce environment to a version control system (VCS) repository branch.
  • appops:checkout – deploys data from a VCS repository branch to a Salesforce environment.
  • appops:deploy – deploys data from one Salesforce environment to another Salesforce environment.
  • appops:manage – authorizes a Salesforce environment for use by the plugin.

appops:checkin 

To save data from a Salesforce environment to a VCS repository branch, enter this command at the command line prompt in your Salesforce DX CLI command shell:

$ sfdx appops:checkin [OPTIONS]

This table lists all the available options:

OptionsPurpose
-c <comment>,
–comment=<comment>
Use to include a VCS commit message.
-i <environment>,
–instance=<environment>
Use to specify the Salesforce environment that contains the data to save to its associated VCS repository branch.
-u <username>,
–targetusername=<username>
Use to specify the username or alias of the destination environment, overriding any default scratch org you specified in the optional setup steps.
-v <username>,
–targetdevhubusername=<username>
Use to specify the username or alias of the dev hub org, overriding any dev hub org you specified in the optional setup steps.
–apiversion=<apiversion>Use to override the API version used for API requests made by this command.
–jsonUse to receive an output response. When included, the response is in JSON format. When not included, no response is given.
–loglevel=<level>Use to specify the logging level for this command invocation with one of these levels:errorwarninfodebugtracefatalFor details, refer to https://developer.salesforce.com/docs/atlas.en-us.sfdx_setup.meta/sfdx_setup/sfdx_dev_cli_log_messages.htm.

appops:checkout 

To deploy data from a VCS repository branch to a Salesforce environment, enter this command at the command line prompt in your Salesforce DX CLI command shell:

$ sfdx appops:checkout [OPTIONS]

This table lists all the available options:

OptionsPurpose
-e <deactivate>,
–deactivate
Use to temporarily deactivate all events AppOps has permission to deactivate.
-i <environment>,
–instance=<environment>
Use to specify the destination Salesforce environment to deploy the data from its associated VCS repository branch to.
-u <username>,
–targetusername=<username>
Use to specify the username or alias of the destination environment, overriding any default scratch org you specified in the optional setup steps.
-v <username>,
–targetdevhubusername=<username>
Use to specify the username or alias of the dev hub org, overriding any dev hub org you specified in the optional setup steps.
–apiversion=<apiversion>Use to override the API version used for API requests made by this command.
–jsonUse to receive an output response. When included, the response is in JSON format. When not included, no response is given.
–loglevel=<level>Use to specify the logging level for this command invocation with one of these levels:errorwarninfodebugtracefatalFor details, refer to https://developer.salesforce.com/docs/atlas.en-us.sfdx_setup.meta/sfdx_setup/sfdx_dev_cli_log_messages.htm.

appops:deploy 

To deploy data from one Salesforce environment directly to another Salesforce environment, enter this command at the command line prompt in your Salesforce DX CLI command shell:

$ sfdx appops:deploy DATA [ENVIRONMENTS] [OPTIONS]

The parameters provide for maximum flexibility when using the CLI command. Deployment requires these three pieces of information:

  • Deployment instructions (deployment plan or data set)
  • The environment to use as the source of the data to deploy
  • The environment to use as the source destination of the data to deploy

Here are all the available parameters:

Data

ParameterPurpose
-p <deployment plan>,
–plan=<deployment plan>
Use to specify the name or record ID of the deployment plan to deploy.
-t <dataset>,
–dataset=<dataset>
Use to specify the name or record ID of the data set to deploy.

Notes: Specify exactly one deployment instructions parameter. Specifying zero or more than one deployment instructions parameter results in an error. For each data set and deployment plan in the deployment, Active must be selected in the corresponding AppOps record.

Environments

ParameterPurpose
NoneUse to specify the dev hub org as the source environment and the scratch org as the destination environment.
-s connection,
–source=<connection>
Use to specify an AppOps connection name or record ID as the source environment and the scratch org as the destination environment.
-d <connection>,
–destination=<connection>
Use to specify the scratch org as the source environment and an AppOps connection name or record ID as the destination environment.

Notes: Specify zero, one, or both org parameters. When not specifying an org parameter, you must specify the scratch and dev hub orgs either with the optional setup steps or with the -u/–targetusername and -v/–targetdevhubusername options. When specifying an AppOps connection record, Active must be selected in the AppOps connection record. When specifying an AppOps connection record as the destination environment, Do Not Allow As Destination must not be selected in the AppOps connection record. When specifying an AppOps connection record by a name that exists for more than one record, AppOps uses the last-modified connection.The dev hub org cannot be the destination environment.

Options

ParameterPurpose
-b <nickname>,
–label=<nickname>
Use to specify a nickname for the environment.
-e,
–deactivate
Use to temporarily deactivate all events AppOps has permission to deactivate.
-l,
–simulation
Use to preview the source records that would be deployed.
-n <deployment name>,
–name=<deployment name>
Use to specify a name for the deployment.
-o <notes>,
–notes=<notes>
Use to include notes in the deployment results.
-q <query filter>,
–filter=<query filter>
Use to specify a query filter override for a data set deployment.
-u <username>,
–targetusername=<username>
Use to specify the username or alias of the destination environment, overriding any default scratch org you specified in the optional setup steps.
-v <username>,
–targetdevhubusername=<username>
Use to specify the username or alias of the dev hub org, overriding any dev hub org you specified in the optional setup steps.
–apiversion=<apiversion>Use to override the API version used for API requests made by this command.
–jsonUse to receive an output response. When included, the response is in JSON format. When not included, no response is given.
–loglevel=<level>Use to specify the logging level for this command invocation with one of these levels:errorwarninfodebugtracefatalFor details, refer to https://developer.salesforce.com/docs/atlas.en-us.sfdx_setup.meta/sfdx_setup/sfdx_dev_cli_log_messages.htm.

The AppOps service retrieves the active control environment connection information from the dev hub control org. If not found, the service returns an error and terminates.

The scratch and dev hub org connections are based on access tokens only. You cannot use refresh tokens. This requirement means the session settings you configure in the environments apply. Any deployment running for longer than the session timeout terminates on next connection access.

For any deployment involving the dev hub org, the plugin uses the control environment connection from AppOps as the control environment connection for the actual deployment, not the dev hub org connection from DX. The user who created the control environment connection in AppOps can be different than the user who authenticated the dev hub org in Salesforce DX.

The plugin uses the DX dev hub connection to query for connections and insert the result, and uses the DX dev hub connection as the source connection when the source environment is also the control environment. The AppOps service uses the control environment connection to report results and the source connection to query for data and metadata.

AppOps service inserts deployment result record into your control environment. Monitor the deployment and view the results in the Prodly AppOps app on the Deployment Results tab.

appops:manage 

To authorize (or unauthorize) a Salesforce environment (not already added to the Environments page in AppOps Release) for use by the plugin, enter this command at the command line prompt in your Salesforce DX CLI command shell:

$ sfdx appops:manage INSTRUCTIONS [ENVIRONMENTS] [OPTIONS]

This table lists all the available options:

OptionsPurpose
-b <nickname>,
–label=<nickname>
Use to specify a nickname for the environment.
-c <comment>,
–comment=<comment>
Use to include a VCS commit message.
-i <environment>,
–instance=<environment>
Use to specify the Salesforce environment ID on which to perform the action.
-l,
–list
Use to see the list of all environments added via this plugin and/or the AppOps Release UI.
-m,
–manage
Use to make the Salesforce environment available to AppOps Release and the other appops DX plugin commands.
-n <connection>,
–connection=<connection>
Use to specify the connection record to use to access the Salesforce environment.
-p,
–print
Use to see a standardized-format list of all environments added via this plugin and/or the AppOps Release UI.
-s,
–version
Use to create a VCS repository branch, merge data from main into it, and deploy the data to  the Salesforce environment.
-u <username>,
–targetusername=<username>
Use to specify the username or alias of the destination environment, overriding any default scratch org you specified in the optional setup steps.
-v <username>,
–targetdevhubusername=<username>
Use to specify the username or alias of the dev hub org, overriding any dev hub org you specified in the optional setup steps.
-x,
–unmanage
Use to make the Salesforce environment unavailable to AppOps Release and the other appops DX plugin commands.
–apiversion=<apiversion>Use to override the API version used for API requests made by this command.
–jsonUse to receive an output response. When included, the response is in JSON format. When not included, no response is given.
–loglevel=<level>Use to specify the logging level for this command invocation with one of these levels:errorwarninfodebugtracefatalFor details, refer to https://developer.salesforce.com/docs/atlas.en-us.sfdx_setup.meta/sfdx_setup/sfdx_dev_cli_log_messages.htm.

Response 

When you include –json in your appops:deploy command, you receive the following output when the deployment initiates:

{
“Deployment launched with the result ID “${insertResult[0].id}
}

Examples 

CommandResult
$ sfdx appops:deploy -p MyDeploymentPlanUses a deployment plan to deploy data to the default scratch org from the default dev hub org.
$ sfdx appops:deploy -t MyDataSet -u FixesScratchOrg -v MainDevHubUses a data set to deploy data to a specified scratch org from a specified dev hub org.
$ sfdx appops:deploy –dataset=MyDataSet –targetusername=test-utxac7gbati9@example.com –targetdevhubusername=jsmith@acme.comUses a data set to deploy data to a specified scratch org from a specified dev hub org using long parameter names.
$ sfdx appops:deploy -t MyDataSet -d “UAT Sandbox Connection”Uses a data set to deploy data to a specified UAT sandbox org from the default scratch org using the named connection record.
$ sfdx appops:deploy –plan=MyDeploymentPlan –targetusername=test-utxac7gbati9@example.com –source “Production Connection”Uses a deployment plan to deploy data to a specified scratch org from the production org using the named connection record and long parameter names.