-
Notifications
You must be signed in to change notification settings - Fork 1
Fallback System
ESMira is relatively robust regarding connectivity issues. Most functionalities work offline, and if an ESMira server is temporarily unreachable most users will likely not even notice during normal use of the application. However, while a running study can work offline temporarily, a reachable server is crucial for joining a study, as some potential participants will not try to join again repeatedly. The fallback system tries to increase the robustness of this process, by providing an alternative server to retrieve the study config from in case the primary server is down.
By default, all ESMira servers are independent. The fallback system allows you to connect two servers, so that one might act as the fallback for the other. Once a server is set up as another server's fallback server, studies that are saved on the primary server will also be stored on the fallback server. The links that users can use to join studies can then include an (optional) fallback parameter. This parameter encodes the address of the fallback server. This means that the QR codes and links to the study info page and app install page that ESMira generates on the Publish page keep working, both for reaching these pages with a regular QR code scanner, as well as for joining a study within the app. However, in case the primary server is not reachable, the ESMira app can use the additional information to attempt requesting the study configuration from the fallback server. Once the study is joined, everything will work offline until the primary server comes back online again.
Note that the relationship between primary server and fallback server is asymmetrical. Any ESMira server may be defined as any other server's fallback server. It is possible, but not necessary, to define two ESMira servers as each others fallback servers.
Any regular ESMira server can be used as fallback server. To allow a server to act as fallback for another server, the primary server must use a setup token provided by the fallback server. To generate a setup token on the fallback server, a user needs to be either an admin, or have permission to generate these (granted by an admin). Our recommendation is to give the admin of the primary server a user account with that permission on the fallback server.
A user with the appropriate permission will see the button Fallback System when logged in on the fallback server. On the Fallback System page is a list of all incoming connections (which will be empty if there are no connections yet). A button at the bottom of the page allows the generation of a setup token. Once clicked, the page will display both the fallback server's url, as well as the setup token. Both of these are necessary for the setup.
Note that setup tokens are single-use, and only valid for a few minutes. For that reason they will only be displayed once when generated. If something does not work, a new one can be generated easily.
To set up the fallback server on the primary server, log into the primary server with an account with admin permissions (the permission to generate fallback setup tokens is not enough on the primary server's side). There, navigate to the Fallback System page, similar to before. go to the Outgoing Connections tab. Add the url and token you got from the fallback server under Add a Connection. Once you click save, ESMira will attempt to create the connection. If there are no problems, the server will be added to the list of outgoing connections. Otherwise ESMira will display an error message.
If you successfully connected the servers, everything should work. If you still want to test the connection, you can do so by navigating to the Outgoing Connections tab on the Fallback System page (on the primary server). Click on the gear icon next to the server you want to test. Click on the Test connection to fallback server button. This will send a request to the fallback server that goes through all the usual authentification steps. If this connection test is successful, it means that the primary server can reach the fallback server and can successfully authenticate there.
On this page you also find a button to Synchronize all studies. Clicking this button will push all studies from this server to the fallback server. This can be useful when you first make a connection. Later on this should not be necessary, as from now on any time a study is saved on the primary server it will also be sent to the fallback server.
Once the fallback system is set up this information will be included in the Publish page (Publication, Links & QR code) of a study (provided the study does not opt out of using the fallback system via its study settings). Both the Study Information link and the App installation instructions link will include an additional parameter (?fallback=...) encoding the address of the fallback server. This information is also present in the QR code, and when scanning the QR code the ESMira application can extract this information to attempt retrieving the study from the fallback server in case the primary server is not reachable.
Note, however, that a normal browser cannot interpret this information this way, meaning that if the primary server is down, the links will stop working. It is possible to display the app install instructions for a study on the fallback server. You can find the link for that under Fallback app installation instructions (A QR code for this will not be created, as the ESMira app could not interpret that link properly to join a study). You can then provide potintial participants with both the link to the app installation instructions on the primary server, as well as a backup link to the app install instructions on the fallback server.
Normal users of the ESMira server will only notice the fallback system with the changed links and QR codes on the Publish page. However, other than that the system will be opaque to them, and even if there are issues with the connection they will not be notified. This has two reasons:
- A normal user cannot resolve the problem
- The fallback server is only needed if the primary server is down. If a normal user, e.g., saves a study, then a warning could be misinterpreted as a problem with the primary server. However, unless the primary server is down, everything will work as normal, even if the fallback server does not work.
For this reason warnings and errors will only be displayed to admins under Show error reports.