From e902b96340877f458f796fd1b940ed18b8c17b1c Mon Sep 17 00:00:00 2001 From: Matthias Rolke Date: Sat, 20 Apr 2024 15:01:00 +0200 Subject: [PATCH] docs: plugin scope and profile behaviour [skip ci] --- README.md | 34 ++++++++++++++++++++++++++++------ 1 file changed, 28 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 390ca02..d20674e 100644 --- a/README.md +++ b/README.md @@ -4,13 +4,10 @@ For certain Metadata Types there is a different behaviour of the [file-based](https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/meta_retrieve.htm) vs. [CRUD-based](https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/meta_readMetadata.htm) Metadata API. -This plugin provides the `sf force source read` command to read Metadata using the "CRUD-based" Metadata API -similar to `sf force source retrieve` (which uses the "file-based" Metadata API). +This plugin provides a `sf force source read` command to read Metadata using the "CRUD-based" Metadata API similar to `sf force source retrieve` (which uses the "file-based" Metadata API). -## Example - -- When retrieving a `Profile` using `sf force source retrieve` it only contains ``. -- When retrieving a `Profile` using `sf force source read` it contains all fields like ``, `` and more. +> [!NOTE] +> This plugin simply returns the unfiltered response from the CRUD-based Metadata API. ## Installation @@ -27,6 +24,31 @@ sf force source read -m "RecordType:Account.Business" sf force source read -p force-app/main/default/objects/Account/recordTypes/Business.recordType-meta.xml ``` +## Example + +### Retrieving Profiles using the file-based Metadata API + +When retrieving Profiles, the file-based Metadata API [behaves differently for source-tracked and non source-tracked orgs](https://developer.salesforce.com/docs/atlas.en-us.sfdx_dev.meta/sfdx_dev/sfdx_dev_source_tracking_source_tracking_profiles.htm): + +> Without source tracking, retrieving profiles only returns some profile information + +a.k.a. a minimal Profile containing only `userPermissions` and entries for components listed in the `package.xml` of the retrieve request. + +> With source tracking, retrieving profiles returns profile information pertaining to anything else specified in the package.xml file plus any components getting tracked by source tracking + +a.k.a. a more kind of "full" Profile containing entries for all metadata having a `SourceMember` record in that org. + +### Reading Profiles using the CRUD Metadata API + +The CRUD Metadata API shows yet another behaviour: + +It returns a kind of "full" Profile independent of source tracking and even containing entries for metadata from Managed Packages etc. + +> [!WARNING] +> Unfortunately Profiles might include `tabVisibilites` for tabs not available in the org (see [#66](https://github.com/amtrack/sfdx-plugin-source-read/issues/66)). +> +> Without further processing this will cause deployment errrors. + ## Disclaimer Currently this has been tested only for `Profiles` and `RecordTypes`.