06.c ~ Templating Commands

To create templates, one can use retrieveAsTemplate (rt - this is now deprecated) or buildTemplate (bt). Choosing one or the other command depends on your use case. rt needed to be implemented per type, and we never got around to that - which means there are types for which it wasn't implemented. bt on the other hand, relies on you executing retrieve (r) first and then works for all types you downloaded. It's more generic because it doesn't need to handle downloading a single file.

If you want to use templates, then you have essentially three (+1) ways:

1. Use the commands r, bt, bd/bdb, d
2. Use r, then manually copy & adapt files from retrieve/ to template/, then run bd/bdb, d
3. (deprecated) Use the commands rt, bd/bdb, d

Option 4 is also available and relies on you using a git repo and the commands createDeltaPkg & deploy together. That's mostly for CI/CD-enabled projects, but there are teams that use it manually as well.

build

Command: mcdev build <--buFrom> <--marketFrom> <--buTo> <--marketTo> <--metadata> [--bulk] [--dependencies] [--retrieve] [--skipValidation]

This combines the power of buildTemplate and buildDefinition in one command, making it easier if you continuously use both commands sequentially.

Example:

// before
mcdev bt MyProject/DEV --market pilotMarketDEV1 -m dataExtension:table1 -m dataExtension:table2 -m dataExtension:table3 -m query:sql1 -m query:sql2
mcdev bd MyProject/QA --market pilotMarketQA1 -m dataExtension:table1 -m dataExtension:table2 -m dataExtension:table3 -m query:sql1 -m query:sql2

// after
mcdev build --buFrom MyProject/DEV --buTo MyProject/QA --marketFrom pilotMarketDEV1 --marketTo pilotMarketQA1 -m dataExtension:name:table1 dataExtension:table2 dataExtension:table3 query:sql1 query:name:sql2

Note how you can also use names instead of keys to select metadata by prefixing the name with "name" (e.g query:name:sql2). That however, only works if the name exists only once. Otherwise, the system will show an error, providing the found keys for you to select.

And if you already have market lists set up and want to use buildDefinitionBulk instead all you need to do is append --bulk:

Example:

// before
mcdev bt MyProject/DEV --market pilotMarketDEV1 -m dataExtension:table1 -m dataExtension:table2 -m dataExtension:table3 -m query:sql1 -m query:sql2
mcdev bdb pilotMarketsQA -m dataExtension:table1 -m dataExtension:table2 -m dataExtension:table3 -m query:sql1 -m query:sql2

// after
mcdev build --buFrom MyProject/DEV --marketFrom pilotMarketDEV1 --marketTo pilotMarketsQA --bulk -m dataExtension:table1 -m dataExtension:table2 -m dataExtension:table3 -m query:sql1 -m query:sql2

Note how in this bulk-example the parameter --buTo MyProject/QA was omitted and that --marketTo pilotMarketsQA now holds the name of the market list that bdb needs to work.

build with --dependencies (and with --retrieve):

These two parameters are passed through to buildTemplate. Please see that commands documentation for details. The resulting list of types & keys of whatever buildTemplate will create are then handed over to buildDefinition(Bulk), making this a powerful solution.

build with multiple chained markets

If you have more complex scenarios that would otherwise require setting up lots of mostly cloned markets. Instead, you may define multiple markets that can combined to form one new set of variables that then get applied.

mcdev build --buFrom MyProject/DEV --marketFrom pilotMarketDEV1 addtionalMarketDEV --marketTo pilotMarketsQA addtionalMarketQA --bulk -m dataExtension:table1 -m dataExtension:table2 -m dataExtension:table3 -m query:sql1 -m query:sql2

This will take pilotMarketDEV1 and add whatever is defined in addtionalMarketDEV. If there is an overlap in defined attributes, whatever market is set second, overwrites what is set first in the command. You can chain as many markets as you want. The order of how the markets are defined in the config does not have an effect.

"markets": {
  "addtionalMarketDEV": {
    "c": 6,
    "d": 4,
    "e": 5,
  },
  "pilotMarketDEV1": {
    "a": 1,
    "b": 2,
    "c": 3,
  }
}

The resulting market would be

  {
    "a": 1,
    "b": 2,
    "c": 6,
    "d": 4,
    "e": 5,
  }

buildTemplate

Command: mcdev buildTemplate <business unit> [type] [key] [market] [--metadata] [--market] [--dependencies] [--retrieve]

Alias: mcdev bt

The bt command uses previously retrieved metadata on your local computer and uses your market configuration in .mcdevrc.json to replace strings with variables. The result is then stored in your template/ folder. Please note that files stored here will keep their original name, despite this possibly containing market-specific suffixes or similar. Also note, that contrary to the deploy & retrieve folders, you will not see credential- or Business Unit-sub-folders here.

This command is a prerequisite for the buildDefintion command. Alternatively, you can copy-paste retrieved metadata from your retrieve/ folder to your template/ folder and update it manually - or even create it from scratch.

Note: Before using this command, you need to configure your markets first! Check out our guide on Market Configuration to understand how to use templating and prepare your market config.

Currently supported types: Check out Metadata Type Support.

Example:

mcdev bt MyProject/DEV dataExtension MyUserTable pilotMarketDEV1
mcdev bt MyProject/DEV --market pilotMarketDEV1 -m dataExtension:MyUserTable dataExtension:name:MyUserTableName

This will result in MyUserTable.dataExtension-meta.json being created in your template/ directory. Note how you can also use names instead of keys to select metadata by prefixing the name with "name" (e.g query:name:sql2). That however, only works if the name exists only once. Otherwise, the system will show an error, providing the found keys for you to select.

buildTemplate with --dependencies:

Using the --dependencies option you turn on the most powerful templating feature that allows you to find all related other metadata items across all types. This includes other items linked via r__ field ("r" means "relationship") in their JSON and assets loaded via AMPscript or SSJS using the functions ContentBlockByKey, ContentBlockByName and ContentBlockById. The logic works recursively, finding dependencies of dependencies on all levels.

Example:

mcdev bt MyProject/DEV --market pilotMarketDEV1 -m dataExtension:MyUserTable --dependencies

buildTemplate with --retrieve:

When running buildTemplate you are solely using whats saved locally on your computer. If you want to get a fresh version from the server first, you can of course run mcdev retrieve yourself - or you include the --retrieve option here. If used together with --dependencies, this will download all metadata types for the selected BU. If used without --dependencies option it will only retrieve the types you specified as part of your buildTemplate command.

Example:

mcdev bt MyProject/DEV --market pilotMarketDEV1 -m dataExtension:MyUserTable --retrieve
mcdev bt MyProject/DEV --market pilotMarketDEV1 -m dataExtension:MyUserTable --dependencies --retrieve

buildTemplate for multiple sources:

You can also create multiple templates with multiple sources at once. Simply specify them in a comma-separated list and put that list in quotes:

mcdev bt MyProject/DEV dataExtension "table1,table2,table3" pilotMarketDEV1
mcdev bt MyProject/DEV query "sql1,sql2" pilotMarketDEV1

mcdev bt MyProject/DEV --market pilotMarketDEV1 -m dataExtension:table1 -m dataExtension:table2 -m dataExtension:table3 -m query:sql1 -m query:sql2

This will result in the following files being created in your template/ directory:

• table1.dataExtension-meta.json
• table2.dataExtension-meta.json
• table3.dataExtension-meta.json
• sql1.query-meta.json + sql1.query-meta.sql
• sql2.query-meta.json + sql2.query-meta.sql

buildTemplate with multiple chained markets:

See "build with multiple chained markets" chapter above

buildDefinition

Command: mcdev buildDefinition <business unit> [type] [template name] [market] [--metadata] [--market] [--skipValidation]

Alias: mcdev bd

The buildDefinition command allows to prepare the deployments to one or multiple targets based on templates and Market Configuration. After you have created your templates via retrieveAsTemplate (or manually) in your template/dataExtension/ folder run this command to create the final deployable files in your respective deploy/<business unit>/ folder.

This allows you to double-check if you changed something by comparing the before and after using your favorite Git client. You then have to manually copy the files you want to deploy into the respective deploy/ folder.

Note: Before using this command, you need to configure your markets first! Check out our guide on Market Configuration to understand how to use templating and prepare your market config.

Currently supported types: Check out Metadata Type Support.

Example:

mcdev bd MyProject/QA dataExtension MyUserTable pilotMarketQA1
mcdev bd MyProject/QA --market pilotMarketDEV1 -m dataExtension:MyUserTable

This will result in the following files being created in your deploy/MyProject/QA/dataExtension/ directory:

• MyUserTable.dataExtension-meta.json

buildDefinition for multiple sources:

You can also create definitions based on multiple templates at once. Simply specify them in a comma-separated list and put that list in quotes:

mcdev bd MyProject/QA dataExtension "table1,table2,table3" pilotMarketDEV1
mcdev bd MyProject/QA query "sql1,sql2" pilotMarketDEV1

mcdev bd MyProject/QA --market pilotMarketDEV1 -m dataExtension:table1 -m dataExtension:table2 -m dataExtension:table3 -m query:sql1 -m query:sql2

This will result in the following files being created in your deploy/MyProject/QA directory:

• table1.dataExtension-meta.json
• table2.dataExtension-meta.json
• table3.dataExtension-meta.json
• sql1.query-meta.json + sql1.query-meta.sql
• sql2.query-meta.json + sql2.query-meta.sql

buildDefinition with multiple chained markets:

See "build with multiple chained markets" chapter above

buildDefinitionBulk

Command: mcdev buildDefinitionBulk <market list name> <type> <template name> [--metadata] [--skipValidation]

Alias: mcdev bdb

With buildDefinitionBulk you get a very powerful command that wraps around buildDefinition, which it executes internally. It allows you to create the definitions for multiple Business Units and multiple markets at once.

Instead of passing in the name of credentials, Business Units and markets, you simply refer to a pre-defined market list in your .mcdevrc.json. This enables you to re-use the same configs over and over again, across multiple deployments and share it with your team.

Note: Before using this command, you need to configure your markets first! Check out our guide on Market List Configuration and Market Configuration to understand how to use bulk templating and prepare your market config.

Example:

mcdev bdb pilotMarketsQA dataExtension MyUserTable

mcdev bdb pilotMarketsQA -m dataExtension:MyUserTable -m query:mySQL -m dataExtension:MyOtherTable

buildDefinitionBulk with multiple chained markets:

See the "build with multiple chained markets" chapter above for what this is good for. Due to how bdb works, you have to specify multiple chained markets in a marketList for this to work. Also, because the default logic already allows specifying arrays of markets, you have to specify an array of an array of strings.

Without chaining, the config would look like this and result in buildDefinition getting run twice separately. Once for QA-DE market and once for QA-GULF market:

"markets": {
    "QA-DE": {
        "a": 1,
        "c": 3
    },
    "QA-GULF": {
        "a": 2,
        "b": 2
    }
},
"marketList": {
    "Parent-shared": {
        "description": "used to deploy shared data extensions",
        "MySandbox/_ParentBU_": ["QA-DE", "QA-GULF"],
    }
}

With chaining, the config would look like the following and result in buildDefinition being run once for QA-DE market and QA-GULF market merged:

"markets": {
    "QA-DE": {
        "a": 1,
        "c": 3
    },
    "QA-GULF": {
        "a": 2,
        "b": 2
    }
},
"marketList": {
    "Parent-shared": {
        "description": "used to deploy shared data extensions",
        "MySandbox/_ParentBU_": [
			["QA-DE", "QA-GULF"]
		]
    }
}

The resulting market would have these variables:

{
        "a": 2,
        "c": 3,
        "b": 2
}

retrieveAsTemplate

[DEPRECATED]

Command: mcdev retrieveAsTemplate <business unit> <type> <name> <market>

Alias: mcdev rt

The rt command retrieves metadata from the server and uses your market configuration in .mcdevrc.json to replace strings with variables. The result is then stored in your template/ folder. Please note that files stored here will keep their original name, despite this possibly containing market-specific suffixes or similar. Also note that contrary to the deploy & retrieve folders, you will not see credential- or Business Unit-sub-folders here.

This command is a prerequisite for the buildDefintion command. Alternatively, you can copy-paste retrieved metadata from your retrieve/ folder to your template/ folder and update it manually - or even create it from scratch.

Note: Before using this command, you need to configure your markets first! Check out our guide on Market Configuration to understand how to use templating and prepare your market config.

Currently supported types: Check out Metadata Type Support.

Example:

mcdev rt MyProject/DEV dataExtension MyUserTable pilotMarketDEV1

This will result in MyUserTable.dataExtension-meta.json being created in your template/ directory:

retrieveAsTemplate for multiple sources:

You can also create multiple templates with multiple sources at once. Simply specify them in a comma-separated list and put that list in quotes:

mcdev rt MyProject/DEV dataExtension "table1,table2,table3" pilotMarketDEV1

This will result in the following files being created in your template/ directory:

• table1.dataExtension-meta.json
• table2.dataExtension-meta.json
• table3.dataExtension-meta.json