dmsbbquery 0.4.1
A Python interface for querying the DMS Backbone system via XML. Provides abstract base classes and concrete implementations to construct, send, and parse XML requests for dealer stock information, order data, business partner data and system availability.
Requires Python: >=3.9
Keywords: automotive, dealer management system, dms, query, xml

DMSBackboneQuery is a Python project designed to simplify interactions with the Dealer Management System Backbone. It provides a set of tools and functionalities to streamline the process of making and handling various types of requests.

[![Codestyle: black][codestyle-shield]][codestyle-url]
[![python version][python-version-shield]][python-version-url]
[![WTFPL 3.0][wtfpl-badge]][wtfpl-url]

# Table of Contents
* [About DMSBackboneQuery](#about)
* [Getting Started](#start)
  - [Installation](#installation)
  - [Configuration](#config)
  - [Test your setup](#testing)
* [Usage](#usage)
  - [Module shopdata](#shopdata)
    - [getstock.py](#getstock) - script to query inventory data
    - [Class GetStockInformation](#getstockinfo) - the corresponding class
  - [Module businesspartnerdata](#businesspartnerdata)
    - [Class GetEntry](#getentry) - query customer information
  - [Module workshoporder](#workshoporder)
    - [Class ListOrder](#listorder) - get workshoporder list
    - [Class GetOrder](#getorder) - get order details
* [Contributing](#contrib)
* [License](#license)
* [Contact](#contact)
* [Acknowledgements](#acknowledgements)

<a name="about"></a>
## About DMSBackboneQuery
DMSBackboneQuery provides a framework for executing different types of queries within a Dealer Management System. The project includes several modules and classes, each tailored to specific query needs.

Currently supported (Service - Method):

* **DMSBackbone:**
  - Base class dmsbbquery
  - AliveTest: Check system status
 
* **ShopData:**
  - GetStockInformation: Retrieve stock data
 
* **WorkshopOrder:**
  - ListOrder: List workshop orders
  - GetOrder: Retrieve specific order details
 
* **BusinessPartnerData:**
  - GetEntry: Fetch business partner entry

<a name="start"></a>
## Getting Started
To get everything up and running follow these steps.

<a name="installation"></a>
### Installation
First clone the repository:
```sh
git clone https://gitlab.com/chgaida/dmsbbquery.git

cd dmsbbquery/
```
Even if there are few dependencies, I recommend setting up a virtual environment:
```sh
python3 -m venv env

source env/bin/activate
```
For now there is only one external Python module (requests) that needs to be installed if it's not already.

Install from `requirements.txt`:
```sh
pip install -r requirements.txt
```

<a name="config"></a>
### Configuration
Upon its initial execution, the `getstock` sample script will automatically duplicate the config file `dmsbb.config` to `~/.config/dmsbb/`. Make sure to insert your specific three-digit dealer region and five-digit dealer number. For preliminary testing, you may leave the file unchanged.


<a name="testing"></a>
### Test your setup
You can test the modules and the script with a local server without running DMS-Backbone and without being in your corporate network. For that, you need to edit the url in  `dmsbb.config`:
```
[dms]
url = http://localhost:8080
```

The `getstock` script will initially search for the configuration file in the current directory and then in `~/.config/dmsbb/`.

To start the mock DMS-Backbone server, execute the following commands:
```sh
cd dmsbb_mockserver

python3 dmsbb_srv.py &

cd ..
```

Try `getstock` with any dummy partnumber:
```sh
./getstock.py abc123123
```
The output will begin with the response from the mock server, followed by the stock quantity for the part number.

<a name="usage"></a>
## Usage

<a name="shopdata"></a>
### Module shopdata

<a name="getstock"></a>
#### getstock - Retrieve stock information
Type `getstock -h` to get an overview of the options and arguments.

```sh
usage: getstock [-h] [-v] [-s] [-p] [-i] [-t] [-c] [-g] [-a] [-r] [-A] [-f] [partnumber]

Query the dealer management system.

positional arguments:
  partnumber          part number to query

options:
  -h, --help          show this help message and exit
  -v, --verbose       increase output verbosity
  -s, --store         show storage location
  -p, --price         show price information
  -i, --invoice-text  show invoice text
  -t, --tax-rate      show tax rate (VAT)
  -c, --category      show category
  -g, --group         show group
  -a, --all           show all
  -r, --raw           show raw xml output
  -A, --alive-test    show server status
  -f, --force         try to get a quantity even if an exception has occured
```

<a name="getstockinfo"></a>
#### Class GetStockInformation
The `GetStockInformation` class is used to fetch stock information for a specific part.

```python
>>> from dmsbbquery.shopdata import GetStockInformation
>>>
>>> # Define your region, dealer ID and the server URL
>>> region = "123"
>>> dealer_id = "45678"
>>> url = "http://lpnbb:81" # The URL of the DMS-BB Server
>>>
>>> # Create an instance of the GetStockInformation class
>>> stock = GetStockInformation(region, dealer, url)
>>>
>>> # Define the part number for which you want to query stock information
>>> partnumber = "N  90813202"
>>>
>>> # Request the stock information for the specified part number
>>> stock.request(partnumber)
200 # <- http status code
>>> # Print the quantity in stock and the location
>>> print(f"Quantity: {stock.stock}\nLocation: {stock.store})
Quantity: 201
Location: A3F01
```

<a name="businesspartnerdata"></a>
### Module businesspartnerdata

<a name="getentry"></a>
#### Class GetEntry
Use the Class GetEntry to query customer information.

```python
>>> from dmsbbquery.businesspartnerdata import GetEntry
>>>
>>> customer = GetEntry("123", "45678", "http://lpnbb:81")
>>>
>>> customer.request(first_name="christian", last_name="gaida")
200 # <- http status code
>>> print(customer.rawout())
<?xml version="1.0" ?>
<MESSAGE DTD="XMLMSG" VERSION="1.2.0.0">
    <RESULT>
        <RESPONSE DTD="BusinessPartnerData" ID="45678" NAME="GetEntry" VERSION="1.2.1.0">
            <DATA>
                <BUSINESS_PARTNER TYPE="CUSTOMER">
                    <ACCOUNT_NO>101</ACCOUNT_NO>
                    <MATCHCODE/>
                    <COURTESY_TITLE TYPE="MALE">Herr</COURTESY_TITLE>
                    <NAME TYPE="LAST">Gaida</NAME>
                    <NAME TYPE="FIRST">Christian</NAME>
                    <NAME TYPE="EXTEND"/>
                    <NAME TYPE="TITLE"/>
                    <ADDRESS>Linuxstrasse 1011010</ADDRESS>
                    <ZIP>11010</ZIP>
                    <CITY>Tux City</CITY>
                    <CONTACT TYPE="PHONE">+49 1011 01001011</CONTACT>
                    <CONTACT TYPE="EMAIL">crish@email.tx</CONTACT>
                    <CONTACT SIGN="HOME">+49 1001 1010011</CONTACT>
                    <DATE_OF_BIRTH/>
                    <LAST_MODIFIED>2019-03-07 21:30:46.00000</LAST_MODIFIED>
                </BUSINESS_PARTNER>
            </DATA>
        </RESPONSE>
    </RESULT>
</MESSAGE>
>>>
```

<a name="workshoporder"></a>
### Module workshoporder

<a name="listorder"></a>
#### Class ListOrder

<a name="getorder"></a>
#### Class GetOrder


<a name="contrib"></a>
## Contributing
Please take a look at [CONTRIBUTING.md](./CONTRIBUTING.md) if you're interested in helping!

<a name="license"></a>
## License
Distributed under the WTFPL 3.0 License. See [LICENSE](./LICENSE) for more information.

<a name="contact"></a>
## Contact
finger(1) finger@port70.de



<!-- MARKDOWN LINKS & IMAGES -->
[pipeline-badge]: https://gitlab.com/chgaida/urbdict-bot/badges/develop/pipeline.svg
[pipeline-url]: https://gitlab.com/chgaida/urbdict-bot/-/commits/develop
[pylint-badge]: https://gitlab.com/chgaida/urbdict-bot/-/jobs/artifacts/develop/raw/public/badges/pylint.svg?job=pylint
[pylint-url]: https://gitlab.com/chgaida/urbdict-bot/-/commits/develop
[cover-badge]: https://gitlab.com/chgaida/urbdict-bot/badges/develop/coverage.svg
[cover-url]: https://gitlab.com/chgaida/urbdict-bot/-/commits/develop
[codestyle-shield]: https://img.shields.io/badge/code%20style-black-000000.svg
[codestyle-url]: https://github.com/psf/black
[python-version-shield]: https://img.shields.io/badge/python-3.11-blue
[python-version-url]: https://www.python.org/downloads/release/python-370/
[wtfpl-badge]: https://kidl.at/images/wtfpl-banner.svg
[wtfpl-url]: https://kidl.at/wtfpl-3.0