Scan2Deploy Android Schema

The Scan2Deploy JSON schema is used by Scan2Deploy Android and Scan2Deploy Studio. The latest "stable" version of the schema is available here. You can also access version v1-0-0 of the schema at schemastore.org.

note

The documentation on this page is current as of schema v1-11-0.

Creating Scan2Deploy files

Scan2Deploy JSON files can be created either by Scan2Deploy Studio or manually using a text editor. It's highly recommended to use Scan2Deploy Studio.

Scan2Deploy Studio

Refer to the Scan2Deploy Studio documentation for a detailed description of how to use the tool.

Using a text editor

Scan2Deploy JSON files can be created using any text editor (notepad.exe can be used for example). A JSON schema is available to help ensure valid file content. There are several advantages to using an editor that supports this schema:

  • Provides help text for each field
  • Provides real-time compiler-like messages letting you know when you have made a mistake
  • Allows you to write files faster and with fewer mistakes

$schema

A JSON schema file is used to define the structure and features available in Scan2Deploy. The $schema tag is used to indicate which version of the schema you are using. You can versions of schema along with complete field documentation at the Scan2Deploy Android schema repo.

🔗 Schema Reference

The latest schema can be referenced like this:

{
"$schema": "https://raw.githubusercontent.com/datalogic/scan2deploy-android-schema/master/schema.json"
}

You can also point to a specific version of the schema by pointing to the desired tag. For example:

{
"$schema": "https://raw.githubusercontent.com/datalogic/scan2deploy-android-schema/v1-1-0/schema.json"
}

Choosing an editor

There are several good JSON editors available. We recommend Visual Studio Code. It is free and has many features designed to make writing JSON files easier, including utilizing JSON schemas.

By including the aforementioned $schema tag in you JSON file, Visual Studio Code will provide automatic tool tips and error underlining:

Some other editors know to use the schema files on schemastore.org when a given file uses a specific file extension that is registered on schemastore.org: file-name.dla.json

Generating barcodes

Scan2Deploy barcodes can be generated both by Scan2Deploy Studio and dl_config.exe. It's highly recommended to use Scan2Deploy Studio.

Example JSON files

These examples could be useful if you are making manual edits to your profile.json file.

Detailed

{
"$schema": "http://json.schemastore.org/datalogic-scan2deploy-android",
"layout": {
"description": "This is for our Android devices",
"enroll": true
},
"padlock": {
"valid-until": "20991231235959",
"key": "ihavenomouthandimustscream",
"state": "locked",
"hide-from-launcher": false
},
"global": {
"target-path": "/mnt/sdcard/airwatch",
"install-path": "/mnt/sdcard/airwatch",
"update-path": "/mnt/sdcard/airwatch",
"purge-target-path": true,
"auto-scan": true,
"script": "setup.s",
"action": "close",
"backup-to-enterprise": true,
"script": [
"[Post-Install]",
"DISABLE_APP com.android.chrome"
]
},
"settings": {
"date-time": "Thu, 19 Apr 2018 07:51:37 GMT",
"auto-time": false,
"auto-time-zone": false,
"auto-time-server": "pool.ntp.org",
"debug-bridge": false,
"lock-screen": false,
"status-bar": false,
"navigation-bar": true,
"charge-threshold": 0,
"usb-profile": "NONE",
"usb-function": "CHARGING"
},
"network": {
"essid": "TESTTKIP",
"hidden": false,
"mode": "wpa-psk",
"mode-key": "datalogic",
"mode-key-encrypted": false,
"ephemeral": false,
"wait-for-connection": true
},
"deployment": {
"scheme": "http",
"host": "172.19.0.77",
"port": 8080,
"path": "/airwatch.zip",
"ping-timeout": 1000,
"fetch-timeout": 60000,
"working-archive": "/mnt/sdcard/target.zip",
"skip-inflation": true
},
"blobs": [
{
"file": "/mnt/sdcard/airwatch/credentials.bin",
"content": "fd09B1iL/k4jRWrjrP0/sO44teY +B3UafBLsMsCEqd1KOv6b6JYBXLVv70FmHdZhIVoEOQvHu7O4PUJStpZQ+4PYjPqCO+NQr81M7GOF421Ke8L2u4EYyqDE5qXfLy2shEgaRwRpr2f35/38WZkh6edyiWZQJjyLeZcuI7WiaJPpw7Jcw7ye7mb7Rl+ePNFmfvUrpeRFtN+5kUsx/SbB1v0gDyOOuoep"
}
]
}

Each section is optional in nature. Sections padlock, settings, network, deployment, and blobs are skipped when missing. Also, for the settings section, the configuration parameters are optional and when not provided the current setting is kept.

Update Datalogic Tools

The following example will update the Datalogic tools on the device to the following versions:

  • DXU Agent 1.20.168
  • SoftSpot 1.8.92
{
"$schema": "http://json.schemastore.org/datalogic-scan2deploy-android",
"global": {
"auto-scan": true,
"target-path": "/sdcard/Download/"
},
"deployment": {
"scheme": "https",
"host": "github.com",
"port": 443,
"path": "/datalogic/sandbox/raw/master/demo.zip"
}
}

Schema Versioning

The schema follows the conventions of SchemaVer, provided here for convenience:

SchemaVer is defined as follows: MODEL-REVISION-ADDITION

  • MODEL when you make a breaking schema change which will prevent interaction with any historical data
  • REVISION when you introduce a schema change which may prevent interaction with some historical data
  • ADDITION when you make a schema change that is compatible with all historical data

The schema.json file doesn't contain any indication of it's version on it's own. Instead, we use GitHub releases to version the schema.

important

This documentation describes the latest schema, which may be found here.

Schema documentation

Each section is optional in nature. Sections padlock, settings, network, deployment, and blobs are skipped when missing. Also, for the settings section, the configuration parameters are optional and when not provided the current setting is kept.

Layout

The layout section is used to format the output file. The available parameters are the following

  • description: (optional) Free-form description field (350 max characters). Description will be displayed in header of output file. The default description is none.
  • enroll: (optional) Boolean flag instructing DL-Config to generate Scan2Deploy Device Owner Enrollment QR code in output file. The default value is false.

Padlock

The padlock section is used to configure the staging locking feature. The available parameters are:

  • valid-until: (optional) Specifies the expiration date of the barcode sequence. In order for this to properly work the device date should be synchronized or at least configured. The default value is 20991231235959, that is a non-expiring barcode sequence.
  • key: (optional) Defines the padlock key to be used. If the values doesn't match the device one the barcode is rejected. The default value is the empty string (meaning, no key).
  • state: (optional) Configures the padlock state. Can be either locked indicating that the provided key is possibly set, or unlocked in the case device padlock need to be disabled.
  • hide-from-launcher: (optional) Boolean value that enables the Scan2Deploy to be disabled for good once the staging is complete. Please note that once disabled the application can't be re-enabled unless a factory-reset is performed. The default value is false.

Global

  • action: (optional) Specifies the final action performed by the application at the very end of the staging process. This can be none, close, enterprise-reset, factory-reset, reset, or an intent:/android-app:// URI. The default value is none.
  • backup-to-enterprise: (optional) Boolean flag that activates the enterprise backup persistence for the staging data. That means that both the staging script and archive are copied in the enterprise partition. Upon enterprise reset, the application will re-stage the device with such information. The default value is false.
  • target-path: (optional) This is the base destination folder where any archive/fill will be inflated/written. The default value is "/sdcard/Download/scan2deploy".
  • install-path: (optional) Folder where the application expects auto-installed/auto-updated APKs are to be found. The default value is "/sdcard/Download".
  • update-path: (optional) Folder where the application expects auto-updated OTA packages are to be found. The default value is "/sdcard/Download".
  • purge-target-path: (optional) Boolean value that drives the application behavior with regards to the target path, that is whether a pre-existing target need to be purged (i.e. deleted) prior inflation of the deployment archive. The default value is true in order to ensure a clean deployment.
  • auto-scan: (optional) Boolean value that enables/disables the auto-installation and auto-update of APKs and OTA packages. The default value is false.
  • downgrade-preinstalled: (optional) Boolean value used to force the downgrade even of (system) pre-installed application, if required. The default value is false.
  • oemconfig: (optional) Boolean value that determines whether to broadcast an intent with OEMConfig settings. Default (Android) value is false.
  • script: (optional) Can be either a string specifying the absolute/relative path of a file, or a JSON array of strings describing the file content line-by-line. The script file will be interpreted and run at the very end of the staging process, after any setting/network/deployment has been completed. The default value is the empty string (i.e. ""), disabling the script interpretation. The language structure is a simple one-statement-per-line sequence, executed in order. The supported commands are documented below.

Settings

The settings sections can be used to controls some inner device settings, that typically need to be changed from the default (Android) setting. The available parameters are the following

  • date-time: (optional) String representation, in RFC-1123 format, of the date to be set. The default value is null, which leave the current device date untouched.
  • auto-time: (optional) Boolean value controlling the Date & Time automatic date-time adjustment setting. The default (Android) value is true.
  • auto-time-zone: (optional) Boolean value controlling the Date & Time automatic time-zone adjustment setting. The default (Android) value is true.
  • auto-time-server: (optional) Address of the NTP server to be used for date-time synchronization. Please note that the timezone won't possibly be synched due to lack of a GPS unit in the device. If the server is set a device reboot is suggested for the new setting to be spread system-wide. The default value is null, which leave the default NTP is used (i.e. asia.pool.ntp.org).
  • debug-bridge: (optional) Boolean value controlling the state of Android Debug Bridge. The default (Android) value is false.
  • lock-screen: (optional) Boolean value controlling the state of Android's lock-screen, requiring the user to swipe the display to unlock the device. The default (Android) value is true.
  • status-bar: (optional) Boolean value controlling the (top) display status-bar. By hiding the status-bar notifications will disappear, too. The default (Android) value is true.
  • navigation-bar: (optional) Boolean value controlling the (bottom) display navigation-bar. The default (Android) value is true.
  • charge-threshold: (optional) Integer value in the range 0 to 100 indicating the charge threshold a battery exhausted device need to reach to automatically boot when recharging. The default value is 5.
  • usb-profile: (optional) USB communication profile in use. Available values are NONE, BOTH, DATA, and CHARGE. The default (Android) value is BOTH. Note: this feature is only available on the Memor 1 device.
  • time-zone: (optional) Set the device's time zone. 591 possible valid time zones. The default (Android) value is Europe\Sarajevo.

default-home - Added in schema v1-6-0

  • package-name: (required if action is custom-app) String value. Package name of the home app.
  • action: (optional) Enumeration value indicating the home app type. Available values are custom-app and aosp-launcher-app.

Network

The network section defines a Wi-Fi network to be configured on the device. The available parameters are the following:

  • essid: (required) The wireless network ESSID. The default value is "".
  • hidden: (optional) Boolean value indicating whether the wireless network is using a hidden ESSID. The default value is false.
  • mode: (required) The wireless connection mode. Supported values are open, wep-40, wep-104, wpa-psk, wpa2-psk, wpa-eap, wpa2-eap, owe, wpa3-sae, and wpa3-eap-192. There is no default value.
  • mode-key: (optional) The wireless network key, if needed. The default value is the empty string (i.e. "").
  • mode-key-encrypted: (optional) Boolean value reporting if the mode-key is written in plain-text or encrypted (with a custom encryption algorithm). The default value is false.
  • eap-method: (optional) Configures the EAP authentication method. Supported values are none, peap, tls, ttls, pwd, sim, aka, and aka-prime. The default value is none.
  • eap-phase2: (optional) Configures the EAP phase 2 authentication method. Supported values are none, pap, mschap, mschapv2, and gtc.The default value is none.
  • eap-identity: (optional) Indicates the EAP identity. The default value is the empty string (i.e. "").
  • eap-anonymous-identity: (optional) Indicates the EAP anonymous identity, used as the unencrypted identity with certain EAP types. The default value is the empty string (i.e. "").
  • eap-password: (optional) Sets the EAP password, if needed. The default value is the empty string (i.e. "").
  • eap-password-encrypted: (optional) Boolean value reporting if the eap-password is written in plain-text or encrypted (with a custom encryption algorithm). The default value is false.
  • eap-certificate: (optional) Base64 representation of the EAP certificate to use. The default value is the empty string (i.e. "").
  • proxy-host: (optional) Server name or IP address of the proxy to be user for HTTP/HTTPS communications. The default value is the empty string (i.e. "").
  • proxy-port: (optional) Server IP port of the proxy for HTTP/HTTPS communications. The default value is 0.
  • purge: (optional) Boolean value telling if any currently configured wireless network is to be removed. This can be useful in order to avoid profile roaming. The default value is true.
  • reconfigure: (optional) When the purge parameter is set to false the wireless network the application is going to set-up could already be existing. This boolean parameter controls the application behavior, that will re-configure any existing and matching network (true) or skip it and leave it untouched (false).
  • sleep-policy: (optional) Wireless sleep policy, as for Android's Settings.Global parameter. Available values are 0 (WIFI_SLEEP_POLICY_DEFAULT), 1 (WIFI_SLEEP_POLICY_NEVER_WHILE_PLUGGED), and 2 (WIFI_SLEEP_POLICY_NEVER). The default value is 2 (i.e. WIFI_SLEEP_POLICY_NEVER).
  • save-to-file: (optional) Absolute path of the file where the current network configuration will be saved. The default value is the empty string (""), indicating that the network configuration will not be serialized to file.
  • ephemeral: (optional) If set to true the wireless connection profile will be solely used during the staging process, and deleted once complete. When false the profile will still be present after the staging process. The default value is false.
  • wait-for-connection: (optional) Tells whether a valid Wi-Fi connection has to be waited once the network configuration is complete. Can be useful when the device need to be configured but a valid Wi-Fi connection is not ready, yet. The default value is true.

Additional Networks

Added in schema v1-11-0

The additional-networks section is a JSON array of objects and each object in the array defines a Wi-Fi network to be configured on the device that is not required for staging. The default value is [ ]. The available parameters of each object are as following:

  • essid: (required) The wireless network ESSID. The default value is "".
  • hidden: (optional) Boolean value indicating whether the wireless network is using a hidden ESSID. The default value is false.
  • mode: (required) The wireless connection mode. Supported values are open, wep-40, wep-104, wpa-psk, wpa2-psk, wpa-eap, wpa2-eap, owe, wpa3-sae, and wpa3-eap-192. There is no default value.
  • mode-key: (optional) The wireless network key, if needed. The default value is the empty string (i.e. "").
  • eap-method: (optional) Configures the EAP authentication method. Supported values are none, peap, tls, ttls, pwd, sim, aka, and aka-prime. The default value is none.
  • eap-phase2: (optional) Configures the EAP phase 2 authentication method. Supported values are none, pap, mschap, mschapv2, and gtc.The default value is none.
  • eap-identity: (optional) Indicates the EAP identity. The default value is the empty string (i.e. "").
  • eap-anonymous-identity: (optional) Indicates the EAP anonymous identity, used as the unencrypted identity with certain EAP types. The default value is the empty string (i.e. "").
  • eap-password: (optional) Sets the EAP password, if needed. The default value is the empty string (i.e. "").
  • eap-certificate: (optional) Base64 representation of the EAP certificate to use. The default value is the empty string (i.e. "").
  • proxy-host: (optional) Server name or IP address of the proxy to be user for HTTP/HTTPS communications. The default value is the empty string (i.e. "").
  • proxy-port: (optional) Server IP port of the proxy for HTTP/HTTPS communications. The default value is 0.
  • reconfigure: (optional) When the purge parameter is set to false the wireless network the application is going to set-up could already be existing. This boolean parameter controls the application behavior, that will re-configure any existing and matching network (true) or skip it and leave it untouched (false).

Deployment

The deployment section can be used to download a ZIP archive from a server and inflate it to the target-path folder. The available parameters are the following

  • scheme: (optional) The deployment download scheme to use. Can be one of http, https or ftp. The default value is http.
  • host: (optional) The host-name or internet-protocol address of the server from which the resource is to be fetched. Default value is empty string "".
  • port: (optional) TCP/IP port to be used to contact the server. The default value is 80.
  • path: (optional) Path to the server resource to download, complete with query-string if needed. The default value is the empty string ("").
  • check-timeout: (optional) The timeout value (in milliseconds) used when attempting to reach the host server. The default value is 3000.
  • fetch-timeout: (optional) The timeout value (in milliseconds) used when fetching resource from host. The default value is 60000.
  • skip-inflation: (optional) Boolean value instructing the application not to inflate the deployment archive once downloaded. This can be useful to speed the OTA update process up. The default value is false.
  • working-archive: (optional) String value storing a local path to a Scan2Deploy archive (.tar file). The default value is /sdcard/Download/scan2deploy.archive. For example, if usb-drive is used for storage-type and bar.tar is located on a USB drive in a folder foo, then working-archive should be set to /foo/bar.tar.
  • alternate-hosts: (optional) Alternate host-names or internet-protocol addresses of the server from which the resource is to be fetched. Default value is [].
  • ftp-username: (optional) Used when ftp is used for scheme. The username for the FTP server connecting to. The default value is the empty string ("").
  • ftp-password: (optional) Used when ftp is used for scheme. The password for the FTP server connecting to. The default value is the empty string ("").
  • storage-type: (optional) Type of device storage used for local deployment. Supported values are none, internal-storage, removable-sdcard, and usb-drive. The default value of none indicates that the archive should be downloaded from the location specified in the host field. For any of the other values (internal-storage, removable-sdcard, and usb-drive), use the working-archive field to specify the path to the archive on the given device.

Blobs

The blobs (optional) section is a JSON-array of objects. Each object must contain the following two attributes

  • file, the path of the file to be created, and
  • content, the base64 representation of the actual file content.

The file attribute can be either absolute or relative (in this latter case, relative to the global/target-path parameter value). During the files de-serialization any required (parent) path is automatically created.

In order to generate the base64 representation of a give binary file any suitable tool can be used (e.g. base64 command-line program, or online services such as HexEd.it or CyberChef).

Update Scan2Deploy

The update-scan2deploy section contains just one field:

  • update-version, the desired version to self-update scan2deploy to. The default (Android) value is false.

Scripting

Description of commands supported by the script key in the Global section.

  • Command names appear in all-caps. Example: BROADCAST
  • <> Angle brackets indicate required fields
  • [] Square brackets indicate optional fields

BATTERY_OPTIMIZATION

Added in schema v1-11-0

BATTERY_OPTIMIZATION <action> <package>

Enables or disables battery optimization for the given package.

  • action - Required parameter. Allowed values:

    • ENABLE - enable battery optimization for the given package. i.e. the app's background processing capability will be diminished for the sake of improved battery life.
    • DISABLE - the given package will not be limited by the battery optimization feature in any way. Could result in decreased battery life.
  • package - Package name of the app for which battery optimization should be adjusted.

BROADCAST

BROADCAST <arguments>

Broadcasts the intent with the specified intent arguments. Supported extra arguments:

  • -e | -es - Add string data as a key-value pair
  • -ef - Add float data as a key-value pair
  • -ei - Add integer data as a key-value pair
  • -el - Add long data as a key-value pair
  • -ez - Add boolean data as a key-value pair

COPY

COPY <source-file-path> <target-file-path> <overwrite>

Copies a file located on-device from one location to another. If the target-file-path does not exist, it will be automatically created for you, even multiple folders deep if necessary.

  • source-file-path - the full path to the source file to be copied, starting with /.

  • target-file-path - the full path to the destination location where the file should be copied to. Should include the destination file name as well.

  • overwrite - true or false. if set to true, the copy should overwrite an existing file. if set to false, the copy should not overwrite an existing file.

DELETE

DELETE <path> [pattern] [include]

Recursively deletes files/folders starting from path, only if the name matches the pattern regular-expression. If folder path is empty at the end of the process it will be deleted, as well.

  • pattern - Optional regular expression to match. Often, this would just be the name of the file to be deleted. Default value: "^.+$" (i.e. delete all files with names one or more characters long).

  • include - Optional value. If include is true, the matching entries will be deleted. If include is false, the non-matching entries will be deleted. Default value: true.

DISABLE_APP

DISABLE_APP <package-name>

Disables the app with the specified package-name. There is no longer any way an user could launch the app.

ENABLE_APP

ENABLE_APP <package-name>

Enable the app with the specified package-name. The app becomes user-launchable.

GRANT

GRANT [-p permission] [-s grant|deny|default] <package-name>

Grants or revokes permissions on the specified package. The -p and -s parameters are optional.

  • [-p] If a permission is provided using the -p parameter, only that single permission will be affected. If no -p is specified, all the permissions declared in the manifest for the given package-name package will be affected.
  • [-s] The -s parameter can be used to specify that the permission be granted (grant), denied (deny), or user-configurable (default). In the case of grant and deny, the permission set is no longer user-configurable; if you view the permission in the Settings app on the device, you will see that it can't be modified. The default behavior is to grant permission(s).

INFLATE

INFLATE <archive-path> <target-path>

Inflates the ZIP archive found at archive-path to target-path folder.

INSTALL

INSTALL <apk-path>

Installs an application given a complete path to an installable APK.

LAUNCH

LAUNCH <package-name>

Starts the launching intent given an application package-name.

SET_SETTING

SET_SETTING <namespace> <setting> <value>

Set a system setting. namespace must be one of: GLOBAL, SECURE, or SYSTEM.

SHELL

SHELL <adb_shell_command>

Run an arbitrary adb shell command. This is an experimental feature. Not all shell commands that work at an adb shell prompt will work here. No output that may be provided in the command will be displayed.

  • adb_shell_command - the adb shell command to run. This could be any command you can run at an adb shell prompt, although the adb shell has different permission levels than Scan2Deploy, so there is no guarantee if the command will run successfully or not.

  • Android's official documentation for SHELL command can be found here.

UNINSTALL

UNINSTALL <package-name>

Uninstalls a previously installed application given its package-name.

UPDATE

UPDATE <ota-path> [none|factory|enterprise] [none|true]

Installs a firmware update from an OTA package that has already been extracted to the device. There are 2 optional parameters:

  1. Reset type to be performed after update. Valid values are none, factory, and enterprise.

  2. Determines in an update should be "forced" or not. Valid values are none and true.

WAIT

WAIT <milliseconds>

Suspend the script execution for milliseconds milliseconds.