MicroStrategy ONE

Preconfigure MicroStrategy Mobile for Android

In a typical MicroStrategy Mobile deployment, a system administrator emails a mobile configuration URL to users. This configuration URL includes information such as authentication credentials, memory limits, and homescreen preferences. When users click the configuration URL, the MicroStrategy Mobile application on their device is configured with the appropriate connection settings for the MicroStrategy environment.

When the application is upgraded, the configuration generally needs to be changed. The administrator has the ability to override the preconfigured settings as part of the upgrade process.

In this customization, you learn how to:

  • Preconfigure MicroStrategy Mobile with connection settings so that users can start using MicroStrategy Mobile immediately after installing it on their devices. A system administrator preconfigures the connection settings prior to making MicroStrategy Mobile available to the users.
  • Override preconfigured settings so that users can start using MicroStrategy Mobile immediately after upgrading the application on their devices. A system administrator overrides the preconfigured connection settings before making the upgrade available to users.

To preconfigure MicroStrategy Mobile in Android Studio:

  1. Define a new configuration for MicroStrategy Mobile  

  2. Create a JSON object based on the configuration URL  

  3. Set up the environment to use the MicroStrategy Mobile project  

  4. Use the JSON object in the project configuration file  

  5. Replace the default URL used for configuration synching  

  6. Build the project to confirm that the application compiles successfully

To override preconfigured settings during an application upgrade:

  1. Override the existing configuration with a new configuration
  2. Confirm that the application compiles successfully

The steps to preconfigure MicroStrategy Mobile are described below.

  1. Define a new configuration for MicroStrategy Mobile

    Follow these steps to define a new configuration file for the mobile device and copy the ID for this configuration.

    1. Define a new configuration for MicroStrategy Mobile from the Mobile Configuration settings in MicroStrategy Web. This generates an XML configuration file in the MicroStrategy/Mobile Server/WEB-INF/xml/mobile folder of your application server for MicroStrategy Mobile.

      Do not enter user credentials while defining a new configuration. Users will be prompted for their credentials the first time they access the application, and their credentials will be saved for subsequent logins.  

    2. Navigate to the MicroStrategy/Mobile Server/WEB-INF/xml/mobile folder of your application server for MicroStrategy Mobile to locate the XML configuration file created in the previous step. The name of the file uses the following syntax: mobileConfig-configurationID.xml. For example, mobileConfig-3ef9a175-52dc-461d-a0eb-7ae95aac3ecf.xml.  

    3. Copy only the configurationID from the name of the XML file. Based on the example in the previous step, copy 3ef9a175-52dc-461d-a0eb-7ae95aac3ecf.  

  2. Create a JSON object based on the configuration URL

    Follow these steps to create a JSON object from the configuration URL.

    1. Access the Task Administrator application by using the URL below. Replace the value of MobileWebServerName with the name or IP address of your Mobile Web Server machine. For more information on these applications, refer to the Tasks and Service-Oriented Architecture section of the Web SDK.

      J2EE environment:

      Copy 
      http://MobileWebServerName/MicroStrategyMobile/servlet/taskAdmin

      .NET environment:

      Copy 
      http://MobileWebServerName/MicroStrategyMobile/asp/taskAdmin.aspx         

    2. When the Task Administrator application launches, click the Builder tab at the top.  

    3. Select getMobileConfiguration from the Task ID drop-down menu.

      By default, only public tasks are visible in and accessible from the Task Administrator application. The getMobileConfiguration task is private. Click here for instructions on how to make this task visible.

      1. Navigate to the taskProcessorControllerConfig.xml file under the Mobile Server ASPx/WEB-INF/xml folder in the MicroStrategy installation directory.

      2. Open this XML file and locate the line that defines the getMobileConfiguration task as private:

        Copy 
        <taskProcessorController>
            ...
            <privateTasks show="false">
                ...
                <privateTask taskID="getMobileConfiguration" />

      3. Comment out this line:

        Copy 
        <!--<privateTask taskID="getMobileConfiguration" />-->

      4. Save taskProcessorControllerConfig.xml.

      5. Restart the application server.

        If you are using a MicroStrategy Mobile server, the getMobileConfiguration task now appears in the list of tasks on the Task Viewer or Task Administrator application. If you are using a MicroStrategy Web server, no mobile tasks will be visible, regardless of changes you make to the taskProcessorControllerConfig.xml file.

    4. Select xhr from the Task Envelope drop-down menu.  

    5. Select json from the Task Content Type drop-down menu.  

    6. Enter the value of the configuration ID in the Value text box for configurationID and select the Include? check box next to it. This value is the ID value you copied for the configuration file in the step above.  

    7. Enter flatten in the Value text box for >blockTransform and select the Include? check box next to it.  

    8. Enter 1 in the Value text box for blockVersion and select the Include? check box next to it.  

    9. Click Update URL to generate the URL. The generated URL is displayed in the text box below the button.  

    10. Copy the generated URL. It will be used in step 5.b below.  

    11. Click Invoke URL to generate the Task Response. The response is generated as a JSON object in the text box below the button.  

    12. Copy the JSON object. It will be used in step 4.c and step 4.e below.  

  3. Set up the environment to use the MicroStrategy Mobile project

    Set up the environment so that you can use the MicroStrategy Mobile project as the base for your customizations.  

  4. Use the JSON object in the project configuration file

    Follow these steps to use the JSON object in the project configuration file, default_config.json.  

    1. If the MicroStrategyMobile project is not open, open it in Android Studio.  

    2. Navigate into the res folder and create a new folder called raw. The raw folder contains the project configuration file for smartphones.  

    3. Inside the res/raw/ folder, create a file called default_config.json and paste into it the JSON object copied from step 2.l.  

    4. Navigate back into the res folder from step b and create a second folder called raw-large. The raw-large folder contains the project configuration file for tablets.  

    5. Inside the res/raw-large/ folder, create a file called default_config.json and paste into it the JSON object copied from step 2.l.  

    After completing these steps, there should be two new folders, each containing a JSON file, as shown in the paths below:

    • res/raw/default_config.json
    • res/raw-large/default_config.json

  5. Replace the default configuration URL used for configuration synching

    When you use the MicroStrategy Mobile shell project to build your own custom mobile application, you need to change the default configuration URL that is stored in the shell project. This configuration URL is used by the Mobile Server to determine whether a configuration has been updated. If you do not replace the default URL with your own URL, the automatic configuration synching will not work properly on the device. To create your own configuration URL for the Mobile Server to use, simply do the following:  

    1. Create a text file called default_config_url.txt.  

    2. Make sure that  the URL you generated in step 2.j is not encoded.  

    3. Paste this URL into default_config_url.txt and save it in both the res/raw folder and the res/raw-large folder.  

  6. Build the project to confirm that the application compiles successfully  

    1. In Android Studio, build the project.  

    2. Run the compiled application on a device or simulator to confirm that the APK you built can run successfully.

    To distribute mobile applications to your users, refer to the Distributing Android Applications topic.

The steps to override preconfigured settings when MicroStrategy Mobile is upgraded are described below.

  1. Override the existing configuration with a new configuration

    1. Follow steps 1 - 5 above to set default_config.json and default_config_url.txt for the new configuration.

    2. In a text editor, create bools.xml with the following code. When you set "replace_config_with_default_when_upgrade" to "true", it tells the application to use the new configuration.

      Copy 
      <?xml version="1.0" encoding="utf-8"?>
      <resources>
      <bool name="replace_config_with_default_when_upgrade">true</bool>
      </resources>

    3. Save bools.xml under MicroStrategyMobile -> app -> src -> main -> res -> value.

  2. Confirm that the application compiles sucessfully

    1. In Android Studio, build the project.

    2. Run the compiled application on a device or simulator to confirm that the APK you built can run successfull.

    To distribute mobile applications to your users, refer to the Distributing Android Applications topic.