Runtime information for the ImportUsers tool
Before using the ImportUsers tool for the first time, review the following information to familiarize yourself with how several key areas of the tool function.
By default, the tool prompts for the credentials of the user you specify on the command line. However, if you also specify the -preservelogin
option, the tool securely stores the OAuth tokens that it generates from the verified credentials so it can bypass the prompt in the future.
The tool stores OAuth tokens in a .properties
file located in the home directory of the local user account that runs the tool. Starting with version 4.6.2 of the tool, the name of the file is cmxEmailUserName.properties
. For example, if the CMX email address is jsmith@apexCorp.com
, the file name is jsmith.properties
. For versions of the tool earlier than 4.6.2, the file name is always tools.properties
.
NOTE: The .properties
file contains security credentials. To ensure that you do not compromise the security of your system, do not edit this file, share it with others, or change its permissions.
If you plan to use the tool in an automated script, you must first run it interactively with the -preservelogin
option so it stores the OAuth tokens. Subsequent runs do not prompt for credentials unless the tool cannot read the .properties
file because you have edited, moved, or deleted it, or changed its permissions. If you use the -preservelogin
option with version 4.6.2 or later of the tool, you can use more than one Bulk Importer to manage users through a single computer account. This is because the tool creates a unique cmxEmailUserName.properties
file in your home directory for each Bulk Importer.
If your environment support multiple customers, before running the tool, you must close any browser that has the CMX web application open. This ensures that instead of the credentials cached by the browser, the tool uses the ones you provide or, if using the -preservelogin
option, the ones from the .properties
files. Using cached credentials can result in unexpected results.
The tool generates several types of status information that you can use to monitor progress or troubleshoot problems:
-
System errors. Errors that prevent the tool from processing the CSV file due to system or network connectivity issues.
System errors appear in the console window but you can also redirect them to a file. For example:
importusers-version.jar -emailaddress jsmith@apexCorp.com -csvfile Users1.csv -outputdir C:\ 2> sysErrors.txt
-
Audit trail. Information about the actions the tool performs on each row of CSV data and the subsequent result or error that occurs. This information also summarizes the outcome of the rows processed.
Starting with version 4.7.0, the tool writes its audit trail to
csvFileName-MD5Checksum.txt
. You can replace csvFileName with a custom value using the tool's-prefix
option. For earlier versions of the tool, the file name isoutput-DateTimestamp.txt
. Regardless of version, the‑outputdir
option defines where the tool stores the file.Check this audit file each time you run the tool to verify that it successfully processed all CSV data. If any rows failed due to a data or format error, place corrections to those rows in a new CSV file, and then run the tool again.
-
Diagnostic information (ImportUsers tool 4.6.2 or later). Information for monitoring the tool's progress and activity. Types of information include messages to identify the current batch of users being processes or the action of refreshing an authorization token.
The tool logs diagnostic information to
cmx-import-users-tool.log
, located in the folder where it runs. To preserve diagnostics in manageable files, the tool rolls the log file intocmx-import-users-tool-#.log
every 250 MB, to a maximum of 12 files. You can adjust the default rollover policies through thelog4j2.xml
file provided with the tool.
For information about how to troubleshoot errors, see Troubleshoot ImportUsers tool errors.
User limit warning
The tool displays a message for each user added over the company's user limit. This message is only a warning; the tool adds the user regardless of the limit.
Retry logic (ImportUsers tool 4.7.0 and later)
The ImportUsers tool includes logic that enables it to reprocess a CSV file and act on only the entries that previously failed or were not processed due to network issues or heavy system load.
To invoke this retry logic, rerun the tool without changing the CSV file (so it has the same MD5 checksum) and specify the same output location (-outputDir
option) for its audit file. Keeping the CSV file unchanged quickens the retry process by ensuring the tool retries only rows that failed or were not processed due to timeout or server error.