Setup & configuration

From Complete Cyclos documentation wiki
Jump to: navigation, search

This page gives some tips and best practices about the steps of configuring Cyclos. It is good to pay much attention to the setup and configuration because once the system is live and it contains data it will be harder to make modifications.

Definition & planning

Define Monetary model

The first obvious step would be to define monetary model. Cyclos can be used for common monetary models like mutual credit (lets, barter) micro fincance and commerce and consumer networks like C3. The default database of Cyclos comes with an acount and group structure that can be easily adapted or extended for the above mentioned currency systems.

Define Cyclos access

Another important point is to see the type of access that you want to enable for the users (groups). The most common interface is the web interface but you can also enable other interfaces like Mobile phone, and external payments (web-shop). In case your system handles the emissions of scrip/vouchers you might use the paydesk/operator interface.

Configuration & customization

Setup account structure

The first actual configuration is the creation of system and member accounts, transaction types, loans, contributions, taxes & fees and payment filters. The complexity of the account structure depends on the type of system. If you have more currencies within the same system and different types of types of member groups with different configurations the account structure will be the most complex part of the system configuration. If you use a more basic system like for example a LETS the default account structure and configuration will demand little changes. Possibly the default account structure will have items that you will not need. For example if you will not use the 'Voucher account' and its related transactions you can either decide not showing it or remove the account and it's related transactions. More information about the account structure can be found in the Cyclos manuals (login in Cyclos as member or admin and go to: Help - Manual.

Setup group structure

Most of the settings and configuration related to users (members, admins, brokers) is defined in the group configuration and permissions. The group configuration has many options. You can define for example what account(s) and currencies the members of the group have access to, the security level etc. The permissions of a group define what a member of a group can and cannot do. A clear set of groups will offer better security and easier management of Cyclos. This is especially true for administrators. The default system administrator will have all functions enabled and this can be overwhelming. It is good practice is to create administrator groups for specific tasks and functions.

The Cyclos group structure works in such a way that if configurations exists at more than one level (individual, group, system/global). The lower level configuration will overwrite a the higher level configuration. For example, if a member has an individual credit limited defined it will overwrite the credit limit defined for the group it is part of.

Many other configurations can be defined per group. It is possible to define the layout, static pages like login, contact and news, and profile fields per by group (explained below at customization)

More information about groups can be find at: Administration manual - Groups & Permissions

System settings

Like the account and group settings most system settings are 'one time' configurations settings. System settings are 'system wide'. That means that they count for all groups. The system settings define the system locals like language, mailserver, security levels, password, mailing, logging and access settings.

Some settings need to be chosen carefully because it can be hard to change them at a later stage. For example it could be complicated for an organisation to change the format of transaction numbers or member account numbers if you there are already accounts and transactions in the system.

More information about groups can be find at: Administration manual - Settings

Translations (application and internal messages)

The translation of Cyclos resides in the main translation file, help files and manuals and message settings for automatic generated messages. From Cyclos 3.1 all translation functions reside under the main 'Translation' menu in the administration section. The translations that normally need to be reviewed are the message translations because they are specific for the organisation/community.

Notification variables

In some messages, like confirmation message by e-mail it is possible to use variables in the text (e.g. username, accountname). A complete list of message and possible variables can be found at the page Notification variables.

Content management

The Cyclos layout can be adapted from the content management section. It is possible to create a whole 'customized' layout but most organisations chose to upload a logo and chose one of the predefined 'themes' (color scheme and font types). It is also possible to change the layout and content of the static pages like login, news, and contact page directly from the content management section. Only basic html knowledge is needed.

It is possible to set the layout and static pages for specific groups. This way it is possible to setup different layouts for (single) systems that host more than one communities.

Custom fields

If a system has more than one member groups you probably want different profile fields for these groups. For example a 'consumer' group will have different profile fields than a 'business' group. It is possible to specify fields to groups and define field behaviour like type, validation, unique, obligatory etc. It is also possible to create exta custom fields for advertisements, loans and loangroups.
More information about groups can be find at: Administration manual - Custom fields

If you need more complex validation that cannot be solved with a regular expression (in the input pattern of the custom field you can write your own validation class. A typical situation would be if you want to perform a validation based on the calculation of the input, or a remote validation.
Your class will need to implement the interface PropertyValidation (find in cyclos3/utils/validation). Once you have to class ready you can implement it in the following ways.

  • move the class to the directory webapps/cyclos/web-inf/classes, or
  • make a jar file that contains the class and put it in the directory WEB-INF/lib
  • make a jar file that contains the class and put it in tomcat/lib

Category list for the advertisements

Cyclos comes with a default category list. It might need changes to reflect the products and services of your organisation. Note that onces a advertisements exists with a category this category cannot be deleted anymore (only if all the advertisments with that category are deleted)

More information about groups can be find at: Administration manual - Advertisements

Category list for the messages

The categories in Cyclos are used for member to system-and system-to-member messages. Common message categories are: suggestion, problem reporting, loan request etc. It is possible to set specific message to member groups and adminstration groups. This way specific administrators can handle specific types of messages.

Dynamic documents

The administration can make documents that will show up in the Member section. The documents can retrieve fields from the profile of the Member that is viewing the document. It typical custom document would be a loan contract or any kind of request document. Documents can be assigned to member groups. It is possible to set the document only viewable by administrators. There are two types of custom documents. Simple documents in html format that just include member data (profile fields) and documents that present first an input form to the Member that needs to be filled in. When the Member submits the form a result page is generated which can included in the input data as well as the member profile fields. Here are two examples:

### Single document example page ###

<%@ taglib uri="" prefix="cyclos" %>
<%@ taglib uri="" prefix="fmt" %>
<fmt:setLocale value="${localSettings.locale}"/>

<P CLASS="western" ALIGN=CENTER STYLE="margin-bottom: 0cm"><BR>
<cyclos:customImage name="systemLogo" type="system"/></P>
Example simple document
<P>Today is <fmt:formatDate value="${now.time}"
pattern="MMMM, dd 'of' yyyy"/><%--<cyclos:format dateTime="${now}"/>--%> 
and the member: <b>${}</b> is testing de Cyclos 3 version. <br>
Some more text here.<br>
Cyclos Development Team

Form with result document page

## Form ##

<table style="defaultTable" width="100%">
		<td width="35%" class="label">Represented by</td>
		<td><input type="text" name="representant"></td>
		<td class="label">Service request nr</td>
		<td><input type="text" name="srn"></td>
		<td class="label">Image delivered?</td>
		<td><input type="radio" class="radio" checked name="delivered" value="yes"> Yes
		<input type="radio"  class="radio" name="delivered" value="no">No</td>

## Document ##

<%@ taglib uri="" prefix="cyclos" %>
<%@ taglib uri="" prefix="c" %>
<%@ taglib uri="" prefix="html" %>
<%@ taglib uri="" prefix="bean" %>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">

<!-- the first three fields have fixed variable names, custom field names can be taken from the custom field edition page-->
Login Name: ${member.username}<BR>
Member Name: ${}<BR>
E-mail: ${}<BR>
Area: ${member.area}<BR>
City: ${}<BR>
Postal code:${member.postalCode}<BR>
Phone: ${}<BR><BR>

Represented by: ${param.representant}<BR>
Service request number ${param.srn}<BR>
Image delivered?
[${param.delivered == 'yes' ? 'X' : ' '}] Yes
[${param.delivered == 'no' ? 'X' : ' '}] No 

Reports & statistics

The reports and statics functions are very extended. The output of these functions are based for a big part on the payment filters. Payment filters are just a collection of one or more payment types. These filters can be added and modified in the account management section.

Receipt printers

If members/operators want to print with receipt printers you might want to check if they work. A list with known supported printers can be found here

Multi community setup (shared instance)

It is possible to create multiple communities within onc Cyclos instance. This page gives information about the benefits, constraints / considerations and installation tips.


  • Easier installation and configuration of a new communities. (everything can be done from within Cyclos, templates can be used)
  • Cheaper hosting
  • Possibility to allow payments between communities.

Constraints & considerations

  • All communities must share more or less the same methodology if inter-payments (between communities) will be allowed. This will be most probably 'mutual credit' and one local currency. In this case the Unit value must be of equal value for all communities. It is currently not possible to have exchange rates between communities.
  • You can allow either transactions between a community with all other communities or have the community in its own (isolated) environment (like a single instance)
  • Different taxes and fees can be defined per community.
  • Layout (logo, colors) and static pages (news, about, login, contact etc) can be defined per community. The login URL will be something like
  • It is possible to define extra functions per community like member records which is a strong feature. This is more work for the system admin and should probably be charged separately.
  • The advertisements categories are system wide! So every community will have to same advertisements categories. If a complete set of categories is created this should not be a problem.

System setup

  • Define & create default (local) member, broker and admin group (permissions and settings)
  • Create member account and create default transaction types, payment filters, fees etc.
  • Create main login page (system wide). This can be a simple webpage or maybe a page with links to all the community login pages

Typical community configuration

  • 1 group filter per community (typically a community like a lets group, city etc)
  • One or more member groups (created by copying the template member group). Preferably one member group but if necessary you can create for example a consumer and a business group. The groups need to be added in the group filter.
  • Local admin group (created by copying the template admin group). Can be one or more admin group in case you want to differentiate tasks. E.g. some admins do pure member administrations and others do specific tasks like updating the news and contact pages. But just one admin group per community makes the setup more simple.
  • Local broker group (optional, created by copying the template broker group). This can be for the role of 'neighbourhood' admin. So somebody that can create users and perform specific actions.
  • Local community (system account). Add transaction types for member to system and system to member (contribution, community work payment)
  • Add possible (community specific) transaction fees and account fees.
  • Add possible extra options like member records (e.g. remarks)
  • Customizations (per group filter). layout with css, login page, contact, news page. Upload community logo. Set community logo path in style.css.


Obviously it is important to test the system before going live. It is common practice to setup a pilot system and test with a group of (semi) advanced users.

Especially if you work with a more complex system (with for example different communities, loan groups, database, currencies, vouchers, modules brokers, loan agents) it is important to test all possible actions in the system.

We suggest to start a live (operational) installation always with a clean database and not a database that has test data in it. We did publish a script that will delete all test data like members, transactions, advertisements etc. and leave the configuration (accounts, transaction types etc) as it is. The script (clean_db.sql) can be found in the directory db in the basic install package. When using the clean db script make sure you test the system well before going live.