Product packaging *

This section if out of date.

This document describes the features in Metrici to package a product and make it available for users of other accounts, and to subscribe to and install the product. It covers:

  • How subscription works
  • Manifests
  • Permission manager
  • Roles
  • Permission rules
  • Template packages
  • Installers
  • Offers
  • Subscriptions
  • Installation
  • Metaproducts

This is intended as an explanatory document for a technical audience.

How subscription works

Subscription involves permitting users of one account to use definitions (such as node types) that have been created by another account.

Metrici's user groups are set up to prevent users from one account from exposing data to users in another account, which would acts as a complete barrier to subscription.

To get around this restriction, subscription takes place using the account authority. An account authority is a special user that is used to create accounts. Provided that both accounts have the same account authority, or they have account authorities which have permitted cross-account-authority subscription, then one account can make a product available for subscription in another account. The account authority acts as a go-between transferring permissions from the publisher to the subscriber.

Internally, subscription uses grant permissions, i.e. the account authority is granted permission to grant permission on the product. Grant permissions are limited, and only allows the account authority to grant usage permissions on nodes (such as read, link and use type). It does not allow the account authority to grant modification permissions on nodes (such as update, administer, use package and execute). This means that the subscriber can only access what has been published, and can not modify it. It also means that the publisher has no access to the subscriber's data, which, for example they could if they could grant use package or execute permissions.

Manifests

A manifest node contains a list of nodes and permissions associated with those nodes. Manifests can be maintained manually or generated. Manifests are used as the basis for transferring permissions during subscription, as well as maintaining permissions within an account.

User groups can be granted "use manifest" permission on a manifest, which grants them the permissions on all the nodes in the manifest. The grants are carried out under the authority of the manifest node owner, and only permissions that the owner is authorised to grant will be granted.

User groups can also be granted "grant use manifest" permission on a manifest, which gives them permission to grant "use manifest" on the manifest.

There is a system-defined Manifest type (system.MANIFEST_TYPE), which holds the manifest items in the member type Manifest Items (system.MANIFEST_ITEMS). There is also an extended Manifest type (library.permission.ManifestType), which has the following additions:

  • It lists the user groups with use manifest permission in the browse view.
  • If the user has execute authority on the node, allows them to maintain the user groups that have use manifest permission. This is carried out under the authority of the manifest owner.
  • It holds a second, hidden list of manifest items (called the secondary manifest items). These are intended for use when the manifest is generated, but can be seen by viewing tab 0. These are merged with the main list as part of derivation processing. This allows a manifest to hold both manually entered items and generated items, allowing the generated items to be refreshed without disrupting the manually entered items.
  • It can hold a role (see below) which supports the permission manager's rule-based, role-based processing.
  • It is tagged as a manifest.

Permission manager

A permission manager (instances of library.permission.PermissionManagerType) is at its simplest a container type for extended manifests. It shows the manifests within it and allows the use manifest permissions to be maintained. Typically the manifests represent different roles, and thus the permission manager supports role-based permissions.

The permission manager can also apply permission rules to generate and maintain manifests. The generation is non-destructive – it will add to what is already there and not overwrite manually created manifests. This makes it easy to set up complex permission structures, for example with a mixture of rule-based generated permissions and manual additions and inheritance, or setting up delegated permission management by using one manifest to provide execute authority on another.

When permission rules are applied, the permission manager takes responsibility for the permissions within a package structure, the top of which is know as the permission root. The permission root is either entered into the permission manager directly, or the permission manager will search up from its own location to a node tagged as the permission root. The permission manager then applies a set of permission rules to the permission root and all the nodes within it.

The permission manager does not search nodes within the permission root that are themselves tagged as permission roots. This allows for delegated permissions of projects, for example setting up high-level permissions and then allowing separate permissions for different projects.

Permission management can be consolidated across permission managers using normal inheritance methods or by adding manifest-level permissions to other manifests, allowing a mixture of global and delegated permission management.

Roles

A role is a logical grouping of authority, such as "administration" or "contribute". A role can be represented by any node, though for convenience the type library.permission.RoleType can be used which tags the roles as roles.

Roles are not global - each permission manager can manage the same or different roles in different ways. So an individual can administer one project, and contribute to another.

Permissions rules

A permission manager can be associated with one or more permission rules, type library.permission.PermissionRuleType. The rules specify the following:

  • A set of tags to which the rules apply, i.e. which nodes should the rules fire.
  • Rule applicability, which specifies which nodes the permissions should be applied to. This can be the node on which the tag is found, its children, itself and its children, or itself and its children provided that they have children (the last of these is for setting package-level permissions).
  • A list of roles and permissions that should apply to those roles.

For example, a rule could say that developers and subscribers should have node-use-type permission on all nodes tagged as types.

A permission rule allows multiple tags and multiple roles/permissions to be defined, though in many cases only one is required.

The permission manager examines all the nodes under the permission root and creates a manifest for each role. This provides rule-based, role-based permissions.

Permission managers support inheritance, allowing a set of permission rules to be defined on a prototype.

Standard tags, roles and rules are available. Of the roles, two apply to product definitions:

  • Developer – has permissions to do everything.
  • Subscriber – has permissions to use everything.

Other roles apply to product users:

  • Contributor – has permissions to use the product, but no permissions to read or update the product data (i.e. other people will create data for them to enter).
  • Read - can read product data, but not update it.
  • Update - can read and update product data.
  • Admistrator - can do everything in the product.

The standard tags for definitions are:

  • Library – container for definitions. Subscriber has all usage permissions, developer has all administrative permissions.

The standard tags for product instances are:

  • Product Root - defines the top of the product. Administator can administer this and everything underneath it.
  • Navigation Package - a package designed for navigation. Everyone can read it, but not necessarily its contents.
  • Data Package - readers can read it and link to it, updaters can update it too, and everything inside it.
  • Results Package - readers and updaters can read it and link to it, and everything inside it.
  • Reference Package - everyone can read it and link to it, and everything inside it.

Template packages

As well as providing a subscriber with an appropriate set of permissions, the subscriber will need to create a structure of nodes to use a product. This could be a simple package, or a complex set of packages and nodes which can even include permission managers for managing permissions on the new installation.

A template package is simply a package that is copied into the subscriber's account to provide this initial structure.

Installers

Installers are special node types that simplify the use of template packages. Each installer specifies a template package. An instance of the installer is created in the install location, and then runs an install script which replaces itself with a deep copy of the template package.

Installers are created using node type library.account.InstallerType.

An installer can also specify two manifests within the template package, to provide initial permissions to the new installation.

  • An admin manifest. The subscriber will be granted node-use-manifest over this manifest. If installed from a subscription, the node-use-manifest and node-grant-use-manifest on the subscription will be added to the manifest.
  • A user manifest. node-use-manifest on the subscription will be added to this manifest.

Installers also automatically create a manifest for the template package, which gives the subscriber the permissions they need to copy it.

Offers

An offer (instances of library.account.OfferType) represents a product that is to be made available to other account holders. It specifies:

  • A manifest which describes the permissions the subscriber needs.
  • Optionally, one or more installers that can be used to install the product. Each installer can be associated with a recommended local reference. The first installer is considered the default installer, and could be used to automatically install a product.

Internally, the offer creates two manifests.

  • It creates an offer manifest, which merges the manifest specified on the offer and the package manifests defined by the installers.
  • It creates an grant manifest which automatically grants the account authority (i.e. the account authority that set up the account that owns the owner of the offer node) the right to grant permissions to all the nodes in the manifest. This gives the account authority the ability to read the offer and create subscriptions to it.

Subscriptions

The subscription process is carried out by the account authority (using the new subscription feature on the account). It creates a new node of type library.account.SubscriptionType. This acts as a manifest, copying the offer manifest. The account authority can then grant node use manifest and node grant use manifest on the subscription node to allow the subscriber to use and grant use on the product.

Installation

Installation is simply a matter of running the Installers associated with an offer.

The My Subscriptions navigation item (library.account.MySubscriptions) lists all the subscriptions for an account and provides links to install the subcribed-to products. It can be used to build an installation page or menu.

Metaproducts

The product management features of Metrici can be applied to the creation of products themselves. It is possible to define a product for creating products, i.e. with a library, template, navigation structures, permission managers, and so on. These metaproducts will greatly simplify the creation of families of fully-featured new products.

Cross-authority publication

Account authorities do not have any permissions to each other, or to each other's accounts. This prevents products created in an account of one authority being subscribed to by an account in another authority.

This restriction can be removed by the admin user creating a trust relationship between a user and another account authority.

Creating a trust relationship

As the admin user, create a user group containing the "to" account authority, and grant the offer owner permission to grant to the user group. These user groups are typically called Grant to XXX (grant-to-xxx), where XXX and xxx are the name and reference of the account authority.

Permitting access to an offer

As the offer owner, grant the following permissions on the offer to the user group containing the "to" account authority.

  • node read all members
  • node link
  • node use draft
  • node use manifest

Remember to refresh the offer node after granting the authorities.

Subscribing to an offer

The "to" account authority can now use the offer to subscribe accounts to the product.

Incorporating an offer into another product

To incorporate an offer into another product:

  • Ensure you are subscribed to it.
  • Add your subscription node as a manifest on your product's offer. (The subscription node acts as a manifest, and by listing it on your offer you will make sure that permissions to use the other product are included with yours.)