Technical Guide

The configuration file is case-sensitive, and Windows paths must use double backslashes (for example "C:\Windows\System32\notepad.exe").

Configuration might required reference to assets and scripts. These are referenced via file path.

Although any file path can be read, it is recommended to create C:\ProgramData\BlueFletch\assets and C:\ProgramData\BlueFletch\scripts folders and save resources accordingly.

Base

Field	Description
configVersion	string A free-form user-defined string that can be used to indicate the version of this configuration file being published. Added as a convenience field to help customers track which configuration file version is on the device.
license	string (mandatory) A customer-specific license key to provide access to the Launcher. There will only be one key assigned per customer and should be applied to all the customer's devices. To obtain a license key, request one from the BlueFletch sales representative.
layouts	object Defines which applications to display based on Login state. See Layouts for more info.
epmConfig	object Enterprise Password Manager settings. For future implementation.
emsSupportTool	object Key Value pairs that control support application processing. See emsSupportTool for more information.
settings	object Key Value pairs of settings that control processing. See Settings for details.
auth_oauth2	object Key Value pairs of settings that control AppAuth/OAuth2 Authorization.
auth_azure	object Key Value pairs of settings that control Entra Id Authorization
assets	object Configuration for specifying UI or file assets to use in UI rendering.
theme	object Contains information on an Organization's device theme. See Theme for details.

Layouts

Layouts represent which applications the launcher will display, based on who is logged in.

Field	FieldDescription
GROUP	object An application object that represents applications for which the logged user has access. Example: manager, associate. Each GROUP has a collection of Application, Folder, and/or Shortcuts. See Application Object, Web Shortcut Object or Folder Object for additional details.

Example:

Copy

    "layouts" : {
        "Manager":[ -Logged in Managers will have access to these Applications.- ],
        "Associates":[ -Logged in Associates will have access to these Applications.- ],
        "*": [ -OPEN ZONE definition of applications- ]
    },

Application Object

Available fields used to describe applications displayed on the Launcher home screen.

Field	FieldDescription
label	string The name of the application to display.
iconUrl	string Represents an icon to override the default application image. Must be a URL. Starting v1.0.45, iconUrl can also be local file path.
path	string Path to executable or shortcut file.
rightClickMenu	Object Contains information for options displayed whe right clicking on application in taskbar - Optional

Example:

    {
      "label": "Notepad",
      "path": "C:\\Windows\\System32\\notepad.exe",
      "iconUrl": "https://ems-services-portal-demo.bluefletch.com/services/apiv1/files/downloadClientFile/c1074a3b-0e13-43eb-b577-fd91649b239e",
      "rightClickMenu": {
              "label": "Terminate",
              "scriptToRun": "C:\\ProgramData\\BlueFletch\\scripts\\kill_notepad.ps1"
            }

    },
    {
      "label": "Calculator",
      "path": "C:\Program Files\BlueFletch\BlueFletch Launcher\resources\shortcuts\calculator.lnk",
      "iconUrl": "https://ems-services-portal-demo.bluefletch.com/services/apiv1/files/downloadClientFile/29ac09d3-60f9-40c6-b156-a008aaccf155"
     }

Web Shortcut Object

Available fields used to describe web shortcuts displayed on the Launcher home screen. URL will open in default browser.

Field	FieldDescription
label	string The name of the application to display.
iconUrl	string Represents an icon to override the default application image. Must be a URL.
url	string A URL to navigate to

Example:

    {
      "label": "BlueFletch",
      "url": "https://bluefletch.com",
      "iconUrl": "https://ems-services-portal-demo.bluefletch.com/services/apiv1/files/downloadClientFile/e7bb137e-6046-4241-aafa-cf59c80ec767"
    }

Folder Object

Available fields used to describe folders on the Launcher home screen.

Field	FieldDescription
label	string The name of the application to display.
iconUrl	string Represents an icon to override the default application image. Must be a URL.
content	array An array of application objects. Used in grouping applications into folders.

Example:

 {
    "label" : "Tools",
    "iconUrl": "https://ems-services-portal-demo.bluefletch.com/services/apiv1/files/downloadClientFile/e7bb137e-6046-4241-aafa-cf59c80ec767"
    "contents":[
        {
          "label": "Notepad",
          "path": "C:\\Windows\\System32\\notepad.exe",
          "iconUrl": "https://ems-services-portal-demo.bluefletch.com/services/apiv1/files/downloadClientFile/c1074a3b-0e13-43eb-b577-fd91649b239e"
        },
        {
          "label": "Calculator",
          "path": "resources\\shortcuts\\calculator.lnk",
          "iconUrl": "https://ems-services-portal-demo.bluefletch.com/services/apiv1/files/downloadClientFile/29ac09d3-60f9-40c6-b156-a008aaccf155"
         },
         {
           "label": "BlueFletch",
           "url": "https://bluefletch.com",
           "iconUrl": "https://ems-services-portal-demo.bluefletch.com/services/apiv1/files/downloadClientFile/e7bb137e-6046-4241-aafa-cf59c80ec767"
         }
     ]
  }

epmConfig

Field	FieldDescription
fastLoginType	string Indicates type of fast authentication. Values are "none" user needs to input credentials, "nfc" user can use provision badge and pin to authenticate.

Example:

  "epmConfig": {
    "fastLoginType": "none"
  }

emsSupportTool

Field	FieldDescription
orgId	string Set to the company's organization ID, as displayed on the BlueFletch Portal Admin - Organization page here.
eventUrl	string Url to send event information. (Starting version 1.0.10)
systemMonitoring	object Key Value pairs that control display of processes and services monitoring. See systemMonitoring for more information. (Starting version 1.0.34)
helpInfo	object Key Value pairs that control display help information. See helpInfo for more information. (Starting version 1.0.34)
showSystemInfoOnDesktop	boolean If true machine name and IP address is shown on the desktop

Example:

  "emsSupportTool": {
    "orgId": "1234567890",
    "eventUrl": "https://ems-services-api-beta.bluefletch.com/eventsAPI/apiv1/event",
    "showSystemInfoOnDesktop":true,
    "systemMonitoring": {
      "services": [
        {
          "name": "EventLog",
          "restart": "C:\\Users\\KioskUser\\Documents\\resources\\powershell\\restart_service.ps1"
        }
      ],
      "processes": [
        {
          "name": "chrome",
          "restart": "C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe"
        }
      ],
      "servicesLabel": "POS Components"
    },
    "helpInfo": {
      "helpLabel": "Service Desk",
      "entries": [
        {
          "label": "Desk Phone",
          "value": "555-1234"
        },
        {
          "label": "Submit a Ticket",
          "url": "https://support.example.com/submit"
        }
      ]
    }
  }

systemMonitoring

Field	FieldDescription
services	object Key Value pairs that control display of services to be monitored. See Service/Process Object for more information.
proceses	object Key Value pairs that control display of processes to be monitored. See Service/Process Object for more information.
servicesLabel	string Title for system monitoring section.

Example:

  "systemMonitoring": {
      "services": [
        {
          "name": "EventLog",
          "restart": "C:\\Users\\KioskUser\\Documents\\resources\\powershell\\restart_service.ps1"
        },
        ....
      ],
      "processes": [
        {
          "name": "chrome",
          "restart": "C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe"
        },
        ...
      ],
      "servicesLabel": "POS Components"
    }, 

Service/Process Object

Field	FieldDescription
name	string Name of the service/process
restart	string executable or file path of service/process

helpInfo

Field	FieldDescription
helpLabel	string Title for help info section
entries	object Key Value pairs that control display of help info. See Help Info Entry Object for more information.

Example:

  "helpInfo": {
      "helpLabel": "Service Desk",
      "entries": [
        {
          "label": "Desk Phone",
          "value": "555-1234"
        },
        {
          "label": "Submit a Ticket",
          "url": "https://support.example.com/submit"
        }
      ]
    } 

Help Info Entry Object

Field	FieldDescription
label	string label for contact info
value	string value for contact info (like phone number, name, address, etc)
url	string url for for help contact (url to submit ticket)

Settings

Field	FieldDescription
useSecondaryAuth	string Indicates type of secondary auth during re-authorization. Values are "none", "pin", "nfc".
secondaryAuthPinLength	integer Set the number of digits required for pin. Maximum value is 12. Default is 6.
pinEnforceConsecutiveRule	boolean If true will not allow more than 3 consecutive similar digits. Default is set to true. (e.g. 1111 will not be allowed, but 1112 is allowed). Available from Auth 3.6.x and above.
pinEnforceSequentialRule	boolean If true will not allow more than 3 sequential digits up or down (e.g. 1234 is not allowed but 1235 is allowed). Default is set to true. Available from Auth 3.6.x and above.
pinEnforceBlackList	string Comma-delimited list of PIN codes that cannot be used by the user (e.g. if 1112 is specified, even if it passes the consecutive rule, it will be disallowed by blacklist). Available from Auth 3.6.x and above.
pinAutoSubmit	boolean If set to false, will require the user to tap on the Enter key after entering their PIN. If set to true, the PIN will be submitted after last entry (based on secondaryAuthPinLength). Default is false.
maxRetryCount	integer Set the number of retries for reauth (available starting v1.0.12) default to 3.
authBrowser	string Indicates the browser to open for authentication. Values are "Edge", "Chrome" (available starting v1.0.23) default to Edge.
inactiveTimeInSeconds	integer Set the maximum number of seconds of user innactivity before locking or logging off user. Default to 0, meaning there is no timout (available starting version 1.0.34).
autoStartScripts	array An array of strings of scripts file path to be auto started post Login (available starting v1.0.47).
adminMode	object Key Value pairs that control display of local admin mode (available starting v1.0.64). See adminMode for more information
defaultUser	object Key Value pairs that control display of Default user (walk-up/kiosk idle) mode. When enabled, the launcher skips the login screen and boots straight to the desktop as this synthetic user, showing the layout named by layoutName. A real user can still sign in from the default desktop (Sign In button, or badge tap when fastLoginType is nfc); logging out returns to the default desktop. The default session never times out and is not reported to the EMS events API. (available starting v1.0.67). See defaultUser for more information

adminMode

Field	FieldDescription
layoutName	string Specifies the layout to expose for admin mode.
processMonitoringName	string Specifies process name to monitor and triger Admin mode exit when ended.
adminPassword	string Field that contains the SHA256 hash of the local admin password (available starting v1.0.48). Defaults to the built-in local admin password.

defaultUser

Field	FieldDescription
enabled	boolean Turns default-user mode on or off.
name	string Display name (and user id) for the default user.
layoutName	string Key in the top-level layouts object to show on the default desktop.
enableLoginButton	boolean Whether the Sign In button is shown on the default-user desktop taskbar (fastLoginType none). Badge-tap sign-in (nfc) is unaffected.

auth_oauth2

OAuth2 configuration will support login through Chrome browser.

Field	FieldDescription
client_id	string The configured client ID for this application.
redirect_url	string The configured redirect callback URL for this application.
baseUrl	string Base URL for the identity provider.
authorize_url	string The full URL for the authorize endpoint for the identity provider.
token_url	string The full URL for the token endpoint for the identity provider.
userinfo_url	string The full URL of the userInfo endpoint for the identity provider.
scopes	string The OpenID scope values required for the identity provider.
claim_userId	string The claim in the access token that contains the user ID of the logged-in user.
claim_username	string The claim in the access token that contains the display name of the logged-in user.
claim_groups	string The claim in the access token that contains the logged-in user's membership groups.

Example:

"auth_oauth2": {
    "client_id": "0oams66ss2iN85i001d7",
    "redirect_url": "http://localhost:3003/bfeWindowsCallback",
    "baseUrl": "https://bluefletch.oktapreview.com",
    "authorize_url": "https://bluefletch.oktapreview.com/oauth2/v1/authorize",
    "token_url": "https://bluefletch.oktapreview.com/oauth2/v1/token",
    "userinfo_url": "https://bluefletch.oktapreview.com/oauth2/v1/userinfo",
    "logout_url": null,
    "logout_redirect": null,
    "scopes": "openid email profile groups",
    "claim_userId": "upn",
    "claim_username": "name",
    "claim_groups": "groups"
  }

auth_azure

Azure configuration will support login through Chrome browser.

Field	FieldDescription
client_id	string The configured client ID for this application.
client_secret	string The configured client secret for this application.
redirect_url	string The configured redirect callback URL for this application.
baseUrl	string Base URL for the identity provider.
authorize_url	string The full URL for the authorize endpoint for the identity provider.
token_url	string The full URL for the token endpoint for the identity provider.
userinfo_url	string The full URL of the userInfo endpoint for the identity provider.
scopes	string The OpenID scope values required for the identity provider.
resource	string Specifies the host to access for a token during login when the IdP does not provide it through userinfo_url. Used in Azure AD authentication (e.g "https://graph.microsoft.com").

Example:

"auth_azure": {
  "client_id": "1234567890",
  "client_secret": "11111111~111111",
  "redirect_url": "http://localhost:3003/bfeWindowsCallback",
  "baseUrl": "https://login.microsoftonline.com/ef9d14d2-4d7e-4945-b082-15926b1ac472",
  "authorize_url": "https://login.microsoftonline.com/ef9d14d2-4d7e-4945-b082-15926b1ac472/oauth2/authorize",
  "token_url": "https://login.microsoftonline.com/ef9d14d2-4d7e-4945-b082-15926b1ac472/oauth2/token",
  "userinfo_url": "https://login.microsoftonline.com/ef9d14d2-4d7e-4945-b082-15926b1ac472/openid/userinfo",
  "scopes": "openid",
  "resource": "https://graph.microsoft.com"
}

Assets

Settings that specify assets that the BlueFletch Launcher should download and use for UI display processing. To reference the asset, use the format of 'assets:name'.

Field	FieldDescription
key	string Asset name.
value	string URL to use to download the asset.

Example:

Shows that two images are being downloaded, and can be referenced as 'imageName' and 'anotherImage'.

  "assets": {
        "logo": "https://somewhere.com/image.png",
        "background": "https://somewhere.com/image2.png"
  }

Theme

Windows BlueFletch Launcher offers robust theming capabilities that allow you to customize its appearance to align with your company's branding guidelines. You can upload your own logo, wallpaper, and color scheme via the Launcher configuration.

Field	FieldDescription
enable	boolean Theme support can be enabled or disabled within the Launcher configuration. If theme is set to true, theme support will be available.
logo	string URL to use to download the asset.
accentColor	string Sets up a company-specific logo for the Launcher UI, add the image from the assets folder
wallpaperImage	string Sets up wallpaper for the Launcher UI, add the image from the assets folder
darkTheme	boolean If darkTheme is set to true, the device changes all app icon element text colors to black. Otherwhite, its set to white.

Example:

Shows how assets can be referenced to set wallpaper and logo images.

  "theme": {
    "enable": true,
    "logo": "assets:logo",
    "accentColor": "#D93832",
    "wallpaperImage": "assets:background",
    "darkTheme": false
  }