System - Configurations

From Cyclos4 Wiki
Jump to: navigation, search

Related sub-modules

Content management - Content items, Content management - Themes, System - Languages, Content management - Translations, Messaging - Alerts

Description

The configuration determines how Cyclos looks like, feels and behaves for groups of logged users or for guests. Some examples of options that can be set in a configuration are the language, the address, the address layout, the number format, the mail server and much more.


Also most content management items are bound to a theme. E.g. per configuration you can edit the banners that are visible. These content management items are however edited through the content menu:

Business rules

Configurations are defined in an hierarchical fashion. There is one, hard-coded configuration, which is the system default. This system default configuration is always the root of any configuration tree. When creating a new configuration an existing 'parent' configuration need to be chosen, this can be the system default configuration or any other configuration the admin has the permission to manage. This means that all configurations descend directly or indirectly from the (hard-coded) system default configuration. An admin can chose to inherit the options from the respective 'parent' configuration or customize them (by selecting the edit icon). It is also possible to 'lock' options (by selecting the lock icon), when options are locked lower level configurations cannot change them anymore. Configurations which have child configurations cannot be deleted. Besides that, configurations may be set for specific guests (matching an URL parameter) and/or to specific users (through group and / or group set).

On runtime, always the most specific configuration is used for guests:

  • Specific guest (matching URL parameter), if any
  • System default

For logged users, the group determines the configuration that will be applied. A group has a configuration property; a configuration does not have a group property. A group can only have one configuration and must have a configuration - it may not be null. Groupsets also have a configuration. The groupset's configuration only determines what the default configuration will be in the form for creating a new group. However, the admin may just choose another configuration for this new group. The default configuration when creating a new groupset is always system default. As stated above, a user group can only have one configuration. However, a configuration is always part of a hierarchical configuration tree. A new configuration always needs to extend a higher level one. This means that all configurations in the system are part of a hierarcal configuration tree. The built-in 'global default' configuration is the top of the hierciarchy

Configuration applicabilitly

When viewing Cyclos as guest (not logged in) the configuration that will be applied is determined by the URL (domain or path) the user accesses. The URL/path is defined in the config.
When a user logs in to Cyclos the configuration will be applied that is bound to the group the user. Be aware, it does not take in account the access URL/path defined in the configuration of the user group. A user can login in to a URL/path defined in configuration at a higher level. But the only difference is that he logs in at another URL. What he sees (layout, pages etc) is from the configuration that is bound to his user group.
Example, system with the following two configurations:

  • Config1: bound to group1, URL: www.mybank.com
  • Config2: bound to group2, extends config1, path: www.mybank.com/city
  • A user from group2 can access both domains, www.mybank.com/city and www.mybank.com. And will get the same result once logged in.
  • A user from group1 can access only by URL www.mybank.com
Restrictions
  • It is also possible to set in a configuration 'access only by URL/path'. This means that users can only login at the path (not at higher defined URL/paths).

The advantage of this is that you can restrict specific access (e.g. global admins or Web services access) to a path, wich can be a hard to find path like www.domain.com/sdlf893knd9234rd.

  • The 'access only by URL/path' restrictions, as well as the white lists restriction are applied when a session is established.
  • If a global admin has session he can switch to lower level configurations without the restrictions being applied.

Therefore, when implementing IP and URL restrictions it is important that the higher global admin groups have similar or more restrictive permissions.

Rules for fields (options):
  • By default the value of the higher configuration is shown for each field, an edit icon is shown in the right column next to the field to customize the field.
    • When a field is not customized (thus inherited) an edit icon is shown.
    • When a field is not edited (customized) no lock icon is shown.
    • When the field is customized an revert to inherited value icon is shown.
    • When a field is customized, and not locked, a green unlocked icon is shown.
    • When a field is customized and locked, a yellow locked icon is shown.
    • When a field is locked in a higher configuration a grey lock icon is shown.
  • In the case of the inheritance from a higher configuration of the selected options in a multi-selection field there are only two options:
    • When the field is customized and locked at a higher configuration level all children have to follow the definitions in the parent.
    • When the field is customized and not locked, each following configuration can select among the available options until on one level the field is locked.

Permissions

Page: Configurations list

Security

Roles:

  • Admin.

View permission:

Other permissions:

Page sections

Search page (filters)

Fields Type Rules
New Multi action button When creating a new configuration an existing 'parent' configuration needs to be chosen, this can be the system default configuration or any other configuration the admin has the permission to manage. At clicking the selected option, an empty details page for creating a new configuration opens based on the chosen 'parent' configuration.


Search result (list *)

* Automatically shows all configurations, shown hierarchical and sorted alphabetically by name.

Fields Type Rules
Name Text (read only) The name of the configuration.
Preview Icon Displays the #Active_Configuration for the selected configuration.
Remove Icon Allows the admin to remove the configuration.
  • Only visible if the admin has the System configuration - Manage permission.
  • A configuration can only be removed if it is not used and / or if it doesn´t have children.


Page: Configuration details

Tabs

Security

Roles:

  • Admin.

View permission:

Other permissions:


Details (tab)

Details page

Fields Type Rules
Parent Text (read only) Indicates which is the direct parent configuration of which the new configuration descends from. All configurations are extended directly from another configuration being or the main configuration which is part of the default database (system default), or any other lower level configuration.
  • Not visible for system default.
  • Definition realized in the upper level, when fixed, cannot be changed in a descending configuration.
Name Text The name of the configuration.
  • Required.
  • Must be unique.
  • Max length of 100 characters.
Description Text Describes the configuration in more detail.
Main URL Text The root URL.
  • Needs to be a valid URL. Either URL of the main webapplication including the internalname of the network (e.g. commmunities.cyclos.org/network1) or an 'own' domain resolving to the IP address of the main webapplication domain (e.g. http://www.mydomain.org pointing to communities.cyclos.org)
  • There shouldn't exist 2 configurations with the same combination of root URL.
URL path Text
  • The path from the root URL to distinguish this configuration from others in the same network. For example, if the global default configuration's root path is http://www.server.org, and the network's internal name is 'england', having a path of 'london' will match requests to http://www.server.org/england/london.
  • Cannot contain May only contain letters, digits, dots, minus or plus characters
  • Maximal 50 characters.
  • The following reserved words that cannot be used as path name: cyclos, js, images, content, web-rpc, java-rpc
  • There is no 'path' option in the default network configuration.
Restrict access to this URL Boolean Restricts access to this URL. This means that users of lower / higher level configurations cannot access via another (higher level) configuration.

In case you want to restrict access to specific users/groups, you can create a configuration and bind it to this group. If you use a hard to guess path it will be more difficult for unauthorized users to try to get access (next to the user/password restriction).

  • Only shown for child configurations (not for default configurations)
Used by groups Links Shows the groups currently using this configuration, with links to the details page
  • User that are not logged in (guests) that access with the Root URL or the Path (see above) will get the current configuration
  • Logged users can only access the configurations in which their group is listed.
User data
Session time out Integer The user (browser) session time out in minutes.
Allow users to retrieve forgotten passwords Boolean Allows user to reset their password. When this settings is enabled the users will need to specify a security question upon first login. This question will be needed for future password retrieval.

Currently the user can chose from 3 security questions, which are fixed.

  • What was the name of your first pet?
  • What was the first name of your maternal grandmother?
  • What was the name of your elementary / primary school?

NOTE: Option is only available is e-mail is required to be unique (see setting below)
NOTE: For the forgot option to be visible (at the login page) you need to set a specific setting in 'Data visible to guests' (see further below)

Require e-mail Boolean Determines whether the e-mail is required or not for users with this configuration.
Unique e-mail Boolean Determines whether the e-mail needs to be unique.
  • Only appears in top level configurations (global, network default)

Note! Making the e-mail not unique effectively disables e-mail as an identification method for access or performing / receiving payments in this configuration and its affected children. Please, proceed with caution

Validate e-mail on registration Multi selection Determines whether the e-mail must be validated by the user before an user registration is completed.
  • only visible when Require e-mail is selected
  • Available options:
    • Public registration
    • Registrations by administrators
    • Registrations by brokers
    • Imported users
    • External registrations (web services)
Default email privacy setting Single selection When a user registers or changes his profile he can determine whether to hide or show his email for others. Here the admin can select the default value for this setting. In general for businesses this value will be visible and for consumers it will be hidden. Options:
  • Hidden for other users
  • Visble to other users
Generated login name Boolean Determines whether new users with this configuration will have their usernames automatically generated (when checked) or will need to provide the username manually (when unchecked). When the username is automatically generated, the length will be the maximum set in the field "Username length". The username will be an integer, when the maximum number of digits is reached another digit will be added.
Regular expression for login name Text Defines the regular mask used to validate manually entered usernames.
  • Visible only when checkbox of generated login name is not checked (username generated manually).
  • It uses the standard Java regular expressions http://docs.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html
  • If the webservices are used please do not allow the use of the colon ":", because this is used to separate the user name and password. So don't add "\p" or "\:".
Username length Integer range Determines the minimum and maximum number of characters for usernames.
Localization
Default language Single selection Indicates the default language for the application and data translations.
  • Shows all languages available in the system. New languages can be created in the content management - application translation (see Languages).
  • Required when system default.
Additional languages Multi selection Indicates the additional languages, besides the default, users can choose.
  • Shows all languages available in the system. New languages can be created in the content management - application translation (see Languages).
  • When no additional languages are allowed, the user will be forced to use the default language
Dictionaries Multi selection Allows choosing the dictionaries used for full text indexing / querying
  • Only visible for default configurations (either global or network)
  • Doesn't allows inheriting / locking
  • Shows all records in the dictionaries table (there is no CRUD for it in Cyclos)
  • The default option is the 'unaccent' dictionary, and is shown first
  • Additional dictionaries which are the 2-letter ISO language code, if the language is supported in Cyclos, shows its name (not reading the name from the dictionaries table)
  • When changing this field, all data in the network will be reindexed.
  • This field cannot be changed if a reindex is currently in place.
Country Single selection with all countries Defines the country which will be used as default for address and phones.
  • Required when system default.
Number format Single selection Indicates the way how numbers will be formatted.
  • Required when system default.

Possible values:

  • Comma as decimal separator;
  • Period as decimal separator.
Distance unit Single selection Defines the scale unit used in the calculations of address distances in user / advertisment search.

Possible values:

  • None
  • Kilometer
  • Mile
Date format Single selection Indicates the way how dates will be formatted.
  • Required when system default.

Possible values:

  • day/month/year
  • day-month-year
  • day.month.year
  • month/day/year
  • month-day-year
  • month.day.year
  • year/month/day
  • year-month-day
  • year.month.day
Time format Single selection Indicates the way how the time (hours / minutes) will be formatted.
  • Required when system default.

Possible values:

  • 24 hours
  • 12 hours
List separator Single selection Indicates which separator to use in CSV exports.
  • Required when system default.

Possible values:

  • Comma
  • Colon
  • Semicolon
  • Pipe
Time zone Single selection Indicates the time zone used to display / parse dates.
  • Required when system default.
  • Possible listed values are all obtained from the java library system.
Addresses
Enabled address fields Multi selection Allows to determine the address fields listed in the profile of the groups with this configuration.
  • Available options:
    • Address line 2
    • Neighborhood
    • PO Box
    • Zip Code
    • City
    • Region or State
    • Country
Required address fields Multi selection Allows to determine the required address fields listed in the profile of the groups with this configuration. Only the address fields selected in the optional address fields label will be shown in the list.
Default city Text Allows to define a default city that will show up in the address of each user who inherits the configuration.
Default region or state Text Allows to define a default region or state that will show up in the address of each user who inherits the configuration.
Require address Boolean If checked, when registering a user with this configuration at least one address is required.
Use google maps Boolean If checked, address(es) will be shown with Google maps tool where possible and the distance search filter will be available in the user and advertisment search.
Default address privacy setting Single selection When a user registers or changes his profile he can determine whether to hide or show his address for others. Here the admin can select the default value for this setting. In general for businesses this value will be visible and for consumers it will be hidden. Options:
  • Hidden for other users
  • Visble to other users
Phones
Always show international phone number Boolean If checked the phone number from users having this configuration will always be shown in international notation.
Unique mobile phone Boolean If checked, the phone number must be unique.
  • Enabled by default (set to yes)
  • Only visible on main configuration

Note! Making the mobile phone not unique effectively disables the SMS channel and mobile phone as an identification method for access or performing / receiving payments in this configuration and its affected children. Please, proceed with caution.

Require mobile phone Boolean If checked, at least one mobile phone number from users having this configuration has to be informed at registration.
Require landline phone Boolean If checked, at least one landline phone number from users having this configuration has to be informed at registration.
Enable landline extension Boolean If checked, an extension can be entered for landline phone numbers:
  • When enabled, minimal size 1 digit, maximal length 6 digits.
Default phone privacy setting Single selection When a user registers or changes his profile he can determine whether to hide or show his phone number for others. Here the admin can select the default value for this setting. In general for businesses this value will be visible and for consumers it will be hidden. Options:
  • Hidden for other users
  • Visble to other users
Display
Application name Text The simple name of the current Cyclos instance, or the project it belongs to.
  • Required when system default.
Application description Text A small description for the application. Is the value of the description meta tag (SEO) of the index page
Administration login name Text An identifier to be shown to regular members instead of the name of a specific administrator, since regular members should never know the specific administrator.
  • Required when system default.
Results on autocomplete fields Integer The number of results on fields that use autocomplete (for example, the UserSelectionField).
  • Required when system default.
Maximum results Integer The maximum results that can be shown per request.
  • Required when system default.
  • It is used for:
    • CSVs and reports.
    • External requests.
    • Pages in Cyclos.
      • The number of results that can be chosen on a page are 20, 60, 100 and 200.
      • When set to "100" the client is only allowed to select 20, 60 or 100 results per page, etc.
      • When set to 20 or less the field to set the amount of results per page is hidden.
Maximum users / advertisements on map Integer The maximum result that can be shown on map per request.
  • It is used for:
    • User search
    • Advertisment search
  • Default value: 50
  • Only visible if "Use google maps" selected.
  • If selecting "Use google maps", a maximum number of results has to be informed here.
User format Custom widget Indicates how users will be displayed. Has a separator and fields that can be added to the format.
  • Required when system default.
  • Maximum of 5 items
User short format Custom widget Indicates how users will be displayed when a short format is required, like in SMS notifications.
  • Required when system default.
  • Maximum of 5 items
Maximum left banners Integer When set, indicates the maximum amount of banner sections on the left of the main window (below the menu and notification windows). When there are more banners than the defined maximum, the banners will rotate (change per period).
Maximum right banners Integer When set, indicates the maximum amount of banner sections on the right of the main window. When there are more banners than the defined maximum, the banners will rotate (change per period).
Seconds before rotating banners Integer When set, indicates the time interval the banners rotate, if exceeding the maximum amount of banners.
Use left spaces for guest pages Boolean If selected, the left column of the main window will display the guest page definitions instead of banners.
Default result type for users Single selection Defines which is the default type of results of a user search.

Options:

  • "Tiled boxes";
  • "List with thumbnails";
  • "Regular list. Without thumbnails".
Default result type for advertisement Single selection Defines which is the default type of results of an advertisement search.

Options:

  • "Tiled boxes";
  • "List with thumbnails";
  • "Regular list. Without thumbnails".
Menu type for users Single selection Indicates which menu type(s) is (are) shown for logged users who have this configuration.
  • Required when system default.

Options:

  • Top and left menu (automatic);
  • Top menu only.
Menu type for guests Single selection Indicates which menu type(s) is (are) shown for guests who have this configuration.
  • Required when system default.

Options:

  • Top and left menu (automatic);
  • Top menu only.
Account number (only visible in global or network default configurations)
Define account number Boolean When checked, indicates that account number settings will be defined for this configuration.
  • Hidden (and assumed as checked) for system default.
Enable account number Boolean When checked, indicates that account numbers will be used for the network
Mask Text The mask used for input and formatting of account numbers.

This masks can restrict which characters will be generated, the size and the format, using the following constructors.

  • #, 0 or 9 - A number.
  • a or A - A letter.
  • ? or _ - Any character.
  • l or L - A lowercase letter.
  • u or U - An uppercase letter.
  • c or C - A capitalized letter. (only the first letter will be capitalized. Ex: using ccc on the mask will result in something like Abc)
  • \\, \#, \0, ... - Those literal characters. Remember that, when you write a string, '\\' means a single backslask. To use a backslash on the mask, you need 4 on the string.

An account number example would be: UUU-########

It will generate account numbers like: ABC-12345678

Generation script Single selection Custom script used to generate account numbers
  • Possible options: all scripts of type Account number generation
Script parameters Textarea Parameters passed to the custom script
  • Only visible if there is an account number generation script
E-mails
Define SMTP server Boolean When checked, indicates that SMTP server settings as a whole will be defined for this configuration. The SMTP server settings can be set separatly for any child configuration if it is not locked in the father configuration. If it is locked in the father configuration, the settings will be inherited to any child configuration.
  • Hidden (and assumed as checked) for system default.
Host Text The URL or IP address of the SMTP server.
  • Required.
  • Only visible when 'Define SMTP server' is checked.
Port Number The SMTP port.
  • Required.
  • Only visible when 'Define SMTP server' is checked.
User Text The SMTP user. Not used when empty.
  • Only visible when 'Define SMTP server' is checked.
Password Password The SMTP password. Not used when empty.
  • Only visible when 'Define SMTP server' is checked.
Use TLS Boolean A flag indicating whether the server will use a secure connection.
  • Only visible when 'Define SMTP server' is checked.
From address on sent e-mails Text The address used for sent e-mails. Always visible when the user receives the email.
  • Required when system default.
Display name on sent e-mails Text The displayed name which can be seen in sent e-mails. Always visible when the user receives the email.
  • Required when system default.
Outbound SMS messages
Define outbound SMS Boolean When checked, indicates that SMS gateway settings will be defined for this configuration. It still can be either empty (not used) or enabled (see next option).
  • Hidden (and assumed as checked) for system default.
  • When outbound SMS is not defined, hide SMS options for users in phones and preferences - notifications
Enable outbound SMS messages Boolean When checked, indicates that SMS gateway settings as a whole will be enabled for this configuration. The SMS gateway server settings can be set separatly for any child configuration if it is not locked in the father configuration. If it is locked in the father configuration, the settings will be inherited to any child configuration.
Gateway URL Text Full URL of Gateway
  • Supported variables (built-in) are {number} (the international number), {national_number} national number, {country_code}, {message}
HTTP username Text The username (given by gateway provider)
HTTP password Text The password (given by gateway provider)
HTTP request type Radio POST or GET (depending on the method used by the gateway provider)
Send ASCI characters only Single select Only allow ASCI characters. ASCI characters with accents will be converted to normal ASCI characters.
Character encoding Text This option allows to customize which encoding to use for both request parameters encoding and body.
  • Only visible when 'Send ASCI characters only' is not checked.
SMS sender script Single selection Custom script used to send SMS messages
  • Possible options: all scripts of type Outbound SMS sending
Script parameters Textarea Parameters passed to the custom script
  • Only visible if there is a SMS sender script selected
Maximum global messages per month Integer The the total maximum of SMS for all the users that use this configuration.
Restrictions
Maximum upload size File size The maximum size accepted for uploads.
  • Required when system default.
Maximum image dimensions Dimensions The maximum dimensions for uploaded images. Images larger than these will be resized.
  • Required when system default.
Maximum medium thumbnail dimensions Dimensions The maximum dimensions for generated medium thumbnails.
  • Required when system default.
Maximum small thumbnail dimensions Dimensions The maximum dimensions for generated small thumbnails.
  • Required when system default.
Maximum PNG images size File size The maximum size accepted for PNG images. PNG images larger than this size will be converted to JPEG.
  • Required when system default.
Purge messages on trash after (days) Time interval ??? TODO: ask programmer why "Time interval" is not used. When set, messages in trash will be removed after the indicated number of days.
  • Only visible for configurations used for logged users.
  • When not set the message will never be removed.
Purge notifications after (days) Time interval When set, notifications will be removed after the indicated number of days.
  • Only visible for configurations used for logged users.
  • When not set the notifications will never be removed.
Purge unconfirmed user registrations after (days) Time interval When set, pending users which didn't confirm the registration (for example, via e-mail) will be removed after the indicated number of days.
  • Only visible for configurations used for logged users.
  • When not set the pending users will never be removed.
Maximum invalid login name attempts Integer When set, indicates that a system alert is generated whenever the same IP address tries to login with invalid login names (to flag brute force attacks).
  • Only visible for configurations used for guests.
After failing usernames, block remote IP for Time interval When set, indicates that after attempting to login with invalid login names more times than specified in 'Maximum invalid login name attempts' within the last hour, the remote address should be prevented to login for the given time interval (to prevent brute force attacks).
  • Only visible for configurations used for guests.
Alerts
Given very bad references Integer When set, an user alert is generated when a member gives the defined amount of very bad references.
  • Only visible for configurations used for logged users.
Received very bad references Integer When set, an user alert is generated when a member receives the defined amount of very bad references.
  • Only visible for configurations used for logged users.
Data visible to guests
Visible user groups Multi selection Allows defining groups / group sets visible to guest users.
  • List of all possible groups and group sets.


warning: Note that by definition only group(set)s visible to the logged user are shown. There is however a difference between view mode and edit mode: in the view mode the configuration is shown as is. This will include groups which are invisible to the logged user. In the edit mode (after clicking the edit icon) only groups visible to the logged user are included in the MultiSelectBox. This means that groups invisible to the logged user will disappear. The reason for this in this way the user cannot select or unselect a group which is invisible to him.

Show the forgot password option in login Boolean When marked forgot password option is shown in the login page under the link 'Click here if you have problems logging in'
  • Be aware that for a user to be able to retrieve a password the group also needs to have configuration that has the 'forgot password option enabled (see section user data: Allow users to retrieve forgotten passwords )
Visible profile fields Multi selection Allows defining what profile fields a guest can see.
  • List of all possible user fields in the network.
Possible groups for public registration Multi selection Defines which groups can be used on public registration for guest users.
  • List of all possible groups.


warning: See warning at previous item.

Visible advertisement category sets Multi selection Indicates which advertisement category sets are visible to guest users.
  • List of all possible category sets.
Show simple ads Boolean Shows advertisements (marketplace) function
Show web shop ads Boolean Shows advertisements (marketplace) function, including web shop ads
Custom users search menu label Text Defines the label used in the menu for user search for guests.
Custom advertisement search menu label Text Defines the label used in the menu for advertisement search for guests.
Logging
Logging directory Text
Maximum size per file Integer
Maximum error log entries Integer Defines the maximum of error log entries. Zero means unlimited. It can only be set in a global configuration.
Maximum rotating files per log Integer
Enable services logging Check box
Log parameters on services Check box
Log results on services Check box
Log services for guests Check box