Technical Flows in Spotlight

The Spotlight application uses standard way of data integration using the object data model provided by the Reference Architecture (MVC).

All the modules (except few exceptions) follow the defined structure to get data from the back-end (Quantum Fabric) to the UI (Form).

Event or data flow as given in the diagram

1. The User UI event is passed from the form through the form controller to the presentation controller.
2. The presentation controller handles this event either to change the UI/form using the presentUserInterfact API or to execute a business by accessing the businessController property.  For example, in presentation controller's method, presentUserInterface('formName', viewModel); this.businessController.doLogin(username,password);
3. This will present the requested form, and invoke the willUpdateUI method with the viewModel parameter on the form controller. Implement the willUpdateUI method to bind the data to the widgets in the form.
4. If any data from the back end is required, the presentation controller calls the module's business controller method sending the request context, and the callbacks (onSuccess and onError).
5. The business controller (delegator) of the module will forward the call to the business controller of the Objects Services Manager.
6. The business controller of the manager will in turn use the data layer, and the generated object models from Quantum Fabric, to hit the Quantum Fabric object services, and sends back the data in the onSuccess Callback.

Exceptions

Login Process

Hit the integration service to login as the Object Services are protected and cannot be hit without first logging on. To login, refer to Quantum Fabric User Guide.

See the code sample:

//this code is extracted from doLogin method in business delegator of Auth Module
	var authParams = {
      "inputUsername": context.username,
      "inputPassword": context.password,
      "loginOptions": {
        "isOfflineEnabled": false
      }
    };
	var authClient = KNYMobileFabric.getIdentityService("KonyBankingAdminConsoleIdentityService");
    authClient.login(authParams, function successCallback(response){
		var options = {
        "IdentityServiceName": "KonyBankingAdminConsoleIdentityService",
        "AuthParams": {
          "loginOptions": {
            "isOfflineEnabled": false
	       		}
        	}
      	};
		authClient.getBackendToken(true, options, function TokenSuccessCallback(response){
			kony.mvc.MDAApplication.getSharedInstance().appContext.session_token = resTokenSuccess.value;
		}, tokenErrorCallback);
	}, errorCallback);
//ignore error flow - errorCallback, tokenErrorCallback for now

The sample above shows the Login flow. We must login using the Quantum Fabric API and get a back-end Token with authClient.getBackendToken method. We should store this token into kony.mvc.MDAApplication.getSharedInstance().appContext.session_token. The future calls to object services will send this token to Quantum Fabric for authentication.

Fetch from Configuration Framework

We also use a configuration framework provided by MVC 2.0 Architecture to fetch some security permissions for the current logged in user. We use these permissions to hide some flexes/widgets in the UI that the current user is not permitted to see.

The code sample below provides how we use the configuration framework API.

var mfURL = KNYMobileFabric.mainRef.config.reportingsvc.session.split("/services")[0]; // assuming the configuration MF app is in the same MF server
kony.servicesapp.loadAndConfigureApp(null, mfURL, function(){
	kony.servicesapp.preferenceConfigHandler.getInstance().getPreferenceValue('key'); // get the value stored in the configuration framework for the key - 'key'
	//the below code is how we actually use this configuration framework to load the form permissions configuration
	//we use our module 'configurationImporter' that will construct the tree structure from the flat structure supported by configuration framework
	var config = configurationImporter.buildConfigurationWith(function(key){
            return kony.servicesapp.preferenceConfigHandler.getInstance().getPreferenceValue(key);
    });
    permissionsConfig.registerConfig(config);
});

File Downloads

As the Object data layer provided by the Architecture does not support files, we use the pattern shown below:

//form controller method that will start the download of a csv file
downloadAttachment: function (mediaId) {
    var self = this;

    var authToken = KNYMobileFabric.currentClaimToken;
    var mfURL = KNYMobileFabric.mainRef.config.selflink;
	//get the MF url for the current server
    mfURL = mfURL.substring(0, mfURL.indexOf("/authService"));
	//construct the download link
    var downloadURL = mfURL + 
		"/services/data/v1/CustomerManagementObjService/operations/CustomerRequest/downloadMessageAttachment" + //the object service to download the file from
		"?mediaId=" + mediaId + //Add the required parameters
		"&authToken=" + authToken;
	//create an <a> tag in html for the download
    var encodedURI = encodeURI(downloadURL);
    var downloadLink = document.createElement("a");
    downloadLink.href = encodedURI;
    downloadLink.download = "branchAtmCSV.csv";
	//start download
    document.body.appendChild(downloadLink);
    downloadLink.click();
	//remove the temporary <a> tag
    document.body.removeChild(downloadLink);
}

The example shown earlier is taken from Messages module where we download the message attachments. We also use this pattern in Customer Management, Locations, Logs, and Reports Management modules.

File Uploads

The code shown below from Locations module to import new locations, shows how to send files to Quantum Fabric server.

//The code below has been extracted from Locations Module - Form Controller, Presentation Controller and Business Delegator.
//It was rewritten by removing all code unrelated to uploading a file
kony.io.FileSystem.browse(config, function csvCallback(event, filesList){
	var csvFile = (event.target.files[0]);
	var mfURL = KNYMobileFabric.mainRef.config.selflinksubstring(0, mfURL.indexOf("/authService"));
	var authToken = KNYMobileFabric.currentClaimToken;
    var user_ID = kony.mvc.MDAApplication.getSharedInstance().appContext.userID;
	//contruct the upload url
	var uploadURL = mfURL + "/services/data/v1/LocationObjService/operations/LocationsUsingCSV/importLocations";//here we are uploading to LocationObjService

	//contruct the FormData
	var formData = new FormData();
    formData.append("user_ID", user_ID);
    formData.append("branchAtmCSV.csv", csvFile);

	//send the FormData to server
    var xhr = new XMLHttpRequest();
    xhr.open('POST', uploadURL, true);
    xhr.setRequestHeader("X-Kony-Authorization", authToken);

    xhr.onreadystatechange = function() {
		if (xhr.readyState === 4 && xhr.status === 200)  {
			var importLocationsResponse = JSON.parse(xhr.responseText);
			callback(kony.mvc.constants.STATUS_SUCCESS, importLocationsResponse);
        }else if(xhr.status !== 200) {
			callback(kony.mvc.constants.STATUS_FAILURE, "Import locations server error");//update user if error
        }
	};

      xhr.send(formData);
});