General Resource Loader - GRLoader

Contents
casm1401
Contents
GRLoader Considerations
Review the following considerations before you use GRLoader:
  • GRLoader Release 12.9 is compatible with earlier releases of CA CMDB, but early releases of GRLoader are incompatible with CA CMDB Release 12.9. For example, a site has an existing CA CMDB r11.2 installation and later installs CA CMDB Release 12.9, so the site has two installations. GRLoader Release 12.9 works with both installed systems, but GRLoader r11.2 only works with the r11.2 installation. You can use the - s parameter to specify which one of the multiple installations for GRLoader to use.
  • We recommend that you migrate all your MDR scripts to use the latest version of GRLoader. If you want to insert new CIs, migration requires altering existing scripts to specify -n.
    If you do not specify -n or -a, GRLoader does not insert or update CIs and relationships.
  • You can specify GRLoader options in a configuration file.
  • Whenever you update a CI with the -a option, Last Change Date and user displayed in the Configuration Item List are updated even if no attributes were changed. This update occurs whether a CI was edited in the user interface (and saved without changes) or updated by using GRLoader.
  • If GRLoader generates a warning, the error log records the CI information, an error, or a skip. For example, when GRLoader loads CIs, but -a is not specified to allow updates, the information appears in the error log with an appropriate message.
  • When you run GRLoader from a batch file, specify the 
    -ad attr=value
     as 
    -ad attr{value}
     to get past the Windows command parser which may remove the equal "=" symbols.
  • Do 
    not
     use curly brackets "{ }" as work area delimiter characters when you want GRLoader to insert CIs into the CMDB. TWA delimiters work properly when inserting CIs from general notes, CSV and Excel files, and JDBC/ODBC databases.
  • GRLoader does not support smart quotes. Use double quote characters, or any other single character delimiter instead.
  • GRLoader does not let you create NULL or empty relationships between CIs. The CA SDM web interface lets you create these relationships, but GRLoader displays the 
    ERROR:Relationship type is required
     message in the generated error XML file.
  • GRLoader does not let you create duplicate relationships between the same two CIs. Instead, GRLoader tries to update the existing relationship between the same two CIs that have the same relationship type.
    For example, the CMDB contains a relationship such as 
    ci_1 manages ci_2
    . When you try to insert the same relationship through GRLoader, the utility tries to update the existing relationship, instead of creating a new relationship. The CA SDM web interface lets you create a duplicate relationship between the same two CIs, or update the existing relationship.
  • You cannot use the 
    SELECT *
     syntax on UNIX systems.
Use Database Queries to Verify Correct Data
We recommend that you use database queries before executing GRLoader. These queries help you debug imports to SQL Server. For example, you want to specify Server as the class in your SQL statement.
Follow these steps:
  1. Create a configuration file named sqlServer.cfg with the following code:
    grloader.jdbc.driver=com.microsoft.sqlserver.jdbc.SQLServerDriver grloader.jdbc.url=jdbc:sqlserver://sqlserverhostname:1433;databaseName=mdb; grloader.jdbc.user=userid grloader.jdbc.password=password
  2. Save the file.
  3. Execute the following query in SQL Server:
    select ca_owned_resource.resource_name as name, ca_resource_class.name as class from ca_owned_resource, ca_resource_class where ca_owned_resource.resource_class = ca_resource_class.id
    The query executes successfully because you specified the correct class name.
  4. Open GRLoader.
  5. Execute the following command:
    GRLoader -cfg sqlserverdb.cfg -u userid -p password -E -s http://sdmhostname:8080 -E -dbstmt "select ca_owned_resource.resource_name as name, ca_resource_class.name as class from ca_owned_resource, ca_resource_class where ca_owned_resource.resource_class = ca_resource_class.id" -a -e "c:\errorjdbc1.xml"
    The data is imported.
The GRLoader Command
The General Resource Loader (GRLoader) imports CI information into CA SDM. GRLoader uses XML documents as input, which lets you import data that originates in different data sources. Run GRLoader from a command prompt or by using a .bat or .cmd file. The CA SDM installation adds the GRLoader to the path during installation, so it runs from any directory.
Results from an import show counts for all processed CIs and Relationships, including the amount of Read, Skipped, Inserts, Updates, Errors, and Warnings. GRLoader logs all processing details and errors in the 
nx_root
/log/grloader.log file, where 
nx_root
 specifies the CA SDM installation directory.
Syntax
C:\WINDOWS>GRLoader -?
The GRLoader command uses the following parameters:
  • -u 
    userid
    (Required) Specifies the user ID that runs the GRLoader process.
  • -p 
    password
    (Required) Specifies the password for the user ID. If you run GRLoader without the -p parameter, the utility prompts the console for the password.
  • -s http[s]://
    cmdb_servername
    :
    port
    (Required) Specifies the server URL including the port number that runs the web services. For running GRLoader on the primary server or application server in a default installation, you can use the following command:
    -s http://localhost:8080
    If you specify the optional -C parameter, GRLoader ignores the -s parameter.
  • -i 
    input_file
    (Required) Specifies a full path name or a relative path name. If the filename contains a .xls or .xlsx suffix, GRLoader considers the file as a spreadsheet, otherwise it considers it as an XML file.
  • -n
    (Optional) Allows new CI insertion into the CMDB. Without -n, CIs write to the XML error file (see the -e parameter). Relationships are only added if either -n or -a is specified. If neither is specified, no updates are performed. Updating CIs also require the -a parameter.
  • -a
    (Optional) Allows updates to configuration items (by default, updates are not allowed if the CI exists in the CMDB). The -n flag also is required to add new CIs.
  • -D
    (Optional) Specifies a name prefix for relations (defaults to "GRLoader"). Use the prefix for the sym field in new relationships. The sym file must be unique, so a datetime field and a number is appended to this prefix to make it unique. 
    Default Prefix:
     GRLoader.
  • -e
     XML_err_file
    (Optional) Produces an XML error file when GRLoader detects errors or warnings. By default, the error file name uses the name of the input file, appended with _err.xml. For example, using the input file as abc.xml creates the error file as abc_err.xml. Use the -e parameter to override this default name.
  • -E
    (Optional) Lets you overwrite the XML error file. By default, the error file is not overwritten.
  • -I
    (Optional) Ignores case. When you use this parameter, GRLoader is not case-sensitive when comparing the input value of a lookup field with the actual value stored in the database. By default, lookups are case-sensitive.
  • -ua
    Always updates the CMDB.
  • -lftwa [-chg 
    nnnn
    (Optional) Loads TWA transactions into the CMDB. If used with -chg, the load selects only those transactions associated with change order 
    nnnn
    .
    The Change Order string is not validated when loaded into the CMDB.
  • -lftwai [-chg 
    nnnn
    ]
    (Optional) Runs TWA transactions to update the CMDB. Transactions that run successfully are set to Inactive so that they do not appear in lists. If you use -chg, the load selects only those transactions associated with change order 
    nnnn
    .
  • -lttwa 
    (Optional) Loads XML into the transaction work area (TWA) instead of directly into the CMDB. After data has been loaded into the TWA, it can be edited, changed and verified. After the data modification process completes, individual transactions can load into the CMDB (see - lftwa).
  • -lttwar
    (Optional) Loads XML into the initial state in the transaction work area (TWA) instead of directly into the CMDB. Transaction data in the TWA can be edited, changed, and verified (see -simci and -simrel). After the data modification process completes, individual transactions can load into the CMDB (see - lftwai).
  • -nospinner (-spinner)
    (Optional) Turns off the spinner that displays CI and relationship progress. Use -spinner to enable the progress display.
  • -P
    (Optional) Specifies preload data to improve performance for large processing. For large input files, supplying the - P parameter preloads a few tables into memory so that they can be processed more quickly. For smaller inputs (< 50 entries), preload is not necessary.
  • -rs
    (Optional) Replaces symbolic values that CA SDM includes in the XML input file. If you enable this parameter, corresponding values replace the following symbolic values:
    • *now* -- Replaced by a unique date/time string appended with a sequence number to help ensure uniqueness.
    • *userid* -- Indicates the userid specified in the -u parameter.
    • *inputfile* -- Indicates the filename specified in the -I parameter.
    • *relationcount* -- Specifies the number of relationships processed so far in this GRLoader run.
    • *lastciuuid* -- Specifies the UUID of the most recently processed CI.
    • *cicount* -- Specifies the number of CIs processed so far in this GRLoader run.
Examples: Use the -rs Parameter
With -rs enabled, the following example creates 100 CIs named ci1, ci2, …, ci100
<GRLoader> <ci><name>ci*cicount*</name><class>Server</class></ci> [...repeated 100 times...] </GRLoader>
With -rs enabled, the following example updates the CI description with information about the most recent update.
<GRLoader> <ci> <name>server1</name> <description>updated by *userid* on *now* using input file *inputfile*</description> </ci> </GRLoader>
  • -simci
    (Optional) Simulates CI operations to predetermine whether a set of transactions creates CIs, and therefore possible ambiguities for other CIs.
  • -simrel
    (Optional) Simulates relationship operations to predetermine whether a relationship transaction creates a relationship or updates a relationship.
  • -T 
    trace_level
    (Optional) Specifies the tracing level. Known tracing levels are 0 (off, the default), 1 (low), 5 (medium) and 10 (verbose). We recommend only using this setting when necessary because much output can result.
  • -tf 
    filename
    (Optional) Runs GRLoader using translation rules. 
    filename
     specifies the name of the file that contains the translation rule set.
  • -slump
    (Optional) Specifies the slump.jar file. This parameter can provide better performance than web services. 
    Important:
     -slump only can be used with the -s parameter to target the following server:
    • Conventional: Primary server
    • Advanced Availability: Application server.
    If another CA product is installed, for example, CA Coheshion ACM or CMDB service pack is installed, verify that the slump.jar file is identical to the one that is installed on the target CA SDM system.
  • -C
    (Optional) Validates the XML input file without any additional processing. This argument only validates the XML tags, not field values.
  • -h (or -?)
    (Optional) Displays online help.
  • -v
    (Optional) Displays the GRLoader product version and build date.
  • -maxerror 
    number
    (Optional) Specifies the maximum number of errors that can occur before remaining CIs or relationships are skipped.
  • -maxwarn 
    number
    (Optional) Specifies the maximum number of warnings that can occur before remaining CIs or relationships are skipped.
  • -chg 
    nnnn
    Used with - lftwa and -lftwar. Loads only those transactions associated with change order 
    nnnn
    .
    The Change Order string is not validated when loaded into the CMDB.
  • -cfg 
    myconfigfile
    .cfg
    (Optional) Specifies the name of the input configuration file.
  • -dt t
    enant
    (Optional) Specifies the tenant assignment for the CI/relationship. You must enable multi-tenancy to use this parameter. You can use PUBLIC to indicate that the object is public. If the tenant access of the user does not authorize creating public objects, the object is created using the default tenant.
  • -sc classname
    Lists the attributes of CIs in the class you specify.
  • -scx classname
    Lists the attributes of CIs in the class you specify in XML format. The XML is stored in a file named classname.xml. Any special characters are removed from the class name.
Example: Load CI and Relationship Data
The following example loads the CI and relationship data contained in the filehardware_servers.xml (in the current directory) into the CMDB that resides on the server located on the local computer on port 8080.
grloader -u CMDBAdmin -p password -s http://localhost:8080 -i hardware_servers.xml -n