Rename-sapimclient (#44)

* rename

Name change to SAP Incentive Management

* rename CommissionsClient to Tenant

.devcontainer/Dockerfile

@@ -1,4 +1,4 @@
-FROM mcr.microsoft.com/devcontainers/python:1-3.12
+FROM mcr.microsoft.com/devcontainers/python:1-3.11
 
 # Uninstall pre-installed formatting and linting tools
 # They would conflict with our pinned versions

.devcontainer/devcontainer.json

@@ -41,6 +41,6 @@
       ]
     }
   },
-  "postCreateCommand": "git config --global --add safe.directory /workspaces/python-sapcommissions && pre-commit install --install-hooks",
+  "postCreateCommand": "git config --global --add safe.directory /workspaces/sapimclient && pre-commit install --install-hooks",
   "postStartCommand": "pip install -e .[dev]"
 }

.github/ISSUE_TEMPLATE/config.yml

@@ -2,10 +2,10 @@ blank_issues_enabled: false
 contact_links:
   - name: SAP for Me
     url: https://me.sap.com/home
-    about: Visit SAP for Me for support with your SAP Commissions product.
+    about: Visit SAP for Me for support with your SAP Incentive Management product.
   - name: SAP Community
     url: https://answers.sap.com/tags/73555000100800001602
-    about: Visit the SAP Community to find or ask a question about your SAP Commissions product.
+    about: Visit the SAP Community to find or ask a question about your SAP Incentive Management product.
   - name: SAP Influence
     url: https://influence.sap.com/sap/ino/#/campaign/2460
-    about: Visit SAP Influence to submit an Improvement Request for the SAP Commissions product.
+    about: Visit SAP Influence to submit an Improvement Request for the SAP Incentive Management product.

.github/ISSUE_TEMPLATE/issue_template.yml

@@ -1,5 +1,5 @@
 name: Issue Form
-description: Report an issue with python-sapcommissions
+description: Report an issue with sapimclient
 title: "[Issue]: "
 labels: ["Issue"]
 body:

.github/workflows/publish.yml

@@ -42,7 +42,7 @@ jobs:
 
     environment:
       name: testpypi
-      url: https://test.pypi.org/p/python-sapcommissions
+      url: https://test.pypi.org/p/sapimclient
 
     permissions:
       id-token: write # IMPORTANT: mandatory for trusted publishing
@@ -67,7 +67,7 @@ jobs:
     runs-on: ubuntu-latest
     environment:
       name: pypi
-      url: https://pypi.org/p/python-sapcommissions
+      url: https://pypi.org/p/sapimclient
     permissions:
       id-token: write # IMPORTANT: mandatory for trusted publishing
 

README.rst

@@ -1,17 +1,33 @@
-Python SAP Commissions®
-=======================
+Python SAP Incentive Management®
+================================
 
-# python-sapcommissions is now sapimclient
+An Asynchronous Python client to communicate with SAP Incentive Management®.
 
 .. note::
     This package has been renamed. Use `pip install sapimclient` instead.
 
-    New package: https://pypi.org/project/sapimclient/
+.. image:: https://www.buymeacoffee.com/assets/img/custom_images/orange_img.png
+    :alt: BuyMeACoffee
+    :target: https://www.buymeacoffee.com/niro1987
+
+Documentation
+-------------
+
+Read the full documentation on [Read the Docs](https://sapimclient.readthedocs.io/)
+
+REST API
+--------
+
+This project mimics the usage of the SAP Incentive Management REST API. Visit
+:code:`https://{TENANT}.callidusondemand.com/APIDocument` to read the full specification,
+replacing :code:`TENANT` with your tenant-id.
 
 Legal Disclamer
 ---------------
 
-This software is designed for use with SAP Commissions®. It is not affiliated with SAP® and the developers
-take no legal responsibility for the functionality or security of your Commissions environment.
+This software is designed for use with SAP Incentive Management®. It is not affiliated
+with SAP® and the developers take no legal responsibility for the functionality or
+security of your Incentive Management environment.
 
-SAP Commissions is a registered trademark of SAP SE or its affiliates in Germany and in other countries.
+SAP Incentive Management is a registered trademark of SAP SE or its affiliates in
+Germany and in other countries.

docs/requirements.txt

@@ -1,3 +1,3 @@
 sphinx==7.4.7
-sphinx-rtd-theme==2.0.0
+sphinx-rtd-theme
 myst-parser==4.0.0

docs/source/cli.rst

@@ -0,0 +1,200 @@
+Command-Line Interface
+======================
+
+Usage
+-----
+
+This project includes some command-line-interface commands,
+to install the required dependencies, install them with pip:
+
+.. code-block:: console
+
+    (.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:
+
+.. code-block:: console
+
+    (.venv) $ python -m sapimclient --help
+
+.. code-block:: console
+
+    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:
+
+.. code-block:: console
+
+    (.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:
+
+.. code-block:: console
+
+    (.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 :ref:`model:data type`.
+
+To correctly identify the :ref:`model: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.
+
+.. code-block:: console
+
+    (.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 :py:class:`Calendar <sapimclient.model.resource.Calendar>` filter on the exported data.
+    - ``--period {PERIOD}`` *Optional*
+        Apply :py:class:`Period <sapimclient.model.resource.Period>` filter on the exported data.
+        Requires ``--calendar`` to be provided.
+    - ``--filters {FILTER_TEXT}`` *Optional*
+        Apply :py:class:`Period <sapimclient.model.resource.Period>` filter on the exported data.
+        Can be applied more then once.
+
+.. tip::
+
+    Refer to the :ref:`API Documentation <index:rest api>` 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:
+
+.. code-block:: console
+
+    (.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,-:
+
+.. code-block:: console
+
+    (.venv) $ python -m sapimclient \
+        --tenant {TENANT} \
+        --username {USERNAME} \
+        --password {PASSWORD} \
+        --logfile log.txt \
+        export PAYMENTS payments.txt \
+        --filter "payment ge '100000 EUR'"

docs/source/client.rst

@@ -0,0 +1,14 @@
+Client
+======
+
+.. autosummary:: sapimclient.client
+
+.. hint::
+    See :ref:`usage:examples`
+
+.. automodule:: sapimclient.client
+
+    .. autoclass:: sapimclient.Tenant
+        :members:
+        :private-members: _request
+        :member-order: bysource

docs/source/conf.py

@@ -4,7 +4,7 @@
 
 
 # Project information
-project = "python-sapcommissions"
+project = "sapimclient"
 copyright = "2024, Niels Perfors"
 author = "Niels Perfors"
 release = _version(project)