Product permissions

Nodes in your product need to be made available to authorised users and kept secure from non-authorised users. You do this by setting permissions.

Metrici supports very granular permissions which gives fine control over who can do what. See Permission for full documentation on how to set up permissions.

Within a product, there are typically two different ways of managing permissions:

  • Static permissions based on a Permission Manifest are used where the nodes upon which permissions should be granted are creted when the structure is created. All products need static permissions.
  • Managed permissions based on a Permission Manifest Manager are used where the nodes on which permissions should be granted are created during the running of the application, and simple folder permissions will not suffice. More complicated products may need managed permissions.

Static permissions

Static permission provide authority on the fixed parts of the product. To set up static permissions, you need to:

  • Create a library permission manifest
  • Define roles
  • Define permission items
  • Bundle the permission items into a specification
  • Create a permission manifest

Create a library permission manifest

Users of your product need to be authorised to use your "code", i.e. your node types, etc. To do this, create a node of type Manifest inside your advanced settings folder. Link to this in the Inherit Subscription Manifests field in your product builder (see Product builder and installer).

See Library permission manifest for an example. This does not contain any items, but when the product is installed it will be linked to a manifest associated with the product subscription.

Define roles

Within the permission setup, a role specifies a user or a group of users. Typically these are represented by a user group identified by a binding.

Within your product library, use Permission Manifest Role to create a role for each different category of users. At the very least, you need a role for each of the user groups you have created.

See User Role for an example role setup, which identifies the node with the binding "users" as having the User Role.

Depending on how you have set up your role maintainer, one role may include another. In the sample, all administrator users also have the user role, so permissions granted to users are also granted to administrators.

Define permission items

A permission item specifies one or more types of permission that should be granted on one or more nodes to one or more roles. Permission items are held in the product library, and are connected to the instance nodes using bindings.

Use type Permission Manifest Item to create permission items.

When setting up static permissions, identify each node to be authorised using binding references only. Use the drop-down list to select roles.

For permissions, you can enter permission types separately, or use the "... (group)" items to set bundles of permissions, which is simpler and clearer. These define a simple hierarchy of permissions, read-link-execute-update-administer, which can be applied to individual nodes or at the folder level. There are also groups for using and administering user groups, and for using folders. The table below describes the items you will need in a typical small application.

Description Permission type Role Nodes Example

Permit all users to read (and link to) the top-level product folder.

 Link to node (group) Users Main folder Node Permissions

Permits all users to read (and link to) the contents of the top-level folder and data folders where they have no update permission.

 		 Link to folder (group) Users Main folder, 
data folders to which users only have read access		 Folder Permissions 

Permit all users to update and administer items in data folders.

 		 Administer folder (group), Use folder (group) Users Data folders over which users have update rights Folder Update Permissions 

Permit all users to grant permissions to each other.

 Grant to user group (group) Users Users user group User Group Permissions

Permit all users to use the product library code.

 Node use manifest Users  Library permission manifest Use Manifest Permissions

Permit nodes created by any user to be managed by the permission manifest manager.

 Folder use, Node read all members, Node use draft Users Permission manifest manager Permission Manifest Manager Permissions

Permit adminstrators to execute nodes.

 		 Execute node (group) Administrators User roles  Administer Execute Permissions

Permit adminstrators to update items in folders that cannot be updated by normal users.

 Administer folder (group), Use folder (group) Administrators Data folders over which only administrators have update rights Administer Folder Update Permissions

Permit administrators to administer the user groups.

 Administer user group (group) Administators  All user group nodes Administer User Group Permissions

Create a specification

Within your product library, create a node of type Permission Manifest Specification and link to each of your permission manifest items in the Include field.  Permission Manifest Specification is like Permission Manifest except that it does not actually grant permissions, and so can be used to create a prototype for the real permission manifest.

See Permission Manifest Prototype for an example.

Create a permission manifest

Inside your instance folder advanced settings, create a node of type Permission Manifest and link to your specification using the Include field.

When you are in browse view, this will show you the permission setup. It will have picked up many of the node bindings from the bindings on the top-level folder. However, some will be missing because they are only needed to set permissions, and will be shown as ${reference}, rather than a link. Go back into edit and set additional bindings.

See Permission manifest for an example.

Permission manifest initialization

The permission manifest must be initialized after the user groups. Add the permission manifest to the initialization list, after the user groups. See Product instance – general configuration.

Managed permissions

Managed permissions provide authority over the variable parts of the structure, where this cannot be achieved using static permissions.

For example, in the sample the gadgets may have attachments which use the gadget node as a folder. The folder permissions on the gadgets folder don't reach down far enough to see the attachments, so additional permissions are required for each gadget to grant users rights over the attachments.

To create managed permissions:

  • Define roles, as for static permissions.
  • Make sure that each node type for which permissions are to be added has:
    • A tag which identifies the node type.
    • The Make permission manifest root field which registers nodes of that type with the permission manifest manager.
    See Gadget for an example.
    (This is optional. If you need to manage permissions of nodes inside a fixed folder, you can just add that fixed folder to the permissions manifest manager.)
  • Define rules for managed permissions.
  • Create a permission manifest manager.

Define permission manifest rules

The Permission Manifest Manager uses rules based on tags to work out what permissions to grant to nodes. Each node to be managed must have an appropriate tag.

Create rules using the type Permission Manifest Rule and hold them in your product library. On this specify the tag or tags that trigger the rule, and the permission types and roles to which the rule applies, just like a permission manifest item.

You also need to specify a rule applicability. This specifies to which nodes, relative to the tagged node, should the permissions be applied.

See Gadget User Permissions Rule for an example, which uses folder permissions to gives all users administrative rights to all nodes in the taggged node.

Create a permission manifest manager prototype node of type Permission Manifest Manager in your product library and add all your rules to the permission manifest rules list.

See Permission Manifest Manager Prototype for an example.

Create a permission manifest manager

Create a node of type Permission Manifest Manager in your product instance advanced settings folder, and use the Inherit From field (in Rules, advanced section) to link to your permission manifest manager prototype. (Don't link to your prototype using the permission manifest rules field, it won't work.)

See Permission manifest manager for an example.

Add a binding of reference permissionManifestManager in your top-level node to link to the permission manifest manager. Include the permission manifest manager itself in the main permission manifest, as described above.

When nodes with dynamic permissions are created, they will locate the permission manifest manager and create a permission manifest within it based on the rules for its tag.