-
Notifications
You must be signed in to change notification settings - Fork 39
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #133 from amtrack/docs
docs: improve README
- Loading branch information
Showing
1 changed file
with
90 additions
and
84 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -4,116 +4,66 @@ | |
| [](https://travis-ci.org/amtrack/sfdx-browserforce-plugin) | ||
|
|
||
| Unlike the [Scratch Org Definition Configuration](https://developer.salesforce.com/docs/atlas.en-us.sfdx_dev.meta/sfdx_dev/sfdx_dev_scratch_orgs_def_file.htm) which can only be used **on the creation of a scratch org** (`sfdx force:org:create -f config/scratch-def.json`), | ||
| the _Browserforce Configuration_ allows to "shape" **any org**, (e.g. scratch org, sandbox or production org) with **similar preferences and unofficial preferences** that are not (yet) available in the _Scratch Org Definition Configuration_ or as _Metadata_ (`sfdx browserforce:apply -f config/setup-admin-login-as-any.json -u [email protected]`). | ||
|
|
||
| Further benefits: | ||
|
|
||
| - comfortable configuration using JSON Schema (similar to the [Scratch Org Definition Configuration](https://developer.salesforce.com/docs/atlas.en-us.sfdx_dev.meta/sfdx_dev/sfdx_dev_scratch_orgs_def_file.htm)) | ||
| - idempotency of the `apply` command only applies what's necessary and allows re-execution (concept similar to [terraform](https://www.terraform.io/docs/commands/apply.html)) | ||
| - browser automation powered by [Puppeteer](https://github.com/GoogleChrome/puppeteer) (Chromium) | ||
| - implement your own custom preferences (a.k.a. plugins; to be improved) | ||
|
|
||
| # Installation | ||
|
|
||
| Install either globally (and use it via `sfdx browserforce`) | ||
| There are several different methods to install `sfdx-browserforce-plugin`: | ||
|
|
||
| ```console | ||
| # as an sfdx plugin globally | ||
| sfdx plugins:install sfdx-browserforce-plugin | ||
| ``` | ||
|
|
||
| or in your project as a dev dependency (and use it via `npx sfdx-browserforce-plugin browserforce`). | ||
| # or standalone globally | ||
| npm install --global sfdx-browserforce-plugin | ||
|
|
||
| ```console | ||
| # or standalone locally (as a dependency in your Node.js project) | ||
| npm install --save-dev sfdx-browserforce-plugin | ||
| ``` | ||
|
|
||
| # Usage | ||
|
|
||
| ```console | ||
| sfdx browserforce -h | ||
| npx sfdx-browserforce-plugin browserforce -h | ||
| ``` | ||
|
|
||
| # Commands | ||
|
|
||
| <!-- commands --> | ||
| * [`sfdx-browserforce-plugin browserforce:apply`](#sfdx-browserforce-plugin-browserforceapply) | ||
| * [`sfdx-browserforce-plugin browserforce:plan`](#sfdx-browserforce-plugin-browserforceplan) | ||
|
|
||
| ## `sfdx-browserforce-plugin browserforce:apply` | ||
|
|
||
| apply a plan from a plan file or remote state | ||
|
|
||
| ``` | ||
| USAGE | ||
| $ sfdx-browserforce-plugin browserforce:apply | ||
| OPTIONS | ||
| -f, --definitionfile=definitionfile path to a browserforce definition file | ||
| The schema is similar to the scratch org definition file. | ||
| See | ||
| https://github.com/amtrack/sfdx-browserforce-plugin#supported-org-pref | ||
| erences for supported values. | ||
| -p, --planfile=planfile path to a browserforce plan file | ||
| -s, --statefile=statefile path to a browserforce state file | ||
| -u, --targetusername=targetusername username or alias for the target org; overrides default target org | ||
| Depending on your choice of installation, you can find the `browserforce` namespace: | ||
|
|
||
| --apiversion=apiversion override the api version used for api requests made by this command | ||
| --json format output as json | ||
| ```console | ||
| # globally in the sfdx cli | ||
| sfdx browserforce | ||
|
|
||
| --loglevel=(trace|debug|info|warn|error|fatal) logging level for this command invocation | ||
| # globally in the sfdx-browserforce-plugin executable | ||
| sfdx-browserforce-plugin browserforce | ||
|
|
||
| EXAMPLE | ||
| $ sfdx browserforce:apply -f ./config/setup-admin-login-as-any.json --targetusername [email protected] | ||
| Applying plan file ./config/setup-admin-login-as-any.json to org [email protected] | ||
| logging in... done | ||
| [Security] retrieving state... done | ||
| [Security] changing 'loginAccessPolicies' to '{"administratorsCanLogInAsAnyUser":true}'... done | ||
| logging out... done | ||
| # locally in the sfdx-browserforce-plugin executable (npx is awesome!) | ||
| npx sfdx-browserforce-plugin browserforce | ||
| ``` | ||
|
|
||
| _See code: [src/commands/browserforce/apply.ts](https://github.com/amtrack/sfdx-browserforce-plugin/blob/v0.0.0-development/src/commands/browserforce/apply.ts)_ | ||
|
|
||
| ## `sfdx-browserforce-plugin browserforce:plan` | ||
|
|
||
| retrieve state and generate plan file | ||
| ```console | ||
| $ sfdx-browserforce browserforce -h | ||
| browser automation | ||
|
|
||
| ``` | ||
| USAGE | ||
| $ sfdx-browserforce-plugin browserforce:plan | ||
| $ sfdx-browserforce-plugin browserforce:COMMAND | ||
|
|
||
| OPTIONS | ||
| -f, --definitionfile=definitionfile path to a browserforce definition file | ||
| The schema is similar to the scratch org definition file. | ||
| See | ||
| https://github.com/amtrack/sfdx-browserforce-plugin#supported-org-pref | ||
| erences for supported values. | ||
| -p, --planfile=planfile path to a browserforce plan file | ||
| -s, --statefile=statefile path to a browserforce state file | ||
| -u, --targetusername=targetusername username or alias for the target org; overrides default target org | ||
| --apiversion=apiversion override the api version used for api requests made by this command | ||
| --json format output as json | ||
| --loglevel=(trace|debug|info|warn|error|fatal) logging level for this command invocation | ||
| EXAMPLE | ||
| $ sfdx browserforce:plan -f ./config/setup-admin-login-as-any.json -o /tmp/state.json --targetusername | ||
| [email protected] | ||
| Generating plan with definition file ./config/setup-admin-login-as-any.json from org [email protected] | ||
| logging in... done | ||
| [Security] retrieving state... done | ||
| [Security] generating plan... done | ||
| logging out... done | ||
| COMMANDS | ||
| browserforce:apply apply a plan from a plan file or remote state | ||
| browserforce:plan retrieve state and generate plan file | ||
| ``` | ||
|
|
||
| _See code: [src/commands/browserforce/plan.ts](https://github.com/amtrack/sfdx-browserforce-plugin/blob/v0.0.0-development/src/commands/browserforce/plan.ts)_ | ||
| <!-- commandsstop --> | ||
| Both the `browserforce:apply` and `browserforce:plan` commands expect a config file and a target username or alias for the org. | ||
|
|
||
| # Example | ||
|
|
||
| To enable `Setup -> Security Controls -> Login Access Policies -> Administrators Can Log in as Any User`, the config file (here: `./config/setup-admin-login-as-any.json`) should look like this: | ||
|
|
||
| ```json | ||
| "$schema": "https://raw.githubusercontent.com/amtrack/sfdx-browserforce-plugin/v1.2.0/src/plugins/schema.json", | ||
| { | ||
| "settings": { | ||
| "security:" { | ||
|
|
@@ -125,14 +75,70 @@ To enable `Setup -> Security Controls -> Login Access Policies -> Administrators | |
| } | ||
| ``` | ||
|
|
||
| Tip: If you use _Visual Studio Code_, you can leverage tab completion to build the config (powered by the JSON Schema). | ||
|
|
||
| Next apply the config: | ||
|
|
||
| ```console | ||
| $ sfdx browserforce:apply -f ./config/setup-admin-login-as-any.json --targetusername [email protected] | ||
| Applying plan file ./config/setup-admin-login-as-any.json to org [email protected] | ||
| logging in... done | ||
| [Security] retrieving state... done | ||
| [Security] changing 'loginAccessPolicies' to '{"administratorsCanLogInAsAnyUser":true}'... done | ||
| logging out... done | ||
| ``` | ||
|
|
||
| # Supported Settings | ||
|
|
||
| See the [JSON Schema](src/plugins/schema.json) for supported settings. | ||
| See the [JSON Schema](src/plugins/schema.json) for all supported settings. | ||
|
|
||
| Here is a full blown example showing most of the supported settings in action: | ||
|
|
||
| ```json | ||
| { | ||
| "$schema": "https://raw.githubusercontent.com/amtrack/sfdx-browserforce-plugin/v1.2.0/src/plugins/schema.json", | ||
| "settings": { | ||
| "communities": { "enabled": true }, | ||
| "companySettings": { | ||
| "criticalUpdates": [ | ||
| { | ||
| "name": "*Security*", | ||
| "active": true, | ||
| "comment": "activated by sfdx-browserforce-plugin" | ||
| }, | ||
| { | ||
| "name": "Disable Access to Non-global Controller Methods in Managed Packages", | ||
| "active": true, | ||
| "comment": "YOLO - activated by anonymous" | ||
| } | ||
| ] | ||
| }, | ||
| "customerPortal": { "enabled": true }, | ||
| "homePageLayouts": { | ||
| "homePageLayoutAssignments": [ | ||
| { | ||
| "profile": "Standard User", | ||
| "layout": "Home Page Default" | ||
| }, | ||
| { | ||
| "profile": "System Administrator", | ||
| "layout": "DE Default" | ||
| } | ||
| ] | ||
| }, | ||
| "salesforceToSalesforce": { "enabled": true }, | ||
| "security": { | ||
| "loginAccessPolicies": { "administratorsCanLogInAsAnyUser": true }, | ||
| "sharing": { "enableExternalSharingModel": true } | ||
| } | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| # Environment Variables | ||
|
|
||
| - `BROWSERFORCE_NAVIGATION_TIMEOUT_MS`: adjustable for slow internet connections (default: `90000`) | ||
| - `BROWSER_DEBUG` run in non-headless mode (default: `false`) | ||
| - `BROWSERFORCE_NAVIGATION_TIMEOUT_MS`: adjustable for slow internet connections (default: `90000`) | ||
|
|
||
| # Contributing | ||
|
|
||
|
|
||