Version 2021

Customize client error messages in any language

Identity server provides a way to customize client error messages in any language. Use the procedure below to set up iOS and Android properties files for custom error messages. This functionality does not include the setup of informative messages.

This functionality is only supported for Account SDK and not Badge SDK.

  1. Create two bundle files, one for iOS and one for Android, named DefaultClientMessageBundleios.properties and DefaultClientMessageBundleAndroid.properties. Two files are necessary since some messages may be different between iOS and Android. For example, a biometric failure message on iOS may mention face ID, whereas on Android it mentions fingerprints. If you decide to support multiple languages and need a global fallback language, these files should contain the fallback language. Otherwise, these two files should be the only ones you use.

    Copy 
    #DefaultClientMessageBundleIos.properties
    #central.client.message.version should only be presented in DefaultClientMessageBundleIos.properties instead of individual bundle file
    central.client.message.version=0.1.0
    # only put other items if one wants to have a global fallback. Otherwise, please leave it empty and only edit the individual language files.
    # This instructs the client to use its own preconfigure message for unknown languages on the server side.
    mstr_ios_-1001=Network timeout
    mstr_ios_-1009=Network offline
    mstr_ios_-1200=Invalid certificate for network
  2. The two root bundles, DefaultClientMessageBundleIos.propeties and DefaultClientMessageBundleAndroid.properties, contain a version number in central.client.message.version. You should update the version number after the messages in each bundle are updated. The version should be at least 0.0.1 and be incremented each time the messages are updated.
  3. To customize your error messages, add the string key and customized message string using the syntax shown in the code snippet above. See Android error message keys and iOS error message keys for the available string keys, as well as the default English strings and error codes.

  4. To support multiple languages, you must create iOS and Android files for each language. The end of the filename must contain a BCP 47 language tag code. For example, the name of the American English bundle should be DefaultClientMessageBundleIos_en_US.properties and DefaultClientMessageBundleAndroid_en_US.properties. If you update a specific language file, you must also update the version number in the original DefaultClientMessageBundleIos.properties and DefaultClientMessageBundleAndroid.properties files. To do this safely in a multiple node environment, remove the associated node from the load balancer before you update the messages and put it back after you update the messages.

    Copy 

    #DefaultClientMessageBundleIos_en.properties
    mstr_ios_-1001=Network timeout
    mstr_ios_-1009=Network offline
    mstr_ios_-1200=Invalid certificate for network
  5. Save the bundle files in <Identity Server installation>/usherApps/shardIDM/webapps/ROOT/WEB-INF/classes/. Since this folder is managed by Tomcat, it should backed up and restored in each war deployment.

Encoding

If you create the properties file in one type environment and then use it in another type of environment, you may need to convert unrecognized characters to ISO-8859-1, so that it is compatible with MicroStrategy's currently supported version of Java 8. For example, if you create the file in a Linux environment and then use it in Windows. You can create or convert your property file using the Oracle native2ascii tool.

Configurable cache period

The default cache time is one hour. This means that if the messages are changed, it takes one hour for the client to see updated messages. The value can be changed by modifying client.message.cache.ttl in serverdb.conf. This file is normally located in <Identity Server installation>/db_configs/usher/password. The value is in seconds. The default value is 3600, which is one hour. Changing the value does not require a server restart.

Upgrading

The <Identity Server installation>/usherApps/shardIDM/webapps/ROOT directory is created a result of deploying ROOT.war. This means that a new deployment removes the existing root directory, along with your message bundle files. If you are upgrading, downgrading, or redeploying, you need to backup the bundle files. After deployment, restore them under <Identity Server installation>/usherApps/shardIDM/webapps/ROOT/WEB-INF/classes.

To perform an upgrade in a multiple-node environment:

  1. Remove the associated node from the load balancer.
  2. Back up all of the files that start with DefaultClientMessageBundleIos and DefaultClientMessageBundleAndroid under <Identity Server installation>/userApps/shardIDM/webapps/ROOT/WEB-INF/classes.
  3. Upgrade the Identity server and restart it.
  4. Add the files you backed up to <Identity Server installation>/usherApps/shardIDM/webapps/ROOT/WEB-INF/classes.
  5. Add the node back to the load balancer.