Skip to Content
Version 63.1 by Martijn Woudstra on 2022/10/25 11:42
Show last authors
1 {{container}}{{container layoutStyle="columns"}}(((
2
3 In this microlearning, we will focus on how to create a message definition within the eMagiz tooling. Should you have any questions, please contact [[academy@emagiz.com>>mailto:academy@emagiz.com]].
4
5 == 1. Prerequisites ==
6
7 * Basic knowledge of the eMagiz platform
8
9 == 2. Key concepts ==
10
11 This microlearning centers around the creation of message definitions in the Design Phase within eMagiz.
12 With a message definition, we mean a collection of data elements and fields that are sent or received by an application.
13 The structure of this message definition will eventually create the data validation which validates the content of the message in the Deploy Phase.
14
15 In this microlearning, we will explain the following items
16
17 * Create an entity
18 * Create an attribute
19 * Create a relationship between entities
20 * Creating a message definition
21
22
23
24 == 3. Creating a message definition ==
25
26 To create a message definition you navigate to the Design phase of eMagiz.
27 Within the Design phase of eMagiz, you will right mouse click on the integration where you want to add the message definition.
28
29 After you clicked several options are visible, depending on the integration type and transport mechanism.
30
31 For instance, if you click on a synchronous flow the option you will select is "Go to the request system message". For asynchronous this will be "Go to system message".
32
33 [[image:Main.Images.Microlearning.WebHome@crashcourse-platform-design-creating-a-messagedefinition--go-to-systemmessage.png]]
34
35 === 3.1 Create an entity ===
36
37 When you start with the design of a new integration after clicking on the option "Go to system message" eMagiz will load an empty overview.
38
39 [[image:Main.Images.Microlearning.WebHome@crashcourse-platform-design-creating-a-messagedefinition--design-from-scratch-systemmessage.png]]
40
41 If you have an existing file eMagiz will load the message definition that is now in place.
42
43 In this overview, you will have several options to complete your message definition. Before you can use them, you have to click on "Start editing".
44 This microlearning will focus on the option to manually add the system message definition to the integration.
45
46 [[image:Main.Images.Microlearning.WebHome@crashcourse-platform-design-creating-a-messagedefinition--adding-a-entity.png]]
47
48 The first step is to add an entity for your message definition. Click on the entity icon on the right side and drag and drop it on the canvas. A pop-up will appear with the canvas.
49 Name your entity and click on save. eMagiz will add the entity to the canvas.
50
51 [[image:Main.Images.Microlearning.WebHome@crashcourse-platform-design-creating-a-messagedefinition--a-entity-added-to-systemmessage.png]]
52
53 If you made a mistake and want to start over again use right mouseclick on your added entity and choose the option delete entity.
54
55 === 3.2 Create an attribute ===
56
57 When your entity is created you can add an attribute to the entity. By attribute, we mean the characteristics of an entity.
58 For adding an attribute you are still in the edit modus of the system message in the design.
59 By right-clicking on the lower part of the added entity you will get the option "Add attribute".
60 Clicking on this option will resolve a pop-up that allows you to add an attribute.
61
62 [[image:Main.Images.Microlearning.WebHome@crashcourse-platform-design-creating-a-messagedefinition--adding-a-attribute.png]]
63
64 In this popup, you have the following options to add.
65
66 * Name: This name is the name you will see as the display name, but also later on as a validation name.
67 * Description: You can use this field to add some extra information about the name. For instance, if the name is an abbreviation or code, you can use the description to explain the field
68 * Data type: What data type is the attribute
69 * Confidential: Is the attribute that you use confidential or not
70
71 To choose the datatype for your attribute eMagiz provides you with the following options:
72
73 [[image:Main.Images.Microlearning.WebHome@crashcourse-platform-design-creating-a-messagedefinition--adding-a-attribute-dropdown.png]]
74
75 * String: a sequence of characters
76 * Integer: a numeric type of attribute
77 * Decimal: a numeric type with a non-round character.
78 * Boolean: represents the values true and false
79 * DateTime: is used for values that contain both date and time
80 * Enumeration: a set of distinct values. Only those values are accepted for this attribute
81
82 When choosing the option confidential to an attribute and pressing save the attribute will be added to the entity in the canvas with a lock icon in front of it.
83
84 [[image:Main.Images.Microlearning.WebHome@crashcourse-platform-design-creating-a-messagedefinition--complete-entity.png]]
85
86 === 3.3 Create a relationship between entities ===
87
88 A single entity is normally not the case. In a message definition, you mostly see a set of entities that are related to each other.
89 When manually adding all the entities and attributes for your message definition the next step is to define the relationship between the entities.
90
91 To add a relation between two entities you always start from the element that is the child of the parent. The setting of a relationship will be done via drag and drop from child to parent.
92
93 [[image:Main.Images.Microlearning.WebHome@crashcourse-platform-design-creating-a-messagedefinition--adding-a-relation.png]]
94
95 The relation is automatically added with the structure more to one. If you want to change this double click on the relation.
96
97 [[image:Main.Images.Microlearning.WebHome@crashcourse-platform-design-creating-a-messagedefinition--changing-the-relation.png]]
98
99 The options in eMagiz relationships:
100
101 * one-to-one relationship: by changing in this case the source cardinality
102 * one-to-more relationship: one entity can have multiple child entities
103 * more-to-more relationship: by changing in this case the destination cardinality
104
105 When you are satisfied press Save. If you made a mistake and want to start over again completely press Cancel.
106
107 === 3.4 Creating a message definition ===
108
109 When you have added a relation to two entities the message definition is automatically created by eMagiz. The message definition is found on the right side of the canvas in a structured manner.
110
111 [[image:Main.Images.Microlearning.WebHome@crashcourse-platform-design-creating-a-messagedefinition--created-message-definition.png]]
112
113 If you are satisfied with this message definition you are finished. If it is not what you expect you can change this message definition.
114 To change the message definition you have to change the root of the message. This can be done by using the root icon.
115
116 [[image:Main.Images.Microlearning.WebHome@crashcourse-platform-design-creating-a-messagedefinition--changing-the-message-definition-root-icon.png]]
117
118 After clicking on the root icon you can choose the entity that should be the root of your message definition.
119 Click on this entity and eMagiz will give a pop-up with a warning that you are changing the root entity of a message definition.
120 This warning gives you a heads up that all your progress of the message on the right side will be lost.
121
122 [[image:Main.Images.Microlearning.WebHome@crashcourse-platform-design-creating-a-messagedefinition--changing-the-message-definition-root-warning.png]]
123
124 You have two options. If you agree this will be the root of your message definition press Change root. If you made a mistake and want to start over again completely press Cancel.
125 When change root is chosen the message definition will only exist of the selected entity with all the attributes.
126
127 [[image:Main.Images.Microlearning.WebHome@crashcourse-platform-design-creating-a-messagedefinition--a-new-message-definition-after-changing-root.png]]
128
129 The next step is to add the other entities to build up the structure of your message definition. Press the canvas icon to add new entities to your message definition.
130
131 [[image:Main.Images.Microlearning.WebHome@crashcourse-platform-design-creating-a-messagedefinition--changing-the-message-definition-canvas-icon.png]]
132
133 After clicking on this icon when you go to the canvas the other entities can be selected.
134
135 When you are satisfied with the structure of your message definition you can make attributes optional. This can be done by using the toggle when you hover over the attribute in your message definition.
136
137 [[image:Main.Images.Microlearning.WebHome@crashcourse-platform-design-creating-a-messagedefinition--making-a-attribute-optional.png]]
138
139
140
141 == 4. Assignment ==
142
143 Manually create a message definition for a flow within your (Academy) project.
144 This assignment can be completed with the help of the (Academy) project that you have created/used in the previous assignment.
145
146 == 5. Key takeaways ==
147
148 To manually create a message definition you need the following:
149
150 * Create an entity
151 * Create an attribute
152 * Create a relationship between entities
153 * Creating a message definition
154
155
156 == 6. Suggested additional readings ==
157
158 If you are interested in this topic and want more information on it please read the help text provided by eMagiz.
159
160 == 7. Silent demonstration video ==
161
162 {{video attachment="crashcourse-platform-design-creating-a-messagedefinition.mp4" reference="Main.Videos.Microlearning.WebHome"/}}
163
164 )))((({{toc/}}))){{/container}}{{/container}}