| Description | manuals and libraries |
LedgerSMB::Database::SchemaChecks::JSON - Input for schema upgrades
use LedgerSMB::Database::SchemaChecks::JSON;
use LedgerSMB::Database::ChangeChecks qw( run_checks load_checks );
my @checks = load_checks('path-to-some-file-with-checks');
my $out = json_formatter_context {
return ! run_checks( \@checks );
} 'path-to-directory-with-response-files';If any of the checks fails, $out contains the path of a file containing the data of the failure which can be used to compose a response.
This module provides a way to specify non-interactive input for schema upgrade precondition checks.
A use-case for specifying non-interactive input would be an iterative process where a user is trying to migrate a database from an earlier version of LedgerSMB, repeating the process until all questions have been answered. When the process works on a backup database, the recorded answers can be used for the final migration.
Another use-case involves simulating user input in our test suite.
Each migration failing check wants a response. Each response is stored in its own file. When no response file exists, the module generates one populated with the data that it needs a response for.
Response files are JSON files where the top-level is an object with the following structure:
- failure
- title
- description
- confirmations
- grids
- <grid1>
- rows
- options
- row1
- field1
- option1
- optionN
- fieldN
- rowN
- adjustment_fields
- response
- confirm
- <grid1>The data under the failure key will be populated by the module when a failing test is detected. The data under the response key is to be provided by the user and will be used by the module to resolve the data issues detected. The failure section is optional.
Each response must provide a confirm field in the response section which has the value of one of the keys in confirmations. E.g. when confirmations contains
[ { "abc": "Description of ABC"},
{ "def": "Description of DEF"} ]Then the confirm key could be:
"confirm": "abc",The other keys in the response section depend on the names of the UI elements having been generated. At the moment, these can only be grids. The available keys are listed in the failure.grids section.
Each grid has a key adjustment_fields which is an array of fields which needs to be edited for the rows to become compliant with the check.
The quickest solution to generating a response is by copying the rows in the failure section, edit the adjustment_fields columns and choose a confirm value. Note that providing more than just adjustment_fields in the response is optional, however a column called __pk must be provided. It's used to identify the rows.
E.g. when the failure section looks like:
{ "failure": {
"title": "Assert that 'a' or 'b' isn't NULL",
"description": "Enter a string in either 'a' or 'b'",
"confirmations": [
{ "save" : "Save" },
{ "cancel": "Cancel" }
],
"grids": {
"adjustment_fields": [ "a", "b" ],
"fail_data": {
"rows": [
{ "__pk": "MQ==", "a": null, "b": null },
{ "__pk": "Mg==", "a": null, "b": null }
]
}
}Then the response section could look like:
{ "response": {
{ "confirm": "save",
"fail_data": [
{ "__pk": "MQ==", "a": "a string", "b": null },
{ "__pk": "Mg==", "a": null, "b": "another string" }
]
}
}This module doesn't specify any methods.
Calls $coderef with a hash-argument containing the ChangeCheck formatters required to be passed to run_with_formatters in that module; also sets up a context for the formatters based on $dir, allowing non-interactive responses to be read from files in it.
Returns undef when the $coderef returns false.
Returns a name of a file in directory $dir when $coderef returns true. This file contains a JSON object describing a (failed) change check. The contents of the file is meant to be edited. The edited file provides the corrected data to be uploaded to the database.
Copyright (C) 2018 The LedgerSMB Core Team
This file is licensed under the GNU General Public License version 2, or at your option any later version. A copy of the license should have been included with your software.