ExportData CLI reference

The following sections provide detailed information about how to use the ExportData tool's command-line interface (CLI).

To run the tool by its CLI, use one of the following commands in the ExportDataTool folder that you previously extracted:

  • No proxy server required for Internet access:

    java -jar ExportData.jar commandOptions

  • HTTP-based proxy server required for Internet access:

    java -Dhttp.proxyHost="proxyHost" [-Dhttp.proxyPort=proxyPort] -jar ExportData.jar commandOptions

  • HTTPS-based proxy server required for secure Internet access:

    java -Dhttps.proxyHost="proxyHost" [-Dhttps.proxyPort=proxyPort] -jar ExportData.jar commandOptions

Where:

  • -Dhttp.proxyHost="proxyHost" and -Dhttps.proxyHost="proxyHost" specify the host name of the proxy server that you use to access the Internet. For example, "proxy1.mycompany.com".

  • -Dhttp.proxyPort="proxyPort" and -Dhttps.proxyPort="proxyPort" specify the port number on which the proxy server listens for connections. If the server listens on its default port (80 for HTTP and 443 for HTTPS), you do not need to specify the port argument.

  • commandOptions represents one of the sets of option combinations listed in Command-line options. To specify an option by its full name, preface the name with two dashes (--), to specify its short name, use one dash (-). For example, --help or -h.

The ExportData CLI supports the following usage patterns:

• java -jar ExportData.jar  [-cl] [-cn] [-cr] [-d <destination>] [-e
<emailaddress>] [-ex <export>] [-fe <fileextension> | -fn
<filename> | -fp <folderpathsfilter> | -rp <regexpathfilter>]
[-h] [-list] [-p] [-re]  [-rq <request>] [-url <url>] [-users
<users>]
• ExportData.jar --cancel --request request
• ExportData.jar --clearall
• ExportData.jar --list
• ExportData.jar --resume --emailaddress email --request request --url url [--preservelogin]
• ExportData.jar --help

Each usage pattern consists of a combination of primary and secondary options.

Primary options

Primary options define the main set of the ExportData tool's CLI functions. Most primary options require secondary options to specify the object on which the tool acts. The following table describes the set of primary options.

Option name

Short name Required
secondary options		 Description
cancel cn request

Cancels a request and deletes its information from the tool's history. You can cancel any request that has not completed successfully.

Files that the tool exported before you cancel the request remain available in the destination
clearall cl None

Removes all successfully completed requests from the tool's internal history but retains each request's exported files in the destination.

If you no longer need the exported files associated with completed requests, you must manually delete them. For more information, see the example Clear all successfully completed requests.
create cr

emailaddress
request
url
destination
(export or users)

Optional:

(fileextension or
filename)

Creates a request to export data based on the criteria that you specify by the CLI's secondary options.

For a detailed description of these options, see Secondary options.

help

h None Displays detailed information about the tool's CLI usage.
list list None
Lists all requests from the tool's internal history and provides a detailed status of each one.

For each request, the tool identifies:

  • User. Connected user whose data the tool exports. The tool reports a separate status for each user in a request.
  • Data Exported. Amount of the user’s data exported out of the total amount to export.
  • Files Exported. Number of the user’s files exported out of the total number to export.
  • Progress. Percent of the user's export that is complete, based on the amounts listed in the Data Exported field.

  • Status. Current status of the export process, identified by one of the following values:

    • ACTIVE. The tool was processing the request before it stopped without finishing.

      For example, you stopped the tool either by pressing Ctrl+C or by closing the command window or the computer shut down either inadvertently or on your command.

    • COMPLETE. The tool finished processing the request and exported all files successfully.

    • COMPLETED WITH FAILURES. The tool finished processing the request but did not export all files successfully. To retry exporting the files that failed, resume the request.

    • ERROR. The tool stopped processing the request because of an error.
    • PEND. The request is ready for processing. It starts as soon as the tool assigns it to an available thread.
    • PREP. The tool is creating the request's manifest of files to export.
preservelogin p None

Flag that indicates whether the tool saves the OAuth token that it generates from your credentials in order to bypass the credential prompt in the subsequent run.

By default, the tool does not save the token so it prompts for credentials each time it runs. For more information about how this option works, see how the CLI uses credentials.
resume re

emailaddress
request
url

Resume a request that completed with failures or that did not finish and was not canceled.

If you resume a request that completed with failures, the tool tries to export only files that previously failed. If you resume a request that did not finish, the tool continues processing the request at the point where it left off. For example, suppose a request contains two users. The first user's export completed with failures and you stopped the tool while it was processing the second user. When you resume the request, the tool exports only the failed files for the first user and continues the second user's export at the point it left off.

Secondary options

Secondary options provide the information necessary for the ExportData tool to process the action of its primary option. The following table describes the set of secondary options.

Option name and required value Short name Description

destination path

d
Location, up to 80 characters in length, in which to store the exported files.

Destination guidelines:

  • Specify either an absolute or relative path, such as C:/temp/exports or /exports, respectively.

  • Specify a relatively short path.

    The tool prefixes a combination of the destination, user, and device to the original path of files that it exports. To minimize the chance that the resulting path length exceeds the limit of the destination's operating system, specify a short path. If the derived path exceeds the limit, the tool truncates the path.

  • Ensure the path exists and the destination has enough space available to store the exported data.
  • Ensure that your local computer account has write access to the path.

For a detailed explanation of the folder structure that the tool uses to store exported files, see Location of exported data.
emailaddress email e

Email address of the Connected Bulk Exporter user that runs the tool.
export devicesFile ex
File, in CSV format, containing the set of user devices from which to export data. You can export any number of devices per user for up to 10 users.

File guidelines:

  • Specify devicesFile as either an absolute or relative full path to the file.

  • List each user's devices on a single line in the following format:

    userEmail, deviceID

    For example, the following rows define the export of two devices for one user and one device for another:

    bstewart@xyz123.com, 571508667310579071
bstewart@xyz123.com, 571508685718695936
mjefferson@xyz123.com, 571508667141531098

    TIP: The best way to find device IDs is to use the output of the User Devices report. This report, available to Connected administrators, provides a mapping between device names and device IDs. For more information, see the Connected Help Center.

NOTE: This option lets you export a subset of a user's devices. To export all of them, specify the users option, instead.
folderpathsfilter folderpathsfilter fp
Folder path with text or wild card characters, up to 255 characters in length.

Folder path guidelines:

  • Use this option along with file name and file extension options to narrow down the exported data from the devices.

  • Always separate the folder names with a slash (either forward (/) or backward (\) depending on the Operating System).

  • Maximum of 20 folder paths can be mentioned and the maximum length of one folder path should not be greater than 255 characters.

    Examples,

    -fp “C:\Users\folder1,C:\Users\folder2,C:\Users\folder5,C:\Users\Folder7"

    -fp C:\Users\folder1,C:\Users\folder2,C:\Users\folder5,C:\Users\Folder7

    NOTE: Make sure that there is no space before or after the comma (,) when you separate multiple folder paths.

  • ? and * are the only wild card characters allowed.

The following lists identify the reserved characters and names to avoid on each operating system:

macOS

  • \ (backslash)

Windows

  • < (left angle bracket)

  • > (right angle bracket)

  • " (double quote)

  • / (forward slash)

  • | (vertical bar or pipe)

NOTE: If you are using special characters to specify folder path, make sure to enclose the path within double quotes. For example, "C:\Users\jane\Do*" and "C:\Documents\*.pdf".
regexpathfilter regexpathfilter rp

Regular expression, up to 255 characters in length. You must mention both the path and the file name along with the extension in the regular expression.

NOTE: If you are using special characters to specify regular expression, make sure to enclose the path within double quotes. For example, "([a-zA-Z0-9])*(.txt)".
fileextention fileExt fe
Type of files to export, based on file extension.

File extension guidelines:

  • To export multiple types of files, specify extensions as a comma-separated list.
  • Do not precede extensions with a dot (.). For example, specify txt not .txt.
  • To match files without an extension, specify a dot (.). For example, . matches report or myReport.

  • Maximum length of all the file extensions should not be greater than 512 characters.

  • Maximum length of individual file extension should not be greater than 255 characters.

The following lists identify the reserved characters and names to avoid on each operating system:

macOS

  • : (colon)

  • / (forward slash)

  • { }(curly brackets)

  • [ ] (square brackets)

Windows

  • < > (angle brackets)

  • : (colon)

  • " (double quotes)

  • / (forward slash)

  • \ (backslash)

  • | (vertical bar or pipe)

  • ? (question mark)

  • * (asterisk or star)

  • { }(curly brackets)

  • [ ] (square brackets)

The fileextention and filename options are mutually exclusive.
filename fileName fn
Name of the file to export.

File name guidelines:

  • Include the file's extension but not its path. For example, specify report.txt not C:\tmp\report.txt.
  • To export multiple files based on name, specify the names as a comma-separated list.

  • To match a single character in an item's name, enter a question mark (?).

    For example:

    • report-?? matches Report-AB but not report-A

      To match a file name, include the file's extension. For example, report-??.txt matches report-AB.txt and report-?? does not.

    • do? matches dot or doc but not docx

  • To match zero or more characters in a name, enter an asterisk (*).

    For example:

    • report* matches Report and Report1; *report matches MyReport

    • doc* matches doc and docx

  • Do not include the following characters in the name: left brace ({), right brace (}), left bracket ([), right bracket (]), and colon (:)

  • Maximum length of all the file names should not be greater than 512 characters.

  • Maximum length of individual file name should not be greater than 255 characters.

The following lists identify the reserved characters and names to avoid on each operating system:

macOS

  • : (colon)

  • / (forward slash)

  • { }(curly brackets)

  • [ ] (square brackets)

Windows

  • < > (angle brackets)

  • : (colon)

  • / (forward slash)

  • \ (backslash)

  • | (vertical bar or pipe)

  • { }(curly brackets)

  • [ ] (square brackets)

The filename and fileextention options are mutually exclusive.
request request rq
Unique case-insensitive name, up to 64 characters in length, to associate with this particular run of the tool. The name must be valid for the operating system of the destination.

The tool creates a folder with the specified request name in which to store exported files. Therefore, specify a name that meets the requirements of folder names on the destination's operating system. The following lists identify the reserved characters and names to avoid on each operating system.

macOS

  • Reserved characters:

    • /  (forward slash)

  • Reserved names:

    No reserved names

Windows

  • Reserved characters:

    • *  (asterisk)
    • \  (backslash)
    • :  (colon)
    • "  (double quote)
    • /  (forward slash)
    • >  (right angle bracket)
    • <  (left angle bracket)
    • ?  (question mark)
    • |  (vertical bar or pipe)
    • any control character

  • Reserved names:

    • AUX
    • CON
    • COM[1-9]
    • LPT[1-9]
    • NUL
    • PRN
    • listed names that include a file extension, such as AUX.TXT
    • any name that contains a trailing space or period (.)

If you specify a name that exists in the tool's internal history, an error occurs. If you specify a name previously used but no longer in the history and the same existing destination as that request, the newly exported files will intermix in the same folders as the older files and overwrite any having the same name.
url url url

URL to the server that hosts your Connected environment.

Specify url as one of the following:

  • https://cmx-us.connected.com
  • https://cmx-uk.connected.com
  • https://cmx-eu.connected.com
  • https://cmx-sg.connected.com
  • https://cmx-ca.connected.com

If you are not sure which one to use, you can determine it from the URL that you use to access the Connected web application.
users users users

Comma-separated list of Connected email address for up to 10 users whose data you want to export.

NOTE: This option exports all devices for each user. To export only a subset of them, use the export option, instead.

NOTE: To ensure that the ExportData tool correctly reads each value that you specify, follow these rules:

  • Separate multiple values for the same option with a comma (,).
  • Use quotation marks (") to enclose data that contains a line-break, quotation mark ("), comma (,), or space.
  • Use two sets of quotation marks in succession to represent a quotation mark in data. For example, to specify the text abc"def, use abc""def.
  • Optionally, enclose any field in quotation marks. For example. "John".

Here are a few examples of using the ExportData tool's command-line interface. All examples assume that the tool uses the proxy server's default port and, unless noted, preserve the authorization token for the specified user so the next time the tool will not prompt for credentials.

  • Export all files from all devices for three users.

    The following command exports all files for three specific users to the existing exports folder in the root drive of the local computer.

    • Windows:

      java -Dhttps.proxyHost="proxy1.xyz123.com" -jar ExportData.jar --create --emailaddress jdoe@xyz123.com --request AllData --url https://cmx-us.connected.com --destination C:\exports --users msmith@xyz123.com,bjones@xyz123.com,tcampa@xyz123.com --preservelogin

    • Mac:

      java -Dhttps.proxyHost="proxy1.xyz123.com" -jar ExportData.jar --create --emailaddress jdoe@xyz123.com --request AllData --url https://cmx-us.connected.com --destination "Mavericks HD/exports" --users msmith@xyz123.com,bjones@xyz123.com,tcampa@xyz123.com --preservelogin

  • Export all files from specific devices for two users.

    The following command exports all files from the specific devices of two users to the existing exports folder in the root drive of the local computer. The list of users and corresponding devices are defined in the file C:\temp\userDeviceList.csv, which contains the following data:

    bstewart@xyz123.com, 571508667310579071
bstewart@xyz123.com, 571508685718695936
mjefferson@xyz123.com, 571508667141531098

    • Windows:

      java -Dhttps.proxyHost="proxy1.xyz123.com" -jar ExportData.jar --create --emailaddress jdoe@xyz123.com --request AllData --url https://cmx-us.connected.com --destination C:\exports --export C:\temp\userDeviceList.csv --preservelogin

    • Mac:

      java -Dhttps.proxyHost="proxy1.xyz123.com" -jar ExportData.jar --create --emailaddress jdoe@xyz123.com --request AllData --url https://cmx-us.connected.com --destination "Mavericks HD/exports" --export "Mavericks HD/temp/userDeviceList.csv" --preservelogin

  • Export all files by file extension for a single user.

    The following command exports all PNG and JPG image files for a single user and stores them on a remote drive. It does not include the preservelogin option so the tool deletes the dataExport.properties file. As a result, the tool prompts for credentials the next time that it runs.

    • Windows:

      java -Dhttps.proxyHost="proxy1.xyz123.com" -jar ExportData.jar --create --emailaddress jdoe@xyz123.com --request ImageData --url https://cmx-us.connected.com --destination \\svr1.xyz123.com\exports --users bstewart@xyz123.com --fileextention png,jpg

    • Mac:

      java -Dhttps.proxyHost="proxy1.xyz123.com" -jar ExportData.jar --create --emailaddress jdoe@xyz123.com --request ImageData --url https://cmx-us.connected.com --destination //svr1.xyz123.com/exports --users bstewart@xyz123.com --fileextention png,jpg

  • Export files by name for a single user.

    The following command exports all files whose name contains "report", regardless of case or file type, and stores them on a remote drive. It does not include the preservelogin option so the tool deletes the dataExport.properties file. As a result, the tool prompts for credentials the next time that it runs.

    • Windows:

      java -Dhttps.proxyHost="proxy1.xyz123.com" -jar ExportData.jar --create --emailaddress jdoe@xyz123.com --request reportData --url https://cmx-us.connected.com --destination \\svr1.xyz123.com\exports --users mjefferson@xyz123.com --filename *report*

    • Mac:

      java -Dhttps.proxyHost="proxy1.xyz123.com" -jar ExportData.jar --create --emailaddress jdoe@xyz123.com --request reportData --url https://cmx-us.connected.com --destination /Volumes/RemoteDrive/exports --users mjefferson@xyz123.com --filename *report*

    For another example, the following command exports all files with the name "Report-2016.txt", regardless of case.

    • Windows:

      java -Dhttps.proxyHost="proxy1.xyz123.com" -jar ExportData.jar --create --emailaddress jdoe@xyz123.com --request reportData --url https://cmx-us.connected.com --destination \\svr1.xyz123.com\exports --users mjefferson@xyz123.com --filename Report-2016.txt

    • Mac:

      java -Dhttps.proxyHost="proxy1.xyz123.com" -jar ExportData.jar --create --emailaddress jdoe@xyz123.com --request reportData --url https://cmx-us.connected.com --destination /Volumes/RemoteDrive/exports --users mjefferson@xyz123.com --filename Report-2016.txt

  • List status of all requests.

    The following command lists the detailed status of all requests.

    • Windows:

      java -Dhttps.proxyHost="proxy1.xyz123.com" -jar ExportData.jar --list

    • Mac:

      java -Dhttps.proxyHost="proxy1.xyz123.com" -jar ExportData.jar --list

  • Cancel a specific request.

    The following cancels a request named cparkerAllData that is running in the current command window:

    • Open a new command window, and then enter the following:

      • Windows:

        java -Dhttps.proxyHost="proxy1.xyz123.com" -jar ExportData.jar --cancel --request cparkerAllData

      • Mac:

        java -Dhttps.proxyHost="proxy1.xyz123.com" -jar ExportData.jar --cancel --request cparkerAllData

      The tool runs commands in the foreground, which requires you to wait for them to finish before typing another command. Therefore, opening another window to cancel a request is required only to cancel a request that is running, such as in this example.

    Any files that the tool exported before being canceled remain available in the destination location.

  • Resume a request that completed with failures, stopped, or was interrupted.

    The following command resumes the request ImageData, which either completed with failures or did not finish because it stopped or was interrupted.

    • Windows:

      java -Dhttps.proxyHost="proxy1.xyz123.com" -jar ExportData.jar --resume --emailaddress jdoe@xyz123.com --request ImageData --url https://cmx-us.connected.com --preservelogin

    • Mac:

      java -Dhttps.proxyHost="proxy1.xyz123.com" -jar ExportData.jar --resume --emailaddress jdoe@xyz123.com --request ImageData --url https://cmx-us.connected.com --preservelogin

  • Clear all successfully completed requests.

    The following command removes all successfully completed requests from the tool's internal history.

    • Windows:

      java -Dhttps.proxyHost="proxy1.xyz123.com" -jar ExportData.jar --clearall

    • Mac:

      java -Dhttps.proxyHost="proxy1.xyz123.com" -jar ExportData.jar --emailaddress jdoe@xyz123.com --clearall --preservelogin

    This command does not delete the exported data associated with these requests; you must do that manually. To do so, use the following steps:

    1. Run the tool with the list option to view the status of all requests and make note of those with a status of COMPLETE.

    2. Run the tool with the clearall option to remove all completed requests from the tool's history.

    3. For each request that you noted, delete the corresponding exported files from the destination\request folder.

      For example, to delete all data exported to C:\Connected on a Windows-based computer that is associated with the request bsmithData, delete the folder C:\Connected\bsmithData. For more information about exported data, see Location of exported data.