icatingest

Synopsis

icatingest [standard options] [-i FILE] [-f FORMAT]

[–upload-datafiles] [–datafile-dir DATADIR] [–duplicate OPTION]

Description

This script reads an ICAT data file and creates all objects found in an ICAT server. The format of that file depends on the backend that can be selected with the --format option.

Options

The configuration options may be set in the command line or in a configuration file. Some options may also be set in the environment.

Specific Options

The following options are specific to icatingest:

-i FILE, --inputfile FILE: Set the input file name. If the value - is used, the input will be read from standard input. This is also the default.

-f FORMAT, --format FORMAT: Select the backend to use and thus the input file format. XML and YAML backends are available.

--upload-datafiles: If that flag is set, Datafile objects will not be created in the ICAT server directly, but a corresponding file will be uploaded to IDS instead.

--datafile-dir DATADIR: Directory to search for the files to be uploaded to IDS. This is only relevant if --upload-datafiles is set. The default is the current working directory.

--duplicate OPTION

Set the behavior in the case that any object read from the input already exists in the ICAT server. Valid options are:

THROW: Throw an error. This is the default.
IGNORE: Skip the object read from the input.
CHECK: Compare all attributes from the input object with the already existing object in ICAT. Throw an error of any attribute differs.
OVERWRITE: Overwrite the existing object in ICAT, e.g. update it with all attributes set to the values found in the input object.

If --upload-datafiles is set, this option will be ignored for Datafile objects which will then always raise an error if they already exist.

Standard Options

The following options needed to connect the ICAT service are common for most python-icat scripts:

-h, --help: Display a help message and exit.

-c CONFIGFILE, --configfile CONFIGFILE: Name of a configuration file.

-s SECTION, --configsection SECTION: Name of a section in the configuration file. If set, the values in this configuration section will be applied to define other options.

-w URL, --url URL: URL of the ICAT server. This should point to the web service descriptions. If the URL has no path component, a default path will be added.

--idsurl URL: URL of the IDS server. This is only relevant if --upload-datafiles is set. If the URL has no path component, a default path will be added.

--no-check-certificate: Do not verify the ICAT server’s TLS certificate. This is only relevant if the URL set with --url or --idsurl uses HTTPS. It is mostly only useful for connecting a test server that does not have a trusted certificate.

--http-proxy HTTP_PROXY: Proxy to use for http requests.

--https-proxy HTTPS_PROXY: Proxy to use for https requests.

--no-proxy NO_PROXY: Comma separated list of exclusions for proxy use.

-a AUTH, --auth AUTH: Name of the authentication plugin to use for login to the ICAT server.

-u USERNAME, --user USERNAME: The ICAT user name.

-p PASSWORD, --pass PASSWORD: The user’s password. Will prompt for the password if not set.

-P, --prompt-pass: Prompt for the password. This is mostly useful to override a password set in the configuration file.

Known Issues and Limitations

The user running this script need to have create permission for all objects in the dump file. In the generic case of restoring the entire content on an empty ICAT server, the script must be run by the ICAT root user.
A dump and restore of an ICAT will not preserve the attributes id, createId, createTime, modId, and modTime of any object. As a consequence, access rules that are based on the values of these attributes will not work after a restore.
Dealing with duplicates, see --duplicate, is only supported for single objects. If the object contains embedded related objects in one to many relationships that are to be created at once, the only allowed option to deal with duplicates is THROW.

Environment Variables

ICAT_CFG: Name of a configuration file, see --configfile.

ICAT_CFG_SECTION: Name of a section in the configuration file, see --configsection.

ICAT_SERVICE: URL of the ICAT server, see --url.

ICAT_DATA_SERVICE: URL of the IDS server, see --idsurl.

http_proxy: Proxy to use for http requests, see --http-proxy.

https_proxy: Proxy to use for https requests, see --https-proxy.

no_proxy: Exclusions for proxy use, see --no-proxy.

ICAT_AUTH: Name of the authentication plugin, see --auth.

ICAT_USER: ICAT user name, see --user.