Changing the Server URL during runtime

Introduction

An often requested feature by customers for MobileFirst Platform (previously Worklight) is having the ability to change, during runtime, the MobileFirst Server URL an application will attempt connecting to.

What can you do with it, you ask? Well, an example scenario would be a single client application for multiple sites/locations or customers. It could be likened to the MobileFirst Application Center Installer app, where you are not required to re-build the application for every server, rather you simply set a different IP address via the app's UI in order to connect to a different Application Center server to be served whichever applications that were deployed to it.

Now, starting MobileFirst Platform v6.3, this is also possible for Hybrid (iOS, Android) and Native (iOS, Android, WP8) applications attempting to connect to a MobileFirst Server during runtime and without the need to re-build the application.

In this blog post I will provide a quick usage example for the Hybrid API methods, for getting and setting the server URL in a simple demo application.

Note on feature availability

This feature can be used only in emulators/simulators and physical devices.
It is not supported while previewing the application's web resources in the MobileFirst Console.

Download and documentation

You can download the demo application from my GitHub repository.
For API documentation visit this IBM MobileFirst Platform Foundation user documentation page.

Demo application

So what's going on in the application?

As written above, this is a pretty simple application. It allows you to get & set the server URL as well as provide a verification that the URL change was successful. After the image is a quick rundown of the application's flow.

Application flow

Step 1

WL.Client.connect is called in order to connect to a MobileFirst Server. This can be either the MobileFirst Development Server in Eclipse, or a remote MobileFirst Server.

One pre-requisite is to make sure the .wlapp file of the application is deployed at each server that you intend to be able to connect to from the application.

Step 2

To find out what is the URL of the current server the application is intended to connect to, WL.App.getServerUrl is used:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
function getServerURL() {
    WL.App.getServerUrl(getServerURLSuccess, getServerURLFailure)
}

function getServerURLSuccess(serverURL) {
    WL.SimpleDialog.show(
	"Change Server URL", "Server URL is: " + JSON.stringify(serverURL),
	[{
	    text: "Close", handler: function() {}
	}]
    )
}
...
...

Step 3

The application successfully connected to a MobileFirst server using the current server URL. To change the server URL to another server's URL, WL.App.setServerUrl is used. In this sample I chose to have the end-user manually enter a fully qualified address by inputting the protocol, host/IP address, port and context root, but of course this is purely applicative.

Possible alternatives:

• A UI with a dropdown or otherwise, pre-filled with pre-defined server URLs
• Entering only the context root or only the host/IP address (and handling in the app logic any string operations)
• You name it

1
2
3
4
5
6
7
8
9
10
11
function setServerURL() {
    // Get the URL from the text field.
    var serverURL = $("#serverURL").val();
    WL.App.setServerUrl(serverURL, setServerURLSuccess, setServerURLFailure);
}
function setServerURLSuccess() {
    // Display the newly set server URL.
    getServerURL();
}
...
...

Step 4

After setting the new server URL, we can now tap the connect button to connect again. Viola!