Customize Your Mobile App Configuration Using config.json (Private Deployment Only)

EMS Mobile App ships with a config.json file that you can use to customize before re-signing and distributing in your app store or similar.

This topic provides the following information:

ClosedFind the config.json File 

After unzipping the respective app files, the paths to the file for each OS are:

iOS 

  • config.json (top-level file)

Android 

  • assets > config.json

The file looks like the example below (subject to change, per development):

{
    "api_doc": [
        "Configure the API here"
    ],
    "api": {

        "url_doc": [
            "The API EMS Mobile App should connect to"
        ],
        "url": ""
    }
}

ClosedSet the API URL

  1. Open the config.json file in a text editor.
  2. In the API section, find the URL property.
  3. Set the URL property to your desired value (e.g., https://Yourcompany.com/EmsPlatform).

ClosedConfigure Authentication

EMS Mobile App does not ship with an authentication configuration section by default, but you can add it as follows.

If you are adding authentication configuration, it is also necessary to set the API URL.

Below is an example (the ..._doc entries are omitted for brevity):

{
    "api": {
        "url": "https://yourcompany.com/EmsPlatform"
    },
    "authentication": {
        "activities": "openId",
        "openID": {
            "discoveryURL": "https://yourcompany.com/openid",
            "authorizationURL": "",
            "tokenURL": "",
            "clientID": "abcdefxabQijQcJstY4nImWYL5y12345",
            "redirectURL": "emssoftware://oauth-callback/x"
        }
    }
}

ClosedSupported Authentication Configurations

Open ID

"authentication": {
    "activities": "openId",
    "openID": {
        "discoveryURL": "https://yourcompany.com/openid",
        "authorizationURL": "",
        "tokenURL": "",
        "clientID": "abcdefxabQijQcJstY4nImWYL5y12345",
        "redirectURL": "emssoftware://oauth-callback/x"
    }
}
  • Set the activities to openId
  • Add an openID section next to activities

Properties for the openID Section

  • discoveryURL
    • if your IdP provides it, this is the URL for EMS Mobile App to automatically configure its Open ID settings.
    • if you provide this, leave authorizationURL and tokenURL empty.
  • authorizationURL
    • this is the endpoint to send the initial Open ID authorization request
  • tokenURL
    • this is the endpoint to request an Open ID access token
  • clientID
    • the client ID for the EMS Mobile App as configurd in the IdP
  • redirectURL
    • leave this set to emssoftware://oauth-callback/x for EMS Mobile App
    • this is the URL the IdP will redirect to during the Open ID authentication flow

ClosedSAML 

"authentication": {
    "activities": "saml",
    "saml": {
        "url": "https://yourcompany.com/ems-platform...ntication/saml`
    }
}
  • Set the activities to saml
  • Add a saml section next to activities

Properties for the SAML Section 

  • URL
    • this property is optional
    • you can manually specifiy the initial request URL for SAML authentication
    • this URL will be opened in a webview in EMS Mobile App
    • if you do not specify this property, EMS Mobile App will assume the default SAML endpoint for the REST API
      • This is one reason you must specify the URL in the api section for custom authentication configuration (e.g., if you set the custom API URL to https://ems.example.com/api, then EMS Mobile App will use https://ems.example.com/api/api/v1/a...ntication/saml as its initial SAML url)

Examples

Custom URL only 

{
    "api": {
        "url": "https://yourcompany.com/EmsPlatform"
    }
}

Open ID with Discovery URL

{
    "api": {
        "url": "https://yourcompany.com/EmsPlatform"
    },
    "authentication": {
        "activities": "openId",
        "openID": {
            "discoveryURL": "https://yourcompany.com/openid/discovery",
            "authorizationURL": "",
            "tokenURL": "",
            "clientID": "abcdefxabQijQcJstY4nImWYL5y12345",
            "redirectURL": "emssoftware://oauth-callback/x"
        }
    }
}

Open ID without Discovery URL 

{
    "api": {
        "url": "https://yourcompany.com/EmsPlatform"
    },
    "authentication": {
        "activities": "openId",
        "openID": {
            "discoveryURL": "",
            "authorizationURL": "https://yourcompany.com/openid/authorize",
            "tokenURL": "https://yourcompany.com/openid/token",
            "clientID": "abcdefxabQijQcJstY4nImWYL5y12345",
            "redirectURL": "emssoftware://oauth-callback/x"
        }
    }
}

SAML with Default API SAML Endpoint 

{
    "api": {
        "url": "https://yourcompany.com/EmsPlatform"
    },
    "authentication": {
        "activities": "saml"
    }
}

SAML with Specific API SAML Endpoint

{
    "api": {
        "url": "https://yourcompany.com/EmsPlatform"
    },
    "authentication": {
        "activities": "saml",
        "saml": {
            "url": "https://ems.example.com/saml"
        }
    }
}

ClosedChange Logging Location 

  1. Modify the logFilePath attribute: 
"logFilePath": ".\\LogFiles\\api.log"