[#197] Klanten API migration command (#263)

Co-authored-by: Sonny Bakker <sonny@maykinmedia.nl>
Co-authored-by: Steven Bal <steven@maykinmedia.nl>

CHANGELOG.rst

@@ -9,6 +9,8 @@ Change history
 **New features**
 
 * Updated OAF version to 0.9.0. This upgrade allows admin users managing their sessions through the admin.
+* [#197] Added a ``migrate_to_v2`` management command which allows users of version ``1.0.0`` to migrate to version ``2.4.0``
+  More information can be found in the `documentation <https://open-klant.readthedocs.io/en/latest/installation/migration.html>`
 
 **Bugfixes/QoL**:
 

docs/development/index.rst

@@ -0,0 +1,13 @@
+.. _development_index:
+
+Development
+============
+
+**Open Klant** is open-source software. We'd love to have you
+contribute!
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Further reading
+
+   migration

docs/development/migration.rst

@@ -0,0 +1,41 @@
+.. _migration_developer_docs:
+
+Migration
+=========
+
+To test the migration command, tests are written using VCR, which records the (relevant)
+outgoing requests to cassette files. Whenever tests need to be updated, consider
+re-recording the corresponding cassettes.
+
+To re-record tests, a separate docker compose file is available to run a
+version ``1.0.0`` Open Klant instance next to the ``StaticLiveServer`` (which
+sets up a live server) which runs version ``2.0.0``. The `web` container from the
+docker compose setup should load the corresponding fixture which reside in the
+``migration/fixtures`` folder. A typical workflow, to re-record cassettes,
+could look like the following:
+
+.. code-block:: bash
+
+    # Start the docker compose setup
+    $ docker compose up --detach
+
+    # Load a fixture for a certain test
+    $ docker compose exec -it web \
+        ./src/manage.py loaddata migration/credentials migration/test_digitaal_adres
+
+    # Run the corresponding test
+    $ ./src/manage.py test openklant.tests.test_migrate.MigrateTestCase.test_digitaal_adres
+
+    # Stop and destroy the containers (to start with a clean slate on the next run)
+    $ docker compose down
+
+
+After running the test a cassette should be created (with the test name as filename)
+in the ``migration/cassettes`` folder.
+
+Note that the docker compose setup, with its fixtures are only needed to (re)create
+cassettes for VCR. The migration tests can be ran without the docker compose setup.
+
+Some tests require custom responses, for example to retrieve the ``subjectIdentificatie``
+when a ``subject`` URL is supplied. For these cases a ``test_server.py`` file is added
+that can be modified as needed to create a response for a cassette.

docs/index.rst

@@ -28,3 +28,4 @@ Open Klant `is`_ and only uses open source.
    :hidden:
 
    installation/index
+   development/index

docs/installation/index.rst

@@ -15,3 +15,4 @@ this.
    :caption: Further reading
 
    config
+   migration

docs/installation/migration.rst

@@ -0,0 +1,21 @@
+.. _migration_user_docs:
+
+Migration
+=========
+
+Users of Open Klant version ``1.0.0`` willing to migrate to version ``2.4.0`` or higher
+can make use of the ``migrate_to_v2`` management command. This command **only** migrates
+``Klant`` instances from version ``1.0.0``. The command expects two URLs; a URL for the
+Open Klant instance of version ``1.0.0`` and a URL for version ``2.0.0``.
+
+The command also expects a ``ACCESS_TOKEN`` environment variable to be set, to authenticate to
+the Open Klant ``1.0.0`` instance. For the ``2.0.0`` instance a dummy token will be
+created. This dummy token will be removed after the command ran (be it successfully or not).
+
+An example of how one might want to run this command can be seen below:
+
+    .. code-block:: bash
+
+        $ ACCESS_TOKEN="openklant-v1-token" ./src/manage.py migrate_to_v2 \
+            https://example.openklant.nl \
+            https://example.klantinteracties.nl

migration/cassettes/test_digitaal_adres.yaml

@@ -0,0 +1,38 @@
+interactions:
+- request:
+    body: null
+    headers:
+      Accept:
+      - '*/*'
+      Accept-Encoding:
+      - gzip, deflate
+      Connection:
+      - keep-alive
+      User-Agent:
+      - python-requests/2.32.3
+    method: GET
+    uri: http://localhost:8000/klanten/api/v1/klanten
+  response:
+    body:
+      string: '{"count":1,"next":null,"previous":null,"results":[{"url":"http://localhost:8000/klanten/api/v1/klanten/dbfdb3f2-e153-49ea-9e26-e55220605c14","bronorganisatie":"215906846","klantnummer":"0","bedrijfsnaam":"","functie":"","websiteUrl":"","voornaam":"","voorvoegselAchternaam":"","achternaam":"","telefoonnummer":"","emailadres":"example@maykinmedia.nl","adres":null,"subject":"","subjectType":"natuurlijk_persoon","aanmaakkanaal":"","geverifieerd":false,"subjectIdentificatie":{"inpBsn":"","anpIdentificatie":"0","inpANummer":"","geslachtsnaam":"Greene","voorvoegselGeslachtsnaam":"","voorletters":"","voornamen":"Lori","geslachtsaanduiding":"","geboortedatum":"1981-04-15","verblijfsadres":null,"subVerblijfBuitenland":null}}]}'
+    headers:
+      API-version:
+      - 1.0.0
+      Allow:
+      - GET, POST, HEAD, OPTIONS
+      Content-Length:
+      - '726'
+      Content-Type:
+      - application/json
+      Referrer-Policy:
+      - same-origin
+      X-Content-Type-Options:
+      - nosniff
+      X-Frame-Options:
+      - DENY
+      X-XSS-Protection:
+      - 1; mode=block
+    status:
+      code: 200
+      message: OK
+version: 1

migration/cassettes/test_existing_dummy_tokens.yaml

@@ -0,0 +1,38 @@
+interactions:
+- request:
+    body: null
+    headers:
+      Accept:
+      - '*/*'
+      Accept-Encoding:
+      - gzip, deflate
+      Connection:
+      - keep-alive
+      User-Agent:
+      - python-requests/2.32.3
+    method: GET
+    uri: http://localhost:8000/klanten/api/v1/klanten
+  response:
+    body:
+      string: '{"count":1,"next":null,"previous":null,"results":[{"url":"http://localhost:8000/klanten/api/v1/klanten/7853958c-4ff1-4b62-bb81-1277346692bf","bronorganisatie":"719250341","klantnummer":"0","bedrijfsnaam":"","functie":"","websiteUrl":"","voornaam":"Harry","voorvoegselAchternaam":"","achternaam":"Potter","telefoonnummer":"","emailadres":"","adres":null,"subject":"","subjectType":"natuurlijk_persoon","aanmaakkanaal":"","geverifieerd":false,"subjectIdentificatie":{"inpBsn":"024325818","anpIdentificatie":"0","inpANummer":"","geslachtsnaam":"Huffman","voorvoegselGeslachtsnaam":"","voorletters":"H","voornamen":"Frank","geslachtsaanduiding":"","geboortedatum":"2005-09-30","verblijfsadres":null,"subVerblijfBuitenland":null}}]}'
+    headers:
+      API-version:
+      - 1.0.0
+      Allow:
+      - GET, POST, HEAD, OPTIONS
+      Content-Length:
+      - '727'
+      Content-Type:
+      - application/json
+      Referrer-Policy:
+      - same-origin
+      X-Content-Type-Options:
+      - nosniff
+      X-Frame-Options:
+      - DENY
+      X-XSS-Protection:
+      - 1; mode=block
+    status:
+      code: 200
+      message: OK
+version: 1

migration/cassettes/test_incorrect_subject_url.yaml

@@ -0,0 +1,38 @@
+interactions:
+- request:
+    body: null
+    headers:
+      Accept:
+      - '*/*'
+      Accept-Encoding:
+      - gzip, deflate
+      Connection:
+      - keep-alive
+      User-Agent:
+      - python-requests/2.32.3
+    method: GET
+    uri: http://localhost:8000/klanten/api/v1/klanten
+  response:
+    body:
+      string: '{"count":1,"next":null,"previous":null,"results":[{"url":"http://localhost:8000/klanten/api/v1/klanten/c59c00b3-3445-4731-8a6b-ee26992a5358","bronorganisatie":"892036175","klantnummer":"0","bedrijfsnaam":"","functie":"","websiteUrl":"","voornaam":"","voorvoegselAchternaam":"","achternaam":"","telefoonnummer":"","emailadres":"","adres":null,"subject":"","subjectType":null,"aanmaakkanaal":"","geverifieerd":false}]}'
+    headers:
+      API-version:
+      - 1.0.0
+      Allow:
+      - GET, POST, HEAD, OPTIONS
+      Content-Length:
+      - '416'
+      Content-Type:
+      - application/json
+      Referrer-Policy:
+      - same-origin
+      X-Content-Type-Options:
+      - nosniff
+      X-Frame-Options:
+      - DENY
+      X-XSS-Protection:
+      - 1; mode=block
+    status:
+      code: 200
+      message: OK
+version: 1

migration/cassettes/test_natuurlijk_persoon.yaml

@@ -0,0 +1,38 @@
+interactions:
+- request:
+    body: null
+    headers:
+      Accept:
+      - '*/*'
+      Accept-Encoding:
+      - gzip, deflate
+      Connection:
+      - keep-alive
+      User-Agent:
+      - python-requests/2.32.3
+    method: GET
+    uri: http://localhost:8000/klanten/api/v1/klanten
+  response:
+    body:
+      string: '{"count":1,"next":null,"previous":null,"results":[{"url":"http://localhost:8000/klanten/api/v1/klanten/c29538c1-98b8-4773-8ac1-f0af110d92f9","bronorganisatie":"620357848","klantnummer":"0","bedrijfsnaam":"","functie":"","websiteUrl":"","voornaam":"Harry","voorvoegselAchternaam":"","achternaam":"Potter","telefoonnummer":"","emailadres":"","adres":null,"subject":"","subjectType":"natuurlijk_persoon","aanmaakkanaal":"","geverifieerd":false,"subjectIdentificatie":{"inpBsn":"024325818","anpIdentificatie":"0","inpANummer":"","geslachtsnaam":"Williams","voorvoegselGeslachtsnaam":"","voorletters":"H","voornamen":"Nicole","geslachtsaanduiding":"","geboortedatum":"1973-02-23","verblijfsadres":null,"subVerblijfBuitenland":null}}]}'
+    headers:
+      API-version:
+      - 1.0.0
+      Allow:
+      - GET, POST, HEAD, OPTIONS
+      Content-Length:
+      - '729'
+      Content-Type:
+      - application/json
+      Referrer-Policy:
+      - same-origin
+      X-Content-Type-Options:
+      - nosniff
+      X-Frame-Options:
+      - DENY
+      X-XSS-Protection:
+      - 1; mode=block
+    status:
+      code: 200
+      message: OK
+version: 1

migration/cassettes/test_niet_natuurlijk_persoon.yaml

@@ -0,0 +1,40 @@
+interactions:
+- request:
+    body: null
+    headers:
+      Accept:
+      - '*/*'
+      Accept-Encoding:
+      - gzip, deflate
+      Connection:
+      - keep-alive
+      User-Agent:
+      - python-requests/2.32.3
+    method: GET
+    uri: http://localhost:8000/klanten/api/v1/klanten
+  response:
+    body:
+      string: '{"count":1,"next":null,"previous":null,"results":[{"url":"http://localhost:8000/klanten/api/v1/klanten/abd7a618-1177-4d17-a9d9-a3b6f9ee8606","bronorganisatie":"613907826","klantnummer":"0","bedrijfsnaam":"","functie":"","websiteUrl":"","voornaam":"","voorvoegselAchternaam":"","achternaam":"","telefoonnummer":"","emailadres":"","adres":null,"subject":"","subjectType":"niet_natuurlijk_persoon","aanmaakkanaal":"","geverifieerd":false,"subjectIdentificatie":{"innNnpId":"807371440","annIdentificatie":"","statutaireNaam":"Foobar
+        Inc.","innRechtsvorm":"vereniging_van_eigenaars","bezoekadres":"Masonhof 351\n6335
+        OX\nMetslawier","subVerblijfBuitenland":null}}]}'
+    headers:
+      API-version:
+      - 1.0.0
+      Allow:
+      - GET, POST, HEAD, OPTIONS
+      Content-Length:
+      - '660'
+      Content-Type:
+      - application/json
+      Referrer-Policy:
+      - same-origin
+      X-Content-Type-Options:
+      - nosniff
+      X-Frame-Options:
+      - DENY
+      X-XSS-Protection:
+      - 1; mode=block
+    status:
+      code: 200
+      message: OK
+version: 1

migration/cassettes/test_no_subject_and_no_subject_identificatie.yaml

@@ -0,0 +1,38 @@
+interactions:
+- request:
+    body: null
+    headers:
+      Accept:
+      - '*/*'
+      Accept-Encoding:
+      - gzip, deflate
+      Connection:
+      - keep-alive
+      User-Agent:
+      - python-requests/2.32.3
+    method: GET
+    uri: http://localhost:8000/klanten/api/v1/klanten
+  response:
+    body:
+      string: '{"count":1,"next":null,"previous":null,"results":[{"url":"http://localhost:8000/klanten/api/v1/klanten/c59c00b3-3445-4731-8a6b-ee26992a5358","bronorganisatie":"892036175","klantnummer":"0","bedrijfsnaam":"","functie":"","websiteUrl":"","voornaam":"","voorvoegselAchternaam":"","achternaam":"","telefoonnummer":"","emailadres":"","adres":null,"subject":"","subjectType":null,"aanmaakkanaal":"","geverifieerd":false}]}'
+    headers:
+      API-version:
+      - 1.0.0
+      Allow:
+      - GET, POST, HEAD, OPTIONS
+      Content-Length:
+      - '416'
+      Content-Type:
+      - application/json
+      Referrer-Policy:
+      - same-origin
+      X-Content-Type-Options:
+      - nosniff
+      X-Frame-Options:
+      - DENY
+      X-XSS-Protection:
+      - 1; mode=block
+    status:
+      code: 200
+      message: OK
+version: 1

migration/cassettes/test_no_subject_and_subject_identificatie.yaml

@@ -0,0 +1,38 @@
+interactions:
+- request:
+    body: null
+    headers:
+      Accept:
+      - '*/*'
+      Accept-Encoding:
+      - gzip, deflate
+      Connection:
+      - keep-alive
+      User-Agent:
+      - python-requests/2.32.3
+    method: GET
+    uri: http://localhost:8000/klanten/api/v1/klanten
+  response:
+    body:
+      string: '{"count":1,"next":null,"previous":null,"results":[{"url":"http://localhost:8000/klanten/api/v1/klanten/c29538c1-98b8-4773-8ac1-f0af110d92f9","bronorganisatie":"620357848","klantnummer":"0","bedrijfsnaam":"","functie":"","websiteUrl":"","voornaam":"Harry","voorvoegselAchternaam":"","achternaam":"Potter","telefoonnummer":"","emailadres":"","adres":null,"subject":"","subjectType":"natuurlijk_persoon","aanmaakkanaal":"","geverifieerd":false,"subjectIdentificatie":{"inpBsn":"024325818","anpIdentificatie":"0","inpANummer":"","geslachtsnaam":"Williams","voorvoegselGeslachtsnaam":"","voorletters":"H","voornamen":"Nicole","geslachtsaanduiding":"","geboortedatum":"1973-02-23","verblijfsadres":null,"subVerblijfBuitenland":null}}]}'
+    headers:
+      API-version:
+      - 1.0.0
+      Allow:
+      - GET, POST, HEAD, OPTIONS
+      Content-Length:
+      - '729'
+      Content-Type:
+      - application/json
+      Referrer-Policy:
+      - same-origin
+      X-Content-Type-Options:
+      - nosniff
+      X-Frame-Options:
+      - DENY
+      X-XSS-Protection:
+      - 1; mode=block
+    status:
+      code: 200
+      message: OK
+version: 1