Domains and accounts *

Note. This section is incomplete and not fully implemented.

A domain is a domain in the DNS sense and identifies a logical instance of the Metrici product. It is not physically separate from other advisor domains served by the same application instance, but allows control over appearance, data visibility and user access.

Each domain it identified by the server name, for example "advisor.metrici.com".

The list on node "domains" equates server names with domain definitions nodes. These are typically held within the domains package, e.g. "domains.MetriciMetrici".

Each domain definition node identifies the following:

  • The node to be shown as the home page when the user is not signed on, and when they are signed on (though the latter is usually supplied at user or account level).
  • A theme reference for the domain.
  • A list of high level packages that should be visible within the domain.

The domain node is consulted from the UI in the following ways:

  • When a session is first created, the domain node is used to lookup which theme to use, and to lookup which node should initially be shown to the user.
  • Whenever a node is accessed, the domain node is used to check that the high level package of the node is valid for the domain.

The minimum theming aspects for a domain are to change the application name (from "Metrici") and to change the footer.

The default_ui.xml file below shows how the Metrici theme file is set up. The footer is read from domains.MetriciMetrici.footer.

<UserInterface>
  <extends>default</extends>
  <Constant>
    <name>applicationName</name>
    <value>Metrici</value>
  </Constant>
  <Page>
    <pageReference>footer</pageReference>
    <WidgetList>
      <Widget>
        <widgetName>node_description.jsp</widgetName>
        <nodeVersionReference>domains.MetriciMetrici.footer</nodeVersionReference>
      </Widget>
    </WidgetList>
  </Page>
</UserInterface>

The the footer page above outputs outputs the description of the referenced node as the footer. Remember that public must have read all members authority on this node, and (if necessary) node use draft authority.

An account records the relationship between an individual or organisation and the provider of services through Metrici.

An account is represented by an account node. The account node can be anywhere, but typically accounts are arranged in a package which holds all the accounts provided by the same provider. For example, all accounts provided by Metrici are held in package metrici.accounts.

The account node records the services subscribed to by the account holder, the current state of the account, and other account-wide information. It holds:

  • Links to one or more high-level package which belong to the account, and usage of which will be counted against this account. Each package can be linked to only one account, irrespective of version. This is enforced by a special node controller.
  • Subscriptions, each one of which is a specific usage agreement for Metrici.
  • A list of current licenses, against which are stored current usage levels.
  • A link to the signed on home node of the account. If given, this is used in preference to the home node on the domain.
  • A list of accounts that the account trusts.

The node owner of the account is termed the "account authority". For accounts provided by Metrici this is the "metrici" user. The account authority controls the data within the account.

Users

Within Metrici, users are independent entities. Each user has a unique logon reference, and can potentially perform any action to which they are permitted.

However, conventions are used to arrange users into accounts and to limit their activity.

The main record of the user is not held within the node structure. However, a shadow of the record is held in system.USERS.reference, where reference is the user's logon reference converted to be a valid node local reference. This records:

  • The user's name. This is a derived field, and can not be updated.
  • The user's email address. This is also derived.
  • The user's account.
  • The user's home node. This is the node which will be shown to the user when they select the "Home" link. If given, this is used in preference to the home node on the account record and on the domain record.

User groups

Users are grouped into user groups. Each user also has an "individual user group" containing just themselves.

User groups are then used for setting permissions, including permissions on user groups.

Some user group permissions authorise users to grant to a user group, or include members of one user group in another user group.

Typically, the users associated with an account are made members of an "owning user group", which has an ability to grant to itself. This means that any of the users within the user group can grant permissions to each other, or include the members of the owning user group in other user groups. This effectively constrains the users in an account to only be able to see and grant to each other. However, this is controlled solely through user group permissions, and not through the account.

Accounts are also set up with at least one user group to which the account authority can grant permissions. Only users of this group can subscribe to and install new products.

Node references are arranged hierarchically, using a dot-delimited set of references.

Each node is logically contained within a parent package, e.g. "somecompany.foo.bar" is held in package "somecompany.foo", which is itself held in the high-level package "somecompany".

Each high-level package is associated with one, and only one, account. All the nodes within the high-level package are accounted for within the account that owns the high-level package.

High level packages can be identified either by the absence of a dot in the node reference, or by a null node identifier package field.

A manifest is the fundamental building block of product packaging.

A manifest is a list of specific versions of nodes which users of a product may reference. There is a value associated with each node version, typically used to manage permissions (see below).

Manifests are used by the upgrade process to ensure integrity when installed product are upgraded.

A permission profile is an extension of a manifest. It contains:

  • For each node version on the manifest, a list of permissions that users of the products require.
  • A list of user groups to which permissions should be granted.

A product may have a number of permission profiles:

  • A primary permission profile which contains the permissions required to install the product.
  • One or more secondary permission profiles which contain the permissions required to use an installed product.

Permission profiles use a special node controller class which examines the lists of nodes and user groups and creates all the required permissions. The permissions are tagged with the node version identifier of the permission profile, making it possible to update or remove all of the permissions without altering other permissions.

A license is represented by a node, termed a license tag, which represents an agreement to use something.

Node types can be associated with license tags. This indicates that instances of the node type are only permitted within accounts that are licensed for that tag.

As well as license tags for node types, there are two special license tags:

  • The node license tag. This is required for all nodes.
  • The full user license tag. This is required for all users who have permission to create nodes.

 

An offer represents a type of agreement to use a product. It holds a number of things:

  • A description of the offer, so that the subcriber can understand it.
  • It holds offer licenses. These identify a license tag and provide a count for the number of instances of the license that this deal permits. The count also allows for "unlimited".
  • It holds the primary permission profile, without a user group, which describes the permissions that a user must have in order to install the product.
  • Whether the subscription has an end date, and if so how this is calculated. class="tbc"It holds offer period rules - details used to build subscriptions:

A product creator can make an offer available to other account holders. To do this, they:

  • Create one or more node types used to install the product. An installation node type could just be a high-level package used to contain the product. It could, through the use of an action button and a script, perform more detailed setup including granting other users various permissions.
  • Create an offer node which embodies what they want to offer. This includes deal licenses, primary permission profile and deal period rules.
  • Grant their account authority a "node-grant-use" authority over all the nodes in the primary permission profile. This allows the account authority to grant read, use draft, use node type, link and may grant authorities on nodes.
  • Grant the account authority "node-link" authority over all license tags.
  • Grant the account authority read all members authority over all the nodes that make up the deal, and link authority over the deal itself.

The account authority can then grant installation rights to users from other accounts, provided that they are also the account authority of those other users.

Subscription and installation are logically distinct. A user subscribes to a product only once, but can then install that product multiple times if necessary.

Having identified an offer to which to subscribe, the user executes a subscribe method on the account passing it the reference to the deal.

The subscribe method can perform anything. It could, for example, kick off a series of steps to request payment prior to subscription. In a typical scenario (as per current version):

  • The method checks whether the account that owns the product is trusted by this account, i.e. it is on the list of trusted accounts on the account node.
  • If the provider account is not trusted, the method records the subscription as pending. A confirmation email is sent to the user, with a unique token. If the user returns this token then the subscription is considered authorised. If the token is not received within a period of time, the subscription is cancelled.
  • If the provider account is trusted, or when the confirmation token is received, the subscription is created and activated. A subscription node is created which links to the deal. A permission profile is also created and populated from the primary permission profile from the deal, using a user group passed when the subscription was set up. Creating this permission profile, which automatically creates the appropriate permissions, provides the permission required to install the product.

 

Installation is simply a matter of instantiating a node type from the node provider. This may require the installer to enter user groups to use the product, and may create secondary permission profiles to grant these users appropriate permissions.

There are two aspects to upgrade:

  1. Upgrading instances to a new release.
  2. Upgrading the subscription to reference the correct permission profile so that step 1 can take place and so that the upgraded instance is usable,

This is complicated because the user will need both "old" and "new" permissions while the upgrade is taking place. Also, they might want to upgrade some instances (or try the upgrade out) while keeping other instances on the old levels.

The subscription has an upgrade option. This searches for all versions of the deal later than the one subscribed to, and adds any additional permissions to the subscription permission profile. Once the subscription has been ugpraded, instances can be upgraded using the normal version management features.

Uninstall can mean one of three things:

  1. Removal of an instance. This just uses Metrici's normal features for node delete.
  2. Removal of the subscription. This removes the ability to remove new instances of the product. It might also prevent existing instances from being used, because the installer's permission to grant permissions to the user will be removed, which will in turn remove the user's permission.
  3. The subscription could be disabled, or graced. This retains sufficient permission for existing instances to be used, possibly with reduced functionality, while removing the ability to create new instances of the product.

Generally, option 2 is avoided unless option 1 has also been followed. If all instances are removed, then the subscription can be removed. It instances are to be retained, then the subscription should be retained (though possibly past is validity period) and the instances will be graced (see below).

Within an account, three different types of resource are accounted for:

  • The total number of nodes.
  • The number of full users, who are permitted to create new nodes.
  • The number of instances of types with license tags.

The permitted counts for all of these are read from the deal licenses, linked to via subscriptions and deals.

A process runs periodically on the account to count the nodes, and to identify the users and licensed instances. These are recorded in current license nodes. In the case of users and instances with license tags, links indicating the assignment of the license are also retained.

This accounting information is checked when nodes are created, and node creation will fail if the permitted counts are exceeded.

The accounting information is also checked when users are created and users added to user groups.

The accounting information may become out of date, for example if the user performs mass change actions, which is why it is periodically refreshed.

When a subscription expires, it is "graced". This means that the user's instance data is not deleted and is still accessible, but that functions are no longer available.

If no licenses are available, edit is also disabled. This means that if all your subscriptions have ended, you can only read your data. But provided that you have one subscription left, you can edit your data.When a subscription is graced, the licenses will no longer be associated with the account, which will automatically prevent creation of new instances.

 

Accounts have a standard set of user groups which are used to control who can do what.

  • account. This is the individual user group of the main account administrator.
  • account-users. These are full users who have authority to create new nodes. Users in this group can:
    • Grant permissions to any or all of the account-users members.
    • Create two different types of user group:
      • Nornal user groups. The user can add other account-users members to the user group (and members of other user groups they have created), and grant to the user group.
      • Owning user group. The user can create users within the user group, but can not add other users to the user group. This is intended for users temporarily required for surveys, for example.

        (Note to self: Perhaps this should be embodied in a special node type which creates and destroys a user group? Or maybe a special service authorised by admin.)

    • Create new users owned by the user groups they have created.
    • Administer users contained within owning user groups that they have created.

    All members of account administrators (including account) should also be members of account-users.

In a single user account, the user simply uses the account sign on, which gives them all necessary permissions. So there is no difference between a single user account and a multi user account, other than the creation of additional users.