[TASK] Explain when MID is appended to CustomerKey during assets deployment

[ccarswell]

Is there an existing issue for this?

• I have searched the existing issues

Current Behavior

When deploying an asset to a child Business Unit, Marketing Cloud has a restriction that all CustomerKeys should be unique.
When deploying an asset, the following error is shown if the asset has a conflicing CustomerKey in the same enterprise.

This coincides with the following message from with Marketing Cloud indicating that all CustomerKeys must be unique across the enterprise.

Expected Behavior

One way around this is to append the MID to the end of the CustomerKey on deployment like this.
[CustomerKey]-[MID]. I believe this was existing functionality of mcdevtools. This would prevent the errors from occuring, while still allowing user defined CustomerKeys in mcdevtools. This is particularly useful for mass deployments across many Business Units using the mcdev bdb $marketList' functionality

Steps To Reproduce

1. Create asset in Marketing Cloud in another Business Unit (manually or via mcdev)
2. Retrieve this metadata file using mcdev retrieve
3. Deploy this metadata file to another credential (Business Unit) using mcdev deploy
4. The following error is shown:
   

Version

6.0.2

Environment

• OS:
• Node:
• npm:

Participation

• I am willing to submit a pull request for this issue.

Additional comments

No response

[JoernBerkefeld]

i tried copying an asset to another BU via mcdev deploy ACN-Learning/MCDEV_Training_Target_1 "asset" "STG_Social_Icons" which is of block / htmlblock and it automatically appended the target's MID to the key:

- created asset: STG_Social_Icons-7330929 / STG_Social_Icons

Let's check your deployment file together

[JoernBerkefeld]

we need to add a section here:
https://github.com/Accenture/sfmc-devtools/wiki/08.-Metadata-specific-settings-&-options

the issue is missing documentation, not a bug.
the code looks at the field memberId and compares its value to the deployment-target's MID. If it's equal, then no MID-suffix is appended. if the attribute is not equal (including "undefined") then the MID-suffix will be appended - unless the last characters already equal the MID.

also needs to advice that if templating auto-replaces the MID in the asset with the target-MID then one needs to take care of changing the suffix yourself.

[JoernBerkefeld]

https://github.com/Accenture/sfmc-devtools/wiki/08.-Metadata-specific-settings-%26-options/_edit

Content Builder (asset)

How mcdev auto-appends the MID to keys

Content Builder is special among all systems in SFMC because the metadata it maintains shares the namespace for its keys throughout the entire instance. Normally, keys are only required to be unique across a single BU (except shared data extensions). That presents a unique challenge when you want to clone assets from one BU to another. Mcdev's internal logic, therefore, automatically checks the field memberId, which holds the MID of the BU on which the asset was created - practically the owning BU. If memberId is not set or otherwise not equal to the target BU, mcdev takes appropriate actions during execution of deploy.

Deploying to the owning BU

If you try to deploy to the owning BU, it will not touch the key, assuming you wish to override your build.

Deploying to other BUs with automatic key change

If you try to deploy to any other BU (including on other instances), it will append the MID to key, separated by a hyphen (e.g. "-123456"). The maximum length of asset keys is 36 characters. If your key is too long to fit the appended MID, mcdev will automatically shorten it accordingly. This CAN lead to unwanted abbreviations and hence is not ideal.

Deploying to other BUs with custom suffixes / templating

If you choose to use your own key across BUs, make sure to use buildTemplate and buildDefinition(-Bulk) to disable the automatic key change:

1. ensure your markets auto-replace the MID in memberID
2. append a suffix to every asset you have in your lower environments; make sure you leave enough character space within the max length of 36 chars to fit suffixes across all environments!
3. ensure your markets auto-replace the suffix in the keys
   a) if you have one production environment, either keep the suffix empty there or append something like "_PROD"
   b) if you have multiple production environments, come up with easily identifiable suffixes for them (e.g. 2-letter-iso codes for countries, or something similar for your brands)

Example:

"markets": {
        "dev": {
            "mid": "12345",
            "suffix": "_DEV",
        },
        "qa": {
            "mid": "23456",
            "suffix": "_QAS",
        },
        "prod": {
            "mid": "34567",
            "suffix": "",
        }
 },

Note: The auto-replacement of the key could potentially lead to unwanted overrides and hence is not to be assumed a perfect solution. Meanwhile, setting up your own suffix scheme can be painful at first and you need to manually ensure that you will have enough characters left to append suffixes in all environments. Rule of thumb: if you use 2-letter iso codes for countries, then your more generic suffixes (e.g. _DEV) better have at least 3 letters to avoid clashing with country codes. QA and QAS are good examples: QA is often used for Quality Assurance but also happens to be the ISO code for Qatar.