Feature/1270 add method replaceReference to find & replace contentBlockByX with one of the other options

[JoernBerkefeld]

PR details

What changes did you make? (Give an overview)

• closes [FEATURE] add method replaceReference to find&replace ampscript contentBlockByX with one of the other options #1270

Further details (optional)

TODO: documentation & self-check of code

Checklist

• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• test scripts updated
• Wiki updated (via Feature/1270 add method replaceReference to find & replace contentBlockByX with one of the other options #1353 (comment))

[JoernBerkefeld]

Documentation

https://github.com/Accenture/sfmc-devtools/wiki/06.b-~-Standard-Commands/_edit

replaceContentBlock

Command: mcdev replaceContentBlock <--bu business unit> <--to 'key' | 'name' | 'id'> [--metadata type] [--from 'key' | 'name' | 'id'] [--skipRetrieve] [--skipDeploy] [--refresh]

Alias: mcdev rcb

This replaces ContentBlockByName, ContentBlockById, or ContentBlockByKey with your chosen method. It works for Ampscript and the "Platform.Function."-prefixed SSJS alternatives. It retrieves specified metadata to ensure it parses the latest server versions, prepares the update locally, and then redeploys the metadata.

--bu
Contrary to older methods, replaceContentBlock requires you to define the target BU via the --bu parameter instead of just naming it directly after the command itself. That gives you a bit more flexibility in how you write your commands, but it makes no difference otherwise.

--to
This defines which function you want your code to be converted to use. Possible values: "name", "id", "key".

--metadata (optional)
Set the types (or even type and keys/ids/names) that you want to fix. If omitted, all supported types will be updated - unless they are not listed in your mcdev config for retrieval.

--from (optional)
You may choose to limit what methods get swapped out by defining the --from parameter in case you want to keep one but swap out the other. By default, --from is set to whatever you did not choose for --to. Example: --to key means that --from is auto-set to "name id" and hence ContentBlockByName and ContentBlockById will be replaced with ContentBlockByKey. Any other combination, of course, also works. Possible values: "name", "id", "key".

--skipRetrieve (optional)
If you are absolutely sure you have the latest version of the code already downloaded or you want to override the server versions for some other reason then this option allows you to run rcb directly on your local code and skip the otherwise mandatory retrieve in the beginning. You will however still see that caching is conducted from the server, because Ids/ObjectIds are typically not saved in your downloaded JSONs.

--skipDeploy (optional)
With this option you enable dry-run mode, allowing you to review the deployment package carefully. Keep in mind that changes are made to your files in the retrieve-folder and not in the deploy-folder. At the end of execution, rcb will acknowledge dry-run mode and provide you with a one-liner to execute the targeted deploy for changed files once you are ready.

--refresh (optional)

This is the same option already available for deploy. It only works if you did not use the --skipDeploy option. See deploy docs for more details.

Example:

mcdev rcb --bu MyProject/DEV --to key
mcdev rcb --bu MyProject/DEV --to key -m senderProfile
mcdev rcb --bu MyProject/DEV --to name -m journey --skipDeploy
mcdev rcb --bu * --to id -m triggeredSend -m script -m asset 
mcdev rcb --bu * --to key --from name -m asset --refresh
mcdev rcb --bu * --to key -m "asset:key1" --refresh
mcdev rcb --bu MyProject/DEV --to key automation --skipRetrieve --skipDeploy
mcdev rcb --bu MyProject/* --to key journey --skipRetrieve