This documentation applies to the 8.1 version of Remedy Action Request System, which is in "End of Version Support."

To view the latest version, select the version from the Product version menu.

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] [-t  multiMatchOption] [-v] [-i]
[-D  duplicateIDOption] [-q  option] [-c  option] [-h  option]
[-charset  name] [-M  fullyQualifiedMappingFileName]

Note

[-m mappingFileName ] [-d directoryWithMappingFile ] Enclose arguments that contain blank spaces or symbols in double quotation marks.



The following table describes available options.

Option Description
-u

User name — Required login parameter that identifies the user account.

Note

Every cross-platform CLI command opens a sep arate 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

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

One of the following paths:

  • Path to a directory of data files — For multithreaded environments, the -o option specifies the path to the directory that contains the data files to import.
  • Path to data file — For single-threaded environments, the -o option specifies the file that contains the data files to import.

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.

Note

Make sure that your hardware configuration can handle the number of threads that you enter.

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.

-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:

  • 0 (the default) — Logs appear on the console.
  • 1 — Logs do not appear on the console.  They appear in the log file specified with the -l option.  If the -l option is not used, the logs will not be created.
-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.)
-b

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

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
-t Multiple match option — 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.

  • 0 — Do not suppress default values for mapped fields, but ignore non-mapped fields.
  • 1 — Suppress default values for mapped fields, but ignore non-mapped fields.
  • 2 — Suppress default values for mapped fields, suppress default values for non-mapped fields by explicitly putting NULL value.
  • 3 — Do not suppress default values for mapped fields, suppress default values for non-mapped fields by explicitly putting NULL value.

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:

  • 0 — Generate new ID for all records.
  • 1 — Reject duplicate records.
  • 2 — Generate new IDs for duplicate records.
  • 3 — Replace old records with new records.
  • 4 — Update old records with new records' data (the default).
  • 5 — Reject duplicate records silently.

Note

The Reject duplicate records silently mode (parameter value 5) is available in the BMC Remedy Data Import command-line utility only.

-q Suppresses the required field property for non-core fields. The options are 1 (on) and 0 (off) .
-c 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:

  • 0: OFF
  • 1: ERROR
  • 2: WARN
  • 3: INFO
  • 4: DEBUG
  • 5: TRACE
  • 6: ALL

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.)

Note

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.

Option Description
-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.

This version of the documentation is no longer supported. However, the documentation is available for your convenience. You will not be able to leave comments.

Comments

  1. Foued Ben hadj ali

    Hi,

    Is there a way to pass Xms and Xmx parameters to Dataimport when using it in a command line ?

    Thanks

    Mar 30, 2016 05:27
    1. Poonam Morti

      I will verify this with the SME and get back to you.

      Thanks,

      Poonam

      Mar 30, 2016 05:59
    1. Poonam Morti

      Hi,

      This can be done by modifying the DataImport batch file located in the <AR Install Dir>\dataimporttool directory.

      java -Xms64m -Xmx512m com.bmc.arsys.apiext.data.DataImport %*

      If you are running the dataimport application then for setting the Xmx and Xms parameters, you need to modify the dataimporttool.ini file.

      -vm
      <C:\Program Files\Java\jre1.8.0_66\bin\javaw.exe>
      -startup
      plugins/org.eclipse.equinox.launcher_1.3.100.v20150511-1540.jar
      --launcher.library
      plugins/org.eclipse.equinox.launcher.win32.win32.x86_64_1.1.300.v20150602-1417
      -vmargs
      -Xms64m
      -Xmx1024m

      Thanks,

      Poonam

      Apr 06, 2016 01:58
  2. Foued Ben hadj ali

    Hi,

    ok thanks

    Apr 06, 2016 02:37
  3. Nagendra Prasad

    Hi, 

    Is there a way to capture the results of this utility, on to a field ? 

    For example - 

    Number of Records Successfully imported = $Field1$

    Number of Records Failed = $Field2$

     

    Apr 21, 2016 02:39
    1. Poonam Morti

      Hi,

      I will check this with the SME and get back to you soon.

      Thanks,

      Poonam

      Apr 21, 2016 03:14
    1. Poonam Morti

      Hi,

      I have verified this with the SME, we cannot set the results of import command line utility in a field.

      Thanks,

      Poonam

      May 16, 2016 04:53
  4. Deepak Mishra

    What command gets fire when you start import?

    Aug 30, 2017 02:04
    1. Anagha Deshpande

      Hello Deepak,

      I will check this with the SME and will write back to you.

      Regards,

      Anagha 

      Aug 30, 2017 09:58
      1. Anagha Deshpande

        Hello Deepak,

        Could you please elaborate on what exact information you are looking for? For example, what happens on server side when you run the Data- Import command line utility to import data?

        Please respond.

        Regards,

        Anagha

        Sep 11, 2017 10:30