Overview:
Currently, distributing files to Android devices requires the IBM MaaS360 Docs app, which not only needs an additional license but also must be deployed to each device, making the process more complex. To streamline file distribution, IBM MaaS360 version 9.15 introduces a new capability allowing administrators to upload files directly to a specified device path using a custom command action. Files can be pushed either through a secure HTTPS URL or, for smaller files, by embedding the Base64-encoded content within the command itself. The feature also supports deleting previously uploaded files from the device.
Steps to execute the command:
1. Log in to the MaaS360 Portal.
2. Navigate to the desired Device or Device Group.
3. Select the Android Custom Command action.
4. Enter the command details and click Run.
The Android Custom Command action interface will appear as shown in the screenshot below.
Use Cases:
1. Distribute Documents Without Extra Licensing for Docs app
Organizations can send necessary files without purchasing or deploying the Docs app, reducing cost and dependency on additional software. This allows seamless and faster adoption of file distribution across all managed devices.
2. Faster rollout of files to a group of devices
Admins can push files instantly to a targeted set of devices without user interaction. This ensures rapid access to required documents or resources in time-sensitive situations.
3. Deploy Configuration Files for Enterprise Apps
Enterprise apps can receive updated configuration data automatically, ensuring consistent settings across devices. This eliminates manual configuration efforts and reduces configuration errors.
4. Ensured file integrity & authenticity with SHA-256 verification
SHA-256 ensures files aren’t tampered with or corrupted during transit. This gives organizations confidence that only trusted and validated content reaches devices.
5. Support for URL-Based File Upload
Admins can distribute large files by providing a secure HTTPS download link. Files are fetched directly on the device, reducing upload limitations and infrastructure load.
6. Inline File Content Upload
For smaller files, the content can be entered directly in the command payload itself in Base64-encoded format. This avoids the need for hosting and enables quick updates or emergency deployments.
Syntax:
The syntax for the Upload File custom command is:
upload-file [options] <destination file name and path>
Options
The following options control how the file is uploaded to the device:
- -url <url> : Downloads and uploads a file from the specified HTTPS URL. The URL must be correctly formatted (no spaces or invalid characters) and must not require authentication. There is no upper limit for file size in url case.
- -base64 <base64> : Uploads a file directly using the provided Base64-encoded string. This method is suitable for smaller files since maximum number of characters allowed in the command text area is 2500. You can generate Base64 content using an online tool such as https://www.base64encode.org/.
- -delete : Removes a file that was previously uploaded to the device.
- -notify (Optional) : Sends a notification to the device user when a file is uploaded or deleted.
- -verify <sha-256> (Optional) : Validates the file downloaded using -url by comparing its SHA-256 hash with the provided value. The hash must be a 64-character hexadecimal string, for example: 70ba33708cbfb103f1a8e34afef333ba7dc021022b2d9aaa583aabb8058d8d67
Destination File Name and Path:
This defines where the uploaded file will be stored on the device and what it will be named.
The path can be specified in two ways:
Example: /path/to/file.ext
A path relative to one of the predefined path constants listed below.
Path constants:
These predefined path constants help ensure files are stored in valid and accessible locations on Android devices.
|
Constant
|
Android Version
|
File Type
|
Description
|
|
%directory_external%
|
(Legacy) Android 10 or below
|
Any
|
The root of the "external" storage device (typically a separate partition in the internal device storage, but on old devices may be an SD card).
|
|
%directory_alarms%
|
All
|
Audio
|
Standard directory in which to place any audio files that should be in the list of alarms that the user can select (not as regular music).
|
|
%directory_audiobooks%
|
Android 10+
|
Audio
|
Standard directory in which to place any audio files that should be in the list of audiobooks that the user can select (not as regular music).
|
|
%directory_dcim%
|
All
|
Image, Video
|
The traditional location for pictures and videos when mounting the device as a camera.
|
|
%directory_documents%
|
(Legacy) Android 10 or below
|
Any
|
Standard directory in which to place documents that have been created by the user.
|
|
%directory_downloads%
|
All
|
Any
|
Standard directory in which to place files that have been downloaded by the user.
|
|
%directory_movies%
|
All
|
Video
|
Standard directory in which to place movies that are available to the user.
|
|
%directory_music%
|
All
|
Audio
|
Standard directory in which to place any audio files that should be in the regular list of music for the user.
|
|
%directory_notifications%
|
All
|
Audio
|
Standard directory in which to place any audio files that should be in the list of notifications that the user can select (not as regular music).
|
|
%directory_pictures%
|
All
|
Image, Video
|
Standard directory in which to place pictures that are available to the user.
|
|
%directory_podcasts%
|
All
|
Audio
|
Standard directory in which to place any audio files that should be in the list of podcasts that the user can select (not as regular music).
|
|
%directory_recordings%
|
Android 12+
|
Audio
|
Standard directory in which to place any audio files that should be in the list of voice recordings recorded by voice recorder apps that the user can select (not as regular music).
|
|
%directory_ringtones%
|
All
|
Audio
|
Standard directory in which to place any audio files that should be in the list of ringtones that the user can select (not as regular music).
|
|
%directory_screenshots%
|
Android 10+
|
Image
|
Standard directory in which to place screenshots that have been taken by the user.
|
Notes:
- Legacy paths such as %directory_external% and %directory_documents%, as well as any paths not included in the supported constants, are only accessible on Android 10 or lower — unless the MaaS360 agent is granted access through custom device firmware.
- The file type must match the destination path requirements. For example, image paths should use valid extensions like: .jpg, .jpeg, .bmp, .png, .gif.
- On Android 10 or earlier, the MaaS360 agent requires Read External Storage and Write External Storage permissions to upload files. On Android Enterprise devices, these permissions are automatically allowed unless restricted by policy.
- Devices enrolled using a Work Profile (PO or WPCO) can only upload files into work-profile-specific directories. Uploading outside these folders is not permitted.
- If a file with the same name and type already exists at the specified path, it will be overwritten.
- Uploading to locations outside the supported path constants below is only allowed on Android 10 or earlier, as Android 11+ restricts direct file system access.
Command Examples:
- Upload a file from a URL to a subfolder within the Downloads directory of the current user: upload-file -url https://my.domain.com/path/somefile.ext %directory_downloads%/path/somefile.ext
- Upload a file from a URL, verify the SHA-256 hash, and notify the user: upload-file -url https://my.domain.com/path/somefile.ext -notify -verify 70ba33708cbfb103f1a8e34afef333ba7dc021022b2d9aaa583aabb8058d8d67 %directory_downloads%/path/somefile.ext
- Upload Base64-encoded file data directly to a specific path on the device: upload-file -base64 ZmlsZSBkYXRhIGdvZXMgaGVyZQphbm90aGVyIGxpbmUKeWV0IGFub3RoZXI= /some/path/somefile.ext
- Delete a previously uploaded file: upload-file -delete %directory_downloads%/path/somefile.ext
Device History:
The Device History section in the MaaS360 portal will display the status of the executed custom command action for upload file, including detailed information if the file upload fails. A sample status history is shown in the screenshot below.