Setting Up the CDM
In the previous microlearning session, we explored the concept of the CDM (Canonical Data Model) and its role in messaging integrations. In this microlearning, we will dive deeper into the practical steps of setting up and maintaining your CDM within the eMagiz platform. By the end of this microlearning, you will have a clear understanding of how to create and manage your CDM effectively as your integration landscape evolves.
If you have any questions along the way, feel free to reach out to us at academy@emagiz.com.
1. Prerequisites
- Basic knowledge of the eMagiz platform
2. Key concepts
This microlearning centers around setting up the CDM via eMagiz.
- With setting up we mean: Creating the CDM for the first time and maintaining it when changes occur
Key considerations when setting up the CDM are:
- When you throw something away that is already used in Create you also lose that
- Be careful with promoting to CDM. This can lead to replication of entities (i.e. Order and Order_1)
- Choose one naming convention and one language
- Discuss which characteristics (i.e. attributes) belong to which entities
3. Setting Up the CDM
In the last microlearning, we learned what the CDM is and what it represents within the context of eMagiz. In this microlearning, we will take a closer look at the CDM in terms of how you can create the CDM and maintain the CDM when your integration landscape grows.
3.1 Delete behavior
Before we start discussing how you should create the first contours of the CDM and how you can manage the CDM
properly we would like to first address the fact that when you delete something in the CDM it can impact a lot of integrations within your landscape.
So before deleting anything from the CDM always consult with at least one colleague before proceeding.
3.2 Promoting to CDM
An easy way to start building your CDM is to use the Promote to CDM functionality.
However, this functionality has two downsides you need to be aware of before thinking of using this functionality:
- If you already have a CDM message for the message type for which you press Promote to CDM it will overwrite that CDM Message (which could lead to loss of data across your integration landscape)
- If a certain entity already exists in the CDM the Promote to CDM won't override it but will create a new entity with a \_1 behind it. So Order will become Order_1
Having said that, when the CDM is still empty and you have a dominant system within your integration landscape that feeds most data this is a useful method to quickly start building your CDM.
3.3 One naming convention
A third consideration before adding entities and attributes to the canvas is the naming convention that will be used.
This naming convention consists of two aspects:
- The language (choose one language and don't mix languages)
- The notation of the names of entities and attributes. Do you start each word with a capital for example (i.e. PaymentCompensation)? Or do you start each new word with capital with exception of the first word (i.e. paymentCompensation)
3.4 What belongs to what
The fourth consideration you should take into account when setting up and maintaining your CDM is how you are going to assign certain attributes to certain entities.
For example, if you have an Order with the following attributes there are two distinct ways of creating this in your CDM:
- ID
- Name
- Description
- ExecutionDateTime
- ReceivedDateTime
The first option would be to add all these characteristics to the Order entity which will result in the following solution in your CDM.
A second option would be to create a separate entity for DateTime which has a Type and a Value.
Both options have their advantages and disadvantages. The point of the matter is that you should make consistent choices with regards to which option you choose for your CDM.
3.5 Building the CDM
Now that we have discussed the key considerations let us turn our attention to actually learning how to build the CDM. There are two distinct methods of adding information to the CDM:
- Drag and drop entities to the canvas and manually add attributes (as we learned in the crash course platform)
- Use the promote CDM button on the message level
In this microlearning, we will not explain the dragging and dropping of entities and adding attributes again.
Instead, we will explain a new piece of functionality we have not explained yet called the Promote to CDM.
If you navigate to Design and access the context menu to get to the system message you will see a canvas in which the system message is filled in or not.
If it is filled in you can promote the structure that is represented in the system message to the CDM
You can do so after you have left Start Editing Mode. By selecting this button any existing creation on the CDM message level will be wiped clean.
To remind you of that eMagiz shows you the following pop-up
When you are confident that this is the right move you can press the Promote button.
This will promote the system message to the CDM message and in turn, will add the entities and attributes to the CDM.
This behavior is shown below
4. Key takeaways
- Key considerations when setting up the CDM are:
- Consistent Naming Conventions: Choose a single language and adhere to a consistent naming convention for entities and attributes to avoid confusion and maintain clarity.
- Entity and Attribute Assignment: Decide carefully how to assign attributes to entities, whether grouping them under one entity or creating separate entities for specific attributes.
- Promoting to CDM: The "Promote to CDM" feature can overwrite existing CDM messages or create new entities with suffixes (e.g., Order_1). Use this function with caution and ensure it's the right approach for your setup.
- Impact of Deletion: Deleting elements from the CDM can affect multiple integrations. Always consult with a colleague before making deletions.
- Maintenance Considerations: Regularly review and maintain your CDM with these considerations in mind to ensure its effectiveness and integration with your evolving landscape.
- Always take these considerations in mind when maintaining your CDM
5. Suggested Additional Readings
If you are interested in this topic and want more information on it please read the help text provided by eMagiz and read the following link: