Skip to Content

Changes for page Exercises

Last modified by Carlijn Kokkeler on 2022/10/19 13:32
From version 19.1
edited by eMagiz
on 2022/10/19 12:51
Change comment: There is no comment for this version
To version 1.1
edited by Carlijn Kokkeler
on 2022/09/30 09:23
Change comment: There is no comment for this version

Summary

Details

Page properties
Author
... ... @@ -1,1 +1,1 @@
1 -XWiki.eMagiz
1 +XWiki.CarlijnKokkeler
Content
... ... @@ -9,245 +9,71 @@
9 9  
10 10  == 2. Key concepts ==
11 11  
12 -This microlearning centers around understanding the concept data modeling in design. Please note the following items for completing this exercise
13 -* Ensure to make a small Capture phase that draws the system CAPE and a message type "TransportOrder"
14 -* The system CAPE provides messages as JSON
12 +This microlearning centers around understanding the concept of the message definition.
15 15  
16 -== 3. CDM, CDM & system message, message mapping ==
17 -By following the steps below, you should gain a better understanding of the differences between CDM, CDM messages, and system messages.
14 +With message definition we mean: A visual representation of how the elements are related to each other, whether they are mandatory and the data types they have that can be used in the message mapping
18 18  
19 -* Creating a CDM
20 - ** Please import the file Order.xsd in your CDM. The code for this file can be found in section 4. Code for xsd files.
21 -* Creating a CDM message
22 - ** Now, go to your CDM message and select Order as root entity.
23 - ** Add all other entities and attributes from Order.xsd, which were imported into the CDM, to your CDM message definition.
24 -* Creating a system message
25 - ** In one of your System messages, import the file TransportOrder.xsd. The code for this file can be found at the bottom of this page.
26 -* Creating a CDM message
27 - ** Select CreateOrder as root entity and add all other entities and attributes to your system definition.
28 -* Complete message mapping
29 - ** Now that you have completed these steps, go to Message mapping and complete the mapping. Please add the following to the Design mapping
30 - *** Ensure to properly map the address type
31 - *** Ensure to properly document mappings where required
32 -* Update the CDM and CDM message and remove the housenumber attribute
33 - ** Update the mapping accordingly
34 -* Update the System and CDM message to set the country attributes as enumerations
35 - ** System message uses an ISO-2 standard for country code
36 - ** CDM message uses an ISO-3 standard for country code
37 -
16 +In other words, the message definition defines the structure of the data that will be sent or received.
38 38  
39 -The solutions to these exercises can be found [[here>>doc:Main.eMagiz Academy.Use Cases.Data modeling in Design.Exercises.Solutions.WebHome||target="blank"]].
18 +== 3. What is a message definition ==
40 40  
41 -== 4. Code for xsd files ==
42 -=== 4.1 Code for Order.xsd ===
43 -{{code language="xml"}}
44 -<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
45 - xmlns="http://www.carlijnsplatform.com/ns/capetms/cdm/1.0/"
46 - attributeFormDefault="unqualified"
47 - elementFormDefault="qualified"
48 - targetNamespace="http://www.carlijnsplatform.com/ns/capetms/cdm/1.0/">
49 - <xs:complexType name="Order">
50 - <xs:sequence>
51 - <xs:element name="Date" type="xs:dateTime"/>
52 - <xs:element name="OrderId" type="nonEmptyString"/>
53 - <xs:element name="Customer" type="Customer"/>
54 - <xs:element name="PickupAddress" type="PickupAddress"/>
55 - <xs:element name="DeliveryAddress" type="DeliveryAddress"/>
56 - <xs:element maxOccurs="unbounded" name="OrderLine" type="OrderLine"/>
57 - </xs:sequence>
58 - </xs:complexType>
59 - <xs:complexType name="Customer">
60 - <xs:sequence>
61 - <xs:element name="Name" type="nonEmptyString"/>
62 - <xs:element name="Email" type="nonEmptyString"/>
63 - </xs:sequence>
64 - </xs:complexType>
65 - <xs:complexType name="PickupAddress">
66 - <xs:sequence>
67 - <xs:element name="Name" type="nonEmptyString"/>
68 - <xs:element name="Street" type="nonEmptyString"/>
69 - <xs:element name="StreetNumber" type="nonEmptyString"/>
70 - <xs:element name="PostalCode" type="nonEmptyString"/>
71 - <xs:element name="City" type="nonEmptyString"/>
72 - <xs:element name="Country" type="nonEmptyString"/>
73 - </xs:sequence>
74 - </xs:complexType>
75 - <xs:complexType name="DeliveryAddress">
76 - <xs:sequence>
77 - <xs:element name="Name" type="nonEmptyString"/>
78 - <xs:element name="Street" type="nonEmptyString"/>
79 - <xs:element name="StreetNumber" type="nonEmptyString"/>
80 - <xs:element name="PostalCode" type="nonEmptyString"/>
81 - <xs:element name="City" type="nonEmptyString"/>
82 - <xs:element name="Country" type="nonEmptyString"/>
83 - </xs:sequence>
84 - </xs:complexType>
85 - <xs:complexType name="OrderLine">
86 - <xs:sequence>
87 - <xs:element name="PackageUnit" type="nonEmptyString"/>
88 - <xs:element name="Quantity" type="xs:long"/>
89 - <xs:element name="Description" type="nonEmptyString"/>
90 - <xs:element name="Weight" type="xs:decimal"/>
91 - </xs:sequence>
92 - </xs:complexType>
93 - <xs:simpleType name="nonEmptyString">
94 - <xs:restriction base="xs:string">
95 - <xs:minLength value="1"/>
96 - </xs:restriction>
97 - </xs:simpleType>
98 - <xs:element name="Order" type="Order"/>
99 -</xs:schema>
100 -{{/code}}
20 +A message definition is a visual representation of how the elements are related to each other, whether they are mandatory and the data types they have that can be used in the message mapping.
21 +In all integration patterns (Messaging, API Gateway, and Event Streaming) we have message definitions.
101 101  
102 -=== 4.2 Code for TransportOrder.xsd ===
103 -{{code language="xml"}}
104 -<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
105 - xmlns="https://transportinc.nl/ns/tms/1.0/"
106 - attributeFormDefault="unqualified"
107 - elementFormDefault="unqualified"
108 - targetNamespace="https://transportinc.nl/ns/tms/1.0/">
109 - <xs:complexType name="CreateOrder">
110 - <xs:sequence>
111 - <xs:element name="Order" type="Order"/>
112 - </xs:sequence>
113 - </xs:complexType>
114 - <xs:complexType name="Order">
115 - <xs:sequence>
116 - <xs:element name="OrderID">
117 - <xs:simpleType>
118 - <xs:restriction base="xs:string">
119 - <xs:maxLength value="200"/>
120 - </xs:restriction>
121 - </xs:simpleType>
122 - </xs:element>
123 - <xs:element name="OrderDate" type="xs:dateTime"/>
124 - <xs:element minOccurs="0" name="Order_Customer" type="Order_Customer"/>
125 - <xs:element name="Address" type="Address"/>
126 - <xs:element name="PartnerInfo_Order" type="PartnerInfo_Order"/>
127 - <xs:element name="OrderLine_Order" type="OrderLine_Order"/>
128 - </xs:sequence>
129 - </xs:complexType>
130 - <xs:complexType name="Order_Customer">
131 - <xs:sequence>
132 - <xs:element minOccurs="0" name="Customer" type="Customer"/>
133 - </xs:sequence>
134 - </xs:complexType>
135 - <xs:complexType name="Customer">
136 - <xs:sequence>
137 - <xs:element name="Name">
138 - <xs:simpleType>
139 - <xs:restriction base="xs:string">
140 - <xs:maxLength value="200"/>
141 - </xs:restriction>
142 - </xs:simpleType>
143 - </xs:element>
144 - <xs:element minOccurs="0" name="Contact_Customer" type="Contact_Customer"/>
145 - </xs:sequence>
146 - </xs:complexType>
147 - <xs:complexType name="Contact_Customer">
148 - <xs:sequence>
149 - <xs:element maxOccurs="unbounded"
150 - minOccurs="0"
151 - name="Contact"
152 - type="Contact"/>
153 - </xs:sequence>
154 - </xs:complexType>
155 - <xs:complexType name="Contact">
156 - <xs:sequence>
157 - <xs:element name="eMail">
158 - <xs:simpleType>
159 - <xs:restriction base="xs:string">
160 - <xs:maxLength value="200"/>
161 - </xs:restriction>
162 - </xs:simpleType>
163 - </xs:element>
164 - <xs:element minOccurs="0" name="Name">
165 - <xs:simpleType>
166 - <xs:restriction base="xs:string">
167 - <xs:maxLength value="200"/>
168 - </xs:restriction>
169 - </xs:simpleType>
170 - </xs:element>
171 - </xs:sequence>
172 - </xs:complexType>
173 - <xs:complexType name="Address">
174 - <xs:sequence>
175 - <xs:element name="Type" type="nonEmptyString"/>
176 - <xs:element name="Name" type="nonEmptyString"/>
177 - <xs:element name="Street" type="nonEmptyString"/>
178 - <xs:element name="PostalCode" type="nonEmptyString"/>
179 - <xs:element name="City" type="nonEmptyString"/>
180 - <xs:element name="Country" type="nonEmptyString"/>
181 - </xs:sequence>
182 - </xs:complexType>
183 - <xs:complexType name="PartnerInfo_Order">
184 - <xs:sequence>
185 - <xs:element maxOccurs="unbounded"
186 - minOccurs="0"
187 - name="PartnerInfo"
188 - type="PartnerInfo"/>
189 - </xs:sequence>
190 - </xs:complexType>
191 - <xs:complexType name="PartnerInfo">
192 - <xs:sequence>
193 - <xs:element name="UUID">
194 - <xs:simpleType>
195 - <xs:restriction base="xs:string">
196 - <xs:maxLength value="64"/>
197 - </xs:restriction>
198 - </xs:simpleType>
199 - </xs:element>
200 - </xs:sequence>
201 - </xs:complexType>
202 - <xs:complexType name="OrderLine_Order">
203 - <xs:sequence>
204 - <xs:element maxOccurs="unbounded"
205 - minOccurs="0"
206 - name="OrderLine"
207 - type="OrderLine"/>
208 - </xs:sequence>
209 - </xs:complexType>
210 - <xs:complexType name="OrderLine">
211 - <xs:sequence>
212 - <xs:element name="Description">
213 - <xs:simpleType>
214 - <xs:restriction base="xs:string">
215 - <xs:maxLength value="200"/>
216 - </xs:restriction>
217 - </xs:simpleType>
218 - </xs:element>
219 - <xs:element name="Quantity" type="xs:long"/>
220 - <xs:element name="Unit" type="Enum"/>
221 - <xs:element minOccurs="0" name="Weight" type="xs:double"/>
222 - </xs:sequence>
223 - </xs:complexType>
224 - <xs:simpleType name="nonEmptyString">
225 - <xs:restriction base="xs:string">
226 - <xs:minLength value="1"/>
227 - </xs:restriction>
228 - </xs:simpleType>
229 - <xs:simpleType name="Enum">
230 - <xs:restriction base="xs:string">
231 - <xs:enumeration value="COLLI"/>
232 - <xs:enumeration value="EURO"/>
233 - <xs:enumeration value="BOX"/>
234 - <xs:enumeration value="SACK"/>
235 - </xs:restriction>
236 - </xs:simpleType>
237 - <xs:element name="CreateOrder" type="CreateOrder"/>
238 -</xs:schema>
239 -{{/code}}
23 +On one hand, we have message definitions that relate to a system.
24 +These definitions tell us something about how the system will send or wants to receive messages (data).
25 +On the other hand, we have message definitions that relate to eMagiz.
26 +These are generic and consistent across systems (i.e. CDM messages, Gateway messages, Topic messages).
27 +
28 +[[image:Main.Images.Microlearning.WebHome@crashcourse-platform-design-what-is-a-message-definition--design-overview.png]]
29 +
30 +In this phase, you can open the context menu on the integration level (remember, that is a line between eMagiz and an external system).
31 +The context menu will look slightly different based on the integration pattern. These differ as the use cases for each pattern differ slightly.
32 +
33 +[[image:Main.Images.Microlearning.WebHome@crashcourse-platform-design-what-is-a-message-definition--context-menu-messaging-definition.png]]
34 +
35 +[[image:Main.Images.Microlearning.WebHome@crashcourse-platform-design-what-is-a-message-definition--context-menu-api-definition.png]]
36 +
37 +[[image:Main.Images.Microlearning.WebHome@crashcourse-platform-design-what-is-a-message-definition--context-menu-es-definition.png]]
38 +
39 +Selecting one of the above options will lead you to an overview similar to the one that is shown below.
40 +
41 +[[image:Main.Images.Microlearning.WebHome@crashcourse-platform-design-what-is-a-message-definition--message-definition.png]]
42 +
43 +In this overview, you can import a definition or create one yourself.
44 +
45 +=== 3.1 eMagiz datamodels ===
46 +
47 +Above the focus was on the system messages (i.e. the definitions as defined by the external system). Within each of the patterns eMagiz supports (Messaging, API Management, and Event Streaming) we support an eMagiz data model. In these data models you can define how the messages should look like when they pass through the system of eMagiz. When creating a message transformation you always have atleast one eMagiz part that is based on an eMagiz data model. This is needed as you need to transform from the external system to the eMagiz data model for example.
48 +
49 +In messaging terms we call this eMagiz data model a CDM for example. Based on the pattern you are implementing the naming can change slightly but the conceptual idea is the same. For more information on the various data models we support for the patterns please check out the suggested additional readings section below.
50 +
51 +
52 +
53 +== 4. Assignment ==
54 +
55 +Navigate to Design and open the message definition option of at least one integration within your project.
56 +This assignment can be completed within the (Academy) project that you have created/used in the previous assignment.
57 +
240 240  == 5. Key takeaways ==
241 241  
242 -* The CDM holds all entities and attributes that are relevant within the context of your complete integration landscape.
243 -* The CDM message is tailor-made for a specific piece of data and only holds the entities and attributes relevant for that piece of data.
244 -* A system message is specific to a system.
60 +* A message definition is a visual representation of how the elements are related to each other, whether they are mandatory and the data types they have that can be used in the message mapping
61 +* Some message definitions are specific to a system. Others are generic across systems
245 245  
246 246  
64 +
247 247  == 6. Suggested Additional Readings ==
248 248  
249 -If you are interested in this topic and want more information on it please read the help text provided by eMagiz.
67 +If you are interested in this topic and want more information on it please read the help text provided by eMagiz. Furthermore check out these links if you want a more in-depth knowledge of the eMagiz data models:
250 250  
69 +* [API Gateway model](crashcourse-api-gateway-api-data-model.md)
70 +* [Understanding the eMagiz CDM](crashcourse-messaging-what-is-cdm.md)
71 +* [Event Streaming data model](intermediate-configuring-event-streaming-data-model.md)
251 251  
73 +== 7. Silent demonstration video ==
252 252  
75 +This video demonstrates a working solution and how you can validate whether you have successfully completed the assignment.
76 +
77 +{{video attachment="crashcourse-platform-design-what-is-a-message-definition.mp4" reference="Main.Videos.Microlearning.WebHome"/}}
78 +
253 253  )))((({{toc/}}))){{/container}}{{/container}}