03. Updating mcdev

Update mcdev to the newest version

If you have mcdev already installed you can update your installation in a simplified way:

npm update -g mcdev

Migration Guide - v6 to v7

As mentioned in the v7 release there are a number of breaking changes that might disrupt existing processes after the update to v7. The following will show the changes split by metadata type. As part of #1333 the references to other metadata types was updated and as part of #1292 the way retention policies are displayed on dataExtensions was updated. Therefore, existing metadata needs to be updated manually or re-retrieved before it can be deployed again.

Asset

v6	v7
r__assetTemplate_Key	r__asset_key

AttributeGroup

v6	v7
attributeSetIdentifiers	r__attributeSet_key

AttributeSet

v6	v7
r__dataExtension_CustomerKey	r__dataExtension_key
relationships[].leftItem.r__attributeGroup_definitionKey	relationships[].leftItem.r__attributeGroup_key
relationships[].rightItem.r__attributeGroup_definitionKey	relationships[].rightItem.r__attributeGroup_key
relationships[].leftItem.r__attributeSet_definitionKey	relationships[].leftItem.r__attributeSet_key
relationships[].rightItem.r__attributeSet_definitionKey	relationships[].rightItem.r__attributeSet_key

Automation

v6	v7	Comment
steps[].activites[].name	steps[].activites[].r__key	❗ This is a change of the field name and its content. In v6 and before it was showing the name of the activity, starting with v7 it's listing the key.

DataExtensions

v6	v7
r__dataExtensionTemplate_Name	r__dataExtensionTemplate_name

The following shows the part of the dataExtension covering data retention only:

none:

// before:
{
    "RowBasedRetention": false,
    "ResetRetentionPeriodOnImport": false,
    "DeleteAtEndOfRetentionPeriod": false,
    "RetainUntil": "",
}

// after
{
    "c__retentionType": "none",
}

allRecordsAndDataextension:

// before:
{
    "DataRetentionPeriodLength": 6,
    "DataRetentionPeriodUnitOfMeasure": 3,
    "RowBasedRetention": false,
    "ResetRetentionPeriodOnImport": false,
    "DeleteAtEndOfRetentionPeriod": false,
    "RetainUntil": "5/9/2024 12:00:00 AM",
}

// after
{
    "c__retentionType": "allRecordsAndDataextension",
    "DataRetentionPeriodLength": 6,
    "c__dataRetentionPeriodUnitOfMeasure": 'Days',
//  "RowBasedRetention": false,
    "ResetRetentionPeriodOnImport": false,
//  "DeleteAtEndOfRetentionPeriod": false,
    "c__retainUntil": "2024-05-09",
}

individialRecords:

// before
{
    "DataRetentionPeriodLength": 6,
    "DataRetentionPeriodUnitOfMeasure": 3,
    "RowBasedRetention": true,
    "ResetRetentionPeriodOnImport": false,
    "DeleteAtEndOfRetentionPeriod": false,
    "RetainUntil": "",
}

// after
{
    "c__retentionType": "individialRecords",
    "DataRetentionPeriodLength": 6,
    "c__DataRetentionPeriodUnitOfMeasure": 'Days',
//    "RowBasedRetention": true,
    "ResetRetentionPeriodOnImport": false,
//    "DeleteAtEndOfRetentionPeriod": false,
//    "RetainUntil": "",
}

allRecords:

// before
{
    "DataRetentionPeriodLength": 6,
    "DataRetentionPeriodUnitOfMeasure": 3,
    "RowBasedRetention": false,
    "ResetRetentionPeriodOnImport": false,
    "DeleteAtEndOfRetentionPeriod": true,
    "RetainUntil": "5/9/2024 12:00:00 AM",
}

// after
{
    "c__retentionType": "allRecords",
    "DataRetentionPeriodLength": 6,
    "c__DataRetentionPeriodUnitOfMeasure": 'Days',
//    "RowBasedRetention": false,
    "ResetRetentionPeriodOnImport": false,
//    "DeleteAtEndOfRetentionPeriod": true,
    "c__retainUntil": "2024-05-09",
}

allRecords and resetOnImport: (like allRecords!)

{
    "c__retentionType": "allRecords",
    "DataRetentionPeriodLength": 6,
    "c__DataRetentionPeriodUnitOfMeasure": 'Days',
//    "RowBasedRetention": false,
    "ResetRetentionPeriodOnImport": true,
//    "DeleteAtEndOfRetentionPeriod": true,
    "c__retainUntil": "2024-05-09",
}

EmailSend

v6	v7
r__email_Name	r__email_name
r__assetMessage_Key	r__asset_key
r__assetMessage_Name	r__asset_name_readOnly
SendDefinitionList[].r__dataExtension_Key	SendDefinitionList[].r__dataExtension_key
r__senderProfile_CustomerKey	r__senderProfile_key
r__sendClassification_CustomerKey	r__sendClassification_key

Event

v6	v7
r__dataExtension_CustomerKey	r__dataExtension_key

ImportFile

v6	v7
c__destinationType	destination.c__destinationType
r__dataExtension_CustomerKey	destination.r__dataExtension_key
c__codeKeyword	destination.r__mobileKeyword_key
r__list_PathName	destination.r__list_PathName
c__sourceObjectKey	source.r__dataExtension_key
r__fileLocation_name	source.r__fileLocation_name

Journey

v6	v7
activities[].metaData.highThroughput.r__dataExtension_CustomerKey	activities[].metaData.highThroughput.r__dataExtension_key
activities[].configurationArguments.c__mobileCode	activities[].configurationArguments.r__mobileCode_key
activities[].configurationArguments.c__mobileMessage_id	activities[].configurationArguments.r__mobileMessage_key
activities[].configurationArguments.r__assetMessage_Name_readOnly	activities[].configurationArguments.r__asset_name_readOnly
activities[].configurationArguments.r__mobileKeyword_codeKeyword	activities[].configurationArguments.r__mobileKeyword_key.current activities[].configurationArguments.r__mobileKeyword_key.next
activities[].configurationArguments.r__transactionalEmail_definitionKey	activities[].configurationArguments.r__transactionalEmail_key
activities[].configurationArguments.triggeredSend.r__dataExtension_CustomerKey	activities[].configurationArguments.triggeredSend.r__dataExtension_key
activities[].configurationArguments.triggeredSend.r__sendClassification_CustomerKey	activities[].configurationArguments.triggeredSend.r__sendClassification_key
activities[].configurationArguments.triggeredSend.r__assetMessage_Name_readOnly	activities[].configurationArguments.triggeredSend.r__asset_name_readOnly
activities[].configurationArguments.triggeredSend.r__assetMessage_Key	activities[].configurationArguments.triggeredSend.r__asset_key
activities[].configurationArguments.triggeredSend.r__email_Name	activities[].configurationArguments.triggeredSend.r__email_name

MobileMessage

v6	v7
code.code	r__mobileCode_key
keyword.c__codeKeyword	keyword.r__mobileKeyword_key
subscriptionKeyword.c__codeKeyword	subscriptionKeyword.r__mobileKeyword_key
nextKeyword.c__codeKeyword	nextKeyword.r__mobileKeyword_key
c__campaignNames	r__campaign_key

Query

v6	v7
targetKey	r__dataExtension_key

SendClassification

v6	v7
r__senderProfile_CustomerKey	r__senderProfile_key

TransactionalEmail

v6	v7
r__asset_customerKey	r__asset_key
subscriptions.r__dataExtension_CustomerKey	subscriptions.r__dataExtension_key

TransactionalPush

v6	v7
content.customerKey	r__asset_key

TransactionalSMS

v6	v7
subscriptions.shortCode	subscriptions.r__mobileCode_key
subscriptions.keyword	subscriptions.r__mobileKeyword_key

TriggeredSend

v6	v7
r__assetMessage_Name_readOnly	r__asset_name_readOnly
r__assetMessage_Key	r__asset_key
r__email_Name	r__email_name
r__senderProfile_CustomerKey	r__senderProfile_key
r__sendClassification_CustomerKey	r__sendClassification_key

Verification

v6	v7
r__dataExtension_CustomerKey	r__dataExtension_key

Migration Guide - v7 to v8

Version 8 introduced several improvements and changes. Here are the key points to be aware of:

Node.js Requirements

• Minimum Node.js version changed to ^18.18.0 || ^20.9.0 || >=22
• If you're on an older Node.js version, upgrade before updating mcdev

New Metadata Types

The following new metadata types were added:

Type	CLI Argument	Description
Data Filter	dataFilter	Filter definitions for Data Extensions
Domain Verification	domainVerification	SAP/Domain verification management
Triggered Send Summary	triggeredSendSummary	Retrieve-only statistics for triggered sends

Deploy Option Changes

v7	v8	Notes
--noMidSuffix	--autoMidSuffix	Logic inverted: v7 disabled auto-suffix, v8 enables it

New Commands

• stop - Stops running journeys (previously only pause was available)
• validate - Validates draft journeys without publishing
• audit - Shows audit log for journeys

Journey Version Syntax

Journey commands now consistently support version specification:

• /3 - specific version (e.g., mcdev pause cred/bu journey key/3)
• /* - all versions (e.g., mcdev stop cred/bu journey key/*)

Migration Guide - v8 to v9

Version 9 brought significant changes, particularly around Node.js requirements and configuration.

Node.js Requirements (Breaking Change!)

• Minimum Node.js version changed to ^20.19.0 || ^22.13.0 || >=24
• Node.js 18.x is no longer supported
• We recommend using Node.js 22 LTS

ESLint Configuration (Breaking Change!)

• mcdev projects now use ESLint flat config format (eslint.config.js)
• The legacy .eslintrc file format is no longer generated
• Run mcdev upgrade to get the new configuration files

New Configuration Options

{
  "options": {
    "deployment": {
      "branchSourceTargetMapping": {
        "sit": {
          "deployment-sit-source": "deployment-sit-target"
        },
        "uat": {
          "deployment-uat-source": "deployment-uat-target"
        }
      }
    }
  },
  "metaDataTypes": {
    "createDeltaPkg": []
  }
}

• branchSourceTargetMapping - Allows different source-target mappings per git branch
• metaDataTypes.createDeltaPkg - Separate list of types for createDeltaPkg command

New Metadata Types

Type	CLI Argument	Description
Mobile Application	mobileApplication	Mobile push applications (retrieve only)
Mobile Push	mobilePush	Mobile push messages
Filter Definition	filterDefinition	Data filter definitions

New Commands

• clone - Clones metadata items across Business Units with automatic templating

New CLI Options

Command	New Option	Description
retrieve	--onlyPublished / --op	Retrieve only published versions (for journeys)
retrieve	--fix	Auto-fix validation issues during retrieve
build/bd/bdb	--purge	Clear deploy folder before building
deploy	--validate	Validate journeys after deploy
cdp	--dependencies	Include dependencies in delta package

File Location Types

File Location (fileLocation) now supports additional storage types:

• AWS S3
• Azure Blob Storage
• Google Cloud Storage
• External SFTP

Recommended Actions

1. Before upgrading: Ensure Node.js 20.19.0+ or 22.13.0+ is installed
2. After upgrading: Run mcdev upgrade to update project configuration files
3. Re-retrieve: Consider re-retrieving metadata to get the latest JSON structure