Last modified by Erik Bakker on 2023/01/24 15:03
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 == 3. Creating a message definition ==
23
24 To create a message definition you navigate to the Design phase of eMagiz.
25 Within the Design phase of eMagiz, you will right mouse click on the integration where you want to add the message definition.
26
27 After you clicked several options are visible, depending on the integration type and transport mechanism.
28
29 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".
30
31 [[image:Main.Images.Microlearning.WebHome@crashcourse-platform-design-creating-a-messagedefinition--go-to-systemmessage.png]]
32
33 === 3.1 Create an entity ===
34
35 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.
36
37 [[image:Main.Images.Microlearning.WebHome@crashcourse-platform-design-creating-a-messagedefinition--design-from-scratch-systemmessage.png]]
38
39 If you have an existing file eMagiz will load the message definition that is now in place.
40
41 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".
42 This microlearning will focus on the option to manually add the system message definition to the integration.
43
44 [[image:Main.Images.Microlearning.WebHome@crashcourse-platform-design-creating-a-messagedefinition--adding-a-entity.png]]
45
46 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.
47 Name your entity and click on save. eMagiz will add the entity to the canvas.
48
49 [[image:Main.Images.Microlearning.WebHome@crashcourse-platform-design-creating-a-messagedefinition--a-entity-added-to-systemmessage.png]]
50
51 If you made a mistake and want to start over again use right mouseclick on your added entity and choose the option delete entity.
52
53 === 3.2 Create an attribute ===
54
55 When your entity is created you can add an attribute to the entity. By attribute, we mean the characteristics of an entity.
56 For adding an attribute you are still in the edit modus of the system message in the design.
57 By right-clicking on the lower part of the added entity you will get the option "Add attribute".
58 Clicking on this option will resolve a pop-up that allows you to add an attribute.
59
60 [[image:Main.Images.Microlearning.WebHome@crashcourse-platform-design-creating-a-messagedefinition--adding-a-attribute.png]]
61
62 In this popup, you have the following options to add.
63
64 * Name: This name is the name you will see as the display name, but also later on as a validation name.
65 * 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
66 * Data type: What data type is the attribute
67 * Confidential: Is the attribute that you use confidential or not
68
69 To choose the datatype for your attribute eMagiz provides you with the following options:
70
71 [[image:Main.Images.Microlearning.WebHome@crashcourse-platform-design-creating-a-messagedefinition--adding-a-attribute-dropdown.png]]
72
73 * String: a sequence of characters
74 * Integer: a numeric type of attribute
75 * Decimal: a numeric type with a non-round character.
76 * Boolean: represents the values true and false
77 * DateTime: is used for values that contain both date and time
78 * Enumeration: a set of distinct values. Only those values are accepted for this attribute
79
80 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.
81
82 [[image:Main.Images.Microlearning.WebHome@crashcourse-platform-design-creating-a-messagedefinition--complete-entity.png]]
83
84 === 3.3 Create a relationship between entities ===
85
86 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.
87 When manually adding all the entities and attributes for your message definition the next step is to define the relationship between the entities.
88
89 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.
90
91 [[image:Main.Images.Microlearning.WebHome@crashcourse-platform-design-creating-a-messagedefinition--adding-a-relation.png]]
92
93 The relation is automatically added with the structure more to one. If you want to change this double click on the relation.
94
95 [[image:Main.Images.Microlearning.WebHome@crashcourse-platform-design-creating-a-messagedefinition--changing-the-relation.png]]
96
97 The options in eMagiz relationships:
98
99 * one-to-one relationship: by changing in this case the source cardinality
100 * one-to-more relationship: one entity can have multiple child entities
101 * more-to-more relationship: by changing in this case the destination cardinality
102
103 When you are satisfied press Save. If you made a mistake and want to start over again completely press Cancel.
104
105 === 3.4 Creating a message definition ===
106
107 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.
108
109 [[image:Main.Images.Microlearning.WebHome@crashcourse-platform-design-creating-a-messagedefinition--created-message-definition.png]]
110
111 If you are satisfied with this message definition you are finished. If it is not what you expect you can change this message definition.
112 To change the message definition you have to change the root of the message. This can be done by using the root icon.
113
114 [[image:Main.Images.Microlearning.WebHome@crashcourse-platform-design-creating-a-messagedefinition--changing-the-message-definition-root-icon.png]]
115
116 After clicking on the root icon you can choose the entity that should be the root of your message definition.
117 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.
118 This warning gives you a heads up that all your progress of the message on the right side will be lost.
119
120 [[image:Main.Images.Microlearning.WebHome@crashcourse-platform-design-creating-a-messagedefinition--changing-the-message-definition-root-warning.png]]
121
122 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.
123 When change root is chosen the message definition will only exist of the selected entity with all the attributes.
124
125 [[image:Main.Images.Microlearning.WebHome@crashcourse-platform-design-creating-a-messagedefinition--a-new-message-definition-after-changing-root.png]]
126
127 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.
128
129 [[image:Main.Images.Microlearning.WebHome@crashcourse-platform-design-creating-a-messagedefinition--changing-the-message-definition-canvas-icon.png]]
130
131 After clicking on this icon when you go to the canvas the other entities can be selected.
132
133 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.
134
135 [[image:Main.Images.Microlearning.WebHome@crashcourse-platform-design-creating-a-messagedefinition--making-a-attribute-optional.png]]
136
137 == 4. Key takeaways ==
138
139 To manually create a message definition you need the following:
140
141 * Create an entity
142 * Create an attribute
143 * Create a relationship between entities
144 * Creating a message definition
145
146 == 5. Suggested additional readings ==
147
148 If you are interested in this topic and want more information on it please read the help text provided by eMagiz.
149 )))((({{toc/}}))){{/container}}{{/container}}