15849: Moves script to the documentation, includes it on the admin section.

Arvados-DCO-1.1-Signed-off-by: Lucas Di Pentima <ldipentima@veritasgenetics.com>

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 e72983885847116a7221ea2ad24b4635ad920b63..3bccf6108347e63c2cadae07b715b7957439bdc5 100644 (file)
--- 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 82c384c282f7ad06bca1c001df8e8c9db16dfaca..4ff35c363c0bbe2fddd9da687c5fbbdfcc7806bc 100644 (file)
--- 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