37 Document how to update the server when the OpenAPI specification has been updated

README.md

@@ -38,6 +38,63 @@ TBA
    <http://localhost:8080/api/v1/ui/> to check that the web service of the Data
    Node started successfully.
 
+### Update the codebase when a new OpenAPI spec is available
+
+When a new API has been released there are 2 ways to update this repository
+with the new specification.
+
+The procedure in both cases starts by checking out the [nlp-sandbox-schemas](https://github.com/Sage-Bionetworks/nlp-sandbox-schemas) repository that contains the
+newest API Specification of all NLP Sandbox projects. Make sure you have the prerequisits installed for that project
+before proceeding. These instructions assume you have checked out ALL projects to your home directory
+identified as ~ in the following documentation. Start by running the following:
+
+    cd ~/nlp-sandbox-schemas
+    npm run build openapi/data-node/openapi.yaml
+
+This will generate an output file dist.yaml in the current directory. It should output the following:
+
+    npm run build openapi/data-node/openapi.yaml
+
+    > [email protected] build ~/nlp-sandbox-schemas
+    > openapi bundle -o dist $npm_config_entrypoint "openapi/data-node/openapi.yaml"
+
+    bundling openapi/data-node/openapi.yaml...
+    📦 Created a bundle for openapi/data-node/openapi.yaml at dist.yaml in 38ms.
+
+
+Next to re-generate the flask app using one  of two methods.
+
+The first is the easiest and least error prone if you are worried about overriding existing files.
+One can generate a new flask app in a "test" directory and compare results between the old and new
+directories . This is done with the command:
+
+    openapi-generator generate -i dist.yaml -g python-flask -o ~/nlp-sandbox-data-node-i2b2-2014-updated/server
+
+Then compare the ~/nlp-sandbox-data-node-i2b2-2014-updated/server to your existing ~/nlp-sandbox-data-node-i2b2-2014/server directory to see
+what was updated.
+
+The other method, once you are more confident, is to lay the files on top of the existing repository you've already checked with the command:
+
+    openapi-generator generate -i dist.yaml -g python-flask -o ~/nlp-sandbox-data-node-i2b2-2014/server
+
+If one wants to prevent certain files you know have already been customized then add those file names
+cto the ~/nlp-sandbox-data-node-i2b2-2014/server/.openapi-generator-ignore file before running the preceding command.
+
+Then use git to see what is updated and if you overwrote any files you wanted
+to preserve. One can revert those changes and add those files to the .openapi-generator-ignore file for next time there is an update.
+
+## Errors
+
+Columns found incorrect in database :
+
+``` psycopg2.errors.UndefinedColumn: column "filename" of relation "pat_notes" does not exist ```
+
+There nay be times when the Database node needs to be upgraded. As the
+database is stored in a volume, just remove that volume and it will
+be re-created with the new files
+
+ docker volume rm  nlp-sandbox-data-node-i2b2-2014_database-data
+
 ## Access logs
 
 The current logs are saved to `/var/log/app/current`.