VoltMX Iris

These steps show how to add the VoltMX-IDE-SDK to your project and set up VoltMX Foundry Client.

Prerequisites

VoltMX Iris 7.0 and above.

Downloading VoltMX IDE SDK Files

The VoltMX SDK is now included as part of the VoltMX development tools and the SDK version is managed using the update feature within the software.

If you need to install the VoltMX development tools, please download the updates from VoltMX downloads site.

Initializing the VoltMX JS Client SDK

Initialize VoltMX Foundry client with the following code, and start using the services provided in VoltMX Foundry. The initialization method fetches the configuration from VoltMX Foundry and saves it in the cache. Later, the application uses the cached configuration. It is a synchronous call.

The preferred way to initialize the VoltMX JS client SDK is by using the feature initWithServiceDoc through the VoltMX Iris Enterprise application. The client can also be initialized manually, but this is not recommended.

Initializing the VoltMX JS Client SDK with initWithServiceDoc

In Iris Enterprise, follow these steps:

Ensure Iris Enterprise has been logged into using the Cloud console login credentials.
In the top menu of Iris Enterprise Go to Help -> About VoltMX License -> Manage License -> Enter VoltMX Cloud console credentials for your cloud account (https://manage.voltmx.com) -> Finish
Iris Enterprise will login using the credentials. After successful login, the login name would appear in the bottom bar of Iris Enterprise.
Set the correct MobileFoundry server.
Click on the project settings icon (spanner and screw icon) in the left side nav panel in Iris Enterprise -> MobileFoundry Details -> click on the drop down in MobileFoundry Environment -> Choose the correct server where the MobileFoundry app has been published from cloud console.
Choose the MobileFoundry app

Right click the MobileFoundry section in Project -> Use Existing App -> select the MobileFoundry backend app from the list -> Click Use button on the right side of the app name in the list.

If you do not see the MobileFoundry app in this console either the app is not published to an environment in your account.

Once the configure services screen appears you can get back to making further changes by clicking on the workspace icon (9 squares icon).
- MobileFoundry app initialization mode:
Once the mobile foundry app is chosen in previous step, Iris enterprise takes care of automatically initializing the mobilefoundry SDK on app launch.

There are two modes of allowing app to initialize.
- For online only app: Click on the project settings icon (spanner and screw icon) in the left side nav panel in Iris Enterprise -> MobileFoundry Details -> ServiceDoc Preferences -> Select check box “Fetch service document from environment as part of build” -> click finish on bottom of Mobilefoundry Details tab.
  This will ensure that MobileFoundry is initialized by Iris Enterprise on app launch. If device is offline the initialization will fail and app has to be restarted after connecting to network for services to work.
- For online/offline app:
  - Init with ServiceDoc:
    
    This option is available in all 7.0 versions of Iris Enterprise.
    
    If you are using 6.5.x version of VoltMX Studio, please make sure you update the VoltMX Studio plugins to the following versions or later:
  - VoltMX Studio
    
    com.voltmx.core_6.5.2.GA_v201601271530_r8
    
    com.voltmx.thirdparty_6.5.2.GA_v201512291313_r2
- MobileFoundry Client SDK
  - com.voltmx.mobile.foundry.client.sdk_6.5.2.GA_v201601312211_r3
    
    Login to cloud console (https://manage.voltmx.com) in browser -> Apps -> Click on the MobileFoundry app published to environment -> Publish -> Click on the MobileFoundry environment for which app was published -> Right click on cloud download icon -> Click on App Service Document -> Save the contents of the App Service Document as a file with .json extension in local system. Ex: for appname TestMF the content can be saved as TestMF.json
    - Select the check box “Select service document file” -> Browse and upload downloaded service document file -> click Finish on bottom of MobileFoundry Details tab.
If Automatic event capture is required for application events (Available from 6.5.x VoltMX Studio Plugins only), click on the Project Settings icon (spanner and screw icon) in the left side nav panel in Iris Enterprise -> Metrics APM -> Check the box Enable automatic event capture -> check boxes for all event types required to be automatically captured -> Click Finish at the bottom of the tab.
Remove any manual initialization of MobileFoundry app with appkey/appsecret in the app. choosing the MobileFoundry app from MobileFoundry in step c ensures that the client binary has code for automatically initializing the mobile foundry app on application launch.
Clean and build the application for the desired platforms.

init

Manual initialization is not recommended; those with plugins of version 6.5.2.x or higher should always use initWithServiceDoc, as described above.

Initialize the VoltMX Foundry client with the following code.


//Sample code to initialize VoltMX Foundry Client
var appkey = 
var appsecret = 
var serviceURL = 

var client = new voltmx.sdk();
client.init(appkey, appsecret, serviceURL, function(response) {
    voltmx.print("Init success");
}, function(error) {
    voltmx.print("Init Failure");
});

setClientParams for manual init

If you are unable to upgrade to the version 6.5.2.x or higher plugins, you can still initialize the VoltMX JS SDK manually. However, some data types will not be captured in the metrics of the app. Use setClientParameters, shown below, to ensure that application identifiers remain consistent across different data triggers.

Setting clientParams in manual init scenario using setClientParams API allows MobileFoundry SDK to send client side parameters application ID and application name to the parameters set from VoltMX Studio/Iris enterprise and allows it to be consistent across different data collection points like integration services, application events and custom metrics.

Initialize the VoltMX Foundry setClientParams with the following code.


 //Sample code to initialize VoltMX Foundry Client manually   

VMXMobileFoundry = new voltmx.sdk();
    clientParams = {};
    clientParams.aid = appConfig.appId;
    clientParams.aname = appConfig.appName;
    VMXMobileFoundry.setClientParams(clientParams);

Configuring global parameters

The global parameter APIs provide the ability to set, remove, and edit global header params, query params, and body params to send in all subsequent SDK network calls.

enum globalRequestParamType

The globalRequestParamType enum specifies the following param types:

headers
queryparams
bodyparams

getGlobalRequestParams

The getGlobalRequestParams method returns all global params of the specified type that have been set.

Sytnax

getGlobalRequestParams(paramType);

Parameters:

Name	Type	Description
paramType	globalRequestParamType	The type of the param.

Return value:

This method returns a list of all network params in the following format: ({, , },{}). The param type can be either header,post param, or body.

Example


// This example returns all global header params.
var client = voltmx.sdk.getCurrentInstance();
client.getGlobalRequestParams(voltmx.sdk.globalRequestParamType.headers);

setGlobalRequestParam

The setGlobalRequestParam method adds a param with the specified name, value, and type to the network calls. If a param with the same name already exists, this API will override that param. If the same param name is manually added to a network call, the local param will have a higher priority than the global param. Once a param has been added, it is sent globally to all network calls from licensing and the SDK.

Syntax

setGlobalRequestParam(paramName, paramValue, aramType);

Parameters

Name	Type	Description
paramName	String	Name of the parameter
paramValue	String	Value of the parameter
paramType	globalRequestParamType	The type of the parameter

Example


// This example sets a global header with header name testHeader and value testValue.
var client = voltmx.sdk.getCurrentInstance();
client.setGlobalRequestParam("testHeader", "testValue", voltmx.sdk.globalRequestParamType.headers);

removeGlobalRequestParam

The removeGlobalRequestParam method removes the specified param from network calls.

Syntax

removeGlobalRequestParam(paramName, paramType);

Parameters

Name	Type	Description
paramName	String	The name of the parameter.
paramType	globalRequestParamType	The type of the parameter.

Example


// This code example removes the global header with header name testHeader.
var client = voltmx.sdk.getCurrentInstance();
client.removeGlobalRequestParam("testHeader", voltmx.sdk.globalRequestParamType.headers);

resetGlobalRequestParams

The resetGlobalRequestParams method resets all the global request params.

Syntax

resetGlobalRequestParams()

Parameters

None.

Example


// This example resets all the global request params
var client = voltmx.sdk.getCurrentInstance();
client.resetGlobalRequestParams();

Setting User ID

The setUserID API sets the user ID for the data gathered from an application. The user ID allows the data to be tracked on a user basis for broad analysis like how many different users used the application. It also helps to track activities of a specific user, which can help in seeing what activities were done before a crash, or what events led to a transaction not passing through. The user ID allows the same user to be tracked across different devices as well.


 // Sample code to set userid  
voltmx.setUserID("userID");

VMXMetricsService.setUserId has been removed from apps built with VoltMX Iris Enterprise.

Invoking an Identity Service

The following are the methods you can use for an identity service.

Login with provider type as Basic
Login with provider type as OAuth/SAML
Get Backend Token
User Profile
Get Provider Name
Get Provider Type
Logout


// Sample code to authenticate to VoltMX Foundry Client  
var authClient = null;

var  providerName = ;
var  username = ;
var  password = ;
var  loginOptions={};
loginOptions.isSSOEnabled = true;

try {
    authClient = VMXMobileFoundry.getIdentityService(providerName);
} catch (exception) {
    voltmx.print("Exception" + JSON.stringify(exception));
}

authClient.login({
        "userid": username,
        "password": password,
        "include_profile": true,
        "loginOptions": loginOptions
    }, function(response) {
        voltmx.print("Login success" + JSON.stringify(response));
    }, function(error) {
        voltmx.print("Login failure" + JSON.stringify(error));
    }
);

The client is the voltmx.sdk(); object.

This code sample shows:

1. The isSSOEnabled flag set to true, indicating that Single Sign On (SSO) is enabled. This parameter must be passed every time the user logs in. The parameters "userid" and "password" are required only for the first login. For more information about SSO, see the Application SSO section of the Features chapter of the User Guide.

2. The "include_profile parameter is set to true. This parameter specifies whether to encode the user profile as part of the claims token.

When you select VoltMX User Repository as the identity type, the system does not allow you to provide an identity name.

To use VoltMX User Repository as authentication service, the value for providerName must be set as userstore. If you set it with any other value (for example, VoltMX User Repository, User Store or Cloud Repository), the system throws an error.


 // Sample code to authenticate to VoltMX Foundry Client var authClient = null;
var  providerName = ;
var loginOptions={};
loginOptions.isSSOEnabled = true;

try {
    authClient = VMXMobileFoundry.getIdentityService(providerName);
} catch (exception) {
    voltmx.print("Exception" + exception.message);
}
authClient.login({"include_profile": true, "loginOptions": loginOptions}, 
function(response) {
        voltmx.print("Login success" + JSON.stringify(response));
    }, function(error) {
        voltmx.print("Login failure" + JSON.stringify(error));
    }
);

The client is the voltmx.sdk(); object.

This code sample shows the isSSOEnabled flag set to true, indicating that Single Sign On (SSO) is enabled. This parameter must be passed every time the user logs in. For more information about SSO, see the Application SSO section in the Features chapter of the User Guide.

This code sample shows the include_profile parameter set to true. This parameter specifies whether to encode the user profile as part of the claims token.

Get Backend Token


// Sample code to get backend token for provider   
var  userid = ;
var  password = ;
var forceFromServer = true/false;
authClient.getBackendToken(forceFromServer , {
        "userid": userid,
        "password": password
    }, function(response) {
      voltmx.print("Backend token is  :" + JSON.stringify(response));
    }, function(error) {
         voltmx.print("Failed to get backend token : " + JSON.stringify(error));
    }
);

If forceFromServer is true, then the SDK fetches the token from the server. If forceFromServer is false, then the SDK gives you the token present in localStorage. Please note that only few backend providers such as Salesforce support refresh. If a backend provider does not support refresh, passing forceRefreshFromServer=true would result in empty response from this api.

The authClient is the IdentityService object.

User Profile


 // Sample code to get user profile details
var forceFromServer = true/false;
authClient.getProfile(forceFromServer,
function(response) {
        voltmx.print("User profile is  :" + JSON.stringify(response));
    }, function(error) {
        voltmx.print("Failed to fetch profile : " + JSON.stringify(error));
    }
);

If forceFromServer is true, then the SDK fetches the token from the server. If forceFromServer is false, then the SDK gives you the token present in localStorage.

The authClient is the IdentityService object.

Get Provider Name


 // Sample code to get provider name
Var providerName = authClient.getProviderName();

The authClient is the IdentityService object.

Get Provider Type


 // Sample code to get provider type
Var providerType = authClient.getProviderType();

The authClient is the IdentityService object.

Logout


// Sample code to logout from auth service  
var options={}
options["slo"] = true;
authClient.logout(function(response) {
        voltmx.print("Logout success" + JSON.stringify(response));
    }, function(error) {
        voltmx.print("Logout failure" + JSON.stringify(error));
    }, options);

The authClient is the IdentityService object for the loggedIn provider.

This code sample shows the parameter slo set to true, indicating that all apps will be logged out when SSO is enabled. If this parameter is false, or not sent, the user will be logged out of the single app. For more information, see the Application SSO section of the Features chapter of the User Guide.

Invoking an Integration Service

This API invokes an integration service that is configured in the VoltMX Foundryportal.


 // Sample code to fetch the integration service details
var integrationClient = null;
var serviceName = ;
var operationName = ;
var params = { "your-input-keys" : "your-input-values"};
var headers = {"your-header-keys" : "your-header-values"};//If there are no headers,pass null
// options is an optional parameter helps in configuring the network layer. 
// To configure for a thin layer, use xmlHttpRequestOptions instead of httpRequestOptions.
var options={"httpRequestOptions":{"timeoutIntervalForRequest":60,
    "timeoutIntervalForResource":600}} 
try{
    integrationClient = VMXMobileFoundry.getIntegrationService(serviceName);
}
catch(exception){
    voltmx.print("Exception" + exception.message);
}
integrationClient.invokeOperation(operationName, headers, params, 
    function(result) {
          voltmx.print("Integration Service Response is :" + JSON.stringify(response));
    }, 
    function(error) {
          voltmx.print("Integration Service Failure :" + JSON.stringify(error));
    }, options
);

The client is the voltmx.sdk(); object.

Get Endpoint URL


 // Sample code to get endpoint URL   
var url = integrationClient.getUrl();

The integrationClient is the IntegrationService object.

Invoking a Messaging Service

A developer should register with Google Cloud Messaging (GCM) for Android services to get the deviceToken that is used to register with VoltMX Foundry Messaging. Also a developer should fetch the deviceId and userfriendlyId to create an instance of messaging service.

The following are the methods you can use for a messaging service.

Register
Unregister
Update GeoLocation
Fetch All Messages
Mark Message as Read
Fetch Message Content from VoltMX Foundry Messaging