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.

Credentials

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 cmxEmailUserName.properties file, located in the home directory of the local user account that runs the tool. For example, if the Connected email address is jsmith@apexCorp.com, the file name is jsmith.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, 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 Connected 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.

Status and error information

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.

    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 is output-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. 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 into cmx-import-users-tool-#.log every 250 MB, to a maximum of 12 files. You can adjust the default rollover policies through the log4j2.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

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.