☰
Navigation :

Export & Import Geography Sets

Overview

Two scripts are provided with N2ACD to manage Geography Sets from the command line:

Running either program with the --help command line option will show the program usage.

Exporting Geography Sets

Export N2ACD geography sets.

Geography sets are exported in TOML format.  The resulting TOML file is an
array of geography sets in the "geography_sets" array generated at the root of
the TOML file.

    Usage:

    ./export_geography_sets.pl [geography set name] [geography set name] [...]

    Database connection:
    --db-host       = N2ACD database host name or IP address.               Default = localhost
    --db-port       = N2ACD database port.                                  Default = 5432
    --db-name       = N2ACD database name.                                  Default = n2in
    --db-connect    = N2ACD database connection string. Alternative to
                      --db-host / --db-port / --db-name providing full
                      control over the DBI connection string. This may
                      be useful if [for example] connecting to a
                      service defined in ~/.pg_service.conf.
    --db-user       = N2ACD database user name.                             Default = n2acd_owner
    --db-password   = N2ACD database user password. If not directly
                      specified, credentials specified in ~/.pgpass will be used.
    --quiet / -q    = Be quiet - no information on stdout except for the
                      geography set(s).
    --format        = One of:   toml, pretty                                Default = pretty
                      The format to output the geography sets in.
                            pretty: Pretty printed geography set data.
                            toml:   an array of geography_sets in TOML format.
                                    Useful for importing into N2ACD via
                                    the import_geography_set.pl script.

    PostgreSQL "ILIKE" syntax can be used in the set names. To export
    all geography sets, pass '%' as the first (and only) set name.

Parameters

The following common options may be specified when executing manage_internal_users.

Option Type Default Description
--db-host String localhost IP address or FQDN of the PostgreSQL database instance to connect to.
--db-port Number 5432 Port number of the PostgreSQL database instance to connect to.
--db-name String n2in_owner Name of the PostgreSQL database that contains the N2ACD schema.
--db-connect PSQL DB Connection String Alternative option to using --db-host --db-port and --db-name. Specified as a PostgreSQL connection string. See PostgreSQL Connection Strings for more information.
--db-user String n2acd_owner The username of the user to connect to the PostgreSQL database instance with.
--db-password String The password for the user specified with --db-user to connect to the PostgreSQL database instance with.
--quiet Switch When used, will minimise output of the export script.
--format String pretty If set to pretty the output will be pretty printed for general reading. If set to toml then the output will use the TOML file format which can be read by the import_geography_set.pl script.

Usage

Each geography set is given as additional command line arguments. Each given set will be matched against the geography sets in the database using the PostgreSQL ILIKE syntax. The output for all matched geography sets will be written to STDOUT and can be redirected to a file to save.

Example:

./export_geography_sets.pl  --db-port 5433 --db-host localhost -q --format=toml 'Public %' > public_sets.toml

will write all geography sets in the targeted database which start with Public to the file public_sets.toml The content of the TOML file will be the goegraphy set data dump. E.g.:

[[geography_sets]] # Geography Set "Public New Zealand" (ID 3) for Customer "Service Provider" (ID 1)
geography_set_name = "Public New Zealand"
geography_set_id   = 3
customer_name      = "Service Provider"
customer_id        = 1
is_inheritable     = true
cache_prefixes     = true
[geography_sets.geography_entries]
[geography_sets.geography_entries."Auckland"]
"09" = "09"
[geography_sets.geography_entries."Wellington"]
"04" = "04"

Importing Geography Sets

Import N2ACD geography set(s).

Geography sets are exported in TOML format by export_geography_sets.pl
This script will import geography sets that exist in a "geography_sets"
array of the given TOML file.

The format of the TOML file on import must be:

[[geography_sets]]
geography_set_name = "My Geography Set Name"
customer_name = "My Customer"
[geography_sets.geography_entries]
"New Zealand"."Region 1"."Area 1" = "065"
"New Zealand"."Region 1"."Area 2" = "067"
"New Zealand"."Region 2" = "07"
"New Zealand"."Region 3" = "08"
...
[[geography_sets]]
...

where:

    [[geography_sets]] - defines an array in TOML named "geography_sets"

    For each geography_sets array entry:
    geography_set_name - The name to give the geography set imported.
    customer_name - The customer's name. Must exist.
    geography_entries - A hash (table) tree defining the geography set
                        by node name & prefix.

                        Note it is an error for a node of the geography set to
                        have both children (e.g. "New Zealand"."Region 1" in
                        the above example) and an associated prefix. A prefix
                        assigned to a geography set entry means that entry
                        must be a leaf node.


    The following are optional entries for each geography set:

    cache_prefixes - A boolean as to whether to cache prefixes
    is_inheritable - A boolean as to whether the geography set is inherited
                     by children of the customer owning the set.

    By default a geography set will be not inheritable, and will cache
    entries if < 10000 entries.

    NOTE that this script does not overwrite/update existing geography
         sets at this time. It will only create new geography sets.

    Usage:

    ./import_geography_sets.pl <toml file>

    Database connection:
    --db-host       = N2ACD database host name or IP address.               Default = localhost
    --db-port       = N2ACD database port.                                  Default = 5432
    --db-name       = N2ACD database name.                                  Default = n2in
    --db-connect    = N2ACD database connection string. Alternative to
                      --db-host / --db-port / --db-name providing full
                      control over the DBI connection string. This may
                      be useful if [for example] connecting to a
                      service defined in ~/.pg_service.conf.
    --db-user       = N2ACD database user name.                             Default = n2acd_owner
    --db-password   = N2ACD database user password. If not directly
                      specified, credentials specified in ~/.pgpass will be used.
    --quiet / -q    = Be quiet - minimise lines output per geography set imported

    <toml file>     = The name of the TOML formatted file of the geography set(s)

Parameters

The following common options may be specified when executing manage_internal_users.

Option Type Default Description
--db-host String localhost IP address or FQDN of the PostgreSQL database instance to connect to.
--db-port Number 5432 Port number of the PostgreSQL database instance to connect to.
--db-name String n2in_owner Name of the PostgreSQL database that contains the N2ACD schema.
--db-connect PSQL DB Connection String Alternative option to using --db-host --db-port and --db-name. Specified as a PostgreSQL connection string. See PostgreSQL Connection Strings for more information.
--db-user String n2acd_owner The username of the user to connect to the PostgreSQL database instance with.
--db-password String The password for the user specified with --db-user to connect to the PostgreSQL database instance with.
--quiet Switch When used, will minimise output of the export script.

Usage

The file of geography sets to import must be listed on the command line as the argument to the import script. The file must be formatted as a TOML file, with content as is exported by export_geography_sets.pl (with the exception that customer_id and geography_set_id fields are ignored).

Example:

./import_geography_sets.pl --db-port 5433 --db-host localhost --quiet public_sets.toml

will import all geography sets in the file public_sets.toml. Note that the script does not overwrite or update existing geography sets. In the current version of the script only new geography sets can be created.