Skip to Content
Version 1.1 by eMagiz on 2022/05/10 11:15
Show last authors
1 {{html wiki="true"}}
2 <div class="ez-academy">
3 <div class="ez-academy_body">
4
5 <div class="doc">
6
7
8
9 = Configure an integration =
10
11 In this microlearning, we will focus on learning how to configure an integration.
12 Configuring the integration itself is the third and final step in designing an integration within eMagiz
13
14 Should you have any questions, please contact academy@emagiz.com.
15
16 * Last update: July 26th 2021
17 * Required reading time: 8 minutes
18
19 = Intro =
20
21 == 1. Prerequisites ==
22
23 * Basic knowledge of the eMagiz platform
24
25 == 2. Key concepts ==
26
27 This microlearning centers around configuring an integration.
28 With configuration we mean: Adding, Editing, and/or Deleting an integration
29 With integration we mean: A method to exchange data between an external party and eMagiz based on agreed-upon rules and definitions
30
31 To configure an integration you need the following:
32
33 * Connection information (how are you going to exchange information)
34 * Content information (what are you going to exchange)
35 * Security information (how are you going to secure the data exchange)
36
37
38
39 == 3. Configure an integration ==
40
41 As specified before with configure we refer to adding, editing, and/or deleting an integration. Below we will explain the steps in detail.
42
43 === 3.1 Adding a integration ===
44
45 To add an integration you simply drag a line from or to a system on the canvas
46
47 <p align="center">[[image:crashcourse-platform-capture-configure-a-message-type--drag-message-type-on-canvas-start.png||]]</p>
48
49 After you have connected the system to eMagiz (located in the center) you will immediately be presented with the following pop-up. In this pop-up you have a choice to make:
50
51 * Re-use a message type (in case another system already supplies Orders and you want to send these Orders to another system for example)
52 * Add a new message type
53
54 <p align="center">[[image:crashcourse-platform-capture-configure-a-message-type--new-message-type-first-popup.png||]]</p>
55
56 In case you want to add a new message type, please study the microlearning **Configure a message type**.
57
58 In this microlearning, we will assume that the message type you want to use for this particular integration is already available within your eMagiz project.
59 Therefore we will select the message type Configure a message type from the drop-down menu.
60
61 <p align="center">[[image:crashcourse-platform-capture-configure-a-integration--select-message-type.png||]]</p>
62
63 === 3.2 Editing a integration ===
64
65 Editing an integration can mean two things within the context of eMagiz.
66 The first time you connect a system to eMagiz it means filling in the detailed information belonging to the integration.
67 Later on, editing is keeping the information up to date when changes occur.
68
69 Providing detailed information in Capture helps you to better Design, Create, Deploy and Manage your integration.
70 This detailed information is available when you double click on the line you have just drawn (or select the Edit integration option via the context menu).
71
72 <p align="center">[[image:crashcourse-platform-capture-configure-a-integration--edit-integration-context-menu.png||]]</p>
73
74 After you have selected the integration a pop-up will be shown. This pop-up is divided into three segments:
75
76 * General
77 * Connectivity/Security
78 * Content
79
80 ==== 3.2.1 General ====
81
82 This segment answers several general questions surrounding this integration. With the help of the questions on this tab, you can set the stage in terms of the context of what the integration should do and when it is active (or not).
83
84 <p align="center">[[image:crashcourse-platform-capture-configure-a-integration--edit-message-type-general-empty.png||]]</p>
85
86 After you have filled in the general details the information should look similar to something as depicted below
87
88 <p align="center">[[image:crashcourse-platform-capture-configure-a-integration--edit-message-type-general-filled-in.png||]]</p>
89
90 ==== 3.2.2 Connectivity/Security ====
91
92 The second segment has to do with the connectivity (i.e. how will the data be sent to eMagiz or from eMagiz to an external system) and security (i.e. how can you tell the external system to accept your data as coming from you).
93
94 In this segment you will answer questions on:
95
96 * how the messages will be send (i.e. REST web service, file drop, etc.)
97 * What are the specific connectivity details
98 * What do we know about the security of the external system
99 * Retention policy (in case of Event Streaming)
100 * GDPR
101
102 If you have filled in all this information you have learned a lot about how you need to Design and Create your integration.
103
104 <p align="center">[[image:crashcourse-platform-capture-configure-a-integration--edit-message-type-connectivity-security.png||]]</p>
105
106 ==== 3.2.3 Content ====
107
108 The third segment is focused on the content of the message.
109 Remind yourself, in the previous segment we determined the format of the message, now we can zoom in to determine the actual content of the messages that will be exchanged.
110
111 In this question you can add various documents retrieved from the external party that define how messages will be exchanged:
112
113 * Example messages (i.e. examples of how a message could look like, very useful when unit testing your flow)
114 * Definitions (i.e XSD or WSDL, that define the exact structure, order, and data types of the message)
115 * Specification Document (i.e. detailing the method of authentication, order of actions needed to successfully post a message, etc.)
116
117 You can do so by adding attachments to this specific implementation of the message type.
118
119 <p align="center">[[image:crashcourse-platform-capture-configure-a-integration--add-example-message-attachment.png||]]</p>
120
121 <p align="center">[[image:crashcourse-platform-capture-configure-a-integration--add-xsd-attachment.png||]]</p>
122
123 All attachments linked to this specific implementation of the message type are shown in a grid on this third segment.
124
125 <p align="center">[[image:crashcourse-platform-capture-configure-a-integration--message-content-overview.png||]]</p>
126
127 Note that you could also add additional remarks in this segment to provide even more context to those that will be actually building the integration.
128
129 === 3.3 Deleting a integration ===
130
131 Deleting an integration can be done with the help of the context menu on integration level.
132 If you right-click on the line you have just finished you will see an option Delete Integration.
133 Selecting that option will delete your integration.
134
135 <p align="center">[[image:crashcourse-platform-capture-configure-a-integration--delete-integration.png||]]</p>
136
137 Be aware that you can only delete an integration if the integration is not part of the Create phase (anymore).
138
139 ===== Practice =====
140
141 == 4. Assignment ==
142
143 The assignment is simple this time. Simply fill in the relevant details on the message type level.
144 This assignment can be completed with the help of an associated Mendix project linked to the (Academy) project that you have created/used in the previous assignment.
145
146 == 5. Key takeaways ==
147
148 * A integration refers to a specific implementation between a specific external party and eMagiz based on a message type (data object)
149 * Several integrations can re-use the same message type
150 * Filling in the detailed information in Capture helps you to better Design, Create, Deploy and Manage your integration.
151 * Deleting an integration can only be done **after** the integration has been untransferred from Create (or never existed in Create in the first place)
152
153
154
155 == 6. Suggested Additional Readings ==
156
157 If you are interested in this topic and want more information on it please read the help text provided by eMagiz.
158
159 == 7. Silent demonstration video ==
160
161 This video demonstrates how you could have handled the assignment and gives you some context on what you have just learned. Disclaimer, you only see the eMagiz part but if you follow the above steps you are good to go!
162
163 <iframe width="1280" height="720" src="../../vid/microlearning/crashcourse-platform-capture-configure-a-integration.mp4" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
164
165 </div>
166 </div>
167 </div>
168
169 {{/html}}