Hello everyone, Anna here! I work as a projects consultant in Ataccama and today I put together a guide for you on how to migrate permissions after upgrade of v13 to v14. In v14, we introduced a fresh new permissions model introducing Groups and Stewardship. The downside is, though, that after the upgrade the old permissions model cannot be automatically migrated into the new setup.

Attached to this guide is a migration package – a set of plans that you can use that will help you through the process of migrating the old permissions into the new setup in more automated way. It is not meant for fresh v14 installations.

The article is split to two parts:

1. Preparation phase – steps you need to do BEFORE you upgrade your environment to v14.
2. Post-upgrade phase – steps you need to do AFTER the upgrade, meaning in your new v14 environment.

Preparation phase

Following steps should be run on version 13 prior running the migration scripts and upgrade of the environment.

1. Create server connection in ONE Desktop.

Create a generic server in your ONE Desktop called one. Its URL should end with /graphql. The version of ONE Desktop is not important, both v13 and v14 should work because the plans work only with JSON calls.

2. Download the migration scripts

Download the migration scripts attached to this article. Unzip the package. In your ONE Desktop, create a new project and copy the unzipped files there.

Also, create a folder out on the same level as folder in.

3. Modify the list of the nodes

One of the input files for the extraction plan is file in/mmd-nodes.csv. It contains the default entities (e.g. sources, catalog items, terms, …) for which the permissions will be exported. If there are some custom entities created in your environment for which the permissions should be migrated, you need to add those entities into this CSV file.

Fill in the:

• name of the entity as defined in the metadata model,
• order in the output file (the exact number is up to you),
• which property should be used as a name (usually it’s ‘name’ or whatever is used as display name in the metadata model of that entity. You can leave it empty, then _displayName will be used in the JSON call automatically).

4. Extract information from the v13 environment:

Run the extract.plan that will extract following information:

• permissions.json file (both user and system version)
• all sharings of all nodes
• setup of project notification settings

Outputs:

• The main output is sharings.csv. This will be used as an input for migrating the permissions to v14.
• sharings-errors.csv and sharings-gql-errors.csv contains possible errors from the JSON call, check them to verify that everything was processed correctly.
• sharings-roles-stats.csv, sharings-users-stats.csv - how many times was certain role or user assigned
• system-permissions.json5 and user-permissions.json5 (the latter can be empty) and permissions-cmp.txt. The last file just tells whether there are any changes made by the user, possible values are
  • “DEFAULT” = the system default is used and was not changed.
  • “SAME” = user version is used, but it is identical to the system one.
  • “DIFFERENT” = changes were done to the permissions.json5 by some user. This will most likely require additional review. In some cases these changes can by simply new permissions for custom entities (won’t require any further action) but it can also be customization of some behavior which may need to be transferred into the v14 permissions model.
• notif-operation-set-stats.csv and notif-roles-stats.csv can be ignored for now. In the future, project notifications will not be able to target roles but only groups.

Description of the sharings.csv file:

Columns:

• mmd_node, path, type - the static information about the type
• gid, name - the id of the node and its name
• old_capability - the level of sharing (usually owner, editor, viewer)
• old_role_name, old_username - whom it was shared (at most one will be filled)
• access_level - access level of the new sharing (empty)
• group_name, username - whom it should be shared (empty)

If there are multiple (at least one) direct sharings (meaning except the default sharing, someone assigned permissions through the Access tab of an entity) for one node (gid), there will be multiple rows with old_capability filled. If there is no direct sharing, the row for the node will be present with an empty old_capability (because it is using the default access = first rows with the mmd_node ’metadata’)

The last 3 columns are empty and are meant to be populated by you to set up the model for v14.

You may need to increase Timeout limit in all JSON calls in the plan. (under Advanced tab). Also, it may be handy to add request and response debug files (also under the Advanced tab).

5. Prepare new permissions model

Before you upgrade to v14, prepare the new permissions scheme. Use the following steps:

1. Find out what changes there are between user and system version of the permissions.json, and if they are significant (this may require assistance of an Ataccama consultant)
   • —> Use the results from the extract.plan ran in previous step.
2. Learn about the new permissions model from our documentation: https://support.ataccama.com/home/docs/aip/latest/development-guides/one-development-guide/user-management-and-access-configuration and figure out your desired setup (alternatively, you can do some quick “default”).
3. Find out what should be shared to whom and fill the sharings.csv file (see below).

Some rules must be maintained when filling the sharings.csv:

1. Do not change structure of the file.
2. Rows with mmd_node equal to metadata will be ignored (so you can delete them); all such sharings shall be moved to nodes with path matching /*.
3. Pretty much all nodes with path /* need some sharing (otherwise they will only be accessible by admin); nodes with deeper path usually do not.
4. Rows can be removed and/or added if more/fewer sharings are needed.
5. Acceptable values for the access level: full, edit, viewData, viewMetadata. https://support.ataccama.com/home/docs/aip/latest/development-guides/one-development-guide/one-api#ONEAPI-SharingEntities
6. For group and username, use the name, resp. username property (e.g. Default or jane.smith)

The easiest valid setup can be to share almost everything to one group Default. Almost everything means: source, term, rule, component, lookupItem, monitoringProject, regulation, category, policy and omit sharing metadata (not sharable in v14), connection, location, folder, catalogItem (inherit sharing from source).

Example:

Post upgrade steps

Follow these steps after the environment is upgraded to v14.

1. Create the global roles (Governance roles)

Upload the in/global-roles.zip which contains the definition of global roles or create custom roles if needed.

The zip file contains the default global roles that are usually part of the clean installation (Data Consumer, Data Owner etc.). These are missing after upgrade from the v13 but are needed to configure the groups.

You can adjust them later after the upgrade.

Steps to import the zip file:

• Navigate to Global settings —> Import And Export and click in Import

• Drag&Drop the zip file into the Your file section or use the Browse button. 
• Under Data state I recommend to choose Import as draft and publish (if it fails to publish, it will stay in draft).
• Click on Import.

• Check under the Global roles, that the Import was successful.

2. Create structure of groups

Follow this guide to create the groups: https://support.ataccama.com/home/docs/aip/latest/development-guides/one-development-guide/user-management-and-access-configuration/groups Recommended is to create at least a Default group under the Organization as a start if you don’t have any specific requirements for the groups in this phase.

Besides the FE, you can also use create-groups.plan from the migration package. The structure can be filled in the in/groups.csv file:

3. Share everything to groups or users

Once the previous steps are done, you can import the new permissions using the share.plan.

The plan shares the given nodes with the respective users/groups.

• Inputs:
  • sharings.csv has the same format as the output of extract.plan (see above).

It is expected that export is run first, and the resulting sharings.csv is then edited. The important columns are: mmd_node, gid as well as access_level, group_name and username, all others are ignored.

• Outputs:
  • shared-errors.csv and shared-gql-errors.csv - check that all response_code is 200 and there are not gql erros.

You can also check the results of the plan in the web application, if you open an entity and click on Share button, you should see the desired permissions.