Data Import command-line utility options
This section contains information about:
Use the following format in the command line. Items between square brackets are optional.
com.bmc.arsys.apiext.data.DataImport -u userName -p password -x serverName [-w externalAuthenticationString] [-r rpcNumber] [-a portNumber] [-custom custom_optionsFilePath] [-f destinationFormName] -o dataFilePath [-filelist listOfFiles] [-z options.xmlFilePath] [-threads numberOfThreads] [-l logFilePath] [-e duplicateField] [-b bulk size] [-g activateBulkMode] [-n suppressFilters][-s suppressassociations] [-t multiMatchOption] [-v] [-i] [-D duplicateIDOption] [-q option] [-c option] [-h option] [-charset name] [-M fullyQualifiedMappingFileName]
[-m mappingFileName ] [-d directoryWithMappingFile ] Enclose arguments that contain blank spaces or symbols in double quotation marks.
The following table describes available options.
Required login parameter that identifies the user account.
Note: Every cross-platform CLI command opens a separate Data Import session, executes the command, and logs out. Therefore, you must log in with every command. If Data Import does not find the user name, Data Import prints the usage messages and exits.
|-p||Password||Password for the user account. If the user account has no password, omit the -p option.|
|-x||Server name||The server to log in to. If you do not specify the -x option, the server name in the mapping file is used.|
|-w||Authentication string||Name of an external authentication string or Windows NT domain. This is related to the Login window's Authentication field, which is discussed in Setting up an authentication alias.|
|-r||RPC program number||Private server, for example, if a dedicated import server is available. If you do not specify the -r option, the default administrator server's RPC program number (390600) is used.|
|-a||TCP port number||Port number for the server. This value is especially important in a multiple server environment. The option also identifies a TCD specific port, if chosen.|
|-custom||Path to custom_options.xml|
Specifies the path to the custom_options.xml file, which is used to specify date and time formats, the separators to be used, and other information. You can use this option if the source data file is in CSV or ASCII format. See Using the custom_options.xml file.
Note: During installation, a sample empty custom_options.xml file is installed in the installation folders for Developer Studio and Data Import. You can change the name and store it anywhere.
|-f||Destination form name|
Importing with a mapping file
Destination form name — Name of the form to import data into. If you do not specify the -f option, the form specified in the mapping file is used.
Importing without a mapping file
Destination form name or pair. A single name indicates that the form name in the source data file matches the form name on the server. To specify a pair of names, separate the form names with an equal sign, without any spaces around the equal sign:" destinationForm" =" fileForm". The destination form is the form on the server into which data is imported. The file form is the form specified in the data file. Specifying pairs maps data from one form (specified in the data file) to a different form (identified on the server). You can specify multiple pairs by using this option multiple times, for example:
-f "Target_form_a"="File_form_b" -f "Target_form_c"="File_form_d"
If the -f option is not specified, Data Import tries to import all data sets in the source data file. For each data set, if a matching destination form is found on the server, the data is imported. If no matching form is found, the data set is ignored.
|-o||Data File Path|
If you do not specify the -o option, the data file specified in the mapping file is used.
|-z||Path to the options.xml file|
Specifies the path to the options.xml file, which contains the data import commands and the import parameters for individual files and directories for multithreaded import. The Data Import command-line utility uses the -z option to identify the location of the options.xml file. See Using the options.xml file.
Note: The -z option cannot be used in the options.xml file; if used, the Data Import command-line utility disregards this option.
|-filelist||(For multithreaded environments only) List of data files to import||The data files can be of any type (for example, ARX, CSV, XML, and ASC ). All of the data is imported into the form designated with the -f or -M option. If you do not specify the -filelist option, the command imports all the data files in the directory specified with the -o option, regardless of file type.|
|-threads||(For multithreaded environments only) Number of threads in the pool.|
If you do not specify the -threads option, the default of 50 threads is used. If the number of files in the data directory or number of files you specify in the -filelist option is less than the -threads value or the default value (50), the number of threads used is equal to the number of files in the data directory or number of files specified in -filelist option.
Note: Make sure that your hardware configuration can handle the number of threads that you enter.
|-l||Full path name of the log file||Use this option to log details of the import execution.|
If you do not specify this option, the logs will appear on the console instead of displaying an error message that a log file path was not specified.
|-ca||Specifies where log files appear||The options are:|
|-e||Duplicate field||Field ID of the field to check for duplicate data. For example, for the Short Description field, enter 8. To specify multiple values for a single schema, separate them with commas and double quotation marks (for example, "2,4,8" ). The maximum number of IDs you can specify is 6. From this release of BMC Remedy AR System, you can now specify multiple values for multiple schemas. For this, separate the schema names (and their values) by a semi-colon and the values by commas (For example, SchemaName=1,2,3; SchemaName=4,7,8 ). The maximum number of IDs you can specify is 6. Make sure that the source data file includes values for all the fields that are being used for checking duplicate data. When -e option is omitted, then Request ID field (field ID 1) is used. Additionally, if the -e option is not used for importing records, the Data Import utility uses bulk mode to import records. (See the -b option for more information about the bulk size.)|
Specifies the number of records to process in bulk simultaneously. For AR System 7.1.00 and later versions, the default size is 100.
Note: If the -e option is used, records are imported individually. If the value of the -b option is set to 0, bulk mode will not be used.
|-g||Activate Bulk Mode|
If the -e option is used, the bulk transaction mode is switched off by default. In this case, you can still activate the bulk transaction mode using the -g option.
Note: The bulk transaction mode is purposefully switched off with -e option as it gives different results than sequential import when there are duplicate records within the data file itself. To forcefully use bulk mode when the -e option is used, you can use the -g option. You can decide whether you want to use the -g option when there are duplicate records in your data files. For example, you must use the "-g 1 " value in the Java Import command line to use the bulk mode. If any value other than "-g 1 " is used, the force bulk mode is not activated.
|-n||Suppress filters||Suppresses the merge filters during merging of entries on forms.|
Setting this flag causes the server to suspend enforcement of associations on entries getting imported. Associations are still enforced on other entries affected by workflow that might be triggered by entries getting imported. The server will only honor this flag if the user of the import tool is an administrator.
|-t||Multiple match options||Use when more than one entry matches. Enter a value of 3 to affect the first match, and a value of 5 to affect all matches.|
|-v||Forces override||If the user has logged in from a different IP address, this option tells the server to use the new IP address of the Data Import client and invalidates the old IP address.|
|-i||Suppress default values||If specified, this option will ignore the default values of fields if the value in the data file is null or not supplied.|
Note: If the value of –D is set to 4 (update option), then the Data Import utility does not suppress the default values while creating new records.
|-D||Duplicate ID||Defines how to process records that contain request IDs that duplicate those already in the form. Include one of the following numbers with this option:|
Note: The Reject duplicate records silently mode (parameter value
|-q||Suppresses the field property for non-core fields.||Suppresses the required field property for non-core fields. The options are 1 (on) and 0 (off) .|
|-c||Truncates character values||Truncates character values that are longer than the field length for character fields. The options are 1 (on) and 0 (off) .|
|-h||Suppresses pattern matching for fields||If supplied, the $PATTERN$ field limit is ignored. The options are 1 (on) and 0 (off) .|
|-charset||Specifies the character set used in the data file||The character set name must be supplied as listed in the IANA Charset Registry.|
|-debug||Sets the log level||The log levels are:|
OFF does not log any information, and ALL is the maximum log level, which logs detailed log information. The default log level is 3.
To import data with a mapping file, use either -M or a combination of -m and -d to specify the mapping file to use. (You cannot use both the combination of -m and -d with -M ; they are mutually exclusive.)
The combination of -m and -d options is supported for the legacy .arm mapping file types only. If the mapping file is .armx, only -M is valid.
The following table describes the mapping file options. For more information, see Importing with a mapping file.
|-M||Fully qualified path name of the mapping file to use.|
|-m||Name of the mapping file to use. You can verify the required name by opening the mapping file and using the string contained in the first line of the file.|
|-d||Directory that contains the mapping file being referenced with the -m option.|