Integrating the POS

The general process of integrating a POS is roughly the same (so far) regardless of which POS system is involved. Here we describe the setup etc.

We will use CORE-POS as our example, for a few reasons, not least of which is that it’s also free (libre) software. See POS Integration for links to others.

Install Packages

Please remember to activate your virtual environment.

The first thing is, you must install the POS integration packages. The packages for CORE-POS are publiclly available, in which case if you just want the latest releases:

pip install tailbone-theo[app,corepos]

Or if you want to run from source then you can clone/install these:

• https://forgejo.wuttaproject.org/rattail/pycorepos

• https://forgejo.wuttaproject.org/rattail/rattail-corepos

• https://forgejo.wuttaproject.org/rattail/tailbone-corepos

But then just in case, do also run the above command as well, to ensure all dependencies are got.

Modify Config

You must tell Alembic how to find all schema extensions for your POS integration package. Modify /srv/envs/theo/app/rattail.conf per the following.

The default contains:

[alembic]
version_locations = rattail.db:alembic/versions

But you now instead need something like:

[alembic]
version_locations = rattail_corepos.db:alembic/versions rattail.db:alembic/versions

Note that the POS integration path should come before the default path there.

In the same config file, you should declare your integration to Theo:

[theo]
integrate_corepos = true

Migrate Database

Most integrations will require some extra tables installed to your database. But installing them is no different than any other migration, i.e. just run the normal commands:

cd /srv/envs/theo
bin/alembic -c app/rattail.conf upgrade heads

Import POS Data

This process can vary a little but a couple of concepts will be useful regardless.

First is that data “versioning” must be considered here. Theo normally will use the versioning feature, i.e. whenever a record changes, a new “version” record is also created for it. The logic behind this has some performance cost, which is by far most pronounced when there are a “lot” of changes within the same database session.

Therefore a workaround is employed when the database is initially populated: the versioning feature is disabled for the main import, and then version records are created for the initial data in a separate step. So the first import command always includes --no-versiong:

cd /srv/envs/theo
bin/rattail -c app/quiet.conf -P import-corepos-api --no-versioning

Once all the data lives in Theo, then capture the initial version records for everything.

bin/rattail -c app/quiet.conf -P --runas corepos import-versions -m "initial data from POS"

Note the --runas arg above, which declares the Theo username responsible. The user must already exist within Theo, but can be created via the Theo web app.

Ongoing Sync

There are a few ways to do the ongoing “sync” between the POS system and Theo. For now we will only describe a very basic sync which happens once per night, although could also be used hourly etc.

The idea here is basically just like the initial data import, although should not need the versioning workaround. So one command, something like:

cd /srv/envs/theo
bin/rattail -c app/quiet.conf --runas corepos import-corepos-api

This is a very basic example, in particular does not handle “deletions” which may occur in CORE. For now though we’ll leave it at that, hopefully more to come later.