VS-data API

Uses Fast API to provide a simple (documented) API for Vital Seeds data on the local network.

The API is intended to be a very simple wrapper that delegates actual business logic to a separate dedicated python package vs-data, now also in this repo.

Hopefully this will mean that vs-data-api can be dedicated to providing endpoints, leaving the deep FM integration (SQL queries etc) can be neatly encapsulated in vs-data and more easily maintained, tested and extended.

Basic usage

Run the FastAPI server:

uvicorn src.vs_data_api.main:app --reload

Call the API from a FileMaker script:

#  Example call to vs-data-api (without arguments)
#  Set a valid vs-data-api endpoint (development server)
Set Variable [ $URL ; Value: "http://127.0.0.1:8000" ]

Insert from URL [ Select ; With dialog: On ; Target: $RESPONSE ; $URL ]

Set Variable [ $MESSAGE ; Value: JSONGetElement ( $RESPONSE ; "message" ) ]

# Show the response
Show Custom Dialog [ $URL ; $MESSAGE ]

🎉 Should show a dialog with the message VS Data API running (returned from root endpoint)

Tests

Tests are provided using pytest. By default only fully mocked tests are run (see pytest.ini).

To run integration tests, ie those that connect to a local filemaker database file, or development woocommerce site:

pytest -m "fmdb or wcapi"

Test dependencies

To run tests that mock the filemaker database, you will need to install sqliteodbc driver so that pyodbc can connect to the mock database in the same way as it would connect to filemaker (ODBC). Installation instructions for the driver should be available in the downloaded package, but briefly:

• install ODBC Manager
• run installer
• add a user driver from /usr/local/lib/libsqlite3odbc-0.9993.dylib
• create a DSN using that driver (optional)

Troubleshooting

If receive error with normal operations after installing sqliteodbc, eg: Can't open lib 'FileMaker ODBC' : file not found" May need to make sure unixodbc has not been installed somehow. Eg brew uninstall unixodbc.

VS-data

Previously its own installable package, now moved into the this repo to allow simpler maintenance.

This is a python package that serves as a bridge between inventory management in FileMaker, and order details on vitalseeds.co.uk.

Aims to replace opaque and proprietary FM 'scripts' - specifically where they interact with the WooCommerce/WP website.

Requirements

To connect to Filemaker:

• filemaker database
• fm user configured with all access
• Filemaker ODBC driver
• ODBC manager installed and configured with a DSN for the db (optional, can connect direct)
• (Mac only) iodbc library dependency for pypyodbc brew install libiodbc
• Filemaker sharing > enable ODBC

To connect to WooCommerce:

• API credentials

Installation

Set environment variables. See .env.example for full list. Alternatively these options can be passed as arguments eg when calling from FM.

• VSDATA_FM_CONNECTION_STRING
• VSDATA_WC_URL
• VSDATA_WC_KEY
• VSDATA_WC_SECRET

Install python dependencies.

• pip install -e

Install python developer and test dependencies.

• pip install -e ".[dev,test]"

Create an SSL certificate so that the fastapi endpoints can use HTTPS when run by uvicorn. Suggest save to the ssl folder, or you can use the env vars SSL_KEYFILE SSL_CERTFILE to specify the path to these two files.

Setup in FileMaker

Filemaker can trigger actions by requesting fastapi endpoints (running locally).

Filemaker does not support import/export of scripts, so you will need to set these up yourself. See the fm_scripts directory for examples.

Usage

Currently, to run the cli commands in production you will need to explicitly load configuration:

dotenv run -- python vs_data import-wc-product-ids

TODO: This will be moved into pydantic settings and imported automatically as a default.

Run test config via dotenv to test new endpoints etc against a dummy database and staging site:

dotenv -f .env-test run -- python vs_data import-wc-product-ids

Rationale

• FM scripts
  • are quite error prone
  • almost impossible to test and debug
  • have extremely poor documentation
  • have very limited and costly external support
• python scripts can
  • make use of robust third party libraries such as WooCommerce
  • be version controlled
  • use automated testing
  • be edited and searched as text, ie with a full featured code editor like VScode
  • be much more performant
  • be iterated and improved more simply