This web page is about the configuration tool for Webcom MQTT Gateway. It is strongly recommended to read this page before using this tool.
Table of contents:
Where is the configuration tool ?
For now, you can access this configuration tool through the 
tab on Webcom management page.
Once logged in, choose your favorite Webcom application, also known as "namespace", click on the 
button, then on tab. On the page, you should see something like this:
In chapters below, we will show how to write Webcom MQTT Gateway settings for an application called "mqtt-demo".
Notice: Appearance of different forms may change in the future, or look a little different on your browser.
The main form
What you see above is called the "main form" and allows you to:
- handle Subscribe to MQTT -> Put/Push to Datasync configurations,
- handle Listen to Datasync -> Publish to MQTT configurations,
- display running configurations,
- search for running configurations,
- access this documentation :-)
At the top of the form, click on little 
icon to access the top page of this documentation.
Authentication key
Below, you have to provide an "Authentication key" shared by all Webcom MQTT Gateway settings for this Webcom application. For now, this key is one of the secrets keys of your Webcom application, that should be replaced in the future by some more secured type of key...
So, back to the top of the page, choose the 
tab and create there a secret key (we strongly recommend not to use the default one, as it is easier to create/revoke your own ones) through the 
button at the bottom of the page. Click on 
button and copy the key.
Back to our main form, paste the key in "Authentication key" input text box and reload the page. Oops, the key disappeared ! This is because we forgot to hit the 
button. So, paste the key again, click on button and reload the page.
Congratulations, you just successfully started to configure Webcom MQTT Gateway for your Webcom application.
Save and Reload
At the right top of the main form, you can find both and 
buttons.
You can change anything you want in any settings, including the shared "Authentication key", but as long as you do not click on button, nothing happens. So, we strongly recommend to hit that button as soon as you change something, somewhere in some settings.
You have to know that, as soon as you hit that button, the entire set of configurations is parsed by Webcom MQTT Gateway. Any configuration, presenting even a tiny change in its settings, is stopped and start again. So, if you wait to change lots of things in many configurations before hitting the button, this process may take a while...
The button is used as a roll back, as long as you have not hit the button !
Say that you have changed some settings and you want to start from fresh again. You can go back to the previous state of your configurations by hitting that button. Actually, when you click on the button, Webcom MQTT Gateway is requested for your settings, exactly as it is when the main form is first loaded.
You can even use that button, after hitting the button, just to be sure what you just saved was really stored to the Webcom MQTT Gateway.
Configurations
Below the "Authentication key" input text, you can find 
and 
links, each of which purpose is to navigate through configurations in order to change them (or not)
The third link, 
, is bound to configurations that are actually running. It allows to read them, and may be used along with the "Search for running MQTT configurations sub form" that will be described in a specific chapter below.
Handling configurations
Let us create our first configuration, say a Subscribe to MQTT -> Put/Push to Datasync one. On the main form, click on link, the main form turns to the following:
Then, click on the 
link and you should see the following form:
General settings
A new form pops up in front of the main form, which is now unreachable, until you close this form. Closing such a form can be done either with the little cross in its top right or simply by clicking outside of it.
Let us call this new form the "main configuration form".
The main form, however, has changed. Below the link, you can see that there is some kind of a new line, just above the link. It contains nothing for now, but let us type a "Title" and a little "Description" in corresponding input text boxes.
As you can see, title and description appear now on this new line. Actually, this new line is a link representing your new configuration. Clicking on it, when main form is reachable again, pops up the main configuration form again. Give it a try...
Additionally, you may have noticed that the title also appear on top left of the main configuration form.
There is also an "Available" check box, but we cannot check it yet, as some mandatory settings are not set.
On top right, you can find a 
button. Let us try it:
Yet another pop up, asking you if you really want to remove this configuration. Let us keep our settings for now, so just hit the 
button.
MQTT broker settings
In the main configuration form, now click on the 
button, a new form pops up again, that we could call the "MQTT broker form":
As you can see, our three MANDATORY settings (see "MQTT broker settings" on Overview page) are highlighted in red. Let us populate these three settings and see what happen:
As soon as the last input text box losts the focus, another pop up appears:
Just close this pop up and go back to the main configuration form (click outside of the MQTT broker form or click on its upper right little cross) and check that the "Available" check box is now ready for checking. Let us click on it:
Now, if you go back to the MQTT broker form, remove one of the three mandatory settings and come back to the main configuration form, you should see that "Available" check box is no more checked and no more reachable again. Give it a try...
Let us complete the MQTT broker form:
For this MQTT broker, please use the following as the "SSL Certificate":
-----BEGIN CERTIFICATE-----
MIIDSjCCAjKgAwIBAgIQRK+wgNajJ7qJMDmGLvhAazANBgkqhkiG9w0BAQUFADA/
MSQwIgYDVQQKExtEaWdpdGFsIFNpZ25hdHVyZSBUcnVzdCBDby4xFzAVBgNVBAMT
DkRTVCBSb290IENBIFgzMB4XDTAwMDkzMDIxMTIxOVoXDTIxMDkzMDE0MDExNVow
PzEkMCIGA1UEChMbRGlnaXRhbCBTaWduYXR1cmUgVHJ1c3QgQ28uMRcwFQYDVQQD
Ew5EU1QgUm9vdCBDQSBYMzCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEB
AN+v6ZdQCINXtMxiZfaQguzH0yxrMMpb7NnDfcdAwRgUi+DoM3ZJKuM/IUmTrE4O
rz5Iy2Xu/NMhD2XSKtkyj4zl93ewEnu1lcCJo6m67XMuegwGMoOifooUMM0RoOEq
OLl5CjH9UL2AZd+3UWODyOKIYepLYYHsUmu5ouJLGiifSKOeDNoJjj4XLh7dIN9b
xiqKqy69cK3FCxolkHRyxXtqqzTWMIn/5WgTe1QLyNau7Fqckh49ZLOMxt+/yUFw
7BZy1SbsOFU5Q9D8/RhcQPGX69Wam40dutolucbY38EVAjqr2m7xPi71XAicPNaD
aeQQmxkqtilX4+U9m5/wAl0CAwEAAaNCMEAwDwYDVR0TAQH/BAUwAwEB/zAOBgNV
HQ8BAf8EBAMCAQYwHQYDVR0OBBYEFMSnsaR7LHH62+FLkHX/xBVghYkQMA0GCSqG
SIb3DQEBBQUAA4IBAQCjGiybFwBcqR7uKGY3Or+Dxz9LwwmglSBd49lZRNI+DT69
ikugdB/OEIKcdBodfpga3csTS7MgROSR6cz8faXbauX+5v3gTt23ADq1cEmv8uXr
AvHRAosZy5Q6XkjEGB5YGV8eAlrwDPGxrancWYaLbumR9YbK+rlmM6pZW87ipxZz
R8srzJmwN0jP41ZL9c8PDHIyh8bwRLtTcm1D9SZImlJnt1ir/md2cXjbDaJWFBM5
JDGFoqgCWjBH4d1QB7wCCZAA62RjYJsWvIjJEubSfZGL+T0yjWW06XyxV3bqxbYo
Ob8VZRzI9neWagqNdwvYkQsEjgfbKbYK7p2CNTUQ
-----END CERTIFICATE-----
Webcom settings
Go back to the main configuration form and click on the 
button to access what we are going to call the "Datasync form":
Let us populate it according to our example #2 from the Overview page
Go back now to the main configuration form and be sure the "Available" check box is actually checked.
Save the new configuration
Back to the main form, hit the button. The main form now turns to:
As you can see, there is now one running configuration, and if you click on the link, you can navigate through main configuration form, MQTT broker form and Datasync form exactly as explained before, but without the ability to change anything. This is just a read-only way of navigating through your running configurations...
Create another configuration
From the main form, let us use the link to create another configuration. The only change is in the Datasync form that we could populate according to our example #1 from the Overview page
Let us use the following as MQTT broker settings (SSL Certificate is the same as in previous example)
Do not forget to hit the button on the main form.
Running configurations
Let us click on the link, both of our previously configurations appear:
Notice that it is not only a matter of checking if configurations are properly set for running. Webcom MQTT Gateway is requested to check all configurations that are really running. Keep in mind however, that a running configuration may malfunction, in which case Webcom MQTT Gateway will start it again and again until there is no more failure. So, if you do not obtain results you are waiting for, you may check and possibly update your configurations...
Searching for running configurations
Now, let us imagine that we have dozens of configurations for our Webcom application, and that we only want to check the one with topic containing "myTopic". We can use the "searching form" at the bottom of the main form, and as soon as we hit the 
button we obtain the following:
Now, say that we only seek for "Subscribe to MQTT -> Put/Push to Datasync" category of configurations:
Notice that the "Path listened" input text box disappeared as it is useless for Subscribe to MQTT -> Put/Push to Datasync configurations. Its use is the same as "Topic" input text box, meaning that you do not need to type a strictly matching listen path or topic, but only a part of it.
Notice also that criteria use an AND operand, so that if you use all of them, you seek for configurations corresponding to "topic contains a certain string" AND "category is a certain category" AND (if available) "listen path contains a certain string".
From now on, the best way to understand that is giving it some try...