Skip to Content

Wiki source code of SMB Connectivity

Last modified by Danniar Firdausy on 2024/09/18 20:40
Show last authors
1 {{container}}
2 {{container layoutStyle="columns"}}(((
3 In many scenarios, accessing or managing files directly through a local directory isn't feasible, or external requirements might necessitate file placement in different locations. Typically, file transfers are handled via FTP or SFTP protocols, but another option available is Server Message Block (SMB) connectivity. In this microlearning, we will explore how SMB connectivity works within eMagiz, examining how it facilitates file transfers between local and remote systems.
4
5 Should you have any questions, please get in touch with [[academy@emagiz.com>>mailto:academy@emagiz.com]].
6
7 == 1. Prerequisites ==
8
9 * Basic knowledge of the eMagiz platform
10 * Novice course on File-based connectivity
11
12 == 2. Key concepts ==
13
14 This microlearning is about SMB (connectivity).
15 * By SMB connectivity, we mean: Making sure that eMagiz can communicate with the SMB protocol to exchange file-based data.
16
17 == 3. SMB Connectivity ==
18
19 In some cases, there is no communication possible with a local file directory. Or there is a requirement from the external party to place the files somewhere else. Mainly the somewhere else is either an FTP or an SFTP. However, there is a third communication protocol that can be used for file transfer. In this microlearning we will take a look at Server Message Block (SMB) connectivity within eMagiz.
20
21 * SMB (Server Message Block) is a network protocol for transmitting files between computers over Transmission Control Protocol/Internet Protocol (TCP/IP) connections.
22 * In an SMB transaction, the end user's computer is typically called the localhost. The second computer involved in SMB is a remote host, which is usually a server.
23 * Servers must be set up to run SMB services, and the client must have SMB software installed to access these services.
24 * eMagiz provides several components to set up the SMB connection
25
26 So, where the file pickup component searches on the local host for the correct directory, the idea of the SMB setup is that the directory with whom to communicate exists on a remote host. The local host and the remote host can talk to each other via the SMB protocol. That is, in a nutshell, the difference between setting up an SMB connection and communicating with local directories.
27
28 {{warning}}Note that the auto create directory setting on all SMB components only works for a "one-level" directory (i.e. /directory) and not for a "multi-level" directory (i.e. /directory/sub). To ensure this "multi-level" directory is created by eMagiz you need to take a look at this [[microlearning>>doc:Main.eMagiz Academy.Microlearnings.Advanced Level.File based connectivity.advanced-file-connectivity-dynamically-manipulate-smb-settings.WebHome||target="blank"]]{{/warning}}
29
30 eMagiz provides only one support object to connect to an SMB:
31
32 * SMB session factory
33
34 [[image:Main.Images.Microlearning.WebHome@intermediate-file-based-connectivity-smb-connectivity-smb-support-object.png]]
35
36 === 3.1 Configuration in eMagiz ===
37
38 To configure the connection between eMagiz and the SMB, we need two (or three) components. This depends on whether we want to read, write or do both while communicating with the SMB. If we're going to do both, we need both of the functional components. In all other scenarios, you only need one of the functional components. The functional components that you might need are called:
39
40 * SMB inbound Channel adapter
41 * SMB outbound Channel adapter
42
43 On top of that, you need the following support object.
44
45 * SMB session factory
46
47 In this microlearning, we will use the SMB inbound channel adapter combined with the SMB session factory to illustrate the configuration. Please note that any other combination works similarly. To configure the connection with the SMB, we first navigate to the Create phase of eMagiz. Here we open the flow we want to edit. In this example, that will be an entry flow as we want to retrieve (read) data from the SMB.
48
49 When you have opened the flow, you need to enter "Start Editing" mode. After you have done so, we first add the SMB session factory support object to our flow.
50
51 [[image:Main.Images.Microlearning.WebHome@intermediate-file-based-connectivity-smb-connectivity-smb-session-factory-empty.png]]
52
53 Here, we need to define the following:
54
55 * Host
56 * Port
57 * Username
58 * Password
59 * Share and directory
60
61 {{info}}
62 The value for the share and directory field is the main folder for your file share. If the main folder is the exchange folder, then within the SMB inbound channel adapter, a / is needed as remote directory.
63 {{/info}}
64
65 [[image:Main.Images.Microlearning.WebHome@intermediate-file-based-connectivity-smb-connectivity-smb-session-factory-filled-in.png]]
66
67 In the advanced tab there are only two settings to change. The minimum and maximum SMB protocol version. By default, these are set to 2.02 and 3.1.1 respectively to allow a wide range of save protocol version. However, if you want to only allow the best performing version, the minimum 3.0.2 is advised. If you aim for the best secured connection version 3.1.1 has the most functionality in this area. The best practise on this is set the minimum version as high as possible to mimize risks.
68
69 Now that we have configured the support object,we can add the SMB inbound channel adapter to the flow.
70
71 [[image:Main.Images.Microlearning.WebHome@intermediate-file-based-connectivity-smb-connectivity-smb-inbound-channel-adapter-empty.png]]
72
73 In this component, we need to define the remote directory where the original files are located. We need to specify the local directory used to store the files before they are processed temporarily. Furthermore, we need to link the support object we have just created and define a poller. For that last one, the best practice is the use of a cron trigger.
74
75 [[image:Main.Images.Microlearning.WebHome@intermediate-file-based-connectivity-smb-connectivity-smb-inbound-channel-adapter-filled-in.png]]
76
77 Apart from these configurations, you could also add a filter, just as we learned in the [[Crash Course Messaging on file-based connectivity>>doc:Main.eMagiz Academy.Microlearnings.Crash Course.Crash Course Messaging.crashcourse-messaging-pick-up-files||target="blank"]]. Finishing things off, we should consider the delete behavior we will use. Based on the filter and the business requirements, whether to delete and when to delete could differ. So please consider all your options in that regard. In case there are multiple readers from the folder and/or there are legal requirements to store source files for a certain time period, you should not use the delete remote files option. However, not deleting files read files can cause overloading the machine if no alternative delete policies is in place.
78
79 === 3.2 SMB Gateway ===
80
81 The SMB Gateway is an additional component that can be used to interact with your SMB share. It allows the use of a set of pre-configured commands to perform actions such as deleting files. Compared to the outbound channel adapter replies are send back to eMagiz. These reply messages depend on the selected command. Every command option is explained in detail within the helptext. An example configuration to send files is shown below.
82
83 [[image:Main.Images.Microlearning.WebHome@intermediate-file-based-connectivity-smb-connectivity-smb-outbound-gateway-filled-in.png]]
84
85 {{info}}
86 Please note that for some commands an SpEL expression is required to respresent a path. This setting can be found in the advanced settings. An example for the mget command could be **myfilesdirectory/** to get only files from this directory.
87 {{/info}}
88
89 All available options are:
90
91 * List files
92 * List file names
93 * Retrieve file
94 * Retrieve multiple files
95 * Remove file(s)
96 * Move/rename file
97 * Send file
98 * Send mulitple files
99
100 This concludes our microlearning, in which we learned how to set up the connectivity with an SMB.
101
102 == 4. Key takeaways ==
103
104 * Server Message Block (SMB) is a network protocol used for sharing files between computers over TCP/IP connections. It allows a client to access files on a remote server as if they were on the local machine.
105 * In an SMB transaction, the end user's computer is typically called the localhost. The second computer involved in SMB is a remote host, which is usually a server.
106 * Servers must be set up to run SMB services, and the client must have SMB software installed to access these services.
107 * To use SMB with eMagiz, you'll need the SMB Gateway component (that offers pre-configured commands for managing files), the SMB session factory and either an SMB inbound or outbound channel adapter (depending on whether you're reading from or writing to the SMB share).
108
109 == 5. Suggested Additional Readings ==
110
111 If you are interested in this topic and want more information, please read the release notes provided by eMagiz. Furthermore, check out these links:
112
113 * [[eMagiz Store (Menu)>>doc:Main.eMagiz Store.WebHome||target="blank"]]
114 ** [[Accelerators (Navigation)>>doc:Main.eMagiz Store.Accelerators.WebHome||target="blank"]]
115 *** [[SMB Inbound Connectivity (Explanation)>>doc:Main.eMagiz Store.Accelerators.SFTP Inbound Connectivity.WebHome||target="blank"]]
116 *** [[SMB Outbound Connectivity (Explanation)>>doc:Main.eMagiz Store.Accelerators.SFTP Outbound Connectivity.WebHome||target="blank"]]
117 *** [[SMB Gateway Connectivity (Explanation)>>doc:Main.eMagiz Store.Accelerators.SFTP Gateway Connectivity.WebHome||target="blank"]]
118 * [[Crash Course (Menu)>>doc:Main.eMagiz Academy.Microlearnings.Crash Course.WebHome||target="blank"]]
119 ** [[Crash Course Messaging (Navigation)>>doc:Main.eMagiz Academy.Microlearnings.Crash Course.Crash Course Messaging.WebHome||target="blank"]]
120 *** [[Pick up Files (Explanation)>>doc:Main.eMagiz Academy.Microlearnings.Crash Course.Crash Course Messaging.crashcourse-messaging-pick-up-files||target="blank"]]
121 * [[SMB (Search Results)>>url:https://docs.emagiz.com/bin/view/Main/Search?sort=score&sortOrder=desc&highlight=true&facet=true&r=1&f_space_facet=0%2FMain.&l_space_facet=10&f_type=DOCUMENT&f_locale=en&f_locale=&f_locale=en&text=%22SMB%22||target="blank"]]
122 * [[SMB Overview (External)>>https://learn.microsoft.com/en-us/windows-server/storage/file-server/file-server-smb-overview||target="blank"]]
123 * [[SMB Support (External)>>https://docs.spring.io/spring-integration/reference/smb.html||target="blank"]]
124
125 )))((({{toc/}}))){{/container}}
126 {{/container}}