Command-Line Interface

Usage

This project includes some command-line-interface commands, to install the required dependencies, install them with pip:

(.venv) $ pip install sapimclient[cli]

Options:

--tenant {TENANT}: Required
Tenant to connect to, for example ‘CALD-DEV’.
--username {USERNAME}: Required
Username for authentication.
--password {PASSWORD}: Required
Password for authentication.
--no-ssl: Optional
Disable SSL validation.
--logfile {PATH}: Optional
Enable logging to a file.
-v: Optional
Verbose logging.
-debug: Optional
Enable DEBUG logging.

To list all available options and commands:

(.venv) $ python -m sapimclient --help

Usage: python -m sapimclient [OPTIONS] COMMAND [ARGS]...

Command-line interface for Python SAP Incentive Management.

You may provide parameters by setting environment variables
prefixed with 'SAP_' or by passing them as options.
For example: `export SAP_TENANT=CALD-DEV` is equivalent
to passing `--tenant CALD-DEV`

Options:
-t, --tenant TEXT    Tenant to connect to, for example 'CALD-DEV'.
-u, --username TEXT  Username for authentication.
-p, --password TEXT  Password for authentication.
--no-ssl             Disable SSL validation.
-l, --logfile FILE   Enable logging to a file.
-v                   Verbose logging.
-debug               Enable DEBUG logging.
--help               Show this message and exit.

Commands:
calendars  List all calendars.
deploy     Deploy rule elements from a directory to the tenant.
export     Export Resource to a file.
periods    List all periods for a calendar.

Each command has it’s own options, to list all options, append --help to the command.

Calendars

List all calendars:

(.venv) $ python -m sapimclient \
    --tenant {TENANT} \
    --username {USERNAME} \
    --password {PASSWORD} \
    calendars

Periods

Options:

--calendar {CALENDAR} Required
The calendar name to list periods for.
--period {PERIOD} Optional
Name of the Period to search. Allows wildcard like *2024*.

List all periods for a calendar:

(.venv) $ python -m sapimclient \
    --tenant {TENANT} \
    --username {USERNAME} \
    --password {PASSWORD} \
    periods --calendar {CALENDAR}

Deploy

Deploy exported Plan Data and Global Values from a directory to the tenant.

Plan data *.xml is imported with an import pipeline job. Global Values *.txt are imported with their respective Data Type.

To correctly identify the Data Type, files have to follow a specific naming convention:

Event Type.txt

Credit Type.txt

Earning Group.txt

Earning Code.txt

Fixed Value Type.txt

Reason Code.txt

Additionally you can control the order of processing by prefixing the filenames. For example:

01 Event Type.txt

02 Credit Type.txt

03 Plan.XML

Tip

Enable logging to catch import errors. See --logfile log.txt in the below example.

Arguments:

PATH: Required
The path to the directory to be processed.

(.venv) $ python -m sapimclient \
    --tenant {TENANT} \
    --username {USERNAME} \
    --password {PASSWORD} \
    --logfile log.txt \
    deploy ./deploy

Export

Export Credits, Measurements, Incentives, Commissions, Deposits and Payments to a file in the same way you would using the respective UI workspaces.

Options:

--calendar {CALENDAR} Optional
Apply Calendar filter on the exported data.
--period {PERIOD} Optional
Apply Period filter on the exported data. Requires --calendar to be provided.
--filters {FILTER_TEXT} Optional
Apply Period filter on the exported data. Can be applied more then once.

Tip

Refer to the API Documentation to understand the filter mechanism.

Arguments:

RESOURCE Required
The resource to load into a file. One of {CREDITS|MEASUREMENTS|INCENTIVES|COMMISSIONS|DEPOSITS|PAYMENTS}
PATH Required
Path of the file to write to.

Note

Exporting a large number of records will lead to poor performance. It is strngly recommended to stay below 100.000 records.

Tip

Enable logging to catch import errors. See --logfile log.txt in the below examples.

Export credits to a file:

(.venv) $ python -m sapimclient \
    --tenant {TENANT} \
    --username {USERNAME} \
    --password {PASSWORD} \
    --logfile log.txt \
    export CREDITS credits.txt \
    --calendar {CALENDAR} \
    --period {PERIOD}

Export payments above € 100.000,-:

(.venv) $ python -m sapimclient \
    --tenant {TENANT} \
    --username {USERNAME} \
    --password {PASSWORD} \
    --logfile log.txt \
    export PAYMENTS payments.txt \
    --filter "payment ge '100000 EUR'"