Configuring contracts
Introduction
To help monitor document usage in shared environments Funnelback has contracts. Contracts allow an administrator to specify the number of documents a group of collections can use as well as assign contracts to users. Once configured, an administrator can monitor the number of documents in use by a contract and how many can be used.
Creating a contract
To create a contract with ID "foo" create a contract configuration file under the contracts directory. Contract IDs can only contain alphanumeric characters plus -
and _
.
For Linux:
$SEARCH_HOME/admin/contracts/foo.contract
For Windows
%SEARCH_HOME%\admin\contracts\foo.contract
The value of max-documents-permitted
set in the contract configuration file represents the number of documents all collections assigned to the contract can collectively use. In our case zoo is allowed to use 24 million documents so we set in the contract configuration file foo.contract
:
max-documents-permitted=24000000
Assigning a contract to a user
A single user can own many contracts. To add the zoo contract to the admin user, edit the admin user's ini file under the [user-info]
section and set:
contracts = foo
Multiple contracts can be added by separating them by commas for example:
contracts = foo,chocolate_shop,dulce_de_leche_shop
Adding a contract to a collection
A collection can be in at most one contract. To add a collection to the zoo contract in collection.cfg set:
contract_id=foo
For the purposes of document counts, meta collections do not contain any documents which count towards a contract, but a contract_id
can be safely added to the collection.cfg file. The contract_id
should be added to all component collections of the meta collection.
API
Under the License-limits-and-usage
section of the admin API it is possible to view the usage of a contract. In the zoo example we may do a http request:
GET /licence/v1/contracts/zoo/usage
to find out how many documents the zoo contract is permitted to use as well as how many documents all collections in the zoo contract are using.
You can find out what contracts are assigned to your user through the API as well, under the user-account-management section of the API.
Permissions
Users are always permitted to view their own contracts. Users who have the sec.contract.view-all can view all contracts on the server.
Caveats
Contracts are not enforcing. Only the license that the collection is assigned to will enforce the total number of documents. You may view the document usage for each license from the interface for managing your licenses.