Maintenance of the custom_data table (hwm_custom_data)

The maintenance utility for the data stored in the custom_data table allows importing of data from a comma separated data file (CSV) into the table, deleting data from the table and displaying the content of the table. Each of these functions can be applied in a separate call only for one kind of data specified by the data type identifier.

For to start the utility, change in the directory where ProcMan is installed (with cd command in the command window or by setting the work directory in a scheduler) and execute the command:

Windows:

bin\hwm_custom_data.cmd -i <instruction> -t <data_type> [-c <configuration_id>] [-f <file>]

or

bin\hwm_custom_data.cmd -c <configuration_id> [-i <instruction>] [-t <data_type>] [-f <file>]

Unix:

bin/hwm_custom_data.sh -i <instruction> -t <data_type> [-c <configuration_id>] [-f <file>]

or

bin/hwm_custom_data.sh -c <configuration_id> [-i <instruction>] [-t <data_type>] [-f <file>]

<instruction> is the instruction which shall be executed and it can be either import, or delete, or show.

<data_type> is the data type identifier of the data kind for which the instruction has to be applied.

<configuration_id> is a valid configuration identifier of the required configuration section from the configuration file etc/hwm_custom_data_config.php.

<file> is the file path to the CSV file containing the data to be imported.

For the instructions delete and show the -f parameter is not required and not used. In this case the utility can be called simply with the -i and -t parameters. The -c parameter is not required in this case as well. It makes only sense to use it, if one or both of the parameters -i and -t are omitted in the call and the instruction and/or the data type identifier are specified in a configuration section (specified in the -c call parameter) of the configuration file.

For the instruction import the -c parameter is mandatory, as the import requires parameters, which can only be specified in the configuration file. The parameters instruction, data type identifier and file can be specified either in the call parameters (-i, -t, -f) or in the configuration section (specified in the -c call parameter) of the configuration file.

Parameters specified in the call have a higher priority than those specified in the configuration file.

Let us explain the content of the configuration file etc/hwm_custom_data_config.php on an example:

<?php
$hwm_custom_data_config = array(
    'instruction' => 'import',
    'type' => '',
    'csv_file' => '',
    'csv_delimiter' => ';',
    'csv_enclosure' => '"',
    'csv_escape' => '\\',
    'csv_columns' => 'data_str_1,data_str_2,data_str_6',
    'csv_key' => 'data_str_1,data_str_2',
    'csv_ignore_first_line' => false,

    'config' => array(
        'DEFAULT' => array(
            // Using above defaults
        ),
        'SUBJECT_IMPORT' => array(
            'instruction' => 'import',
            'type' => 'SUBJECT',
            'csv_columns' => 'data_str_1,data_str_3',
            'csv_key' => 'data_str_1',
            'csv_ignore_first_line' => true,
        ),
    ),
);
?>

The parameter instruction is the instruction which shall be executed and it can be either import, or delete, or show. It corresponds to the call parameter -i.

The parameter type is the data type identifier of the data kind for which the instruction has to be applied. It corresponds to the call parameter -t.

The parameter csv_file is the file path to the CSV file containing the data to be imported. It corresponds to the call parameter -f.

The parameter csv_delimiter specifies the character used to separate partial values in the CSV file. Usually it is either the comma (,) or the semicolon (;).

The parameter csv_encolsure specifies the character used to enclose values containing special characters (e.g. new lines) in the CSV file. Usually it is the double quotation mark (").

The parameter csv_escape specifies the character used for escaping special characters in the values in the CSV file. Usually it is the backslash ().

The parameter csv_columns specifies which columns in the CSV file correspond to which columns in the custom data table. The value is a list of column descriptors separated by either the comma (,) or the semicolon (;). Only columns of the CSV file, where the column descriptor is matching a column name of the custom_data ProcMan table, are considered for the import. The following column names of the custom_data table can be used in the list of column descriptors: data_int_1, data_int_2, data_str_1, data_str_2, data_str_3, data_str_4, data_str_5 and data_str_6.

The parameter csv_key specifies which custom_table columns build the key in the rows imported from the CSV file. Imported rows overwrite records in the custom_data table having the same key like the imported row. The value of the parameter is a list of custom_data column names separated by either the comma (,) or the semicolon (;). Only table column names specified also in csv_columns are considered to be a part of the key. If this parameter is not specified or empty, all valid table column names from csv_columns are part of the key of the imported rows.

The parameter csv_ignore_first_line specifies whether the first line in the CSV file is a header line, which shall be ignored on the import (value true), or the first line is already a data line, which shall be imported (value false).

In the config section configurations has to be defined. Meaningful is to define at least one configuration. The global parameters defined outside of the config section are used for all configurations unless they are overridden in partial configurations. Each configuration has to have an id and a subsection in which the global parameters can be overridden. The ids of the configurations are being used in the –c parameter in the execution command of the utility to specify the configurations using which the utility shall be executed.