Manage attributes¶

An attribute, such as a member's department or office, is a fact that rules can read. This page shows how to define an attribute, which values it may take, and how to give members and groups a value. What attributes are is in Roles and access.

org-admin defines, changes and deletes attributes. Whoever may change the member or the group, such as people-admin, gives a value when they hold that value themselves; org-admin may give any value. Attributes have no screen in OS yet: you manage them through the API. The examples use $OS, $TOKEN and $ORG as in Manage groups.

Define an attribute¶

curl -s -X POST "$OS/api/v1/organisations/$ORG/attributes" \
    -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
    -d '{"name": "department", "allowed_values": ["sales", "finance"], "multiple": true}'

OS answers 201:

{"id": "atd_...", "name": "department", "allowed_values": ["sales", "finance"],
 "multiple": true, "version": 1, "allowed_actions": ["see", "use", "write", "delete"]}

• name: letters, digits and _ . : -, at most 64 characters. OS works out role, group, subject, os_toolbox, os_offered, os_element, os_audience, os_assistant, os_element_editor, os_project, os_project_chats, os_project_files, os_visitor, os_desk, os_consultant, os_editor_scope and os_kb itself, and you cannot define them.
• allowed_values: the values the attribute may take. Leave it out and any value is fine. With a fixed list OS also refuses a rule that names another value, so a typo does not silently match nothing.
• multiple: whether one member or group may hold more than one value. One by default.

An organisation defines at most 16 attributes: the 32 a member may carry, less role, group, os_toolbox, os_offered, os_element, os_audience, os_assistant, os_element_editor, os_project, os_project_chats, os_project_files, os_visitor, os_desk, os_consultant, os_editor_scope and os_kb, which OS sets itself. OS also counts how many attributes and labels the rules of your organisation, and of every organisation below it, use together: at most 32. OS refuses a new attribute that would take an organisation past that with 409.

Change the allowed values¶

PUT .../attributes/department replaces allowed_values and multiple whole, with the version you read in If-Match. OS refuses with 409 when the change would break something:

• a member or group holds a value no longer in the list: take it back first;
• a rule names a value no longer in the list, in your own organisation or in an organisation below: change that rule first;
• you turn multiple off while someone holds more than one value: take those back first.

Give a value¶

curl -s -X POST "$OS/api/v1/organisations/$ORG/attribute-values" \
    -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
    -d '{"attribute": "department", "value": "sales", "member_id": "mem_..."}'

Give member_id for one member or group_id for a group; every member of a group holds the group's values. The answer has an id such as mat_... (on a member) or gat_... (on a group).

• GET .../attribute-values?member_id=mem_... or ?group_id=grp_... lists the values one member or group holds directly, not those through groups.
• DELETE .../attribute-values/mat_... takes a value back.

A member holds at most 32 values per attribute, each at most 256 characters.

Delete an attribute¶

DELETE .../attributes/department deletes the attribute and every value of it, on members, on groups and in pending invitations. When a rule still reads the attribute, in your own organisation or in an organisation below that does not define it itself, OS refuses with 409; change that rule first.

When OS refuses¶