From 8e1ca7677e20b4b2e3eb3c473bd062de19a26e36 Mon Sep 17 00:00:00 2001 From: Lucas Di Pentima Date: Tue, 26 Nov 2019 11:35:10 -0300 Subject: [PATCH] 15849: Moves script to the documentation, includes it on the admin section. Arvados-DCO-1.1-Signed-off-by: Lucas Di Pentima --- .../_includes/_vocabulary_migrate_py.liquid | 10 +++++----- .../workbench2-vocabulary.html.textile.liquid | 16 +++++++++++++++- 2 files changed, 20 insertions(+), 6 deletions(-) rename tools/vocabulary-migrate/vocabulary-migrate.py => doc/_includes/_vocabulary_migrate_py.liquid (96%) diff --git a/tools/vocabulary-migrate/vocabulary-migrate.py b/doc/_includes/_vocabulary_migrate_py.liquid similarity index 96% rename from tools/vocabulary-migrate/vocabulary-migrate.py rename to doc/_includes/_vocabulary_migrate_py.liquid index e729838858..3bccf61083 100644 --- a/tools/vocabulary-migrate/vocabulary-migrate.py +++ b/doc/_includes/_vocabulary_migrate_py.liquid @@ -1,9 +1,9 @@ #!/usr/bin/env python -# -# Copyright (C) The Arvados Authors. All rights reserved. -# -# SPDX-License-Identifier: AGPL-3.0 -# +{% comment %} +Copyright (C) The Arvados Authors. All rights reserved. + +SPDX-License-Identifier: CC-BY-SA-3.0 +{% endcomment %} import argparse import copy diff --git a/doc/admin/workbench2-vocabulary.html.textile.liquid b/doc/admin/workbench2-vocabulary.html.textile.liquid index 82c384c282..4ff35c363c 100644 --- a/doc/admin/workbench2-vocabulary.html.textile.liquid +++ b/doc/admin/workbench2-vocabulary.html.textile.liquid @@ -48,4 +48,18 @@ The @values@ member is optional and is used to define valid key/label pairs when When any key or value has more than one label option, Workbench2's user interface will allow the user to select any of the options. But because only the IDs are saved in the system, when the property is displayed in the user interface, the label shown will be the first of each group defined in the vocabulary file. For example, the user could select the property key @Species@ and @Homo sapiens@ as its value, but the user interface will display it as @Animal: Human@ because those labels are the first in the vocabulary definition. -Internally, Workbench2 uses the IDs to do property based searches, so if the user searches by @Animal: Human@ or @Species: Homo sapiens@, both will return the same results. \ No newline at end of file +Internally, Workbench2 uses the IDs to do property based searches, so if the user searches by @Animal: Human@ or @Species: Homo sapiens@, both will return the same results. + +h2. Properties migration + +After installing the new vocabulary definition, it may be necessary to migrate preexisting properties that were set up using literal strings. This can be a big task depending on the number of properties on the vocabulary and the amount of collections and projects on the cluster. + +To help with this task we provide below a migration example script that accepts the new vocabulary definition file as an input, and uses the @ARVADOS_API_TOKEN@ and @ARVADOS_API_HOST@ environment variables to connect to the cluster, search for every collection and group that has properties with labels defined on the vocabulary file, and migrates them to the corresponding identifiers. + +This script will not run if the vocabulary file has duplicated labels for different keys or for different values inside a key, this is a failsafe mechanism to avoid migration errors. + +Please take into account that this script requires admin credentials. It also offers a @--dry-run@ flag that will report what changes are required without applying them, so it can be reviewed by an administrator. + +{% codeblock as python %} +{% include 'vocabulary_migrate_py' %} +{% endcodeblock %} \ No newline at end of file -- 2.30.2