Account Setup *

The information about products and subcriptions is out of date.

This section provides step-by-step instructions for account and product management.

• Create an account authority
• Create an account
• Create a normal user
• Create a contributor group
• Create a contributor
• Move an account
• Package a product
• Subscribe to a product
• Install a product
• Upgrade a product

Create an account authority

An account authority is a user who has authority to own other accounts. This user is also the primary user of an account (see below). So creating an account authority is like creating a new account, and then doing extra things to allow the primary user to act as an account authority.

Each account authority represents a separate authority to enter into agreements with account holders. In a Metrici instance, there may be one or more account authorities, but there are unlikely to be a large number of account authorities.

Creating an account authority is not fully automated, and must be carried out by the admin user who has super permission. If an existing primary user is being promoted to an account authority, then follow only the steps that have not already taken place.

Steps:

1. Identify a suitable reference for the account authority, and a name and a password. These are referred to as authority, Authority and password below.

   The reference must be a valid local reference for a node, and not already be in use.

2. Create an account for the account authority. Use the New Account link on the node admin.accounts, or set it programatically using the service call:

   <ExecuteScript>
     <nodeVersionReference>admin.accounts</nodeVersionReference>
     <nodeVersionReferenceMethod>library.account.CreateAccount.1</nodeVersionReferenceMethod>
     <accountName>Authority</accountName>
     <accountReference>authority</accountReference>
     <accountPassword>password</accountPassword>
   </ExecuteScript>

3. Add authority to the account-authorities user group. The account-authorities user group gives the account authorities appropriate permissions, but does not give account authorities visibility of each other.
4. Create accounts package

   Create a node of type Accounts (library.account.AccountsType) as authority.accounts. Give authority node-administer and package-administer permission over authority.accounts, and make authority the owner of authority.accounts.

5. Permit account creation

   Account creation requires node-execute permission on the authority.accounts node. By default, only admin and authority have this permission.

   To allow manual account setup, create a new node of type New Account Form (library.account.NewAccountFormType), for example as authority.accounts.new_account. Enter the accounts package (authority.accounts) on the new account form edit view. Give authority node-administer permission, and make them the owner. authority can now create accounts using this page, or delegate authority to others simply by giving appropriate read permissions.

   The new account form is not a normal node creation form (it uses extension scripts to manage the form). This is necessary to allow users other than the account authority to create accounts.

   Hint: Put the following in the description of the accounts package to provide a shortcut to create a new account:

   <!--break-->
   <ul class="shortcut">
     <li><a href="https://www.metrici.com/metrici/documentation/devguide/accounts_old/account_setup/new_account">New Account</a></li>
   </ul>

Create an account

You can create an account programmatically or through a form. Either way, you need the following information:

• An account name. This can be anything, but would typically be the name of the individual or organisation who owns the account.
• A suitable account reference. This should be a valid node reference which does not correspond to the name of an existing user, user group or high-level package. This is referred to as account.
• A password for the primary user.
• An email address for the primary user.

To create an account programmatically, you must have node-execute permission on authority.accounts. You can then create an account by executing the Create Account Method (library.account.CreateAccountMethod) method on the authority.accounts node, passing it the name, reference, password and email address in the parameters accountName, accountReference, accountPassword and accountEmailAddress. Sample service call:

<ExecuteScript>
  <nodeVersionReference>partner.accounts</nodeVersionReference>
  <nodeVersionReferenceMethod>library.account.CreateAccountMethod.1</nodeVersionReferenceMethod>
  <accountName>Acme Paints</accountName>
  <accountReference>acme_paints</accountReference>
  <accountPassword>go4f7lf</accountPassword>
  <accountEmailAddress>bill.smith@acme-paints.com</accountEmailAddress>
</ExecuteScript>

To create an account through a form, use the new account form, which is typically available at authority.accounts.new_account.

The new account will be represented by a node authority.accounts.account.

When an account is created, the authority automatically has permissions over the account high-level package and over the account-users user group. The primary user of the account can remove these permissions if required, though the authority will then only be able to manage subscriptions to the primary user.

Create a normal user

Account creation creates a single user with a logon reference of account, known as the primary user. This is suitable for single-user accounts or temporary demo accounts. Multi-user accounts should create users for each inidivdual who can use the account.

To create a normal user, sign on as account, and create the user in the normal way, using the account-users owning user group. If you want the user to have authority to administer account users and to install products, also add the user to account-administrators user group.

Create a contributor group

A contributor is a user with reduced priviledges, for example a respondent to a survey. Typically, contributors are not permitted to create new nodes and are do not have visibility of other users in the account.

Contributors are created by first creating a contributor user group, and then creating the contributors within that group. Any normal user can create a contributor group, using the normal user group create function. Select the "Use this user group to create new users" option.

Create a contributor

Contributors are created using the normal user creation methods, specifying the contributor user group as the owning user group.

Move an account

To move an account between account authorities, copy the account node from one accounts package to another, and set the ownership and permissions on the moved account. This may require intervention from admin.

Account deletion

There is currently no automated support for account deletion. To delete an account manually:

• Delete all the users in the account.
• Delete the account-users users group, and any other user groups associated with the account. Other user groups will typically be cleaned up automatically, but deleting them manually will help in some cases.
• Delete the account node. (If you have missed any users, their user nodes will be listed as prevent you deleting the account node.)
• Delete the account high-level package, or move it to some other package for purging later.

Package a product

A product is represented by an offer node. This describes the product on offer, has a link to one or more manifests that specify the contents of the product, and information about the validity and licensing associated with a product. It may also identify a node type and suggested local reference for installation of the product.

Offers are created using offer type nodes. The simplest offer type is Offer (library.account.OfferType), which is not associated with any validity or license information, and provides no processes to support subscription. It is useful for products which are installed manually by the account authority.

To package a product, create one or more manifests which describe the product components and the permissions that users of the product require. Then create an instance of Offer, referencing the product manifests.

Offer automatically grants the account authority with permission to publish the offer to other accounts. If you want a different account authority to have this permission, grant them node-use-manifest, node-read-all-members, node-link and node-use-draft permission on the offer.

Subscribe to a product

To manually create a subscription to a product, create a node of type Subscription (library.account.SubscriptionType) under the account node of the account which holds the subscription. Set the offer to the offer you want to subscribe to.

• To grant a user group rights to use the product, give them node-use-manifest permission on the subscription node.
• To grant a user group rights to delegate rights on the product, give them node-grant-use-manifest permission on the subscription node. They will also need to be able to read the subscription node. This is automatically granted to the account primary user, who can grant this permission on.

Remember to refresh the subscription node after setting permissions.

The account node contains a suitable shortcut for creating a new subscription. It does not automatically set permissions on the subscription.

Install a product

Product installation is separate from subscription. It simply involves instantiating one or more node types.

Deinstallation simply involves deleting the product instance.

Upgrade a product

Product upgrade is a two-stage process:

1. Adding a new version of the subscription that references a new version of the offer. Both versions are required so that instances can work with a superset of the old and new permissions. (In some cases, the new version of the offer might refer to multiple manifest versions, in which case upgrading the subscription will suffice.)
2. Upgrading instances to refer to the new version. Use the manifest option, passing the subscription node itself as the manifest.

Unsubscribe

To remove a subscription, simply delete the subscription node. This will remove all the user's permissions. Generally, this will mean that they will be able to read their data, but not much else.

For some products, users will continue to require some permissions to read their data. In this case, create a separate manifest and offer for read-only access, and then change the subscription to the read-only version of the offer.