unistrant 0.1a4

A unified client for the SAMS Accounting and Metrics System

Contents

• Installation

• Configuration

  • Settings

• Usage

  • Preparing the data directory

  • Registering records

Installation

Create a Python virtual environment, then use pip to install the program in the virtual environment.

python -m venv --upgrade-deps /opt/unistrant
/opt/unistrant/bin/python -m pip install unistrant

A launcher script is created by the installation. To see the command line options run the launcher with the –help command line option.

/opt/unistrant/bin/unistrant --help

Use pip to install updates as new versions are released. Use –upgrade-strategy=eager to also install updates to dependencies.

/opt/unistrant/bin/python -m pip install --upgrade --upgrade-strategy=eager unistrant

Configuration

The program can be configured in order using

• environment variables

• command line options

• the settings file.

If the program has been configured using a settings file, either the command line options or environment variables can be used to override the settings.

The settings file is found in order from

• the path in the environment variable UNISTRANT_SETTINGS

• the path provided by the command line option –settings

• $HOME/.config/sams/unistrant/unistrant.toml

• /etc/sams/unistrant/unistrant.toml.

Only a single settings file can be used. When a settings file is found, no other settings file will be used. The settings file is optional and does not need to be present.

The settings file uses TOML. Most settings are defined in the top-level table using string values. The following is an example of how to set the data directory setting.

data_directory = "/data/sams"

Some settings are grouped into sub-tables. When a setting belongs to a sub-table, the name of the setting is referred to using dotted keys. For example, the certificate and key for authenticating to SAMS belongs to the sams sub-table.

sams.certificate = "/etc/sams-certificate.pem"
sams.key = "/etc/sams-key.pem"

A common alternative is to use a header. The following example is equivalent to using dotted keys.

[sams]
certificate = "/etc/sams-certificate.pem"
key = "/etc/sams-key.pem"

Settings

archive_directory_name

Name of the subdirectory within the data directory where processed files are saved.

Command line:

–archive-directory-name

Environment:

UNISTRANT_ARCHIVE_DIRECTORY_NAME

Default:

archive

data_directory

Path to the data directory.

Command line:

–data-directory

Environment:

UNISTRANT_DATA_DIRECTORY

log_level

Level of messages that will be logged. When defined, this setting will override the general log level defined in the logging setting.

Valid values are CRITICAL, ERROR, WARNING, INFO, and DEBUG in increasing verbosity.

Command line:

–log-level

Environment:

UNISTRANT_LOG_LEVEL

logging

Configuration of the Python logging framework. See the Python configuration dictionary schema for details.

This setting can only be configured using a settings file due to the complexity of the configuration dictionary schema. The default behavior when this setting is not provided is to log to the console.

records_directory_name

Name of the subdirectory within the data directory where unprocessed files are found.

Command line:

–records-directory-name

Environment:

UNISTRANT_RECORDS_DIRECTORY_NAME

Default:

records

sams.certificate

Path to client certificate for authenticating to SAMS.

Command line:

–sams-certificate

Environment:

UNISTRANT_SAMS_CERTIFICATE

sams.key

Path to client certificate key for authenticating to SAMS.

Command line:

–sams-key

Environment:

UNISTRANT_SAMS_KEY

sams.url

Base URL to SAMS.

Command line:

–sams-url

Environment:

UNISTRANT_SAMS_URL

Default:

https://accounting.naiss.se:6143/sgas

Usage

The general form of the command line when launching the program is as follows.

unistrant [global options...] command [command options...]

Most of the global options represent settings, see Settings.

The command is an action that the program can perform. The command can have command-specific options.

Preparing the data directory

The data directory should contain two subdirectories. The subdirectories should be named “archive” and “records,” unless the program has been configured otherwise. The program requires access to read and write to both subdirectories. The subdirectories are expected to exist, and the program will not attempt to create them if they do not.

Registering records

Use the register command to register records with SAMS. The program will look for new records to register in the records directory and send them to SAMS.

When running the register command, the program will

• read the records files

• group records into batches of the same type

• create a new XML document for each batch of records

• send all new XML documents to SAMS

• move the records files to the archive directory.

The records directory can contain record files with records of different types. Each record file can contain either a single record, or multiple records grouped together by a containing XML element of the grouping type corresponding to the record type. A single record file cannot contain different types of records. Records will be sent in batches independent of the number of records stored in each record file.

It is possible that only some of the records are successfully registered; in that case the unsuccessfully registered records are saved to the records directory for later processing. Unsuccessfully registered records are saved in files named with the prefix error.