Configuring contracts

This feature is not available to users of the Squiz Experience Cloud version of Funnelback.

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:


For Windows


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:


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:


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.


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.


Users are always permitted to view their own contracts. Users who have the sec.contract.view-all can view all contracts on the server.


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.