mcdev 3.0.1 → 3.1.1

package/README.md

@@ -1,7 +1,7 @@
-<a id="markdown-accenture-sfmc-devtools" name="accenture-sfmc-devtools"></a>
-
 # Accenture SFMC DevTools
 
+<a id="markdown-accenture-sfmc-devtools" name="accenture-sfmc-devtools"></a>
+
 [![NPM](https://nodei.co/npm/mcdev.png?downloads=true&downloadRank=true&stars=true)](https://www.npmjs.com/package/mcdev)
 
 Accenture Salesforce Marketing Cloud DevTools (mcdev) is a rapid deployment/rollout, backup and development tool for Salesforce Marketing Cloud. It allows you to retrieve and deploy configuration and code across Business Units and instances.
@@ -17,6 +17,7 @@ Accenture Salesforce Marketing Cloud DevTools (mcdev) is a rapid deployment/roll
   - [2.3. Initial project setup](#23-initial-project-setup)
   - [2.4. Joining a project that was set up before](#24-joining-a-project-that-was-set-up-before)
   - [2.5. Recommended additional installs](#25-recommended-additional-installs)
+  - [2.6 Using mcdev in other node packages](#26-using-mcdev-in-other-node-packages)
 - [3. Updating Accenture SFMC DevTools](#3-updating-accenture-sfmc-devtools)
 - [4. Troubleshoot Install/Update](#4-troubleshoot-installupdate)
   - [4.1. Installing specific version](#41-installing-specific-version)
@@ -44,14 +45,16 @@ Accenture Salesforce Marketing Cloud DevTools (mcdev) is a rapid deployment/roll
     - [6.2.7. createDeltaPkg](#627-createdeltapkg)
 - [7. Advanced Configuration](#7-advanced-configuration)
   - [7.1. Config Options](#71-config-options)
-  - [7.2. Metadata specific settings](#72-metadata-specific-settings)
+  - [7.2. Metadata specific settings & options](#72-metadata-specific-settings--options)
     - [7.2.1. Retention Policy fields in Data Extensions](#721-retention-policy-fields-in-data-extensions)
+    - [7.2.2. Adding/Updating Fields on existing Data Extensions](#722-addingupdating-fields-on-existing-data-extensions)
+    - [7.2.3. Renaming fields of a Data Extensions](#723-renaming-fields-of-a-data-extensions)
+  - [7.3. Market Configuration](#73-market-configuration)
+  - [7.4. Market List Configuration](#74-market-list-configuration)
 - [8. Examples](#8-examples)
   - [8.1. Retrieve and deploy Data Extension](#81-retrieve-and-deploy-data-extension)
   - [8.2. Metadata Retrieving/Backup](#82-metadata-retrievingbackup)
   - [8.3. Automation Deployment](#83-automation-deployment)
-  - [8.4. Market Configuration](#84-market-configuration)
-  - [8.5. Market List Configuration](#85-market-list-configuration)
 - [9. Contribute](#9-contribute)
   - [9.1. Install Guide for Developers](#91-install-guide-for-developers)
   - [9.2. Local install](#92-local-install)
@@ -60,28 +63,28 @@ Accenture Salesforce Marketing Cloud DevTools (mcdev) is a rapid deployment/roll
 
 <!-- /TOC -->
 
-<a id="markdown-1-changelog" name="1-changelog"></a>
-
 ## 1. Changelog
 
-Find info on the latest changes in our [Changelog](CHANGELOG.md).
+<a id="markdown-changelog" name="changelog"></a>
 
-<a id="markdown-2-getting-started" name="2-getting-started"></a>
+Find info on the latest changes in our [Changelog](CHANGELOG.md).
 
 ## 2. Getting Started
 
+<a id="markdown-getting-started" name="getting-started"></a>
+
 Accenture SFMC DevTools can be installed as Node.JS package. The following guide will demonstrate how you can get started within 10 minutes or less.
 
 <a name="pre-requisites"></a>
 
-<a id="markdown-21-pre-requisites" name="21-pre-requisites"></a>
-
 ### 2.1. Pre-requisites
 
-<a id="markdown-211-install-nodejs-with-npm" name="211-install-nodejs-with-npm"></a>
+<a id="markdown-pre-requisites" name="pre-requisites"></a>
 
 #### 2.1.1. Install Node.js with npm
 
+<a id="markdown-install-node.js-with-npm" name="install-node.js-with-npm"></a>
+
 1. To check if it is already installed, at the OS command prompt, type: `node --version`
    - If this command reports Node version 14.16.x or later, you’re done—proceed to the next installation. If the reported version is earlier than 14.16.x, continue to step 2.
    - If you get a “command not found” error message, continue to step 2.
@@ -89,10 +92,10 @@ Accenture SFMC DevTools can be installed as Node.JS package. The following guide
 3. Download and run the latest **LTS** installer for your operating system.
 4. When the installer finishes, try step 1 again. If it fails, please restart your terminal. If it still does not work, reboot your computer and try the version check then.
 
-<a id="markdown-212-install-the-git-command-line" name="212-install-the-git-command-line"></a>
-
 #### 2.1.2. Install the Git Command Line
 
+<a id="markdown-install-the-git-command-line" name="install-the-git-command-line"></a>
+
 1. To check if git is already installed, at the OS command prompt, type: `git version`
    - If this command reports a git version such as “git version 2.31.0” (or "git version 2.31.0.windows.1" on Windows), you’re done. Proceed to native Android or iOS environment setup.
    - If you get a “command not found” error message, continue to step 2.
@@ -103,10 +106,10 @@ Accenture SFMC DevTools can be installed as Node.JS package. The following guide
 
 <a name="install-mcdev"></a>
 
-<a id="markdown-22-install-accenture-sfmc-devtools" name="22-install-accenture-sfmc-devtools"></a>
-
 ### 2.2. Install Accenture SFMC DevTools
 
+<a id="markdown-install-accenture-sfmc-devtools" name="install-accenture-sfmc-devtools"></a>
+
 If you experience issues installing Accenture SFMC DevTools, please check out the [Troubleshoot Install/Update](#troubleshoot-installupdate) section in this manual.
 
 **How to:**
@@ -122,12 +125,10 @@ When completed you will see `+ mcdev@3.0.0` printed to your screen (or the curre
 >
 > You may choose to install mcdev globally or locally. Global install runs faster and allows you to initialize new projects by running `mcdev init` in any directory. If your project does require a local installation, please refer to the [Local Install Guide](#local-install).
 
-<a name="initial-project-setup"></a>
-
-<a id="markdown-23-initial-project-setup" name="23-initial-project-setup"></a>
-
 ### 2.3. Initial project setup
 
+<a id="markdown-initial-project-setup" name="initial-project-setup"></a>
+
 After the successful installation, you will now need to setup the connection to your Marketing Cloud instance.
 
 1. In your Marketing Cloud instance
@@ -152,16 +153,16 @@ After the successful installation, you will now need to setup the connection to
    3. If this is the first time you set up Accenture SFMC DevTools or you recently upgraded Accenture SFMC DevTools, please restart VS Code now! A pop-up will likely appear in the lower right corner prompting you to install recommended extensions.
    4. Done.
 3. Sharing the project with your team
-   1. Make sure you have a Git repo (Bitbucket, GitHub, GitLab) set up somewhere. Usually your client will have to do this for you. Sometimes, we host client repos in our own Innersource, which is instance of Bitbucket.
+   1. Make sure you have a Git repo (Bitbucket, GitHub, GitLab) set up somewhere. If you are an SI partner, usually, your client will have to do this for you.
       > While running `mcdev init`, the tool already made sure to set up a local Git repo for you. Now, you need to upload ("push") it to the online repo:
    2. Open the URL of your online repo and find the "CLONE" button. This will likely show you a normal URL, ending on ".git"
    3. Add this as your repository remote named "origin". If you use a GUI based tool, that should be fairly simple, otherwise execute `git remote add origin YOUR-URL` in your project folder.
    4. Now run `git push -u origin master` to actually start the upload.
 
-<a id="markdown-24-joining-a-project-that-was-set-up-before" name="24-joining-a-project-that-was-set-up-before"></a>
-
 ### 2.4. Joining a project that was set up before
 
+<a id="markdown-joining-a-project-that-was-set-up-before" name="joining-a-project-that-was-set-up-before"></a>
+
 If Accenture SFMC DevTools was already used to set up the project by somebody in your team, including all of the steps in the above chapter [Initial project configuration](#initial-project-setup), then basically you are in luck. Things are much faster from here on:
 
 1. Make sure you went through the chapters [Pre-requisites](#pre-requisites) and [Install Accenture SFMC DevTools](#install-mcdev). Do skip [Initial project configuration](#initial-project-setup)!
@@ -174,10 +175,10 @@ If Accenture SFMC DevTools was already used to set up the project by somebody in
 7. At this point the system will recognize the previously set up project and ask you for `Client ID`, `Client Secret` and the `Authentication Base URI`.
 8. Done.
 
-<a id="markdown-25-recommended-additional-installs" name="25-recommended-additional-installs"></a>
-
 ### 2.5. Recommended additional installs
 
+<a id="markdown-recommended-additional-installs" name="recommended-additional-installs"></a>
+
 The following seeks to enhance your daily process. Our guide assumes that you are using [Visual Studio Code](https://code.visualstudio.com/download) to develop, backup and deploy your project. For smooth operations we highly recommend the following Marketing Cloud specific plugins for it.
 
 Nevertheless, Accenture SFMC DevTools will run without them and is not associated with the development of these publicly available apps & plugins.
@@ -213,12 +214,34 @@ Please note that Visual Studio Code might warn you about using the local install
 
 ![VSCode Eslint install warning](img/README.md/vscode-eslint-allow_everywhere.jpg)
 
-<a name="updating-mcdev"></a>
+### 2.6 Using mcdev in other node packages
 
-<a id="markdown-3-updating-accenture-sfmc-devtools" name="3-updating-accenture-sfmc-devtools"></a>
+Install it locally first via the following (or with a [specific version](#41-installing-specific-version)):
+
+```bash
+npm install --save mcdev
+```
+
+And then require it in your code:
+
+```javascript
+const mcdev = require('mcdev');
+
+// download all metadata from your instance's Parent BU
+mcdev.retrieve('MyCredential/_ParentBU_');
+
+// or download all metadata from your instance's Parent BU
+mcdev.retrieve('MyCredential/_ParentBU_', 'dataExtension');
+```
+
+For more details on the available methods look out for what Intellisense will return or refer to the [developer documentation](docs/dist/documentation.md).
+
+<a name="updating-mcdev"></a>
 
 ## 3. Updating Accenture SFMC DevTools
 
+<a id="markdown-updating-accenture-sfmc-devtools" name="updating-accenture-sfmc-devtools"></a>
+
 If you have mcdev already installed you can update your installation in a simplified way:
 
 ```bash
@@ -227,44 +250,46 @@ npm update -g mcdev
 
 <a name="troubleshoot-installupdate"></a>
 
-<a id="markdown-4-troubleshoot-installupdate" name="4-troubleshoot-installupdate"></a>
-
 ## 4. Troubleshoot Install/Update
 
-<a id="markdown-41-installing-specific-version" name="41-installing-specific-version"></a>
+<a id="markdown-troubleshoot-install%2Fupdate" name="troubleshoot-install%2Fupdate"></a>
 
 ### 4.1. Installing specific version
 
+<a id="installing-specific-version" name="installing-specific-version"></a>
+
 To work with our **developer-version** or to install a **specific older version** you can select any branch or tag from our git repository during install to do so:
 
-```bash
-// most recent developer version (using the branch name)
-npm install -g mcdev@develop
+**Most recent developer version (using the GitHub repo & branch name):**
 
-// install specific version (using a tag)
-npm install -g mcdev@3.0.0
+```bash
+npm install -g accenture/sfmc-devtools#develop
 ```
 
-**Warning**: When you used the above method to install Accenture SFMC DevTools for a specific version or tag, trying to [update Accenture SFMC DevTools](#updating-mcdev) might not download the most recently published official version but instead stay on the version or branch you previously selected (in the above examples: develop, 3.0.0)!
+**Install specific version (using a version tag on npm):**
 
-If you opted for `@develop` you will continue to get the latest developer udates. If, however, you opted for a version, you will have to use the install command again to overwrite whatever version you used before.
+```bash
+npm install -g mcdev@3.1.0
+```
 
-> **Note**: The version is currently _not_ updated on the developer branch until a new release is published. Hence, you will not see a change if you run `mcdev --version`.
+**Warning**: When you used the above method to install Accenture SFMC DevTools for a specific version or tag, trying to [update Accenture SFMC DevTools](#updating-mcdev) might not download the most recently published official version but instead stay on the version or branch you previously selected (in the above examples: develop, 3.1.0)!
 
-<a id="markdown-42-using-custom-clis" name="42-using-custom-clis"></a>
+> **Note**: The version is currently _not_ updated on the developer branch until a new release is published. Hence, you will not see a change if you run `mcdev --version`.
 
 ### 4.2. Using custom CLIs
 
+<a id="markdown-using-custom-clis" name="using-custom-clis"></a>
+
 Some users of Accenture SFMC DevTools prefer to use git bash or other CLIs instead of the operating system's default. Please note that some of the functionality of Accenture SFMC DevTools but also of other tools like the Node package manager (npm) do not necessarily function properly in these.
 
 If you encounter problems, we strongly recommend to first try it in the default CLI.
 
 <a name="missing-write-access-toon-macos"></a>
 
-<a id="markdown-43-missing-write-access-toon-macos" name="43-missing-write-access-toon-macos"></a>
-
 ### 4.3. Missing write access to...on MacOS
 
+<a id="markdown-missing-write-access-to...on-macos" name="missing-write-access-to...on-macos"></a>
+
 Depending on your setup, the default global installs & updates might error out with "Missing write access to /usr/local/lib/node_modules". In this case prefix your command with `sudo`:
 
 ```bash
@@ -277,10 +302,10 @@ sudo npm update -g mcdev
 
 ![Mac sudo](img/README.md/troubleshoot-mac-sudo.png)
 
-<a id="markdown-44-running-scripts-is-disabled-on-this-system" name="44-running-scripts-is-disabled-on-this-system"></a>
-
 ### 4.4. ...running scripts is disabled on this system
 
+<a id="markdown-...running-scripts-is-disabled-on-this-system" name="...running-scripts-is-disabled-on-this-system"></a>
+
 If you see the below error then your system's security settings are rather strict.
 
 ![Execution Policy](img/README.md/troubleshoot-execution_policy.jpg)
@@ -295,21 +320,17 @@ Steps to solve this:
 
 Please note that this change is global and not just for your current folder.
 
-<a id="markdown-45-operation-not-permitted-or-no-such-file-or-directory" name="45-operation-not-permitted-or-no-such-file-or-directory"></a>
-
 ### 4.5. Operation not permitted OR No such file or directory
 
+<a id="markdown-operation-not-permitted-or-no-such-file-or-directory" name="operation-not-permitted-or-no-such-file-or-directory"></a>
+
 If you encounter out of the 3 following errors you will have to completely remove Node.JS and install it again afterwards.
 
 **Error 1:** Cannot find module index.js
 
 ![index.js not found](img/README.md/troubleshoot-nodejs-index.jpg)
 
-**Error 2:** Cannot find module postinstall.js
-
-![postinstall.js not found](img/README.md/troubleshoot-nodejs-postinstall.jpg)
-
-**Error 3:** Operation not permitted
+**Error 2:** Operation not permitted
 
 ![operation not permitted](img/README.md/troubleshoot-nodejs-permission.jpg)
 
@@ -345,10 +366,10 @@ Now, please follow the guides above in the [Pre-requisites](#pre-requisites) sec
 
 <a name="metadata-type-support"></a>
 
-<a id="markdown-5-metadata-type-support" name="5-metadata-type-support"></a>
-
 ## 5. Metadata Type Support
 
+<a id="markdown-metadata-type-support" name="metadata-type-support"></a>
+
 The following metadata types are currently supported:
 
 | MetadataType                       | CLI Argument              | Retrieve | Deploy     | Template   | Retrieved by Default | Description                                                                                                        |
@@ -378,11 +399,12 @@ The following metadata types are currently supported:
 | List                               | `list`                    | Yes      | in backlog | -          | Yes                  | Old way of storing data. Still used for central Email Subscriber DB.                                               |
 | Role                               | `role`                    | Yes      | Yes        | -          | Yes                  | User Roles define groups that are used to grant users access to SFMC systems.                                      |
 | Triggered Send                     | `triggeredSendDefinition` | Yes      | Yes        | -          | Yes                  | **DEPRECATED**: Sends emails via API or DataExtension Event.                                                       |
-
-<a id="markdown-6-command-overview" name="6-command-overview"></a>
+| User                               | `accountUser`             | Yes      | in backlog | -          | -                    | Users and Installed Packages including their assigned Roles, BUs and personal permissions                          |
 
 ## 6. Command Overview
 
+<a id="markdown-command-overview" name="command-overview"></a>
+
 If you installed mcdev globally as described above you can run mcdev in any directory. See our [install Accenture SFMC DevTools](#install-mcdev) chapter for more details.
 
 _Example (global install):_
@@ -405,16 +427,14 @@ _Note:_ Parameters listed below in between square brackets = `[...]` are optiona
 
 _Note:_ Credentials and Business Unit names can always be selected interactively. Try inputing a questionmark = `?` in their place if more parameters follow, or omit them completely if no other parameters are required for a command.
 
-<a id="markdown-61-maintenance-and-setup-commands" name="61-maintenance-and-setup-commands"></a>
-
 ### 6.1. Maintenance and setup commands
 
-<a name="init"></a>
-
-<a id="markdown-611-init" name="611-init"></a>
+<a id="markdown-maintenance-and-setup-commands" name="maintenance-and-setup-commands"></a>
 
 #### 6.1.1. init
 
+<a id="markdown-init" name="init"></a>
+
 _Command:_ `mcdev init`
 
 _Alias:_ -
@@ -451,10 +471,10 @@ Example url: `https://mcg123abcysykllg-0321cbs8bbt64.auth.marketingcloudapis.com
 >
 > To get the tenant subdomain, please take the Authentication Base Uri and extract the part after `https://` and before `.auth.marketingcloudapis.com`. In the above example this would therefore be `mcg123abcysykllg-0321cbs8bbt64`.
 
-<a id="markdown-612-upgrade" name="612-upgrade"></a>
-
 #### 6.1.2. upgrade
 
+<a id="markdown-upgrade" name="upgrade"></a>
+
 _Command:_ `mcdev upgrade`
 
 _Alias:_ `mcdev up`
@@ -467,10 +487,10 @@ _Example:_
 mcdev upgrade
 ```
 
-<a id="markdown-613-reloadbus" name="613-reloadbus"></a>
-
 #### 6.1.3. reloadBUs
 
+<a id="markdown-reloadbus" name="reloadbus"></a>
+
 _Command:_ `mcdev reloadBUs [credential]`
 
 _Alias:_ `mcdev rb`
@@ -483,10 +503,10 @@ _Example:_
 mcdev reloadBUs MyProject
 ```
 
-<a id="markdown-614-badkeys" name="614-badkeys"></a>
-
 #### 6.1.4. badKeys
 
+<a id="markdown-badkeys" name="badkeys"></a>
+
 _Command:_ `mcdev badKeys [business unit]`
 
 _Alias:_ -
@@ -499,10 +519,10 @@ _Example:_
 mcdev badKeys MyProject/DEV
 ```
 
-<a id="markdown-615-document" name="615-document"></a>
-
 #### 6.1.5. document
 
+<a id="markdown-document" name="document"></a>
+
 _Command:_ `mcdev document <TYPE> <business unit>`
 
 _Alias:_ `mcdev doc`
@@ -517,6 +537,7 @@ Currently supported types:
 | -------------- | --------------- |
 | Data Extension | `dataExtension` |
 | Role           | `role`          |
+| User           | `accountUser`   |
 
 _Example:_
 
@@ -524,10 +545,10 @@ _Example:_
 mcdev document role myServer
 ```
 
-<a id="markdown-616-selecttypes" name="616-selecttypes"></a>
-
 #### 6.1.6. selectTypes
 
+<a id="markdown-selecttypes" name="selecttypes"></a>
+
 _Command:_ `mcdev selectTypes`
 
 _Alias:_ `mcdev st`
@@ -542,10 +563,10 @@ mcdev selectTypes
 
 _Note:_ You may select non-standard types if you run `mcdev selectTypes --debug`. This may be needed in edge cases but is not recommended in most situations.
 
-<a id="markdown-617-explaintypes" name="617-explaintypes"></a>
-
 #### 6.1.7. explainTypes
 
+<a id="markdown-explaintypes" name="explaintypes"></a>
+
 _Command:_ `mcdev explainTypes`
 
 _Alias:_ `mcdev et`
@@ -560,14 +581,14 @@ _Example:_
 mcdev explainTypes
 ```
 
-<a id="markdown-62-operational-commands" name="62-operational-commands"></a>
-
 ### 6.2. Operational commands
 
-<a id="markdown-621-retrieve" name="621-retrieve"></a>
+<a id="markdown-operational-commands" name="operational-commands"></a>
 
 #### 6.2.1. retrieve
 
+<a id="markdown-retrieve" name="retrieve"></a>
+
 _Command:_ `mcdev retrieve [business unit] [metadata type]`
 
 _Alias:_ `mcdev r`
@@ -622,10 +643,10 @@ mcdev retrieve "*"
 
 > Note: retrieve-all will fail in some CLIs if you do not wrap the asterix (\*) in quotes. This is due to the special meaning of \* as a parameter in these CLIs.
 
-<a id="markdown-622-deploy" name="622-deploy"></a>
-
 #### 6.2.2. deploy
 
+<a id="markdown-deploy" name="deploy"></a>
+
 _Command:_ `mcdev deploy [business unit] [metadata type]`
 
 _Alias:_ `mcdev d`
@@ -668,10 +689,10 @@ mcdev deploy "*"
 
 > Note: deploy-all will fail in some CLIs if you do not wrap the asterix (\*) in quotes. This is due to the special meaning of \* as a parameter in these CLIs.
 
-<a id="markdown-623-delete" name="623-delete"></a>
-
 #### 6.2.3. delete
 
+<a id="markdown-delete" name="delete"></a>
+
 _Command:_ `mcdev delete <business unit> <type> <external key>`
 
 _Alias:_ `mcdev del`
@@ -690,10 +711,10 @@ _Example:_
 mcdev delete MyProject/_ParentBU_ dataExtension MyUserTable
 ```
 
-<a id="markdown-624-retrieveastemplate" name="624-retrieveastemplate"></a>
-
 #### 6.2.4. retrieveAsTemplate
 
+<a id="markdown-retrieveastemplate" name="retrieveastemplate"></a>
+
 _Command:_ `mcdev retrieveAsTemplate <business unit> <type> <name> <market>`
 
 _Alias:_ `mcdev rt`
@@ -728,10 +749,10 @@ This will result in the following files being created in your `template/` direct
 - `table2.dataExtension-meta.json`
 - `table3.dataExtension-meta.json`
 
-<a id="markdown-625-builddefinition" name="625-builddefinition"></a>
-
 #### 6.2.5. buildDefinition
 
+<a id="markdown-builddefinition" name="builddefinition"></a>
+
 _Command:_ `mcdev buildDefinition <business unit> <type> <name> <market>`
 
 _Alias:_ `mcdev bd`
@@ -769,10 +790,10 @@ This will result in the following files being created in your `retrieve/MyProjec
 - `table2.dataExtension-meta.json`
 - `table3.dataExtension-meta.json`
 
-<a id="markdown-626-builddefinitionbulk" name="626-builddefinitionbulk"></a>
-
 #### 6.2.6. buildDefinitionBulk
 
+<a id="markdown-builddefinitionbulk" name="builddefinitionbulk"></a>
+
 _Command:_ `mcdev buildDefinitionBulk <list name> <type> <name>`
 
 _Alias:_ `mcdev bdb`
@@ -789,10 +810,10 @@ _Example:_
 mcdev bdb pilotMarketsQA dataExtension MyUserTable
 ```
 
-<a id="markdown-627-createdeltapkg" name="627-createdeltapkg"></a>
-
 #### 6.2.7. createDeltaPkg
 
+<a id="markdown-createdeltapkg" name="createdeltapkg"></a>
+
 _Command:_ `mcdev createDeltaPkg [range] [filter]`
 
 _Alias:_ `mcdev cdp`
@@ -920,10 +941,10 @@ mcdev createDeltaPkg d21b4221..HEAD 'MyProject/BU1,MyProject/BU3'
 > mcdev createDeltaPkg <range> [filter] --y
 > ```
 
-<a id="markdown-7-advanced-configuration" name="7-advanced-configuration"></a>
-
 ## 7. Advanced Configuration
 
+<a id="markdown-advanced-configuration" name="advanced-configuration"></a>
+
 The tools confiuration can be changed in the file `.mcdevrc.json` located in the root of your project folder.
 
 It contains [Market Configuration](#market-configuration) (`markets: { ... }`), [Market List Configuration](#market-list-configuration) (`marketList: { ... }`) the list of usable Business Units per credentials, `directories`, as well as other `options`.
@@ -932,10 +953,10 @@ You will also find the configuration for what metadata shall be retrieved here i
 
 You will also find a secondary file named `.mcdev-auth.json` containing your credentials. **Do not commit this to your repository!** You should only commit `.mcdevrc.json` as this file contains project wide settings that do not compromise security.
 
-<a id="markdown-71-config-options" name="71-config-options"></a>
-
 ### 7.1. Config Options
 
+<a id="markdown-config-options" name="config-options"></a>
+
 The central config in `.mcdevrc.json` holds multiple adjustable settings:
 
 ```json
@@ -998,23 +1019,24 @@ The central config in `.mcdevrc.json` holds multiple adjustable settings:
 | directories.deploy                       | 'deploy/'                                    | Where `deploy` searches for files to deploy                                                                                 |
 | directories.retrieve                     | 'retrieve/'                                  | Where `retrieve` stores downloaded files                                                                                    |
 | directories.roles                        | 'docs/roles/'                                | Directory for `document role` output                                                                                        |
+| directories.users                        | 'docs/users/'                                | Directory for `document accountUser` output                                                                                 |
 | directories.template                     | 'template/'                                  | Where `rt` stores downloaded templates & `bd` retrieves them from                                                           |
 | directories.templateBuilds               | ['retrieve/','deploy/']                      | Where `bd` saves final deployment versions in. This can hold multiple directories, e.g. ['retrieve/','deploy/']             |
 | metaDataTypes.documentOnRetrieve         | ['role','dataExtension']                     | automatically executes `document` for selected types                                                                        |
 | metaDataTypes.retrieve                   | _changes with each release_                  | check [Metadata Type Support](#metadata-type-support) for current list                                                      |
 
-<a id="markdown-72-metadata-specific-settings" name="72-metadata-specific-settings"></a>
+### 7.2. Metadata specific settings & options
 
-### 7.2. Metadata specific settings
-
-<a id="markdown-721-retention-policy-fields-in-data-extensions" name="721-retention-policy-fields-in-data-extensions"></a>
+<a id="markdown-metadata-specific-settings" name="metadata-specific-settings"></a>
 
 #### 7.2.1. Retention Policy fields in Data Extensions
 
+<a id="markdown-retention-policy-fields-in-data-extensions" name="retention-policy-fields-in-data-extensions"></a>
+
 The way retention policy is saved is a bit misleading and hence we wanted to provide a bit of guidance if you ever need to do a deep dive here.
 
-| Field                                | Description                                                                                                                                                                                                                                                                                                                        | Values                                                                 |
-| ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- | ------------ |
+| Field | Description | Values |
+| ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
 | **DataRetentionPeriod**              | this field should print the value of the unit of measure but it unfortunately is off by one (e.g. showing "weeks" instead of "months"). Also, it seems to have no impact on what's stored.<br> We therefore excluded it from retrieve/deploy                                                                                       | -                                                                      |
 | **DataRetentionPeriodUnitOfMeasure** | represents drop down for "period after" selection                                                                                                                                                                                                                                                                                  | 6: years<br>5: months<br>4: weeks<br>2: days                           |
 | **DataRetentionPeriodLength**        | represents number field for "period after" selection                                                                                                                                                                                                                                                                               | min: 1<br>max: 999                                                     |
@@ -1029,51 +1051,93 @@ To enable "delete All records and data extensions" you have to set RowBasedReten
 
 It seems the 2 other modes were added on top later and hence "all records and data extension" is the default retention mode.
 
-<a id="markdown-8-examples" name="8-examples"></a>
-
-## 8. Examples
-
-<a id="markdown-81-retrieve-and-deploy-data-extension" name="81-retrieve-and-deploy-data-extension"></a>
-
-### 8.1. Retrieve and deploy Data Extension
-
-1. Retrieve metadata by running `mcdev retrieve <BU>` (where the BU corresponds to a credential-Business Unit combo in the **.mcdevrc.json**)
-2. Create a directory called `deploy/` in the root directory
-3. Create a directory called `dataExtension/` in the `deploy/` directory
-4. Copy a single dataExtension directory from the `retrieve/<credential>/<BU-Name>/dataExtension/` directory into `deploy/<credential>/<BU-Name>/dataExtension/`
-5. Run `mcdev deploy <BU>` to deploy everything in the **deploy** folder to the specified Business Unit
-
-<a id="markdown-82-metadata-retrievingbackup" name="82-metadata-retrievingbackup"></a>
-
-### 8.2. Metadata Retrieving/Backup
-
-Metadata of a Business Unit can be retrieved by running the following command:
-
-`mcdev retrieve <BU>`
-
-where `<BU>` needs to be replaced with `credentialName/businessUnit-Name` that is defined in **.mcdevrc.json**.
+#### 7.2.2. Adding/Updating Fields on existing Data Extensions
 
-Run this command for each of your defined Business Units and this will result in a **retrieve** directory with a sub-directory for each Business Unit. Each sub-directory contains the metadata from this Business Unit that is currently supported to **retrieve**.
+<a id="markdown-8-examples" name="8-examples"></a>
 
-This folder structure can be commited into a git repository and used as backup.
+There are a few rules to keep in mind when playing with Data Extensions fields:
 
-<a id="markdown-83-automation-deployment" name="83-automation-deployment"></a>
+- The `FieldType` cannot be changed on existing fields; the API returns in error is the attribute is even provided unchanged during an update
+- `MaxLength` can be increased or kept on the same value but never decreased during an update
+- A Non-Required/Nullable field cannot be set to be required during an UPDATE
+- When new fields are added, they can be required, but then also have to have a `DefaultValue` set
+- The value for `IsRequired` should be 'true' or 'false'
+- The value for `IsPrimary` should be 'true' or 'false'
 
-### 8.3. Automation Deployment
+#### 7.2.3. Renaming fields of a Data Extensions
 
-Now we want to deploy an Automation with it's related metadata. Select a retrieved Automation and copy it into the deploy folder. (`deploy/<credential>/<BU-Name>/automation/myAutomation.meta-automation.json`)
+With a small addition to the Data Extension's JSON it is possible to rename fields via MC DevTools. Imagine the following Data Extension:
 
-Copy all related activity metadata of this automation into the deploy folder. (_Example:_ `deploy/<credential>/<BU-Name>/query/myquery.meta-query.json` and `deploy/<credential>/<BU-Name>/query/myquery.meta-query.sql`)
+```json
+{
+  "CustomerKey": "Account",
+  "Name": "Account",
+  "Description": "",
+  "IsSendable": "false",
+  "IsTestable": "false",
+  "Fields": [
+    {
+      "Name": "BillingCity",
+      "Scale": "0",
+      "DefaultValue": "",
+      "MaxLength": "40",
+      "IsRequired": "false",
+      "IsPrimaryKey": "true",
+      "FieldType": "Text"
+    },
+    {
+      "Name": "BillingCountry",
+      "Scale": "0",
+      "DefaultValue": "",
+      "MaxLength": "80",
+      "IsRequired": "false",
+      "IsPrimaryKey": "false",
+      "FieldType": "Text"
+    }
+  ],
+  "r__folder_Path": "Data Extensions"
+}
+```
 
-To start the deployment run the following command:
+Imagine you wanted to rename `BillingCountry` to `BillingZip` for some reason. Previously, you could either go into the GUI or delete & recreate the field. Now, MC DevTools allows you to specify `Name_new` on the field and the tool will take care of the rest during **deployment**:
 
-`mcdev deploy <BU>`
+```json
+{
+  "CustomerKey": "Account",
+  "Name": "Account",
+  "Description": "",
+  "IsSendable": "false",
+  "IsTestable": "false",
+  "Fields": [
+    {
+      "Name": "BillingCity",
+      "Scale": "0",
+      "DefaultValue": "",
+      "MaxLength": "40",
+      "IsRequired": "false",
+      "IsPrimaryKey": "true",
+      "FieldType": "Text"
+    },
+    {
+      "Name": "BillingCountry" /* old name, keep here for reference during the update! */,
+      "Name_new": "BillingZip" /* new name */,
+      "Scale": "0",
+      "DefaultValue": "",
+      "MaxLength": "80",
+      "IsRequired": "false",
+      "IsPrimaryKey": "false",
+      "FieldType": "Text"
+    }
+  ],
+  "r__folder_Path": "Data Extensions"
+}
+```
 
-<a name="market-configuration"></a>
+All you have to do is deploy the data extension again with Name_new specified for each field that needs to be renamed.
 
-<a id="markdown-84-market-configuration" name="84-market-configuration"></a>
+### 7.3. Market Configuration
 
-### 8.4. Market Configuration
+<a id="markdown-market-configuration" name="market-configuration"></a>
 
 You will want to setup configs for variable parts that change inbetween Business Units. We advise starting this _after_ you've first run the `retrieveAsTemplate` command. This might sound counterintuitive but when you review what was copied into your template folder you will likely spot these variable parts the fastest and can then start setting up your market config. Please consider this an iterative process as you will likely run `rt` followed by another update of your config multiple times until you got it right.
 
@@ -1195,9 +1259,9 @@ Way more complex example with dedicated "Parent" BUs per enviroment (DEV, QA, PR
 
 <a name="market-list-configuration"></a>
 
-<a id="markdown-85-market-list-configuration" name="85-market-list-configuration"></a>
+### 7.4. Market List Configuration
 
-### 8.5. Market List Configuration
+<a id="markdown-market-list-configuration" name="market-list-configuration"></a>
 
 Market Lists are very powerful and you will quickly notice how much time they can safe you during your deployment preparation.
 Let's first look at an example list config:
@@ -1278,16 +1342,56 @@ Apart from that we can see 4 types of lists here:
 3. `Parent-medium-multi`/`Parent-large-multi` (medium:_instance parent_; large:_environment parent_): Any scripts, queries, automations that are executed on the parent but require one per child (e.g. query to fill country-specific Shared Data Extensions)
 4. `Children` (_child BUs_): everything that is needed on the market specific Business Units.
 
-<a id="markdown-9-contribute" name="9-contribute"></a>
+## 8. Examples
+
+<a id="markdown-examples" name="examples"></a>
+
+### 8.1. Retrieve and deploy Data Extension
+
+<a id="markdown-retrieve-and-deploy-data-extension" name="retrieve-and-deploy-data-extension"></a>
+
+1. Retrieve metadata by running `mcdev retrieve <BU>` (where the BU corresponds to a credential-Business Unit combo in the **.mcdevrc.json**)
+2. Create a directory called `deploy/` in the root directory
+3. Create a directory called `dataExtension/` in the `deploy/` directory
+4. Copy a single dataExtension directory from the `retrieve/<credential>/<BU-Name>/dataExtension/` directory into `deploy/<credential>/<BU-Name>/dataExtension/`
+5. Run `mcdev deploy <BU>` to deploy everything in the **deploy** folder to the specified Business Unit
+
+### 8.2. Metadata Retrieving/Backup
+
+<a id="markdown-metadata-retrieving%2Fbackup" name="metadata-retrieving%2Fbackup"></a>
+
+Metadata of a Business Unit can be retrieved by running the following command:
+
+`mcdev retrieve <BU>`
+
+where `<BU>` needs to be replaced with `credentialName/businessUnit-Name` that is defined in **.mcdevrc.json**.
+
+Run this command for each of your defined Business Units and this will result in a **retrieve** directory with a sub-directory for each Business Unit. Each sub-directory contains the metadata from this Business Unit that is currently supported to **retrieve**.
+
+This folder structure can be commited into a git repository and used as backup.
+
+### 8.3. Automation Deployment
+
+<a id="markdown-automation-deployment" name="automation-deployment"></a>
+
+Now we want to deploy an Automation with it's related metadata. Select a retrieved Automation and copy it into the deploy folder. (`deploy/<credential>/<BU-Name>/automation/myAutomation.meta-automation.json`)
+
+Copy all related activity metadata of this automation into the deploy folder. (_Example:_ `deploy/<credential>/<BU-Name>/query/myquery.meta-query.json` and `deploy/<credential>/<BU-Name>/query/myquery.meta-query.sql`)
+
+To start the deployment run the following command:
+
+`mcdev deploy <BU>`
 
 ## 9. Contribute
 
-If you want to enhance Accenture SFMC DevTools you are welcome to fork the repo and create a pull request. Please understand that we will have to conduct a code review before accepting your changes.
+<a id="markdown-contribute" name="contribute"></a>
 
-<a id="markdown-91-install-guide-for-developers" name="91-install-guide-for-developers"></a>
+If you want to enhance Accenture SFMC DevTools you are welcome to fork the repo and create a pull request. Please understand that we will have to conduct a code review before accepting your changes.
 
 ### 9.1. Install Guide for Developers
 
+<a id="markdown-install-guide-for-developers" name="install-guide-for-developers"></a>
+
 Instead of installing Accenture SFMC DevTools as a npm dependency from our git repo, we recommend cloning our repo and then linking it locally:
 
 Assuming you cloned Accenture SFMC DevTools into `C:\repos\sfmc-devtools\` (or `~/repos/sfmc-devtools/` on Mac) you can then go into your project directory, open a terminal there and run:
@@ -1320,10 +1424,10 @@ To test your new **global** developer setup, run `mcdev --version` in CLI which
 
 <a name="local-install"></a>
 
-<a id="markdown-92-local-install" name="92-local-install"></a>
-
 ### 9.2. Local install
 
+<a id="markdown-local-install" name="local-install"></a>
+
 > **Warning:** local installation (leading to the use of [npx](https://github.com/npm/npx#readme)) causes issues when spaces are used in keys/names and is therefore not recommended.
 > You will also make setting up projects much harder if you choose the local installation as you cannot use `mcdev init` to automatically setup your entire project.
 
@@ -1345,10 +1449,10 @@ The following explains how you _could_ install it locally for certain edge cases
 
 When completed you will see `+ mcdev@3.0.0` printed to your screen (or the current version of it respectively).
 
-<a id="markdown-93-npm-scripts" name="93-npm-scripts"></a>
-
 ### 9.3. NPM Scripts
 
+<a id="markdown-npm-scripts" name="npm-scripts"></a>
+
 - `start`: Main entry point
 - `mcdev`: alias for `start`
 - `build`: Runs documentation and linting scripts
@@ -1358,9 +1462,9 @@ When completed you will see `+ mcdev@3.0.0` printed to your screen (or the curre
 - `test`: Runs mocha tests - outdated
 - `upgrade`: run npm-check to test for updated depdencies
 
-<a id="markdown-94-developer-documentation" name="94-developer-documentation"></a>
-
 ### 9.4. Developer Documentation
 
+<a id="markdown-developer-documentation" name="developer-documentation"></a>
+
 - [Link to API Documentation](docs/dist/documentation.md)
 - [Link to Considerations & Findings Documentation](docs/dist/considerations.md)