Automating Host Group Management > Bulk Load Utilities
  
Version 10.1.01
Bulk Load Utilities
The utilities contained in this section load hosts and their relationships to host groups into the Reporting Database as a batch process using a comma-delimited file. These utilities load new hosts as well as update existing hosts.
Bulk Load utilities must be run in SQLPLUS as user aptare.
1. Log in to the Portal server as the user aptare for Linux, or an administrator user for Windows.
su - aptare
2. Open a command-line window.
3. Change the directory to the stored_procedures directory.
/opt/aptare/database/stored_procedures (Linux)
\opt\oracle\database\stored_procedures (Windows)
4. Execute the command: sqlplus portal/portal
5. Run the desired command as listed in the following tables.
 
 
This section contains the following topics:
Load Host Aliases
Load Details of New Hosts or Update Existing Hosts
Load Relationships Between Hosts and Host Group
Load Host Aliases
Description
Sets up host aliases from a comma-delimited file containing a list of hosts and host aliases. See Host Name Processing - Filters and Aliases for a description of the logic used to process hosts and aliases.
Usage
execute load_package.loadHostAliasFile('<file_name>', '<log_path_name>','<log_file_name>');
Where file_name is the fully qualified path to the csv file that contains the aliases to be loaded.
Example of the file_name specification:
'/opt/aptare/database/HostAliases.csv'
Example of the command execution:
execute load_package.loadHostAliasFile('/opt/aptare/database HostAliases.csv', '/tmp','loadHostAlias.log');
Load File Specification
The specification for the comma-delimited file is as follows:
<domain>, <hostname>, <alias_hostname>
Example: Enterprise, whitney,182.16.1.101
The detailed specification for each field follows:
domain CHAR(128) NOT NULL
hostname CHAR(64) NOT NULL
alias_hostname CHAR(64)
The alias_hostname can be either a host name (up to 64 characters) or an IP address.
Data Constraints
Field values cannot contain embedded commas.
The second field, hostname, is the external name, as defined in the Portal database.
The csv file must exist and be readable.
The csv filename must be specified within single quotes.
Logic Conditions
If the host alias already exists, no updates take place.
If the host alias does not already exist in the Reporting Database, the utility adds it.
The utility applies case differences in the input file as updates to preexisting rows.
Logging
The utility logs all additions, updates, warnings and errors to the specified log file. Logging strings are typically in the format: Date -> Time -> load_package:sub_routine -> Action
sub_routine is the sub-routine that is being executed (e.g., loadHostLine).
Load Details of New Hosts or Update Existing Hosts
Description
Imports host details from a comma-delimited file containing a list of hosts and host attributes.
Usage
execute load_package.loadServerFile('<file_name>'[, '<source_name>']);
 
file_name is the fully qualified path to the csv file. Example:
/opt/aptare/database/hosts.csv
source_name is an optional, case-insensitive string, up to 100 characters, representing the source of the host details; for example, CMDB might be relevant for a change management database. This source information is retained for historical purposes, to track how the host was added to the database. If nothing or NULL is provided for this parameter, CSV Load will be inserted as the source into the reporting database.
Load File Specification
The specification for the comma-delimited file is as follows:
path_to_host_group, internal_name, external_name, description, location, IP_address, make, model, OS
 
Example:
/APTARE/Test,testhost01,testhost01,description,location,172.20.16.1,Sun,E450,Solaris 10
/APTARE/Test,testhost02,testhost02,,location,172.20.16.2,Sun,,Solaris
 
The detailed specification for each field follows:
internal_name CHAR(128) NOT NULL
external_name CHAR(128) NOT NULL
description CHAR(256)
location CHAR(64)
ip_address CHAR(40)
make CHAR(64)
model CHAR(64)
os_version CHAR(128)
Data Constraints
Field values cannot contain embedded commas.
The first field, path_to_host_group, must be the full path to an existing host group otherwise the host will not be inserted.
The csv file must exist and be readable.
The csv filename must be specified within single quotes.
Logic Conditions
If the host already exists in the specified host group, the utility updates its details.
If the host does not already exist in the Reporting Database, the utility adds the host to the specified host group.
If a host attribute field has a NULL value in the input file, the corresponding field in the database will not be updated for a pre-existing row.
The utility applies case differences in the input file as updates to preexisting rows.
Since the primary key to the record is the internal_name, the internal_name for a host cannot be updated via this utility.
If the number of parameters passed in a row exceeds 9, the utility skips the row.
Logging
The utility logs all additions, updates, warnings and errors to the file scon.log, which is located under /tmp by default on Linux systems and C:\opt\oracle\logs on Windows systems. Logging strings are typically in the following format:
Date -> Time -> Level -> load_package:sub_routine -> Action
 
Where:
Level is DBG, INFO,WARN, or ERR.
sub_routine is the sub-routine that is being executed (e.g. loadHostLine).
Action is the action that was being reported on.
 
Example:
14-MAY 21:56:08 INFO : updating host: z0001-web0600-s in /APTARE/Infrastructure
 
Load Relationships Between Hosts and Host Group
Description
Imports host-to-host-group relationships from a comma-delimited file. You can choose to audit the host movement, which records the details when a host is removed, added, or moved.
See sample output in:
Usage
execute load_package.loadGroupMemberFile('<file_name>', '<recycle_group>', <remove_old_entries>, '<audit_pathname>', '<audit_output_file>', <do_log>);
 
Where:
file_name is the fully qualified path to the csv file. For example:
/opt/aptare/database/hosts.csv
recycle_group is the full path to the group into which deleted hosts will be moved (i.e., the 'recycle bin').
remove_old_entries enables you to remove relationships in the Reporting Database that are not in the file. If set to 1 and where there are hosts with a previous relationship to a host group and where that relationship is no longer represented within the file, the utility moves those hosts to the recycle group. If set to 0, the utility does not remove those hosts.
audit_pathname is the full path to the audit file, not including the filename.
audit_output_file is the name of the audit file where the audit results will be stored.
do_log enables you to turn on the auditing function so that all host movements are logged in the audit_output_file. Enter a numeric: 0 or 1, where 0 = No, 1 = Yes.
Example command:
execute load_package.loadgroupmemberfile ('/opt/aptare/database/movehosts.csv','/Global1/Recycle',1,'/opt/aptare/database','movehosts.out',1);
 
Load File Specification
The specification for the comma-delimited file is as follows:
path_to_host_group, internal_name1, internal_name2, internal_name3, etc.
 
Where path_to_host_group is the fully qualified path to the host group into which the hosts should be added, and internal_name1 is the internal name of a host within the existing host group hierarchy.
 
Example:
/APTARE/Test, testhost01, testhost02
/APTARE/Infrastructure, testhost02, testhost03
 
Detailed specification for each field follows:
internal_name CHAR(64) NOT NULL
 
Data Constraints
The first field, path_to_host_group, must be the full path to an existing host group. If any host groups in the path_to_host_group field value do not exist, the utility creates them.
Field values cannot contain embedded commas.
The csv file must exist and be readable.
The recycle group folder must exist.
Each row must have at least one host specified, otherwise the row will not be processed.
Logic Conditions
If you list hosts after the path_to_host_group field and those hosts are located in the existing host group hierarchy, the utility adds those host groups to the specified host group.
If a host with the specified internal name does not exist in the hierarchy, the relationship will not be added. The host must already be configured in the reporting database.
If any host groups in the path_to_host_group field value do not exist, the utility creates them.
If the removeOldEntries parameter is set to 1, the utility assumes that this file will contain all the required relationships. In other words, for all the host groups that you specify in the file, only those hosts will be in that group after you run this utility. If the host group previously contained other host(s) that are now no longer listed in the file, the utility removes those host(s) from the host group and moves them to the recycle folder.
The utility does not delete host groups from the Reporting Database; it only removes members of a host group.
If a host group in the Reporting Database is not listed in the file, the utility does not take any processing action against that host group.
Host groups with many hosts can be split into multiple lines for ease of file maintenance—for example, the host group and some of the hosts appear on the first line, then the same host group and other hosts appear on subsequent lines.
Logging
The utility logs all additions, updates, warnings, and errors to the scon.log file, which is located under /tmp by default on Linux systems and C:\opt\oracle\logs on Windows systems. Logging strings are typically in the following format:
 
Date -> Time -> Level -> load_package:sub_routine -> Action
Where:
Level is DBG, INFO,WARN, or ERR.
sub_routine is the sub routine that is being executed (e.g. loadServerLine).
Action is the action that was being reported on.
 
Example:
14-MAY 19:00:06 ERR load_package:loadServerGroupMembers: Host group /APTARE/Business Views/Regional Offices/Connecticut does not exist on line 6 of the data load file
Sample Audit File (output from load_package.loadGroupMemberFile)
27-FEB 14:18:35 Start processing host group membership, filePathname: /opt/mycompany/database/movehosts.csv recycleGroup: /Global/Recycle , removeOldEntries: 1)
27-FEB 14:18:35 Adding host: Whitney (104637) to group: /Global/Corp (102572)
27-FEB 14:18:35 Adding host: K2(104638) to group: /Global/Corp (102572)
27-FEB 14:18:35 Adding host: Everest (102573) to group: /Global/Bangalore (104538)
27-FEB 14:18:35 Adding host: McKinley (104637) to group: /Global/United States/Northwest(104639)
27-FEB 14:18:35 Moving host: testhost (102573) from group: testgroup (102572) to group: /Global/Recycle (104541)
27-FEB 14:18:35 Completed processing host group membership, filePathname: /opt/mycompany/database/movehosts.csv recycleGroup: /Global/Recycle , removeOldEntries: 1)