Configuring collection's managed properties

Collection’s managed properties allow a cluster administrator to enable some special behaviors regarding properties at creation & update times.
This page describes how to enable and configure these behaviors on the API server.

API Server configuration

The Collections.ManagedProperties setting from the config.yml file is used for enabling any of the following behaviors:

Pre-assigned property key & value

For every newly created collection, assign a predefined key/value pair if it isn’t already passed at creation time:

Collections:
  ManagedProperties:
    foo: {Value: bar}

Original owner UUID

This behavior will assign to a property key the UUID of the user who owns the collection’s contaning project.

Collections:
  ManagedProperties:
    responsible_person_uuid: {Function: original_owner}

Protected properties

If there’s a need to prevent a non-admin user from modifying a specific property, even by its owner, the Protected attribute can be set to true, like so:

Collections:
  ManagedProperties:
    sample_id: {Protected: true}

This configuration won’t assign a sample_id property on collection creation, but if the user adds it to any collection, its value is protected from that point on.

Another use case would be to protect properties that were automatically assigned by the system:

Collections:
  ManagedProperties:
    responsible_person_uuid: {Function: original_owner, Protected: true}

If missing, the Protected attribute it’s assumed as being false by default.

Supporting example scripts

When enabling this feature, there may be pre-existing collections that won’t have the managed properties just configured. The following script examples may be helpful to sync these older collections.

For the following examples we assume that the responsible_person_uuid property is set as {Function: original_owner, Protected: true}.

List uuid/names of collections without responsible_person_uuid property

The collection’s managed properties feature assigns the configured properties to newly created collections. This means that previously existing collections won’t get the default properties and if needed, they should be assigned manually.

The following example script outputs a listing of collection UUIDs and names of those collections that don’t include the responsible_person_uuid property.

#!/usr/bin/env python3

import arvados
import arvados.util as util

filters = [['properties.responsible_person_uuid', 'exists', False]]
cols = util.keyset_list_all(arvados.api().collections().list, filters=filters, select=['uuid', 'name'], order='uuid')

print('Found {} collections:'.format(len(cols)))
for c in cols:
    print('{}, "{}"'.format(c['uuid'], c['name']))

Update the responsible_person_uuid property from nil to X in the project hierarchy rooted at P

When enabling responsible_person_uuid, new collections will get this property’s value set to the user who owns the root project where the collection is placed, but older collections won’t have the property set. The following example script allows an administrator to set the responsible_person_uuid property to collections below a certaing project hierarchy.

#!/usr/bin/env python3

import arvados
import arvados.util as util

def get_subproject_uuids(api, root_uuid):
    uuids = []
    groups = util.keyset_list_all(api.groups().list, filters=[['owner_uuid', '=', '{}'.format(root_uuid)]], select=['uuid'], order='uuid')
    for g in groups:
        uuids += ([g['uuid']] + get_subproject_uuids(api, g['uuid']))
    return uuids

def get_cols(api, filters):
    cols = util.keyset_list_all(api.collections().list, filters=filters, select=['uuid', 'properties'], order='uuid')
    return cols

# Search for collections on project hierarchy rooted at root_uuid
root_uuid = 'zzzzz-j7d0g-ppppppppppppppp'
# Set the property to the UUID below
responsible_uuid = 'zzzzz-tpzed-xxxxxxxxxxxxxxx'

api = arvados.api()
for p_uuid in [root_uuid] + get_subproject_uuids(api, root_uuid):
    f = [['properties.responsible_person_uuid', 'exists', False],
         ['owner_uuid', '=', p_uuid]]
    cols = get_cols(api, f)
    print('Found {} collections owned by {}'.format(len(cols), p_uuid))
    for c in cols:
        print(' - Updating collection {}'.format(c['uuid']))
        props = c['properties']
        props['responsible_person_uuid'] = responsible_uuid
        api.collections().update(uuid=c['uuid'], body={'properties': props}).execute()

Update the responsible_person_uuid property from X to Y on all collections

This example can be useful to change responsibility from one user to another.

Please note that the following code should run with admin privileges, assuming that the managed property is Protected.

#!/usr/bin/env python3

import arvados
import arvados.util as util

old_uuid = 'zzzzz-tpzed-xxxxxxxxxxxxxxx'
new_uuid = 'zzzzz-tpzed-yyyyyyyyyyyyyyy'

api = arvados.api()
filters = [['properties.responsible_person_uuid', '=', '{}'.format(old_uuid)]]
cols = util.keyset_list_all(api.collections().list, filters=filters, select=['uuid', 'properties'], order='uuid')

print('Found {} collections'.format(len(cols)))
for c in cols:
    print('Updating collection {}'.format(c['uuid']))
    props = c['properties']
    props['responsible_person_uuid'] = new_uuid
    api.collections().update(uuid=c['uuid'], body={'properties': props}).execute()