Simple Groupware Manual

Table of contents

  1. About Simple Groupware
  2. Why Open Source?
  3. Features
  4. Screenshots
  5. Requirements
  6. Installation
  7. Installation SyncML Server
  8. Update
  9. Extension Manager
  10. Content Management
  11. WebDAV server
  12. SyncML integration
  13. Offline folder synchronization
  14. Desktop Integration
  15. Data Handlers / Data Import
  16. Data Export and URL parameters
  17. Using modules and keyboard shortcuts
  18. Users / Groups
  19. Backup / Restore
  20. System tasks
  21. System configuration
  22. System monitoring
  23. Folder templates
  24. LDAP / Active Directory integration
  25. SOAP Server
  26. Customization
  27. Customization FAQs
  28. Extension Development
  29. Translation / localization
  30. Speedup techniques
  31. Roadmap
  32. sgsML Tutorial
  33. sgsML Reference Guide
  34. sgsML Extended Attributes
  35. sgsML Frequently asked questions / FAQ
  36. Frequently asked questions / FAQ
  37. Support



Links


Short URLs

Here are some short URLs for the most important pages:


About Simple Groupware

Simple Groupware & Content Management System is a complete open source enterprise groupware offering email, calendaring, contacts, tasks, document management, synchronization with cell phones and Outlook, full-text search and many more.

Simple Groupware combines standards like RSS, iCalendar, vCard, IMAP, POP3, SMTP, CIFS, CSV, WebDAV, LDAP and SyncML under one platform.

Simple Groupware features the latest aspects concerning collaboration, document management, event-driven notification, information sharing, knowledge management, helpdesk and customer relationship management, accounting and project management. Simple Groupware is a free groupware written in PHP.

Unlike other PHP or Java groupware applications, Simple Groupware contains the programming language sgsML to enable the quick customization and creation of powerful web applications. Simple Groupware is Free Software, released under the GNU GPLv2 License.

Simple Groupware Solutions is a small German one-man company, founded in September 2003. The business domain is focused on individual services and software development. Simple Groupware is developed in my free time and offered to you for free.


"simple" means:

  • simple installation (only one form)
  • simple update (just a few clicks)
  • simple usage (all modules share a consistent look & feel)
  • simple to adapt to your needs (see sgsML)
  • simple to install extensions from the open source community
  • but not simple in functionality


With Simple Groupware web applications:

  • can be created much faster
  • are easier to maintain
  • contain less errors
  • are easier to write
  • are much smaller in size
  • feature a consistent look


With Simple Groupware You can:

  • build powerful web applications in minutes
  • change web applications in seconds
  • decrease time for implementing and deploying
    web applications by a factor 10, compared to the usual solutions
  • keep costs for maintenance and change
    management to a new minimum


Why Open Source?

<< contents

What is Open Source?

  • Free distribution
  • Source code
  • No license costs, only customizing
  • No forced updates
  • No deployment limits
  • Widely used (production approved, very stable)
  • Open minded, community driven
  • Everybody can contribute and participate
  • Collaborative and social

Why web technology?

  • Latest technology
  • Continuous improvement (Web 2.0, HTML5)
  • Efficient
  • Simple interface
  • Available on all devices (desktop, mobile, tablet)
  • Barrier-free
  • Centralized
  • High performance, scalable (Wikipedia, Facebook)
  • Powerful and robust
  • Open Source (Firefox, Apache, PHP, MySQL)

Why web publishing?

  • flexible
  • consistent
  • active content
  • dynamic pages
  • cross media
  • multi channel
  • multimedia

Why Simple Groupware & CMS?

  • Open Source
  • Web technology
  • Web publishing
  • + Free documentation
  • + Free support

Numbers?

  • SourceForge.net (2.600.000 users, 240.000 projects
  • Github (419.000 users, 1.292.000 repositories)
  • more numbers!


Common issues?

  • What happens when development of a project stops?
    • new community and/or project(s) come up as forks (see MySQL forks)
    • commercial development always possible
  • What happens when support of a project stops?
    • new community takes over support
    • commercial support always possible
  • Free software has no value?
    • Free software reduces costs
    • Free software enables new processes
    • Free software enables new business models
    • Value is generated by customization and user acceptance
  • I use commercial software because competitors can also use Open Source software?
    • Competitors can also use commercial software
    • In most cases, movement to Open Source creates advantage in competition
      • less money for software
      • more money for training courses
      • more money for better products and services


Features

<< contents

General


  • 100% web-based application (no special client applications or plugins required)
  • Offline support for all modules and files directly inside the browser
  • Complete secure communication using SSL
  • Easy and intuitive user interface
  • One platform for managing, controlling and developing business processes
  • Autonomy: Simple Groupware is fully driven with open technologies
  • Individuality: All hierarchical organization structures and responsibilities can be represented and managed in the application
  • Intelligent knowledge management: e.g. find everything faster using phonetic fulltext search algorithms and automatic file / content indexing
  • Multi-language support including right-to-left layout
    (Your help is welcome to provide more translations!)
  • Support for working in different time zones
  • Unicode: Simple Groupware fully supports Unicode characters using UTF-8
  • Low hardware requirements: shared-hosting and vServer is ok!
  • Notifications: get notified by E-mail or RSS when entries are created, changed or deleted, get reminders for appointments, tasks, birthdays, etc.
  • Content management with the PmWiki engine and Smarty templates
  • Mass edit for any subset of entries
  • All information can be easily sorted and filtered by any custom criteria
  • Support for MySQL, PostgreSQL and SQLite (Oracle Database until end of 2010)
  • Easy installation with a small single-file installer
  • Automatic update management for database structures
  • Integrated update procedure with just 4 clicks to update to the latest version
  • 100% Open source: Free Software, released under the GPLv2, Free Support, Free Documentation, released under the GNU FDL.


Modules included


Modules can be assigned to every folder in the tree structure. For example, you can have as many calendars as you like.
Individual permissions (read, write, admin) can be assigned to users and/or groups for every folder. If required, rights can be also assigned to single entries.
Every user can create his own folder structure. By assigning individual rights you can share any information among all users and groups.

  • Calendar
  • Contacts
  • E-mails
  • Tasks
  • Files
  • Notes
  • Passwords
  • Bookmarks
  • Portal
  • Chat
  • FAQ
  • News
  • Forum
  • Gallery
  • Projects
  • Statuses
  • Templates
  • Categories
  • Inventories
  • Resources
  • Brands
  • Locations
  • Distributors
  • Device types
  • HTML docs
  • Wiki docs
  • Offices
  • Positions
  • Companies
  • Departments
  • Contact groups
  • Contact activities
  • Spreadsheets
  • Graphviz
  • Users
  • Groups
  • Events
  • Backups
  • Rights
  • Search
  • Statistics
  • Mail identities
  • IMAP
  • POP3
  • SMTP
  • RSS
  • vCard
  • CIFS
  • Google Docs
    (new in 0.722)
  • LDIF contacts
  • LDAP contacts
  • XML contacts
  • CSV contacts
  • Firefox bookmarks
  • CSV calendar
  • iCalendar (iCal)
  • Local Files
  • Helpdesk / TTS
  • Expenses
  • Timesheets
  • Absence (new in 0.730)
  • HR Contracts (new in 0.730)
  • Surveys
  • CMS (PmWiki)
  • Intranet (PmWiki)

The portal module serves as a customizable overview page (often called dashboard) which can hold summaries of other folders, webpages or Google Widgets.
The search module offers a global (phonetic) search through all folders for all kinds of items.
The calendar module offers day, week, month, year and Gantt views, recurring events, customizable categories, file attachments, etc.
The tasks module automatically highlights late tasks and offers open, closed and calendar views including Gantt diagrams as well as file attachments. Mails and attachments can be directly copied and converted into tasks.
The IMAP, POP3 and SMTP modules turn Simple Groupware into an E-mail client for an unlimited number of accounts. Simple Groupware supports server based sorting and searching in IMAP folders. Mails can be shared by copying/moving them from IMAP/POP3 to the database and back.
The users and contacts module also offer calendar views for displaying birthdays and anniversaries.


Extensions


Similar to Firefox add-ons or mobile application stores, Simple Groupware contains an extension manager which allows you to:

  • use free contributions from the open source community
  • extend and customize Simple Groupware
  • install extensions with 2 clicks
  • get the functionality that best suits your needs


Personalization


Every user can:

  • create his own folder structure
  • create customizable overview pages
  • integrate his own RSS feeds
  • define individual notifications
  • merge other (public) folders with his personal folders


Languages


Simple Groupware includes support for the following languages:

  • English
  • English (UK)
  • German
  • Brazil/Portuguese
  • Portugal/Portuguese
  • Greek
  • Croatian
  • Czech
  • Danish
  • Dutch
  • Ukrainian
  • French
  • Hungarian
  • Italian
  • Russian
  • Polish
  • Slovak
  • Spanish
  • Swedish
  • Turkish
  • Chinese (Simplified)
  • Arabic
  • Indonesian
  • Finnish
  • Japanese


Synchronization of contacts, tasks, notes and appointments


Integration with Funambol SyncML Server (push email, contacts, calendars, tasks, notes):

  • Synchronization using free SyncML clients on Windows Mobile, Blackberry, Outlook, Palm, iPod, iPhone, Gmail, Yahoo, Lotus Domino, Evolution, Thunderbird
  • Synchronization using a free JavaME client (supported by most newer phones from Motorola, Nokia and Sony Ericsson)

Also included: Builtin offline support for all HTML5 compatible browsers on any mobile phone or computer.


Security Features


  • Download restriction for bad file extensions (.exe, .com, .hta, .cpl, etc.)
  • Automatic filter for bad HTML (Javascript, ActiveX, Java Applets, etc.) and Cross-site scripting (XSS)
  • Protection against new methods like Zero-Byte masking, Email header injection, Session hijacking (IP binding to session), Cross-Site Request Forgery (CSRF)
  • Integrated Denial of Service (DoS) protection
  • IP blocking in case of too many bad login attempts
  • Flexible user authentication
  • Individual rights for every folder given to users and/or groups
  • Special algorithms and design to protect against SQL injections and Register_Globals attacks
  • All files can be automatically checked by a virus scanner (e.g. using BitDefender, McAfee, F-Prot, etc.)


Data Integration / Import


Get a new system, convert or migrate all your data? No.
With Simple Groupware you can seamlessly integrate any existing infrastructure:

  • Keep your mail-system using IMAP, POP3 and SMTP accounts (including SSL/TLS)
  • Mail servers tested with Simple Groupware: Courier-IMAP, Cyrus IMAP, Dovecot, Postfix, qmail, Gmail, UW IMAP, hMailServer, MS Exchange
  • Integrate appointments from iCalendar files
  • Access your file-servers directly within Simple Groupware (e.g. Samba, Windows, NetApp, Google Docs, Google Drive)
  • Integrate contacts from vCard files, Thunderbird, Outlook, LDAP / Active Directory
  • Integrate news using RSS feeds
  • Integrate PmWiki page stores
  • Integrate Firefox bookmarks
  • Integrate data from CSV files using Simple Spreadsheet
  • Integrate and access data with the integrated SOAP server
  • View addresses with Google Maps or call contacts with Skype

Once integrated, data can be exported again to XML, CSV, HTML, RSS, iCalendar, vCard, LDIF. For example, you can directly view your Calendar with Mozilla Sunbird. Integration with other relational databases or other data sources can be done using the data handlers api.


Flexible User Authentication


  • Keep your old system(s) and manage only one user database
  • Authenticate using built-in methods of Apache (e.g. Basic, NTLM, etc.)
  • Use NTLM, LDAP (incl. groups), Active Directory (incl. groups), Google Apps, IMAP, POP3 and SMTP to authenticate users (including SSL/TLS)
  • User self registration (not enabled by default)
  • Others (like ODBC) can be added using the authentication api


Content Management


  • Enterprise content management with the PmWiki engine and Smarty templates
  • Very easy and highly extendable Wiki markup
  • Individual templates for every page
  • Static caching: best performance for handling high traffic web sites
  • Multi-user authentication: individual permissions for every page, ideal for Intranets or Extranets pages
  • Media file management with Simple Groupware document management
  • Full support for the PmWiki plugin architecture


Document Management


The files module makes it possible to share files, keep versions of files, manage folders with individual permissions for users/groups, etc. If required, permissions can be also set to single files as an addition to folder permissions. Files can be locked/unlocked for exclusive editing (checkin / checkout).

  • All kinds of documents can be managed centralized and secure
  • Special text indexing algorithms and external converting tools offer automatically searching through MS Office and OpenOffice documents as well as PDF documents and media files (e.g. exif headers in images, id3 tags in mp3)
  • Typical files from Open Office and Microsoft Office can be previewed in the web-browser (.pdf, .doc, .xls, .ppt, .odt, .ods, .odp, .docx, .xlsx, .pptx, etc.)
  • Typical images can be previewed in the web-browser (.tif, .bmp, .eps, etc.)
  • Multimedia files can be played directly in the web-browser (.mp3, .flv)
  • All files can be automatically checked by a virus scanner (e.g. using BitDefender, McAfee, F-Prot, etc.)
  • Files from existing file servers can be directly accessed (Samba, Windows, NetApp, Google Docs / Google Drive, etc.)
  • Custom meta data can be saved along with all kinds of files on an existing file server
  • Drag-and-drop upload for files and URLs to files (HTML5)


GUI components & user interface


The user interface offers:

  • drag and drop
  • compatibility to all favorite browsers (Firefox, Safari, IE, Chrome, Opera)
  • optimization for mobile devices (iPhone, iPad, Android)
  • consistency over all modules
  • easy and intuitive learning
  • flexible layout customization with themes

The Simple Groupware user interface includes the following components:

  • ExtJS Grid
  • TinyMCE: HTML editor, enabling WYSIWYG
  • Simple Spreadsheet: Spreadsheet editor and data import tool
  • Codepress: Code editor
  • Tigra Calendar: Date pickup


Customizing


The more individual you are, the more you will like Simple Groupware:

  • Customizing without overwriting files
  • Changes can be made persistent over updates
  • Theme support (skins): layout customization of colors, text styles, etc.
  • Existing Modules can be expanded and fully customized using sgsML
    (simple groupware solutions Markup Language = XML-based language for defining web applications at lowest expenses)
  • New Modules can be easily created using sgsML
  • New handlers for indexing, converting and previewing can be easily added using the file-handler api
  • Custom PHP functions can be used directly to display content
  • Layout can be customized with Smarty templates


Personal Knowledge Management


All your information is inside the head of your employees. Keep it there using:

  • Personal and global bookmark management
  • Individual composing of small notes
  • Add comments and extra files to your e-mails
  • Private, public and team calendars
  • Mark special entries with colors
  • Visualize diagrams with builtin support for Graphviz


Administrative Workflows


Administrative workflows can kill a lot of time and money. To reduce these costs you can:

  • Manage resources like rooms, computers, beamers, etc. inside one application
  • Administrate a complete IT-Support using the ticket-, resource- and inventory-system
  • Future: Represent all kinds of administrative workflows


System management


  • Create and restore backups of folders
  • Manage open user sessions
  • View all kinds of system events (logins, performance and system problems)
  • Get statistics about page views, uploads, downloads, logins, etc.
  • View database processes, table sizes and status variables
  • Manage trashed contents (deleted datasets, deleted files)
  • Administrate the system with integrated SQL and system consoles (best practice for shared hosting)


More features are coming up in the future, see the Roadmap.


Screenshots

<< contents

Extensions: (available on the Extension Manager)

Simple Groupware Extensions - Compose Html Emails
Compose Html Emails
Simple Groupware Extensions - Task Ratings
Task Ratings
  
Simple Groupware Extensions - Private Items
Private Items
Simple Groupware Extensions - Mini Tasks
Mini Tasks

View more ...



Latest features (version 0.7x):

Simple Groupware SQL Console - Vertical mode
SQL Console - Vertical mode
Simple Groupware Google Docs
Google Docs
Simple Groupware Console module
Console module
Simple Groupware Customization bar
Customization bar
Simple Groupware Create new menu
Create new menu
Simple Groupware Multi spreadsheet import
Multi spreadsheet import
Simple Groupware Intranet module
Intranet module
Simple Groupware Lookup paging
Lookup paging


Latest features (version 0.6x):

Simple Groupware Free/busy view for locations
Free/busy view for locations
Simple Groupware Unattended update
Unattended update
Simple Groupware Play Flash Video
Play Flash Video
Simple Groupware Play MP3
Play MP3
Simple Groupware Login
Login
Simple Groupware Minimal folder structure
Minimal folder structure
Simple Groupware ExtJS grid
ExtJS grid
Simple Groupware Drag and drop
Drag and drop
Simple Groupware Surveys
Surveys
Simple Groupware Quick add
Quick add
Simple Groupware Extension Manager
Extension Manager
Simple Groupware Install an extension
Install an extension

Latest features (version 0.53x): Mobile user interface (iPhone, ipod Touch, Nokia, etc.)


Simple Groupware Mobile user interface - Portal
Portal
Simple Groupware Mobile user interface - Search
Search
Simple Groupware Mobile user interface - Actions
Actions
Simple Groupware Mobile user interface - Portal (horizontal)
Portal (horizontal)
Simple Groupware Mobile user interface - Email (horizontal)
Email (horizontal)
Simple Groupware Mobile user interface - New item
New item
Simple Groupware Mobile user interface - Email
Email
Simple Groupware Mobile user interface - Select subfolder
Select subfolder

Latest features (version 0.5x):

Simple Groupware HTML E-mails
HTML E-mails
Simple Groupware Installer
Installer
  
Simple Spreadsheet Offline Synchronization
Offline Synchronization with Firefox
Simple Groupware Graphviz module
Graphviz module

Latest features (version 0.4x):

PmWiki & Simple Groupware Frontend
PmWiki & Simple Groupware Frontend
Simple Groupware Synchronization with Thunderbird/Lightning
Synchronization with Thunderbird / Lightning
  
Simple Spreadsheet embedded (editor)
Simple Spreadsheet embedded (editor)
Simple Spreadsheet embedded (viewer)
Simple Spreadsheet embedded (viewer)
  
Simple Groupware PmWiki Content Management
PmWiki Content Management
Simple Groupware PmWiki Content Management #2
PmWiki Content Management #2
  
Simple Groupware sgsML Ajax refresh
sgsML Ajax refresh
Simple Groupware Code editor CodePress
Code editor CodePress
  
Simple Groupware folder merging
Folder merging
Simple Groupware SQL console
SQL console (incl. auto complete)

Latest features (version 0.29x):

Simple Groupware WebDAV file server
WebDAV file server
Simple Groupware WebDAV file versioning
WebDAV file versioning
  
Simple Groupware Helpdesk
Helpdesk
Simple Groupware Helpdesk - Details
Helpdesk - Details
  
Simple Groupware Direct file server access (CIFS) - Meta data inclusion
File server access (CIFS) - Meta data
Simple Groupware Direct file server access (CIFS) - Meta data inclusion
File server access (CIFS) - Meta data
  
Simple Groupware RSS feed with layout
RSS feed with layout
 

Calendar

Simple Groupware Calendar - Gantt view
Calendar - Gantt view
Simple Groupware Calendar - Gantt view colors
Calendar - Gantt view colors
  
Simple Groupware Synchronization with Outlook
Synchronization with Outlook
Simple Groupware Synchronization with Windows Mobile
Synchronization with Windows Mobile
  
Simple Groupware Calendar - Day view
Calendar - Day view
Simple Groupware Calendar - Week view
Calendar - Week view
  
Simple Groupware Calendar - Merge folders
Calendar - Merge folders
Simple Groupware Calendar - Using colors
Calendar - Using colors

View more ...


E-Mail

Simple Groupware E-Mails (auto-collapse quoted parts)
E-Mails (auto-collapse quoted parts)
Simple Groupware E-Mails
E-Mails
  
Simple Groupware E-Mails Details
E-Mails Details
Simple Groupware E-Mails (with IMAP)
E-Mails (with IMAP)

Tasks

Simple Groupware Tasks - Gantt view
Tasks - Gantt view
 
  
Simple Groupware Tasks
Tasks
Simple Groupware Synchronization with Outlook (tasks)
Synchronization with Outlook (tasks)

Notes

Simple Groupware Notes
Notes
Simple Groupware Synchronization with Outlook (notes)
Synchronization with Outlook (notes)

Files

Simple Groupware Document locking
Document locking
 
  
Simple Groupware Documents
Documents
Simple Groupware Direct file server access (CIFS)
Direct file server access (CIFS)
  
Simple Groupware Preview for PDF documents
Preview for PDF documents
Simple Groupware Preview for MS Word Documents
Preview for MS Word documents
  
Simple Groupware Preview for vCard files
Preview for vCard files
Simple Groupware Preview for iCalendar files
Preview for iCalendar files

View more ...


Contacts

Simple Groupware Contacts Skype integration
Contacts Skype integration
Simple Groupware Contacts birthday calendar
Contacts birthday calendar
  
Simple Groupware Contacts with new icons
Contacts with new icons
Simple Groupware Synchronization with Outlook
Synchronization with Outlook
  
Simple Groupware Synchronization with Windows Mobile
Synchronization with Windows Mobile
Simple Groupware Contacts from LDAP / Active Directory
Contacts from LDAP / Active Directory

View more ...


Other modules

Simple Groupware Portal with Google Gadgets
Portal with Google Gadgets

Google Universal Gadgets
  
Simple Groupware Spreadsheets
Spreadsheets
Simple Groupware Chat
Chat
  
Simple Groupware Portal
Portal
Simple Groupware Forum
Forum
  
Simple Groupware Photo gallery
Photo gallery
Simple Groupware Templates
Templates

View more ...


General

Simple Groupware - Update process 1/3
Update process 1/3
Simple Groupware - Update process 2/3
Update process 2/3
  
Simple Groupware - Update process 3/3
Update process 3/3
 
  
Simple Groupware Theme tree icons
Theme tree icons
Simple Groupware Users birthdays / anniversaries
Users birthdays / anniversaries
  
Simple Groupware - E-Mail reminder (individual)
E-Mail reminder (individual)
Simple Groupware - E-Mail reminder (daily summary)
E-Mail reminder (daily summary)
  
Simple Groupware E-Mail notification
E-Mail notification
Simple Groupware E-Mail notification
E-Mail notification
  
Simple Groupware User interface - Content pane
User interface - Content pane
Simple Groupware Login screen
Login screen
  
Simple Groupware Filter engine
Filter engine
Simple Groupware Search inside files
Search inside files
  
Simple Groupware Search with wildcards
Search with wildcards
Simple Groupware Phonetic search
Phonetic search

View more ...


Administration

Simple Groupware Administration overview
Administration overview
Simple Groupware System console
System console
  
Simple Groupware SQL Console
SQL console
Simple Groupware Built-in event monitoring
Built-in event monitoring

View more ...


Screenshots - Client


Simple Groupware Client with helpdesk
Client with helpdesk
Simple Groupware Client with calendar
Client with calendar
  
Simple Groupware Client with files
Client with files
Simple Groupware Client with e-mails
Client with e-mails
  
Simple Groupware Client with Windows
Client with Windows
Simple Groupware Client with Ubuntu Linux
Client with Ubuntu Linux
  
Simple Groupware Client with ActiveSync
Client with ActiveSync
Simple Groupware Sync with Windows Mobile
Sync with Windows Mobile


Note: The (Rich-)client has been replaced by the offline synchronization included in the web interface.


Screenshots - Platforms


Windows

Simple Groupware with Safari 3.0
Simple Groupware with Safari 3.0
Simple Groupware with Firefox 2.0
Simple Groupware with Firefox 2.0
  
Simple Groupware with Firefox
Simple Groupware with Firefox
Simple Groupware with Opera
Simple Groupware with Opera

MacOS

Simple Groupware with MacOS Safari
Simple Groupware with Safari
Simple Groupware with MacOS Firefox
Simple Groupware with Firefox

Linux

Simple Groupware with Firefox (SuSE)
Simple Groupware with Firefox (SuSE)
Simple Groupware with Firefox (Ubuntu)
Simple Groupware with Firefox (Ubuntu)


Requirements

<< contents

Simple Groupware has very low system and hardware requirements. All required software components are for free, so you only need to spend some efforts in customization. This will, of course, cost some money, but at a lower price compared to most other systems.


Requirements for the server


  • Operating system: Linux, Windows, Solaris, FreeBSD, MacOS, etc.

    For reasons of performance and maintainability, my recommendation is Debian or Ubuntu Linux. In general, you can use any kind of operating system which is capable of running PHP on a web-server, but Simple Groupware is only tested on Linux and Windows.
  • Apache 2.x and newer / IIS 7 and newer / nginx 1.x and newer

    I recommend Apache 2.2 or later. Apache is very stable, well documented and is available on all platforms.
  • PHP: 5.3.0 and higher

    If PHP is used in (Fast-)CGI mode, please use a newer version like PHP 5.2.4.
  • Database: at least MySQL 5, MariaDB 5, PostgreSQL 8.2, SQLite 3.0

    I recommend using MySQL 5.x. Version 4.0 and 4.1 are no longer supported by MySQL (see this page). Version 5.0 has better performance for schema updates, better unicode support and it includes some great new features like views, stored procedures and triggers.

    Note: Support for Oracle Database will was dropped in 2010.
  • CPU: 1 GHz or more
  • RAM: 512 MB or more
  • Hard disk: 1 GB or more

    The initial disk usage including caches is 75 MB, the database (MySQL) needs 250 KB to get started.


Hardware
For testing you can start with a desktop machine or a notebook. The exact hardware requirements depend on the number of (power-)users and how frequently the system is used by them. With many users, you might use a dedicated server for the database and increase the amount of RAM and CPUs. You can also increase the number of web servers and database servers. When doing performance tests, please make sure to disable DoS protection in setup settings.

Customization
Since Simple Groupware is Open Source, you are not restricted to a special company. If you need special customizations for your business or some extra support level, you can easily hire the programmer or company of your choice.

Security
It is recommended to install the latest security updates for the operating system and its components (Apache / PHP / MySQL).
Using a shared hosting platform can cause unwanted downtime, resource fluctuation, and security problems.
If you want to provide better security for your data, use a dedicated server and make sure to limit physical access to a limited number of people.


Requirements for the client


Simple Groupware is a web-based application that fully runs inside a web-browser.


Supported browsers

  • Firefox 3.x and higher

    It runs on most popular operating systems like Windows, MacOS and Linux. Furthermore it is free and can be run without an installation.
    Firefox is used for testing, development and support. Other browsers like Internet Explorer, Opera, Safari or Konqueror don't provide all the features (e.g. the WYSIWYG-editor) or have limitations in the layout.
  • Chrome 9.x and higher

    Chrome also runs on most popular operating systems. It is very fast, reliable and has no limitations on the layout. If you trust Google, choose it!
  • Opera 9 and higher

    Opera runs much better than other browsers on machines with slower CPUs and/or less RAM. Therefore Opera is recommended on slower machines.
  • Safari 3.x
  • Internet Explorer 7.0 and higher


Browser configuration

  • Javascript needs to be enabled
  • Cookies need to be accepted
  • NOT required: Flash, Java, ActiveX


Installation

<< contents

Simple Groupware is a 100% web-based application. All required components are installed on the server. The client only needs a web-browser. This page describes how to set up the server. The Simple Groupware setup will check permissions, verify the system configuration, and create the database structure automatically.
If you need synchronization on the client, please take a look at SyncML integration or offline synchronization.


MySQL / MariaDB (5.x recommended)


If the user is not root, make sure the user has the following privileges on the Simple Groupware database:

  • Data: SELECT, INSERT, UPDATE, DELETE
  • Structure: CREATE, ALTER, INDEX, DROP, CREATE VIEW
  • Administration (optional): PROCESS

The setup will try to create the database if it doesn't exist. In this case, the user needs the privilege to create databases. For more information about privileges in MySQL, see the online manual. If you're getting "Access denied" errors from the database, you might this page. Experts can optimize MySQL performance with this tool.


PostgreSQL (8.3.x recommended)


When using PostgreSQL instead of MySQL, please make sure to create a database with "UTF8" set in the encoding, or provide the super user credentials so that the database is created automatically.
When using PostgreSQL 8.1/8.2, the "tsearch2" fulltext extension needs to be installed in the database before running the Simple Groupware installation. If you haven't selected "tsearch2" during the PostgreSQL installation, you need to create the database manually and execute the queries from "<postgresql>/share/contrib/tsearch2.sql" using pgAdmin3. The path may be different in your Linux distribution (e.g. /usr/share/postgresql/8.x/contrib/), please check the manuals from your distribution.


SQLite (3.x recommended)


The SQLite database gets automatically created at "<sgs-dir>/simple_store/sqlite3_<database-name>.db". Since SQLite has no authentication, the fields hostname, username and password can hold any non-empty value. The database administration can be done with SQLite Administrator. Please make sure to install the PDO driver for SQLite v3.


Oracle (10.x recommended, support discontinued by the end of 2010)


When using Oracle instead of MySQL, the database doesn't get automatically created. Therefore you need to create an empty database with the Oracle administration tools and give the user the roles "Connect" and "Resource" and the privilege "Create view". The database structure is created automatically by Simple Groupware.
Moreover, you need to set the system environment variable "NLS_LANG" to "AMERICAN_AMERICA.AL32UTF8".
When using Simple Groupware versions before 0.301, please make sure that your php.ini uses the right variables_order to register the environment variable properly:
variables_order = "EGPCS"


nginx (1.x recommended)


Beginning with release 0.721, nginx can be used as web server running PHP in FastCGI mode. A sample configuration is included in "<sgs-dir>/tools/nginx/nginx.conf". Please make sure to use spawn-fcgi instead of calling php-cgi -b xxx directly.


Installation with Linux (Debian 4/5/6)


  • Note: When using a hosted platform, you can skip the next three steps
  • Install the missing packages:
    apt-get install catdoc ppthtml imagemagick unzip xpdf-utils mp3info exiv2 graphviz apache2.2-common libapache2-mod-php5 php5-gd php-apc
    apt-get remove php5-suhosin
    with MySQL (Debian 5): apt-get install php5-mysql mysql-server-5.0
    with MySQL (Debian 6): apt-get install php5-mysql mysql-server-5.1
    with MySQL (Ubuntu): apt-get install php5-mysql mysql-server-5.5
    with PostgreSQL: apt-get install php5-pgsql postgresql-8.4
    with SQLite: apt-get install php5-sqlite
    with Java (Ubuntu server): apt-get install gcj-4.6-jre-headless
    with Java (Debian): apt-get install gij
  • Uncomment ";extension=gd.so" in /etc/php5/apache2/php.ini (Debian 4 only)
  • Restart Apache (/etc/init.d/apache2 restart)
  • Make sure you have MySQL (or PostgreSQL / none for SQLite) and Apache running
  • Download the Simple Groupware installer here
  • Create a new directory under your document root and make it world writable
    (e.g. /var/www/sgs/)
  • Extract the .gz-file (e.g. to /var/www/sgs/)
    (You should now have an existing file like /var/www/sgs/sgs_installer.php)
  • If your server is not connected to the internet, please download the latest version of Simple Groupware (tar.gz) here and place the archive next to "sgs_installer.php".
  • Open your browser and go to: http://your_server/sgs/sgs_installer.php.
    You should now see a page with the title "Simple Groupware Installer".
    Choose your version and click "Install". After the download has finished, click "Continue".
  • Then choose your language. After translations are built, click "Continue".
  • Type in your database credentials
  • Type in your super administrator credentials
  • Confirm the GPLv2 and click "Install"
  • In the next screen click "Continue"
  • Enjoy Simple Groupware!


Installation with Linux (SuSE 10.1)


  • Make sure you have installed MySQL (or PostgreSQL), Apache, Php, Php-gd, Php-zlib
  • Download the Simple Groupware installer here
  • Create a new directory under your document root and make it world writable
    (e.g. /srv/www/htdocs/sgs/)
  • Extract the .gz-file (e.g. to /srv/www/htdocs/sgs/)
    (You should now have an existing file like /srv/www/htdocs/sgs/sgs_installer.php)
  • If your server is not connected to the internet, please download the latest version of Simple Groupware (tar.gz) here and place the archive next to "sgs_installer.php".
  • Open your browser and go to: http://your_server/sgs/sgs_installer.php.
    You should now see a page with the title "Simple Groupware Installer".
    Choose your version and click "Install". After the download has finished, click "Continue".
  • Then choose your language. After translations are built, click "Continue".
  • Type in your database credentials
  • Type in your super administrator credentials
  • Confirm the GPLv2 and click "Install"
  • In the next screen click "Continue"
  • Enjoy Simple Groupware!


Installation with Linux (Amazon Linux AMI, EC2, no RDS)


  • Create a new EC2 instance (Amazon AMI Linux)
  • Assign a new IP address:
    In AWS Management Console, click on "Elastic IPs" and "Allocate New Address", choose EC2. Once the address is created, click on it, then click "Associate Address".
    Select the EC2 instance and associate it.
  • Enable port 80:
    In AWS Management Console, click on "Security Groups" in the Navigation panel.
    Select the Security Group that you used for the instance (e.g. quicklaunch-1).
    Under the "Inbound" tab (bottom), create a new "HTTP" rule and click "Apply Rule Changes".
  • Log into the new instance with SSH
  • Set the right time zone (e.g. Berlin):

sudo ln -sf /usr/share/zoneinfo/Europe/Berlin /etc/localtime
date

  • Install the missing packages:

sudo yum install php-mysql php php-cli php-gd php-xml php-soap php-mbstring php-pecl-apc mysql httpd mysql-server graphviz ImageMagick poppler-utils
sudo /sbin/chkconfig httpd on && sudo /sbin/chkconfig mysqld on
sudo /etc/init.d/mysqld start && sudo /etc/init.d/httpd start
sudo chmod 0777 /var/www/html/
cd /var/www/html/
wget --no-check-certificate http://bit.ly/sginstall
(You should now have an existing file /var/www/html/sgs_installer.php)

  • Set the MySQL password for the user root:

mysqladmin -u root password '<mysql-password>'

  • Open your browser and go to: http://your_server_ip/sgs_installer.php.
    You should now see a page with the title "Simple Groupware Installer".
    Choose your version and click "Install". After the download has finished, click "Continue".
  • Then choose your language. After translations are built, click "Continue".
  • Type in your database credentials
  • Type in your super administrator credentials
  • Confirm the GPLv2 and click "Install"
  • In the next screen click "Continue"
  • Enjoy Simple Groupware!


Installation with Windows (Apache / XAMPP)


  • Go to http://www.apachefriends.org/en/xampp-windows.html
  • Download XAMPP Lite as .zip archive (e.g. XAMPP Lite 1.4.15, 26 MB)
  • Extract the .zip-file (e.g. xampplite-win32-1.4.15.zip to c:\xampp)
  • Run setup_xampp.bat (e.g. C:\xampp\xampplite\setup_xampp.bat)
  • Run xampp_start.exe (e.g. C:\xampp\xampplite\xampp_start.exe)
  • Open your browser and go to http://localhost/xampp/index.php. You should now see a page with the title "Welcome to XAMPP for Windows xy (lite)".
  • Download the Simple Groupware installer here
  • Create a new directory under your document root and make it world writable
    (e.g. C:\xampp\xampplite\htdocs\sgs)
  • Extract the .gz-file (e.g. to C:\xampp\xampplite\htdocs\sgs)
    (You should now have an existing file like C:\xampp\xampplite\htdocs\sgs\sgs_installer.php)
  • If your server is not connected to the internet, please download the latest version of Simple Groupware (tar.gz) here and place the archive next to "sgs_installer.php".
  • Open your browser and go to: http://your_server/sgs/sgs_installer.php.
    You should now see a page with the title "Simple Groupware Installer".
    Choose your version and click "Install". After the download has finished, click "Continue".
  • Then choose your language. After translations are built, click "Continue".
  • Type in your database credentials
  • Type in your super administrator credentials
  • Confirm the GPLv2 and click "Install"
  • In the next screen click "Continue"
  • Enjoy Simple Groupware!


Installation with IIS7 (Microsoft Internet Information Server 7, Windows 2008 Server)


  • Make sure that IIS is installed and running
  • Install PHP as described in this tutorial.
    When running the PHP installer (section Install PHP on IIS 7), make sure to select the extensions "GD2" and "MySQL / PostgreSQL".
  • Download the Simple Groupware installer here
  • Create a new directory under your document root and make it writable for the group "IIS_IUSRS" and the user "NETWORK SERVICE"
    (e.g. c:\inetpub\wwwroot\sgs)
  • Extract the .gz-file (e.g. to c:\inetpub\wwwroot\sgs)
    (You should now have an existing file like c:\inetpub\wwwroot\sgs\sgs_installer.php)
  • If your server is not connected to the internet, please download the latest version of Simple Groupware (tar.gz) here and place the archive next to "sgs_installer.php".
  • Open your browser and go to: http://your_server/sgs/sgs_installer.php.
    You should now see a page with the title "Simple Groupware Installer".
    Choose your version and click "Install". After the download has finished, click "Continue".
  • Then choose your language. After translations are built, click "Continue".
  • Type in your database credentials
  • Type in your super administrator credentials
  • Confirm the GPLv2 and click "Install"
  • In the next screen click "Continue"
  • Enjoy Simple Groupware!


Note: The IIS server does not include the mod_rewrite module. Therefore the Simple Groupware WebDAV server can't run on IIS.


Installation with IIS (Microsoft Internet Information Server 6)


  • Make sure that IIS is installed and running
  • For Windows XP: Install the PHP ISAPI filter under "Default Web Site":
    Filter name: PHP
    Executable: <php-dir>\php5isapi.dll
  • For Windows 2003 server: Add PHP as a new Web Service Extension:
    Extension name: PHP
    Required files: <php-dir>\php5isapi.dll
    Set extension status to Allowed: Checked
  • Make sure that "%systemroot%\system32\cmd.exe" has "Read & Execute" permissions for the users "IUSR_<hostname>" and "NT Authority\Network Service" (needed to preview documents and create thumbnail images)
  • Download the latest version of Simple Groupware here (at least 0.298)
  • Extract the .tar.gz-file (e.g. to C:\Inetpub\wwwroot\sgs)
    (You should now have an existing folder like C:\Inetpub\wwwroot\sgs\src)
  • Make the folders sgs/simple_cache, sgs/simple_store, sgs/bin, sgs/old writable for the users "IUSR_<hostname>" and "NT Authority\Network Service"
  • Open the IIS snap-in and navigate to "Default Web Site"
  • Open the "Properties" of the "sgs" folder and click "Create" in "Application settings"
  • Then click "Configuration" and add a new mapping:
    Executable: <php-dir>\php5isapi.dll
    Extension: .php
  • Confirm the changes
  • Restart IIS (complete restart, start+stop of "Default Web Site" is not enough)
  • In your browser go to http://localhost/sgs/.
    You should now see a page with the title "Simple Groupware".
    Choose your language. After the translations are built, click "Continue".
  • Type in your database credentials
  • Type in your super administrator credentials
  • Confirm the GPLv2 and click "Install"
  • In the next screen click "Continue"
  • Enjoy Simple Groupware!


Note: The php.ini is located in the %systemroot% directory (e.g. c:\winnt). If it does not exist, please create it.

Note: The IIS server does not include the mod_rewrite module. Therefore the Simple Groupware WebDAV server can't run on IIS.


PHP settings


During the setup, Simple Groupware automatically checks you PHP settings. If a setting is not Ok, the setup stops with a message to change the setting.
The settings in detail:

  • PHP version: at least 5.3.0
  • Required database module: any of mysql, pgsql, sqlite
  • Required modules: xml, gd / gd2, pcre, session, zlib


Required PHP settings

SettingValueDescription
zlib.output_compressionoffno automatic output compression
file_uploadsonenable file uploads
memory_limitundefined or at least 24M
session.auto_startoffmanual session handling
magic_quotes_runtimeoffmanual quoting
safe_mode (safe mode)offneeded for document preview
allow_url_fopenonneeded for accessing RSS feeds
register_globalsoffsecurity (until 0.409)
display_errorsonbetter error handling (until 0.657)
apc.shm_size64Mbetter performance

Installations running unicode languages (Arabic, Chinese, Croatian, Czech, Greek, Polish, Russian, Slovak, Swedish, Ukrainian): Please make sure to load the mbstring extension in your php.ini (e.g. extension=php_mbstring.dll or extension=php_mbstring.so) if it is not already loaded and add these lines:

[mbstring]
mbstring.internal_encoding = UTF-8
mbstring.func_overload = 2


Description

When safe_mode is on, PHP checks to see if the owner of the current script matches the owner of the file to be operated on by a file function. This does not protect you against security bugs in PHP or any kind of misuse of the system. Using safe_mode, all files within Simple Groupware must have the same owner, but oftentimes the FTP user is different from the user of the web-server. Also it won't be possible to use tools like imagemagick or catdoc, thus searching in files or previewing images will not work. Therefore safe_mode should be off.

The setting memory_limit should be set to a value equal or higher than 24M to run the installation properly.

If you want to read RSS feeds from servers around the web (RSS data handler), you'll need to set allow_url_fopen to on. This allows PHP to read a remote URL just like a local file. This setting is optional and is not forced by the setup.

If you don't have access to change the php.ini file, it may be possible to adapt the settings by using a graphical interface or create a second php.ini or a .htaccess file. See your hoster's documentation to find out what method you should use.

A .htaccess file is an additional configuration file that affects the directory it is in and all its subdirectories. It requires PHP to loaded as an Apache module. It is not available for (Fast-)CGI. It should be placed in the Simple Groupware installation directory and it contains lines like: php_value register_globals 0

Note: With the "php_value" command, flags must be represented as "0" or "1". E.g. using "php_value safe_mode off" will not work. So the rules in a .htaccess or config file should look like this:

php_value safe_mode 0
php_value zlib.output_compression 0

Older Simple Groupware versions (before 0.657) require display_errors to be set to on in php.ini. This makes error messages appear on the user's screen as an addition to the database logging. That way users are told that something went wrong, instead of believing everything is OK. This helps a lot to solve problems and avoid frustration with missing error messages. Some errors like memory limit exceptions or other critical errors cannot be logged to the database, so it's better to show them instead of presenting a blank screen to the user. The error messages on the screen will never contain any kind of confidential information like memory dumps, stack-traces or information about the database server.

Older Simple Groupware versions (before 0.409) require register_globals to be "off" because "on" can cause a lot of security problems. Newer versions contain special algorithms to protect against register_globals misuse. But whenever possible, this setting should be off (default in PHP5). Normally you can read hacking attacks against PHP programs every week at www.heise-security.co.uk. In most cases, register_globals = on is the door opener for these attacks.

Older Simple Groupware versions (before 0.400) require to disable session.use_trans_sid. If activated without server based output buffering, URLs are automatically expanded with the session id in case the browser has cookies disabled. This can be an additional security risk if users send a URL with an active session id to someone else by email. Therefore session.use_trans_sid should be disabled.


Security


It is recommended to install the latest security updates for the operating system and its components (Apache / PHP / MySQL). Using a shared hosting platform can cause unwanted downtime, resource fluctuation, and security problems. If you want to provide better security for your data, use a dedicated server and make sure to limit physical access to a limited number of people.

Using the Apache module mod_rewrite makes Simple Groupware more secure. Directories like "simple_store/" or "simple_cache/" don't need to be accessible from the outside. Per default, files within these directories are protected with a random hash function, but attackers might override this after a certain time. Therefore a ".htaccess" is already included in these directories and prohibits access if mod_rewrite is laoded.

When using Suhosin, please make sure to disable "session encryption". This feature is enabled by default, but unfortunately not working correctly with PHP 5. Therefore you can edit "suhosin.ini" (e.g. under /etc/php5/conf.d/) and replace:

;suhosin.session.encrypt = on

with:

suhosin.session.encrypt = off

Then restart Apache (/etc/init.d/apache2 restart).

If there are any problems with the setup or the running system, you might also check the configuration of SELinux or suPHP if present.


PHP extensions


PHP consists of core functions and functions loaded from extensions. Extensions are libraries that are used for database connections, image creation, data compression, web services, etc.
In Windows, extensions are .dll files, in Linux/Unix they reside in .so files. Extensions need to be compiled for every PHP version, so if you're not using a binary distribution of PHP you might need to compile them. Fortunately, all extensions required by Simple Groupware are available as binary files for Linux and Windows.

For Windows, you only need to define the directory for the extensions in your php.ini and define what extensions to load:

; Directory for the extensions:
extension_dir = "<directory in your file system>"

; Image creation for the stats module:
extension=php_gd2.dll

; Connecting to LDAP:
extension=php_ldap.dll

; MySQL connection:
extension=php_mysql.dll

; PostgreSQL connection:
extension=php_pgsql.dll

; Oracle connection:
extension=php_oci8.dll

; SQLite connection (also applies to XAMPP):
extension=php_pdo.dll
extension=php_pdo_sqlite.dll

; OpenSSL connections:
extension=php_openssl.dll


For Linux / Unix, you need to install additional packages from your distribution to use the extensions:

; example for installing the GD library in Debian
apt-get install php5-gd

; example for installing the GD library in SuSE yast
; run the module for software installation
; select the package Php-gd and install it


Preview documents with Windows (optional)


In order to preview documents and images with Windows, you need to install the extension "Win32 binaries" using the Extension Manager. It is also recommended to install a Virus scanner on the system.


Preview documents with Linux (optional)


In order to preview documents and images with Linux, you need to install some packages:

catdoc, xlhtml, ImageMagick, Xpdf, UnZip, gzip, tar, mp3info, exiv2, Graphviz

Debian:

Simple Groupware also includes Debian binaries (which can be activated here), but it is more safe to use the standard packages:

 apt-get install catdoc
 apt-get install ppthtml
 apt-get install imagemagick
 apt-get install xpdf-utils
 apt-get install unzip
 apt-get install mp3info
 apt-get install exiv2
 apt-get install graphviz

SuSE:

Install the packages ImageMagick, xpdf-tools, unzip, Graphviz, tk with Yast.
For catdoc you need to download the rpm-package here and install it with:

rpm -i catdoc-0.93.3-2.i386.rpm

For ppthtml you need to download the rpm-package here and install it with:

rpm -i xlhtml-0.5.1-3.i386.rpm

For mp3info you need to download the rpm-package here and install it with:

rpm -i mp3info-0.8.5a-1.i386.rpm

For exiv2 you need to download the rpm-package here and install it with:

rpm -i libexiv2-0.12-101.pm.1.i586.rpm


Using the CIFS module / NTLM authentication (Single sign-on, optional)


If you want to get direct access to a CIFS server (e.g. Samba, Windows or NetApp), you need to start the PHP/Java Bridge on the Simple Groupware server:

cd <sgs-dir>/bin/tools/java_bridge/
java -jar JavaBridge.jar INET_LOCAL:9676 3 ../../../simple_cache/debug/java_bridge.log

# Windows background process
cd <sgs-dir>/bin/tools/java_bridge/
start /B java -jar JavaBridge.jar INET_LOCAL:9676 3 ../../../simple_cache/debug/java_bridge.log

# Linux background process
cd <sgs-dir>/bin/tools/java_bridge/
java -jar JavaBridge.jar INET_LOCAL:9676 3 ../../../simple_cache/debug/java_bridge.log &

Note: To start the PHP/Java Bridge on your system, a Java Runtime is required (e.g. with Debian apt-get install gij or apt-get install gcj-4.6-jre-headless). Please make sure to use at least gij 4.3.2 or gcj 4.6 (java 1.5.0).

Note: Beginning with Simple Groupware 0.510, the Java Bridge is automatically started. The log file is in "<sgs-dir>/simple_cache/debug/java_bridge.log".

Now PHP is able to use the jCIFS library (written in Java) and get direct access to a file server based on the CIFS protocol.


Uninstall Simple Groupware


Remove all files from the hard disk (e.g. C:\xampp\xampplite\htdocs\sgs for Windows or /srv/www/htdocs/sgs for Linux)

Remove all items from the database:

  • MySQL: drop all tables with the prefix "simple_" or delete the complete database (e.g. using phpMyAdmin)
  • PostgreSQL:
    drop all tables with the prefix "simple_"
    drop the views "show_full_columns", "show_processlist", "show_table_status" and "show_index"
    drop the custom functions "instr" and "concat"
    or delete the complete database (e.g. using pgAdminIII)
  • Oracle Database:
    drop all tables with the prefix "simple_"
    drop the views "show_full_columns", "show_index" and "show_table_status"
  • SQLite:
    remove the database file at "<sgs-dir>/simple_store/sqlite3_<database-name>.db"


Unattended installation of Simple Groupware


You can install Simple Groupware without the web interface using this command in a shell:

php -d register_argc_argv=1 -q <sgs-dir>/src/ext/install_unattended.php.txt <url> <lang-code> <admin-user> <admin-pw> <db-type> <db-host> <db-name> <db-user> <db-pw> <demo-data>

The parameters in detail:

  • url = http://<your-server>/<your-sgs-dir>/src/index.php
  • lang-code = ar, cz, cn, da, de, en, enUK, es, fr, gr, hr, hu, idn, it, nl, pl, ptBR, ru, se, sk, tr, uk
  • admin-user = super administrator username
  • admin-pw = super administrator password
  • db-type = mysql, pgsql, oci8, sqlite
  • db-host = database hostname / ip
  • db-name = database name
  • db-user = database username
  • db-pw = database password (use '_' if empty)
  • folder-structure = 0=full, <file>=path / folder template
    e.g. modules/core/folders.xml, modules/core/folders_small.xml

If the script completes successfully, the return code is 0. If there are errors, return code is 1.


Example:

php -q -d register_argc_argv=1 /srv/www/htdocs/sgs/src/ext/install_unattended.php.txt http://localhost/<sgs-url-dir>/src/index.php en admin admin mysql localhost sgs_0290 root _ 0


Installation SyncML Server

<< contents

SyncML is a platform-independent Synchronization Markup Language. SyncML communicates on top of the HTTP protocol and can be used with a normal network or internet connection. This means that you can synchronize all kinds of information between Simple Groupware and your mobile devices. Some mobile devices support SyncML natively, others are used in combination with a special client software on the device to make it SyncML ready.

Simple Groupware itself does not include the SyncML protocol, therefore it communicates with the free SyncML server from Funambol (former Sync4j). The interface between Simple Groupware and Funambol is described here.

Funambol also offers free SyncML clients for: Windows Mobile, Blackberry, iPod, iPhone, Outlook, Evolution, Palm, Thunderbird, Gmail, Yahoo, Lotus Domino, Exchange and a J2ME client

All files from Funambol (server, clients and manuals) are available here.

Note: Using the calendar feature free/busy with Outlook but without Exchange is described here.


Installation with Windows and MySQL (Funambol v7/v8)


  • Funambol v7/v8 requires at least Simple Groupware 0.420 and MySQL 5.0
  • Download the package "PIM & E-Mail Bundle" for Windows from Funambol
    (latest version tested is 8.7.0, all files are here)
  • Install the setup package (e.g. funambol-8.7.0.exe)
  • Open your browser and go to http://localhost:8080/. You should now see a page with the title "The Funambol Data Synchronization Server".
  • Copy the file "<sgs-dir>\bin\tools\funambolv7_syncML\mysql\mysql-connector-java-5.1.6-bin.jar" to "C:\Program Files\Funambol\tools\" (or another location where your Funambol server was installed to).
  • Edit the file "C:\Program Files\Funambol\ds-server\install.properties" and replace:

dbms=hypersonic
...
jdbc.classpath=../tools/hypersonic/lib/hsqldb.jar
jdbc.driver=org.hsqldb.jdbcDriver
jdbc.url=jdbc:hsqldb:hsql://localhost/funambol
jdbc.user=sa
jdbc.password=

with:

dbms=mysql

jdbc.classpath=../tools/mysql-connector-java-5.1.6-bin.jar
jdbc.driver=com.mysql.jdbc.Driver
jdbc.url=jdbc:mysql://<host>/<database>?characterEncoding=UTF-8
jdbc.user=<username>
jdbc.password=<password>

Make sure to replace <host>, <database>, <username> and <password> with your MySQL credentials (same as those used in Simple Groupware).
  • Execute the file "C:\Program Files\Funambol\bin\install.cmd" (double-click in Windows Explorer) and confirm the questions with "y"
  • Start the Funambol Data Synchronization Server:
    Right-click the icon in the taskbar and choose "Start Server" and wait a bit until the icon turns into green color.
  • Make sure that Simple Groupware is installed on the same machine
  • Open your browser and go to http://localhost/<sgs-dir>/bin/index.php.
  • Log in as super administrator
  • Navigate to "/Workspace/System" and choose "Change setup settings".
  • Click the checkbox "Enable Sync4j / Funambol"
  • Then click "Save" and you're done.
  • Read more about the SyncML integration.
  • Enjoy Simple Groupware!


Installation with Windows and PostgreSQL (Funambol v7/v8)


  • Funambol v7/v8 requires at least Simple Groupware 0.420
  • Download the package "PIM & E-Mail Bundle" for Windows from Funambol
    (latest version tested is 8.7.0, all files are here)
  • Install the setup package (e.g. funambol-8.7.0.exe)
  • Open your browser and go to http://localhost:8080/. You should now see a page with the title "The Funambol Data Synchronization Server".
  • Copy the file "<sgs-dir>\bin\tools\funambolv7_syncML\postgresql\postgresql-8.3-603.jdbc3.jar" to "C:\Program Files\Funambol\tools\" (or another location where your Funambol server was installed to).
  • Edit the file "C:\Program Files\Funambol\ds-server\install.properties" and replace:

dbms=hypersonic
...
jdbc.classpath=../tools/hypersonic/lib/hsqldb.jar
jdbc.driver=org.hsqldb.jdbcDriver
jdbc.url=jdbc:hsqldb:hsql://localhost/funambol
jdbc.user=sa
jdbc.password=

with:

dbms=postgresql

jdbc.classpath=../tools/postgresql-8.3-603.jdbc3.jar
jdbc.driver=org.postgresql.Driver
jdbc.url=jdbc:postgresql://<host>/<database>
jdbc.user=<username>
jdbc.password=<password>

Make sure to replace <host>, <database>, <username> and <password> with your PostgreSQL credentials (same as those used in Simple Groupware).
  • Execute the file "C:\Program Files\Funambol\bin\install.cmd" (double-click in Windows Explorer) and confirm the questions with "y"
  • Start the Funambol Data Synchronization Server:
    Right-click the icon in the taskbar and choose "Start Server" and wait a bit until the icon turns into green color.
  • Make sure that Simple Groupware is installed on the same machine
  • Open your browser and go to http://localhost/<sgs-dir>/bin/index.php.
  • Log in as super administrator
  • Navigate to "/Workspace/System" and choose "Change setup settings".
  • Click the checkbox "Enable Sync4j / Funambol"
  • Then click "Save" and you're done.
  • Read more about the SyncML integration.
  • Enjoy Simple Groupware!


Installation with Linux and MySQL (Funambol v7/v8/v10)


  • Funambol v7/v8/v10 requires at least Simple Groupware 0.420 and MySQL 5.0
  • Download the package "PIM & E-Mail Bundle" for Linux from Funambol
    (latest version tested is 10.0.3, all files are [http://sourceforge.net/projects/funambol/files/bundle/|here]])
  • Install the setup package (e.g. funambol-10.0.3.bin)
  • Open your browser and go to http://<your-server>:8080/. You should now see a page with the title "The Funambol Data Synchronization Server".
  • Copy the file "<sgs-dir>/bin/tools/funambolv7_syncML/mysql/mysql-connector-java-5.1.6-bin.jar" to "<funambol-dir>/tools/" (or another location where your Funambol server was installed to).
  • Edit the file "<funambol-dir>/ds-server/install.properties" and replace:

dbms=hypersonic
...
jdbc.classpath=../tools/hypersonic/lib/hsqldb.jar
jdbc.driver=org.hsqldb.jdbcDriver
jdbc.url=jdbc:hsqldb:hsql://localhost/funambol
jdbc.user=sa
jdbc.password=

with:

dbms=mysql

jdbc.classpath=../tools/mysql-connector-java-5.1.6-bin.jar
jdbc.driver=com.mysql.jdbc.Driver
jdbc.url=jdbc:mysql://<host>/<database>?characterEncoding=UTF-8
jdbc.user=<username>
jdbc.password=<password>

Make sure to replace <host>, <database>, <username> and <password> with your MySQL credentials (same as those used in Simple Groupware).
  • Execute the file "<funambol-dir>/bin/install" and confirm the questions with "y"
  • Start the Funambol Data Synchronization Server from the terminal, and wait a bit:
    <funambol-dir>/bin/funambol start
  • Make sure that Simple Groupware is installed on the same machine
  • Open your browser and go to http://<your-server>/<sgs-dir>/bin/index.php.
  • Log in as super administrator
  • Navigate to "/Workspace/System" and choose "Change setup settings".
  • Click the checkbox "Enable Sync4j / Funambol"
  • Then click "Save" and you're done.
  • Read more about the SyncML integration.
  • Enjoy Simple Groupware!


Installation with Linux and PostgreSQL (Funambol v7/v8)


  • Funambol v7/v8 requires at least Simple Groupware 0.420
  • Download the package "PIM & E-Mail Bundle" for Linux from Funambol
    (latest version tested is 8.0.1, all files are here)
  • Install the setup package (e.g. funambol-8.0.1.bin)
  • Open your browser and go to http://localhost:8080/. You should now see a page with the title "The Funambol Data Synchronization Server".
  • Copy the file "<sgs-dir>\bin\tools\funambolv7_syncML\postgresql\postgresql-8.3-603.jdbc3.jar" to "<funambol-dir>/tools/" (or another location where your Funambol server was installed to).
  • Edit the file "<funambol-dir>/ds-server/install.properties" and replace:

dbms=hypersonic
...
jdbc.classpath=../tools/hypersonic/lib/hsqldb.jar
jdbc.driver=org.hsqldb.jdbcDriver
jdbc.url=jdbc:hsqldb:hsql://localhost/funambol
jdbc.user=sa
jdbc.password=

with:

dbms=postgresql

jdbc.classpath=../tools/postgresql-8.3-603.jdbc3.jar
jdbc.driver=org.postgresql.Driver
jdbc.url=jdbc:postgresql://<host>/<database>
jdbc.user=<username>
jdbc.password=<password>

Make sure to replace <host>, <database>, <username> and <password> with your PostgreSQL credentials (same as those used in Simple Groupware).
  • Execute the file "<funambol-dir>/bin/install" and confirm the questions with "y"
  • Start the Funambol Data Synchronization Server from the terminal, and wait a bit:
    <funambol-dir>/bin/funambol start
  • Make sure that Simple Groupware is installed on the same machine
  • Open your browser and go to http://localhost/<sgs-dir>/bin/index.php.
  • Log in as super administrator
  • Navigate to "/Workspace/System" and choose "Change setup settings".
  • Click the checkbox "Enable Sync4j / Funambol"
  • Then click "Save" and you're done.
  • Read more about the SyncML integration.
  • Enjoy Simple Groupware!


Start Funambol automatically with Linux (v7/v8)


The Funambol Data Synchronization Service won’t start automatically when you start the host server. You can follow these steps to automate server startup on Linux:

  • Open a terminal with root privileges:

ln -s <FUNAMBOL_HOME>/bin/funambol /etc/init.d/funambol

e.g.
ln -s /opt/Funambol/bin/funambol /etc/init.d/funambol

  • Open the funambol script with a text editor and repalce the following line:

FUNAMBOL_HOME=`(cd .. ; pwd)`

with:
FUNAMBOL_HOME=`(cd <FUNAMBOL_HOME> ; pwd)`

e.g.
FUNAMBOL_HOME=`(cd /opt/Funambol ; pwd)`

This points the script to the absolute location of your Funambol installation.
  • Finally create a symbolic link to your rc3.d directory using this command:

ln -s /etc/init.d/funambol /etc/rc3.d/S30funambol


See this installation manual for older Funambol versions.


Update

<< contents

Update to PHP 5.3.x


Until Simple Groupware 0.702, the updater is not compatible with PHP 5.3.x. So you need to update Simple Groupware to 0.703+ before updating to PHP 5.3.x. If you change the order, you'll need to do the old update procedure.


Version specific instructions: Update to 0.640+


Beginning with 0.640, Win32 and Debian binaries are no longer included in the default Simple Groupware package. To install them again, do a normal update, login as super administrator, click "Simple Grouwpare Extension Manager" in the admin summary page and install the binary package corresponding to your system.


Version specific instructions: Update to 0.530+


Unfortunately, RSS feeds on Sourceforge.net have changed. So updates from versions before 0.531 cannot be detected automatically. In order to update to the latest release, download a new tar.gz file here and place it under "<sgs-dir>/bin/". Then start the updater and select the new file.


Online/offline update procedure


If your server has a internet connection, you can use the new update procedure to download and install new versions with just 4 clicks in Simple Groupware:

  • Make a complete backup of your database (e.g. using phpMyAdmin)
  • Make a complete backup of your sgs folder (e.g. /var/www/html/sgs/)
  • Make sure both backups are complete!
  • Make the folder sgs/old world writable
  • Login as super administrator
  • Click "Update Simple Groupware" in the administration page
  • Choose the latest release and click "Install"
  • After the new version is processed, click "Continue"
  • When the setup is finished, click again "Continue"
  • Note: If you've changed modules, templates or source code, your changes won't be touched by the update. All files from the old version are moved to "<sgs-dir>/old" and can be merged manually with the new version. To make your changes persistent over updates, see the Customization page.
  • Enjoy Simple Groupware!


If your server has no internet connection, you can use the new update procedure introduced in 0.300 to install a new Simple Groupware package located in the local filesystem:

  • Make a complete backup of your database (e.g. using phpMyAdmin)
  • Make a complete backup of your sgs folder (e.g. /var/www/html/sgs/)
  • Make sure both backups are complete!
  • Make the folder sgs/old world writable
  • Login as super administrator
  • Click "Update Simple Groupware" in the administration page
  • Enter path and filename of the new package and click "Install"
  • After the new version is processed, click "Continue"
  • When the setup is finished, click again "Continue"
  • Note: If you've changed modules, templates or source code, your changes won't be touched by the update. All files from the old version are moved to "<sgs-dir>/old" and can be merged manually with the new version. To make your changes persistent over updates, see the Customization page.
  • Enjoy Simple Groupware!


Unattended update of Simple Groupware


You can update Simple Groupware without the web interface using this command in a shell:

php -d register_argc_argv=1 -q <sgs-dir>/bin/ext/update_unattended.php.txt <url> <admin-user> <admin-pw> <release> <no-backup>

The parameters in detail:

  • url = http://<your-server>/<your-sgs-dir>/bin/index.php
  • admin-user = super administrator username
  • admin-pw = super administrator password
  • release = e.g. 0.659 or latest
  • no-backup = 1=don't backup files, 0=backup files

If the script completes successfully, the return code is 0. If there are errors, return code is 1.


Example:

<perform a backup of your old files and database>

php -q -d register_argc_argv=1 /srv/www/htdocs/sgs/bin/ext/update_unattended.php.txt http://localhost/<sgs-url-dir>/bin/index.php admin admin latest 0


Version specific instructions


Update to 0.500:


To use the new "offline folder synchronization" feature, you need to create a new folder in the user's profile and assign the module "Offline folders" to it. Then set the folder's anchor to "offline_<username>" (directly in the database or under "/Workspace/System/Tree").

Note: New users will automatically have the new folder in their profile.


Update to 0.420:


In case Simple Groupware is used with the Funambol SyncML server, please make sure to uninstall the old Funambol server and install the Funambol v7 server. Also MySQL 5.x or PostgreSQL 8.x is required to run Funambol v7.


Update to 0.321:


This is the last release which is compatible to PHP 4.x.


Update to 0.320:


Upgrade to the new WebDAV server: Please make sure to deploy the new .htaccess from "<sgs-dir>/src/tools/webdav/".


Update to 0.292:


Using MySQL 4.0 is longer possible. So if you're using MySQL 4.0, please upgrade to MySQL 4.1 or 5.x.


Update to 0.291:


This version contains new views for birthdays and anniversaries in contacts and users. These views require a database with sub-query support. So if you're using MySQL 4.0, please upgrade to MySQL 4.1 or 5.x. Also MySQL has discontinued their community support for version 4.0.


Update to 0.270:


The chat module received individual permissions, so passwords are no longer required. The initial permissions include read and write permissions for everyone on each chat room, so you might need to change this after the update in order to protect the chat archives.


Update to 0.252:


In order to use more than one mail address per user, you need to create a new folder called "Mail identities" with the module "System: Mail identities" under "/Workspace/Organisation/".


Update to 0.250:


To get SyncML synchronization working in the user's personal contact folder: Go to "/Workstation/System/Tree" and modify the folder, set the anchor to "contacts_<username>". This marks the folder as the SyncML synchronization folder. If the folder already contains datasets, move the datasets to another folder and move them back, so the triggers can detect the datasets for synchronization. (The user's personal contact folder is located at "/Workspace/Personal folders/<username>/Contacts".)


Update to 0.029:


To get free/busy information about a user's calendar: Go to "/Workstation/System/Tree" and modify the folder, set the anchor to "calendar_<username>" and change the exceptional user rights to "freebusy:read:anonymous". This gives other users the right to read the free/busy information and to find the user's calendar in the tree. (The user's calendar is located at "/Workspace/Personal folders/<username>/Calendar".)


Update to 0.2 beta 11:


Column names have changed in simple_sys_tree. Therefore run this SQL query before doing the update:

ALTER TABLE simple_sys_tree CHANGE level level_old decimal

(e.g. using phpMyAdmin)


Update from 0.2 beta 1-6 to 0.2 beta 7:


Passwords are no longer saved in cleartext. Now the sha1 hash function is used. Therefore you need to modify your database with these sql commands before doing the update:

rename TABLE simple_users to simple_sys_users;

update simple_sys_users set password=sha1(password);

(e.g. using phpMyAdmin)


Update with Linux (e.g. Fedora 4) (old procedure)


  • Make a complete backup of your database (e.g. using phpMyAdmin)
  • Make a complete backup of your sgs folder (e.g. /var/www/html/sgs/)
  • Make sure both backups are complete!
  • DELETE all contents from the bin folder (e.g. /var/www/html/sgs/bin/)
  • Download the latest version of Simple Groupware here.
  • Extract the .tar.gz-file to a temporary folder (e.g. /tmp/sgs/)
    (You should now have an existing folder like /tmp/sgs/src)
  • Copy all files from the temporary folder to your sgs folder and overwrite existing files (e.g. copy from /tmp/sgs/ to /var/www/html/sgs/)
  • Open your browser and go to http://your_server/sgs/bin/.
  • After the translations are rebuilt, click "Continue".
  • Type in your database credentials (the same as in your previous version)
  • Type in your super administrator credentials
  • Confirm the GPLv2 and click "Install"
  • In the next screen click "Continue"
  • Note: If you've changed the configuration in setup settings, you'll need to make these changes again in the new version.
  • Enjoy Simple Groupware!


Update with Windows (old procedure)


  • Make a complete backup of your database (e.g. using phpMyAdmin)
  • Make a complete backup of your sgs folder (e.g. c:\xampp\xampplite\htdocs\sgs\)
  • Make sure both backups are complete!
  • DELETE all contents from the bin folder (e.g. c:\xampp\xampplite\htdocs\sgs\bin\)
  • Download the latest version of Simple Groupware here.
  • Extract the .tar.gz-file to a temporary folder (e.g. c:\temp\sgs\)
    (You should now have an existing folder like c:\temp\sgs\src)
  • Copy all files from the temporary folder to your sgs folder and overwrite existing files (e.g. copy from c:\temp\sgs\ to c:\xampp\xampplite\htdocs\sgs\)
  • Open your browser and go to http://localhost/sgs/.
  • After the translations are rebuilt, click "Continue".
  • Type in your database credentials (the same as in your previous version)
  • Type in your super administrator credentials
  • Confirm the GPLv2 and click "Install"
  • In the next screen click "Continue"
  • Note: If you've changed the configuration in setup settings, you'll need to make these changes again in the new version.
  • Enjoy Simple Groupware!


Extension Manager

<< contents

Similar to Firefox add-ons or mobile application stores, the extension manager allows you to use free contributions from the open source community. That way you can extend and customize Simple Groupware to get the best functionality. Extensions are downloaded directly from sourceforge.net. There are also automatic checks for requirements like minimal PHP or Simple Groupware versions.
This guide describes how the extension manager works and how you can create your own extension(s).

Some facts about Simple Groupware extensions:

  • All extensions are open source
  • All extensions are verified before being published
  • All extensions can be installed and uninstalled with 2 clicks


Extension list


Debian binaries 0.1
Most hosting companies use Debian on their servers, but they don't install packages like catdoc, xpdf or unzip. Also sometimes the packages are installed, but the webpage is running in a chroot environment which forbids to execute these binaries. Using this option, you can directly use Debian binaries included in the Simple Groupware packages. Contents: catdoc exiv2 gzip mp3info pdfinfo pdftotext ppthtml tar unzip xls2csv Note: These packages may not be the latest versions, so you should only use them in combination with a virus scanner.

Win32 binaries 0.1
Most hosting companies use Debian on their servers, but they don't install packages like catdoc, xpdf or unzip. Also sometimes the packages are installed, but the webpage is running in a chroot environment which forbids to execute these binaries. Using this option, you can directly use Debian binaries included in the Simple Groupware packages. Contents: catdoc convert (ImageMagick) exiv2 graphviz gzip mp3info pdfinfo pdftotext ppthtml tar unzip xls2csv Note: These packages may not be the latest versions, so you should only use them in combination with a virus scanner.

Compose Html 0.3
Compose Html makes it possible to write emails in HTML.

Example 0.4
Example is a demonstration module for handling bookmarks. It is similar to the normal bookmarks module, but does not contain categories. A new folder "Example" is created under "/Workspace/Extensions/". v0.3: added PHP include view v0.4: added validator example

Mini tasks 0.2
Mini Tasks is a module for handling personal tasks. It is similar to the normal tasks module, but does not contain responsibles and project management features. A new folder "Mini tasks" is created under "/Workspace/Extensions/".

Private Items 0.1
Private items extends contacts, calendar, tasks, notes with the option to make items private. Private items are only visible to the user who created the asset.

Tasks Rating 0.1
Tasks Rating changes the priority field in the task module from a select box to a rating field.

Extension screenshots


ScreenshotsExtensions##limit

View more ...


Using the extension manager


To start the extension manager, login as super administrator and click "Simple Groupware Extensions" on the administration overview page. The extension manager automatically downloads the list of packages and displays all installed packages:

Simple Groupware Extension Manager - List of packages
Extension Manager - List of packages

When installing a package, the package archive gets downloaded from sourceforge.net and extracted to "<sgs-dir>/simple_cache/". From there the files get translated and moved to "<sgs-dir>/ext/". If a package contains a file named "install.php", the file gets executed during the installation process. Files named "readme.txt" are displayed during the installation.
Folders can be automatically created under "/Workspace/Extensions/" by including a "folders.xml" in the package. The files "modules.txt" in "<sgs-dir>/modules/schema/" and "<sgs-dir>/modules/schema_sys/" can be extended by including a file named "modules.txt" or "sys_modules_ext.txt" in the main folder of the package.

Simple Groupware Extension Manager - Install a package
Extension Manager - Install a package

When uninstalling a package, all files of the package are moved to "<sgs-dir>/old/<package-filename>/" and empty directories are removed if possible. If a package contains a file named "uninstall.php", the file gets executed during the un-installation process. This process does not remove any data from the database.

Note: To install extensions, your server needs to be connected to the internet.


Develop a new extension


To build your own extension, please follow this tutorial.


Content Management

<< contents

Simple Groupware is the first groupware to include the PmWiki engine. PmWiki is a very successful wiki-based system for collaborative creation and maintenance of websites. Combined with Simple Groupware, PmWiki becomes a full multi-user enterprise content management system (CMS), featuring notifications, user/group permissions on pages and media files, WebDAV, and many more.

Of course, www.simple-groupware.de is running Simple Groupware in combination with PmWiki. All manuals are converted to PDF directly from the Homepage using a Perl program called html2ps.

Using an easy Wiki markup, content editors do not need to know HTML or CSS. Pages can be viewed completely in the backend (Simple Groupware) and the frontend (built with Smarty Templates). Administrators can quickly change the appearance of a site by using a stylesheet and a simple HTML template. Access control is offered on a user/group basis for each page or folders containing pages.

Simple Groupware PmWiki - CMS backend
CMS backend
Simple Groupware PmWiki - CMS frontend
CMS frontend

PmWiki has a great plugin architecture: One principle of the PmWiki philosophy is to only include essential features in the core engine, but make it easy for administrators to customize and add new markup. Hundreds of features are already available by using extensions (called "recipes") that are available from the PmWiki Cookbook. PmWiki is a registered trademark of Patrick R. Michaud.


Differences between PmWiki and Simple Groupware


 PmWikiSimple Groupware + PmWiki
Storagefile systemdatabase (MySQL / PostgreSQL)
Themescustom template engineSmarty Template Engine
Permissionspage, page groupsfolder + page permissions
 (users, passwords)(users + groups)
Authenticationfile based, database, LDAPdatabase, LDAP / AD, IMAP, SMTP, NTLM
File uploadsfile systemCMS or files module (+ WebDAV)
CachingWiki content cachingstatic HTML page caching
PreviewNew pageAjax (Shortcut: Alt+(Shift)+p)


Import PmWiki pages into Simple Groupware


Existing PmWiki pages and uploaded files can be imported into Simple Groupware by using the PmWiki data handler.

Steps in the file system:

  • Copy "<pmwiki>/wiki.d/" to "<sgs-dir>/import/pmwiki/"
  • Copy "<pmwiki>/uploads/" to "<sgs-dir>/ext/cms/files/"

Steps in Simple Groupware:

  • Create a new folder with the module CMS
  • Create a new PmWiki mountpoint and choose "../import/pmwiki/" as path
  • Copy all pages from the mountpoint folder to the CMS folder
  • Then you can start editing pages (default page is "Homepage")

Note: When using an older version before (0.412 or upgrade to 0.412), you'll need to copy all pages from "/Workspace/Demo/CMS/Import/pmwiki/" to "/Workspace/Demo/CMS/".


CMS frontend / getting started


The frontend of the CMS module is located at "<sgs-dir>/bin/cms.php". If the URL to Simple Groupware is "http://<your_server>/sgs/bin/index.php", the CMS frontend is available at "http://<your_server>/sgs/bin/cms.php".

In case you've upgraded from an older version of Simple Groupware (before 0.412), you'll need to create the CMS folder and the PmWiki mountpoint to "../import/pmwiki_cms" manually. Then copy all pages from the mountpoint to the CMS folder.

The default page is identified with the page name "Homepage". When requesting cms.php with no parameters, "Homepage" gets displayed. If a page does not exist, the page "Site.PageNotFound" will be displayed. Authentication is done with "Site.AuthForm". So these pages should be readable by "anonymous" and should not be deleted. By default, all "Site.*" pages are placed under "/Workspace/Demo/CMS/".

Note: The frontend displays or includes only pages that have the "Activated" flag checked. The backend shows all pages (no matter if activated is checked).

Links are automatically built like this:

  • Link to a page: cms.php?page=<Page name>
  • Edit a page: cms.php?page=<Page name>&edit
  • View the source of a page: cms.php?page=<Page name>&source
  • View the RSS sheet with the latest changes: cms.php?rss
  • Get a XML sitemap: cms.php?sitemap
  • Search function: cms.php?page=Site.Search&q=<search text>

Note: The default page "Homepage" can be changed in setup settings.


Attachments


In every page in the CMS module, one or more attachments can be added. To reference a file named image1.jpg, just use Attach:image1.jpg in the wiki markup. If the page is named MyPage and included inside another page, just use Attach:MyPage/image1.jpg. Same if the image should be included on another page. For more information about images in PmWiki, please click here. Examples:

# Attach a file from the Attachments field
Attach:image1.jpg

# Attach from another page or include the page
Attach:MyPage/image1.jpg


Real URLs


Normal URLs have the schema "http://<server>/<sgs-dir>/bin/cms.php?page=<pagename>", real URLs are using a shorter format like "http://<server>/cms/<pagename>".

Real URLs can be activated in setup settings by setting the value "Real URL format in the CMS" to "/cms/". In order to redirect the URLs properly, an ".htaccess" file needs to be placed in the document root of your web server:

RewriteEngine On

# css / images
RewriteRule ^cms/ext/(.+)$ /sgs/bin/ext/cms/$1 [L]

# attachments
RewriteRule ^cms/(.*?)/file/(.*) /sgs/bin/cms.php?page=$1&file=$2 [L]

# Thumbnails
RewriteRule ^cms/thumbs/(.*) /sgs/bin/preview.php?filename=$1 [L]

# pages
RewriteRule ^cms/(.*) /sgs/bin/cms.php?page=$1&%{QUERY_STRING} [L]

Note: This examples implies that Simple Groupware is installed under "http://<your_server>/sgs/". It may be necessary to change the paths to match your configuration.

Note: After (de)acticating real URLs, "schema cache" and "CMS cache" need to be cleared. In order to get the .htaccess working, your Apache web server needs to have the mod_rewrite module loaded.


Custom markup: Graphviz diagrams (added with release 0.503)


The following markup can be used to embed Graphviz diagrams into a normal CMS page:

Syntax:

(:graphviz [=
<graphviz content>
=]:)

Example:

(:graphviz [=
digraph G {
  {node[shape=box] process1 process2 process3}
  {node[shape=diamond] decision1 decision2}
  {node[shape=ellipse] startflow endflow}
  startflow -> process1 -> decision1
  decision1:w -> process1:w [label=n]
  decision1 -> process2 [label=y]
  process2:s -> process3:n
  process3 -> decision2
  decision2 -> endflow [label=y]
  decision2 -> process1 [label=n]
}
=]:)

Output:

Simple Groupware & CMS - Graphviz diagrams


Customizing the CMS frontend


The frontend of the CMS module is located at "<sgs-dir>/bin/cms.php". If the URL to Simple Groupware is "http://<your_server>/sgs/bin/index.php", the CMS frontend is available at "http://<your_server>/sgs/bin/cms.php".

The frontend is controlled by a Smarty template and a stylesheet. Every page is assigned to a template. The documentation for Smarty templates is here.

Default template<sgs-dir>/bin/templates/cms/pmwiki.tpl
Default stylesheet<sgs-dir>/bin/ext/cms/styles.css

Additional media files can be placed in "<sgs-dir>/bin/ext/cms/". References in the templates can be something like "ext/cms/xy.jpg".

There are two important variables assigned to the template: page and cms
To view them, you can add "{debug}" to the template and make sure that your browser allows popups for the page.

The "page" variable is an array which contains these properties (found in the database in table simple_cms):

idnumeric identifier (primary key)
foldernumeric identifier for the folder in the backend
pagenameName of the page (also used in the URL)
nameWhen using pagenames like Main.MyPage, MyPage will be the name
groupWhen using pagenames like Main.MyPage, Main will be the group
titlePage title
dataWiki content
templateSmarty template assigned to the page
descriptionPage description (meta data)
keywordsPage keywords (meta data)
authorPage author (meta data)
createdUnix timestamp of creation time
lastmodifiedUnix timestamp of last modification
createdbyPerson (username) that has created the page
lastmodifiedbyPerson (username) has done the last modification of the page
historyHistory of modifications of the page

The "cms" variable represents the cms class, defined in "cms.php".
Important methods are:

$cms->exists ( $pagename )Checks if a given page name exists
$cms->render ( $pagename )Renders a given page to HTML
$cms->get_content_from_url ( $url, $regexp, $regexp_format, $xpath, $time=1800 )Loads content from a special URL, extracts a part of it with a regular expression or xpath, and caches the result for some seconds (0=no cache)

Examples:

Display headlines from Spiegel.de and cache them for half an hour (RSS + XPath):

{* load the data *}
{assign var="data" value=$cms->get_content_from_url("http://www.spiegel.de/schlagzeilen/rss/index.xml","","","//item")}

{* display the data *}
{foreach item=item from=$data}
<a href="{$item->link}"> {$item->title} </a><br/>
{/foreach}


Get the latest version of Simple Groupware without caching the data (RSS + RegExp):

{$cms->get_content_from_url("http://sourceforge.net/export/rss2_projnews.php?group_id=96330","!simple groupware ([^ ]+?) rel!","","",0)}

or directly in the PmWiki markup (Parameters are url, regexp and time):

(:get_content url=http://sourceforge.net/export/rss2_projnews.php?group_id=96330 regexp="!simple groupware ([^ ]+?) rel!i":)

Apply a custom format to a RSS feed (Parameters are url, regexp, regexp_format and time):

(:get_content url=http://www.spiegel.de/schlagzeilen/index.rss regexp="!<title>([^<]+).+?<link>([^<]+).+?<description>([^<]+)!si" regexp_format="<b>%s</b> (<a href='%s'>Link</a>)<br>%s<br><br>" time=3600:)


Note: When using Javascript code inside a Smarty template, "{" and "}" need to be escaped with "{ldelim}" and "{rdelim}". {literal}...{/literal} can be also used to protect the code from being interpreted by Smarty.


WebDAV Server

<< contents

The WebDAV server was removed in 0.800. Clients for Dropbox and Google Drive offer much better performance, including offline usage.

The Simple Groupware WebDAV server is designed to work mainly with Windows XP's builtin WebDAV client (called "Mini-Redirector"). The Mini-Redirector allows to mount a WebDAV server directly to a drive letter in the Windows system. That means all applications can directly work with it just like a local hard disk.
For example, users can double-click a file in the Windows Explorer and the default application assigned for this file type opens and displays the file. In the background, this file gets automatically downloaded from the Simple Groupware WebDAV server.
If a user saves the file in the application, the file gets automatically uploaded and a new version is created on the Simple Groupware server.

Screenshots


Simple Groupware WebDAV file Server
WebDAV file server
Simple Groupware WebDAV file versioning
WebDAV file versioning


WebDAV installation on the server (running Simple Groupware)


Using Simple Groupware as a WebDAV server requires the module mod_rewrite to be loaded in the Apache webserver.
In case you're not sure if the module is already loaded in your configuration, open your browser with Simple Groupware. Then log in as super administrator and click "Phpinfo" in the administration page. In the section "apache2handler", you'll find a parameter called "Loaded Modules" which should contain "mod_rewrite". If it is not there then you need to do the following at the command line (Debian/Ubuntu):

sudo ln -s /etc/apache2/mods-available/rewrite.load /etc/apache2/mods-enabled/
sudo /etc/init.d/apache2 restart

This will provide the necessary hard link to activate mod_rewrite. Go back and check with PhpInfo that the module is now loaded.

Then copy the file "<sgs-dir>/src/tools/webdav/webdav.htaccess" to the webserver's document root folder and rename it to ".htaccess". The document root is the folder representing the location "http://<your-server>/". Next edit the ".htaccess" file and replace "/sgs/bin/" with the right relative path in your system. For example, if your Simple Groupware URL is "http://<your-server>/sg/bin/index.php", then replace "/sgs/bin/" with "/sg/bin/". Finally open your browser with "http(s)://<your-server>/sgdav/test". If everything is working correctly, the page displays "ok". If not, you might check the location of .htaccess and take a look at Apache's error logfile.

Note: If your Apache server is not processing .htaccess files by default, you might need to add "AllowOverride All" inside the <Directory>-tag describing the document root in "httpd.conf". For Debian/Ubuntu, please edit "/etc/apache2/sites-available/default" and restart Apache, for example:

<Directory /var/www/>
  Options FollowSymLinks
  AllowOverride All
  Order allow,deny
  allow from all
</Directory>

Note: In most systems, the document root folder is named "htdocs" or "/var/www". Also the document root folder is what you get if you open your browser with "http(s)://<your-server>/".

Note: The Simple Groupware WebDAV server only works with the Apache webserver and the "mod_rewrite" module. Microsoft's Internet Information Server (IIS) can't be used because it does not include mod_rewrite.

Note: If you open your browser with "http(s)://<your-server>/sgdav/", you'll get a 404 (file not found) error. Please remember that a browser is not a WebDAV client. A browser uses the GET method to list a directory, a WebDAV client uses PROPFIND and initiates the connection normally with a OPTIONS command.

Note: When using Windows Explorer (Mini-Redirector) as WebDAV client, the anonymous login is used by default. So you need to disable anonymous logins in Simple Groupware. Therefore log in as super administrator, click "Change Setup Settings", un-check "Enable anonymous access" and click "Save".


WebDAV installation on the client (Windows XP)


By default, the Mini-Redirector uses Digest authentication which is not compatible with Simple Groupware. But you can change this to Basic authentication in the client's registry. The file "winxp_webdav.reg" is included in the Simple Groupware package under "\src\tools\webdav\". It should be executed with administrator privileges and requires a restart afterwards. It changes the following setting in the Windows registry (click here for more information):

[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\WebClient\Parameters]
"UseBasicAuth"=dword:00000001


Also, the Mini-Redirector included in Windows XP only supports port 80. If your server is only available on SSL, you can use a tool called "stunnel" to provide the missing SSL client. Windows binaries can be downloaded here. Then run "stunnel <config-file>" on the client. The config file should contain:

client=yes
verify=0
[psuedo-https]
accept = 80
connect = <your-sgs-server>:443
TIMEOUTclose = 0

Replace <your-sgs-server> with the IP or the DNS name of your Simple Groupware Server. Using this configuration, stunnel maps the port "<your-sgs-server>:443" to "localhost:80" and handles all the SSL stuff. That also implies that port 80 is not used by another program on the client. After running stunnel, you can mount the driver letter with "http://localhost/sgdav/".


WebDAV installation on the client (Windows Vista)


By default, the Mini-Redirector uses Digest authentication which is not compatible with Simple Groupware. But you can change this to Basic authentication in the client's registry. The file "vista_webdav.reg" is included in the Simple Groupware package under "\src\tools\webdav\". It should be executed with administrator privileges and requires a restart afterwards. It changes the following setting in the Windows registry (click here for more information):

[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\WebClient\Parameters]
"BasicAuthLevel"=dword:00000002

The Mini-Redirector included in Windows Vista fully supports SSL and the port can be different from 80.

To test your settings from the registry, you can open 1 (!!) connection to the Simple Groupware website (password cmscms):

net use z: http://www.simple-groupware.de/sgdav/ /user:cms *


WebDAV installation on the client (Windows 7)


On Windows 7, all requests to WebDAV receive a 3 second delay in the Windows explorer. This makes WebDAV in Windows7 Explorer extremely slow. To fix this, you'll need to change IE's proxy settings:

Open IE -> Go to Tools menu -> Internet Options -> Connections -> LAN settings -> Un-check Automatically detect settings -> Click Ok -> Click Ok

By default, the Mini-Redirector uses Digest authentication which is not compatible with Simple Groupware. But you can change this to Basic authentication in the client's registry. The file "win7_webdav.reg" is included in the Simple Groupware package under "\src\tools\webdav\" and also turns off locking. It should be executed with administrator privileges and requires a restart afterwards. It changes the following settings in the Windows registry (click here for more information):

[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\WebClient\Parameters]
"BasicAuthLevel"=dword:00000002

[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\WebClient\Parameters] "SupportLocking"=dword:00000000

The Mini-Redirector included in Windows 7 fully supports SSL and the port can be different from 80.

To test your settings from the registry, you can open a connection to the Simple Groupware website (password cmscms):

net use z: http://www.simple-groupware.de/sgdav/ /user:cms *


Mount the WebDAV server to a drive letter (Windows XP / Vista)


First make sure the "WebClient" service is started:
Use "Start->Run->services.msc" and start the service "WebClient" if necessary

Then mount the folder structure to a drive letter:

Open Windows Explorer, click Tools->Map Network Drive
Choose a drive letter and define the "folder name" with: http://<your-sgs-server>/sgdav/
Click "Different user name" and enter your credentials
Then click "Finish".

Alternative: Mount with the commandline

net start webclient (if not started automatically)
net use s: http://<your-sgs-server>/sgdav/ /user:<username> *


WebDAV installation on the client (Linux)


Install the package davfs2 (at least version 1.2.1+). Example for Debian:

apt-get install davfs2/testing

In newer versions you might also need to disable the locking function: Therefore set "use_locks 0" in "/etc/davfs2/davfs2.conf".


Mount the WebDAV server to the directory tree (Linux)


Mount with the commandline:

mount -t davfs http://<your-sgs-server>/sgdav/ /mnt


If you disconnect your computer from the network, it is recommended to unmount the WebDAV connection before leaving:

unmount /mnt


Files and directories


The WebDAV folder structure is exactly the same as in the web interface of Simple Groupware. For better performance, mountpoints are not included.
There is only one difference: Windows sorts folders alphabetically. That means the order of the folders can differ from the order defined in Simple Groupware. All permissions assigned to folders and datasets take effect in WebDAV as well.

In Simple Groupware, files are appended to datasets. Every dataset can have several fields with the type "files". Also each field can have several files in one dataset. In order to identify a file, it is necessary to know the id of the dataset, the directory of the dataset, the name of the field in the dataset and the position of the file in the field. The complete filename syntax looks like this:

(Short) syntax:
<dataset-id>_<position>_filename.ext

Long syntax (for dataset fields not equal "filedata"):
<dataset-id>_<dataset-field>_<position>_filename.ext

Creating files can be done by saving a file with "filename.ext" in a WebDAV folder. Simple Groupware automatically creates a new dataset with "<dataset-id>_0_filename.ext", which is linked to "filename.ext". That means you won't see "filename.ext" in the folder, but you can continue to work with the file after saving it.

All files uploaded to Simple Groupware can be changed over WebDAV. Creating new files over WebDAV require the target folder to have the "Files" module assigned to it. New folders created over WebDAV always get the "files" module assigned.

Note: In WebDAV, folders are identified by the name and the path. In Simple Groupware, folders are identified by a unique number. There can be problems in the WebDAV client if you have two folders with the same name and the same path in Simple Groupware.

Note: Directly saving or copying a file to a WebDAV folder is limited to 20 MB per file. Saving new versions to existing files follows the limit defined in the corresponding sgsML module.


Directory indexes


Each folder with at least one dataset contains a directory index. The first index file is named "_index.html" and contains the HTML export of the current folder. The second index is named "_index.xls" and contains the Excel export of the current folder. The HTML index can be opened with your favorite browser and the Excel index can be opened with MS Excel or OpenOffice Calc.


Lock / Unlock files


Under Windows, files can be locked by double-clicking the "Lock_..._#.vbs" file. Under Linux/Unix you can execute the "Lock_..._#.sh" file. For example if you want to lock the file "101_filedata_0_Presenation.ppt", the corresponding lock script will be "Lock_101_filedata_0.vbs". If the .vbs file is not available, the file is already locked by another user.
The process to lock or unlock a file is triggered when you download the contents of the "(un)Lock_..._#.vbs" file. So it is no problem if you're using a different WebDAV client that does not execute files, downloading them is enough.
All locking operations performed with WebDAV are directly visible in the web interface. And all locking operations done in the web interface are directly visible in the WebDAV folder.


Versioning


When a file is saved on the client, the new version of the file gets automatically uploaded to the server. The old version of the file will be archived in the same dataset containing the suffix "_rev#" in the filename.

Warning: There is no limit for the number of versions created for one file. Therefore it is recommended to delete unneeded versions from time to time manually.


Users and passwords


Every user in Simple Groupware has automatically access to WebDAV. When mounting a WebDAV folder to a drive letter, just use the username and password defined in the Simple Groupware user administration (see /Workspace/Organization/Users). The super administrator account also works with WebDAV.

Note: WebDAV does only work if "Disable basic authentication" is not activated in setup settings.


Other issues


Like normal CIFS servers, you can also use the UNC path style with "\\server\share", but that will produce a flood of senseless requests on the webserver. So pay attention to map the location always to a drive letter. Connecting with My Network Places causes the same problem.

If you open the properties of a WebDAV folder in Windows Explorer, counting folders and files will be slower than expected. For example, 100 subfolders require 100 page requests on the Simple Groupware server. In order to protect the server, a delay of 2 seconds is used for requests coming in too fast.

Microsoft Office programs (Word, Excel, Powerpoint, Visio, etc.) always use their own WebDAV client. Therefore, when opening a file from windows explorer, Word always asks again for your username and password.


Implementation status


In the current version you can list directory contents, create and rename directories, (un)lock files and create or change file contents. Deleting directories or files is not yet implemented. But these tasks can be easily done in the web interface.


SyncML integration

<< contents

SyncML is a platform-independent Synchronization Markup Language. SyncML communicates on top of the HTTP protocol and can be used with a normal network or internet connection. This means that you can synchronize all kinds of information between Simple Groupware and your mobile devices. Some mobile devices support SyncML natively, others are used in combination with a special client software on the device to make it SyncML ready.
Free SyncML clients are available from Funambol for: Windows Mobile, Blackberry, iPod, iPhone, Outlook, Evolution, Palm, Thunderbird, Gmail, Yahoo, Lotus Domino and Exchange

Most newer mobile phones from Motorola, Nokia and Sony Ericsson include SyncML natively, others may be able to use the J2ME client from Funambol.

The SyncML clients cover appointments, tasks, notes and contacts whereas emails are synced over POP3 and IMAP in combination with some push techniques. Inside the SyncML messages, other data formats like iCalendar, vCard or SIF (Sync4j Interchange Format) are used. All the conversions between the different formats are handled by the Funambol server.

Simple Groupware itself does not include its own protocol handler for SyncML. Therefore it communicates with the free SyncML server from Funambol (former Sync4j).

Starting with Simple Groupware 0.420, this communication is done over the database. The Funambol server supports MySQL and PostgreSQL. So both systems need to be installed on the same database using the same credentials for the database. Since Simple Groupware has its own table schemas, datasets between both systems get converted using SQL views for import and export. To find changes, the "last_update" field is used in combination with "status" field (D=deleted, N=new, U=updated). To get started with an installation, follow the installation manual.

Before 0.420, the communication is done by exchanging XML files written in the Sync4j Interchange Format (SIF). Exchanging SIF files is done asynchronously over the filesystem, which means, you can always restart one of the servers without any unwanted dependencies. The folder used for interaction is "<Funambol-installation-folder>/ds-server/db". This location needs to be added to Simple Groupware's setup-settings (see Installation SyncML Server). In order to make notification between Simple Groupware and the Funambol Data Synchronization Server more efficient, I've implemented a changelog mechanism which needs to be added manually after the installation. See the diagram for an overview of all components:

Simple Groupware - Funambol Data Synchronization Server interaction

Simple Groupware - Funambol Data Synchronization Server interaction

From the user's point of view, all contacts in his personal contact folder and all appointments in his personal calendar folder get synchronized to the mobile device (only this folder, no subfolders or any other contact/calendar folders). When a new contact or appointment is created / updated / deleted, Simple Groupware writes a SIF dataset in the database. When a synchronization is in the process, the Funambol server reads the SIF datasets and adapts them to the changes delivered by the mobile device. In earlier version, the changes were documented in a changelog file on the filesystem, but this is no longer required. When a user visits his contacts or his calendar the next time within Simple Groupware, all new datasets get processed and the changes are merged into the database.

The synchronization is done in two-ways with only one exception: When a user deletes an item on the mobile device, then the item will still remain within Simple Groupware. Normally mobile devices can only carry a limited number of datasets. That way you can delete items from the mobile device without loosing them completely (you can change this behavior in the system configuration, see "Sync4j remote delete items"). If you need these items again, simply do a slow synchronization on the device which forces a complete new synchronization without taking knowledge about previous synchronizations.

Every user can have many devices used for synchronization. Inside the Funambol Administration Tool, every combination of a user and a device is called a "principal". You need to create a new user in order to get the synchronization working (the device and the principal will be automatically added).

The Funambol Data Synchronization Server has its own user database, so you only need to match the usernames between both systems. E.g. you have a username called "bsimpson" in Simple Groupware with password "trab". Now you create a new user called "bsimpson" in the Funambol Administration Tool and give him the password "asil", create a new device and a new principal. When the user synchronizes his mobile device he needs to provide the username "bsimpon" and "asil" as the password. So the usernames need to match between both systems, but the password on the Funambol system can be different. The URL used for the synchronization will be "http://<funambol-server-ip>:8080/funambol/ds".


Screenshots


Simple Groupware Synchronization with Outlook (calendar)
Synchronization with Outlook
(calendar)
Simple Groupware Synchronization with Windows Mobile (calendar)
Synchronization with Windows Mobile (calendar)
  
Simple Groupware Synchronization with Outlook (tasks)
Synchronization with Outlook (tasks)
Simple Groupware Synchronization with Outlook (notes)
Synchronization with Outlook (notes)
  
Simple Groupware Synchronization with Outlook (contacts)
Synchronization with Outlook
(contacts)
Simple Groupware Synchronization with Windows Mobile (contacts)
Synchronization with Windows Mobile (contacts)


Troubleshooting


When installing the Funambol SyncML server, make sure that the network port 8080 is unused and not blocked by a firewall.
When the synchronization fails, take a look at the logfile located at "<Funambol-installation-folder>/logs/ds-server/ds-server.log".

Database permissions: Both, Simple Groupware and the Funambol server need to access the same database. Therefore it is recommended to connect under the same user account and provide the right privileges.

Deleted items appear again: Please make sure that the Funambol server and the mobile clients have the same date and time configured. If the time is not synchronized properly, it can happen that deleted items come up again after the next sync.


Funambol v7


Simple Groupware 0.420 has support for Funambol version 7.0.
Funambol version 7.0 normally uses the Java-based HSQL database to store the contacts, appointments, tasks and notes. In combination with Simple Groupware, it needs to be installed with MySQL or PostgreSQL (see installation instructions). Any other additional patches are not required.

Workarounds for using Funambol 7.x with Thunderbird/Lightning:

  • Appointment recurrences: If appointment recurrences get lost during synchronization, you might need to change the configuration in the "Funambol Administration Tool", change the type from vCalendar to iCalendar
Funambol SyncSource configuration
  • Timezone conversion: If appointments appear in the wrong timezone within Simple Groupware, you might need to change the timezone handling in the "Funambol Administration Tool":
    • Navigate to <server>/Devices
    • Find the Thunderbird devices (starting with fmz...)
    • Open each item, set the Timezone and click Save
Funambol timezone configuration
Inside Thunderbird, open the Menu Tools->Options->Lightning->Timezone and set your Timezone. Then restart Thunderbird.
Thunderbird timezone configuration


Funambol v6.5


Simple Groupware 0.400 - 0.414 has support for Funambol version 6.5.
Funambol version 6.5 normally uses the Java-based HSQL database to store the contacts, appointments, tasks and notes. A patch was written to get back the old behavior for writing single files to the file system (see installation instructions). Also a new foundation .jar was built to write the changelog files. Using the Funambol v6.5 SyncML server with MySQL (instead of HSQLdb) is not supported.


Other locations


Clients for devices that don't include native support for SyncML can be downloaded here.

Clients for programs that don't include native support for SyncML can be downloaded here.

Documentation about the Funambol Data Synchronization server and the SyncML clients is available here.


Offline folder synchronization

<< contents

Offline folder reading allows you to view the contents of a bunch of folder inside the browser when being offline. This feature requires a browser or an extension that offers you to save web pages for reading them later being offline. This is useful when you have no internet connection but need your tasks, contacts, notes, etc.

To collect the folders to be read offline, every user has a folder named "Offline folders" in his profile. This folder holds one entry for each folder to be read offline. If attachments are saved offline, depends on your browser.

New folders can be quickly added for offline reading by using the top menu Folder -> Add to offline folder. Then open the offline summary page with Main menu -> Offline reading and tell your browser to save the page for offline reading. See the screenshots for a detailed view.

With Android (version 4+), you can use the context menu and choose "Save for offline reading". Using Safari (iPad and iPhone), you can add the offline summary page to the "Reading List". Firefox and Chrome offer offline reading with the extensions like "Readability" or "Read it later".

If your browser does not support reading pages offline, you can save the web page to your disk using "Ctrl + s" or try to use a cached version of the page when you're offline.

Screenshots


Simple Groupware Add a folder for synchronization
Add a folder for synchronization
Simple Groupware Start the synchronization
Start the synchronization
  
Simple Groupware Sync and go offline
Sync and go offline
Simple Groupware View folders in offline mode
View folders in offline mode

Note: Every folder is identified by its URL containing the folder-id and the name of the view. Additional parameters are described here.

Note: If the offline folder is not available in the user's profile (e.g. upgrade from 0.4x), you can create the folder manually in the user's profile and assign the module "Offline folders" to it. Then set the folder's anchor to "offline_<username>" (directly in the database or under "/Workspace/System/Tree").

Note: Changing data or uploading new files is not possible when you're offline.


Desktop Integration

<< contents

Simple Groupware can be integrated into your desktop: You can use it as your default mail client and integrate the bookmarks into Firefox or other RSS clients.


Register Simple Groupware as your default mail client (Windows)

Open regedit and change HKEY_CLASSES_ROOT\mailto\shell\open\command to:

"c:\program files\mozilla firefox\firefox.exe" http(s)://your_server/ \
sgs_path/bin/index.php?view=new&username=<username>&folder=/Workspace/ \
Personal folders/<username>/E-mail/eto=%1"

Or create a .reg file with the following content:

Windows Registry Editor Version 5.00

[HKEY_CLASSES_ROOT\mailto\shell\open\command]
@="\"c:\\program files\\mozilla firefox\\firefox.exe\" \
\"https://invalid.com/sgs/bin/index.php?view=new&username=testuser1& \
folder=/Workspace/Personal folders/testuser1/E-mail/eto=%1\""

The first value is the location of the webbrowser executable, typically Firefox. The second one is the URL of Simple Groupware containing the view ("new"), the folder ("E-mail" in the personal home directory) and the mail address ("%1") to send the mail to. Also if you're not logged in, a popup comes up to ask for the credentials.


Register Simple Groupware as your default mail client (Linux / KDE)

Go to "K (start) -> System -> Configuration -> KDE Components -> Component chooser". Select "Mail Client" and "Use another mail client". Type in the box:

/usr/bin/firefox "http(s)://your_server/sgs_path/bin/ \
index.php?view=new&username=<username>&folder=/Workspace/ \
Personal%20folders/<username>/E-mail/eto=%t"

And click "Apply". The URL may not contain white spaces, therefore use "%20" instead.


Register Simple Groupware as your default mail client (Linux / GNOME)

Go to "Applications -> Preferences -> Preferred Applications". Select "Custom Mail Reader", and type in the box:

/usr/bin/firefox "http(s)://your_server/sgs_path/bin/ \
index.php?view=new&username=<username>&folder=/Workspace/ \
Personal folders/<username>/E-mail/eto=%s"

And click "Save". The URL may not contain white spaces, therefore use "%20" instead.


Using Simple Groupware bookmarks in Firefox

Log in to Simple Groupware and navigate to the bookmarks folder. Then click on the RSS symbol next to the URL in Firefox and confirm with "Ok". A new live bookmark has been created. Now open the bookmarks in the sidebar, right click the new live bookmark and add your username and password to the feed location (e.g. username=testuser1&password=secret). Now the bookmarks from the bookmark folder in Simple Groupware appear as a live bookmark in Firefox. If you have more than one bookmark folder, simply repeat this procedure for the other folders.

Note: RSS feeds are available for every folder in Simple Groupware. If the folder doesn't contain bookmarks, all entries are placed in the live bookmark.


Using Simple Groupware bookmarks with any RSS client

Log in to Simple Groupware and navigate to the bookmarks folder. Below the tree there is a "RSS" link. Copy the link location to your RSS client and add your username and password to it (e.g. username=testuser1&password=secret).

Note: RSS feeds are available for every folder in Simple Groupware. If the folder doesn't contain bookmarks, all entries are placed in the RSS feed.


Data Handlers / Data Import

<< contents

Data import with spreadsheets (.xls) or comma / tab separated values (CSV / TSV files)


Navigate to the target folder where the data should be imported. In the menu at the top of the page click "Im-/Export" and choose "Simple Groupware Import". The import GUI comes up. Here you can choose one or more spreadsheet files to import new datasets. Uploaded files can be validated with the "Validate" button or imported with the "Import" button.

Inside the spreadsheet file, each line represents one dataset. The first line should contain the names of the fields (e.g. Subject, Begin, etc.). An example spreadsheet containing the right field names for the current folder can be downloaded by clicking "Download example file (.xls)".

Note: CSV or TSV files (.csv, .tsv) can be opened in OpenOffice and saved to .xls (Microsoft Excel 97/2000/XP).

Note: Assets can be imported into multiple folders by adding the "Folder" column to the first line and the corresponding folder IDs to the following lines.

Note: Assets can be overwritten by adding the "Id" column to the first line and the corresponding IDs to the following lines.


Direct access with a mountpoint


Simple Groupware can get data form several data sources. Among those are IMAP, SMTP, POP3, iCalendar, RSS, vCard, XML, CSV, LDIF, CIFS, etc.
To read data that is stored outside the database, you need to create a new folder and set a mountpoint to the data source.

In order to import data, you can upload files to the "<sgs-dir>/import/" folder and set a mountpoint to that file. For a user-defined import, upload files to "<sgs-dir>/simple_store/home/<username>/". The mountpoint to this folder is automatically available under "/Workspace/Personal folders/<username>/Files/Import/".

With a mountpoint, external data sources easily get integrated into the Simple Groupware folder tree (similar to the Linux file system). Inside a folder, you can use copy / paste to copy data from external data sources to the Simple Groupware database. In the Simple Groupware database, all data is indexed and can be searched quickly for all users. With the right folder permissions, you can automatically share external data sources with other users. That way, you can create public mail folders, share the latest news, integrate several file servers, etc.

Note: To use the credentials of the current user for a mountpoint, you can specify "%username%" and "%password%" as username/password.

Note: Using mountpoints to servers like IMAP, POP3, CIFS, etc. all data remains on these servers, only the caching goes to "<sgs-dir>/simple_cache".

Create a new mountpoint:

  • Click Options
  • Enter a new folder name
  • Set module to blank
  • Click OK
  • Click Mountpoint
  • Define the mountpoint (see below)
  • Click OK



Mountpoint syntax for IMAP (e-mail client)


Type: IMAP, Username, Password, Port, Security, Hostname, Path

(folder, port and tls are optional)

Example:

  • Type: IMAP
  • Username: johndoe
  • Password: secret
  • Port: 993
  • Security: tls
  • Host: mailserver.example.com
  • Path:

or if you have all your mail folders under inbox and your port is 143 without tls/ssl:

Path: /INBOX/

To use the credentials of the current user, you can specify "%username%" and "%password%" as username/password.

Limitation: In the current version, when you create a new mail in an IMAP folder, the mail gets sent immediately (if the folder is not named "Drafts"). Proxy servers for IMAP are currently not supported.

Note: When deleting a mail, the mail gets copied to the folder "INBOX/Trash" or "Trash" before deleting it. If the folder does not exist, it will be created automatically. In older versions (before 0.407), you might need to create it with a separate mail client.

Note: When sending a mail from an IMAP folder, the mail gets saved to the current folder (not to a predefined "sent" folder).

Note: If you use UW-IMAP as server and see folders that belong to the file system, you may need to specify "subscribed=true" in the options field in order to show only the folders that are subscribed.

Note: (only applies to 0.298, 0.297) If you use an IMAP server that does not support server-based sorting, you need to specify "getall=true" in the options field in order to list mails in a folder. This method will be slower in big folders.


Mountpoint syntax for POP3 (e-mail client)


Type: POP3, Username, Password, Port, Security, Hostname

(folder, port and tls are optional)

Example:

  • Type: POP3
  • Username: johndoe
  • Password: secret
  • Port: 995
  • Security: tls
  • Hostname: mailserver.example.com

or if your port is 110 without tls/ssl:

  • Port:
  • Security:

Warning: POP3 doesn't support server based structure summaries. Every e-mail has to be downloaded and completely parsed by the webserver. This takes a lot of memory and cpu resources and is very slow. Therefore you should use IMAP whenever possible.

Limitation: Proxy servers for POP3 are currently not supported.


Mountpoint syntax for SMTP (e-mail client)


Type: SMTP, Username, Password, Port, Security, Hostname

(port, tls, username and password are optional)

Example:

  • Type: SMTP
  • Username: johndoe
  • Password: secret
  • Port: 465
  • Security: tls
  • Hostname: smtp.example.com
  • Options: johndoe@example.com|John Doe

or if your port is 25 without tls/ssl:

  • Port:
  • Security:

Note: In the current version, mails are sent as a blind carbon copy (bcc) to the sender. If the sender mail address is not given in the options field, it gets determined by username@hostname.

Note: A SMTP mountpoint will only be used under the directory it is created. When sending mails from an email folder or an IMAP/POP3 mountpoint, the default SMTP connection specified for the user will be used, see Administrate Users.

Note: Beginning with version 0.311, you can define a name which is included in the from header of the mails being sent out. This name is defined next to the mail address in the options field, separated with a "|".


Mountpoint syntax for PmWiki page stores


Type: PmWiki, Path: path/ (e.g. a wiki.d/ directory)

Example:

  • Type: PmWiki
  • Path: ../import/pmwiki_cms/

("../import/" references to "sgs/import/", "../simple_store/home/username/" references to the user's directory at "sgs/simple_store/home/username/")

Note: To include uploaded files from PmWiki, you can create a directory named "uploads" in the mountpoint path (e.g. pmwiki_cms/uploads/). Also make sure that there is no ".htaccess" file inside the path that forbids accessing the upload directory.


Mountpoint syntax for Outlook CSV contacts / Google mail contacts


Type: CSV_Contacts, Path: path/filename.csv

Example:

  • Type: CSV_Contacts
  • Path: ../import/example_contacts.csv

("../import/" references to "sgs/import/", "../simple_store/home/username/" references to the user's directory at "sgs/simple_store/home/username/")

An example file is included in "<sgs-dir>/import/example_contacts.csv".

Note: If your csv file is not encoded in UTF-8, make sure that the filename contains "iso", so it gets converted to unicode (e.g. contacts_iso.csv).

Note: The first line of the csv file should look like this: "Title","First Name","Last Name","Company","E-mail Address","...


Mountpoint syntax for LDIF contacts (LDAP Data Interchange Format)


Type: LDIF_Contacts, Path: path/filename.ldif

Example:

  • Type: LDIF_Contacts
  • Path: ../import/example_contacts.ldif

("../import/" references to "sgs/import/", "../simple_store/home/username/" references to the user's directory at "sgs/simple_store/home/username/")

An example file is included in "<sgs-dir>/import/example.ldif".


Mountpoint syntax for LDAP (contacts)


Type: LDAP, Username, Password, Port, Security, Options (base DN), Hostname, Path

(folder, port, tls and base DN are optional)

Example:

  • Type: LDAP
  • Username: Johndoe
  • Password: secret
  • Port: 389
  • Security:
  • Options: dc=example,dc=com
  • Host: ldap.example.com
  • Path:

or if you have all your contacts under a special dn:

Path: /ou=Contacts/

Note: Simple Groupware tries to detect the base DN automatically using namingContexts. If the detection fails, you can specify the base DN manually inside the options field.


Mountpoint syntax for XML contacts


Type: XML, Path: path/filename.xml

Example:

  • Type: XML
  • Path: ../import/example.xml

("../import/" references to "sgs/import/", "../simple_store/home/username/" references to the user's directory at "sgs/simple_store/home/username/")

An example file is included in "<sgs-dir>/import/example.xml".

Note: See "<sgs-dir>/import/example.xml" for an example of a valid XML structure for contacts.


Mountpoint syntax for vCard (contacts)


Type: vCard, Path: path/filename.vcf

Example:

  • Type: vCard
  • Path: ../import/example_contacts.vcf

("../import/" references to "sgs/import/", "../simple_store/home/username/" references to the user's directory at "sgs/simple_store/home/username/")

An example file is included in "<sgs-dir>/import/example_contacts.vcf".


Mountpoint syntax for iCalendar (appointments)


Type: iCalendar, Path: path/filename.ics

Example:

  • Type: iCalendar
  • Path: ../import/WM2006.ics

("../import/" references to "sgs/import/", "../simple_store/home/username/" references to the user's directory at "sgs/simple_store/home/username/")

An example file is included in "<sgs-dir>/import/example_icalendar.ics".

Limitation: In the current version, special recurrences are not supported. Those are recurrences that are not in a regular repeating order. E.g. the recurrence "last Monday of the month". Others are events repeated on more than one day of the week (only the first will be chosen).


Mountpoint syntax for Outlook CSV appointments


Type: CSV_Calendar, Path: path/filename.csv

Example:

  • Type: CSV_Calendar
  • Path: ../import/example_outlook_calendar.csv

("../import/" references to "sgs/import/", "../simple_store/home/username/" references to the user's directory at "sgs/simple_store/home/username/")

An example file is included in "<sgs-dir>/import/example_calendar.csv".

Note: If your csv file is not encoded in UTF-8, make sure that the filename contains "iso", so it gets converted to unicode (e.g. contacts_iso.csv).

Note: The first line of the csv file should look like this: "Subject","Start Date","Start Time","End Date","End Time","All day event","...


Mountpoint syntax for RSS (news feeds, e.g. from Twitter)


Type: RSS, Path: http://hostname/path/filename.xml

Example:

  • Type: RSS
  • Path: http://www.nytimes.com/services/xml/rss/nyt/HomePage.xml

Note: To get a feed URL from a web page, simply click the rss icon in your browser and copy-paste the URL.


Mountpoint syntax for CIFS (file server, e.g. Samba, Windows, NetApp)


Type: CIFS, Username, Password, Hostname, Path

(path is optional)

Example:

  • Type: CIFS
  • Username: johndoe
  • Password: secret
  • Host: fileserver.example.com
  • Path:

or if you want to start in a subdirectory:

Path: /share1/anyfolder/

If your users are inside a domain, use:

Options: domain=my_domain

Note: This extension uses the PHP/Java Bridge. For more information about installing the Java Bridge, see Installation. In order to achieve the best performance, please use the DNS name or the IP address of the server (not "localhost").

Note: Since version 0.294, Simple Groupware can also store metadata for every file on a CIFS server (e.g. approval status, description, history). For a file named "myfile.txt", the metadata will be stored in a separate file called "myfile.txt.meta". So when you rename, remove or delete "myfile.txt" outside Simple Groupware, please make sure to do the same with "myfile.txt.meta".


Mountpoint syntax for Google Docs / Google Drive (online file service from Google Inc.)


Type: Google Docs, Username, Password, Path

(path is optional)

Example:

  • Type: Google Docs
  • Username: johndoe
  • Password: secret
  • Path:

or if you want to start in a subdirectory:

Path: /folder1/folder2/

Note: The mountpoint handler uses the Google Docs API. When making changes in the web interface of Google Docs / Google Drive (e.g. deleting many folders), it can take a few minutes until you can see the changes within Simple Groupware.

Note: Collections which are assigned to several parent collections will only appear on the collection which was assigned last.


Mountpoint syntax for local files


Type: files, Path: ../import/

Example:

  • Type: files
  • Path: ../import/

("../import/" references to "sgs/import/", "../simple_store/home/username/" references to the user's directory at "sgs/simple_store/home/username/")

Note: Normal users are only allowed to access "sgs/import/" and their individual user directory "sgs/simple_store/home/username/".

Note: Simple Groupware can also store metadata for every file in a local directory (e.g. approval status, description, history). For a file named "myfile.txt", the metadata will be stored in a separate file called "myfile.txt.meta". So when you rename, remove or delete "myfile.txt" outside Simple Groupware, please make sure to do the same with "myfile.txt.meta".

Note: To access NFS, you can mount an exported directory locally in the operating system and mount the local directory in Simple Groupware.

Note: The Files handler can be used to copy/paste files from the local file system to the gallery module (mass import).


Mountpoint syntax for Firefox bookmarks


Type: bookmarks, Path: path/bookmarks.html

Example:

  • Type: bookmarks
  • Path: ../import/bookmarks.html

("../import/" references to "sgs/import/", "../simple_store/home/username/" references to the user's directory at "sgs/simple_store/home/username/")

An example file is included in "<sgs-dir>/import/bookmarks.html".

Tip: Automatically view your Firefox bookmarks in Simple Groupware.

Place your bookmarks.html directly on a server:

  • In Firefox navigate to about:config
  • Create the preference name "browser.bookmarks.file" and specify your server location (e.g. "\\myserver\myshare\bookmarks.html")


Data Export and URL parameters

<< contents

Simple Groupware stores its data on the database and the hard disk. In order to use the data together with other programs and systems, you can export datasets to other file formats.


Supported file formats


  • HTML
  • CSV
  • XML
  • RSS (used for news feeds)
  • iCalendar (used for appointments)
  • vCard (used for contacts)
  • LDIF (LDAP data interchange format)
  • Spreadsheet (used in OpenOffice Spreadsheet / MS-Excel)
  • Text document (used in OpenOffice Writer / MS-Word)
  • Flexigrid (Javascript grid component)


Building a custom export


In order to build a custom export, you need to construct a special URL in your browser. The common base is the Simple Groupware URL:

e.g. http://your_server/sgs/bin/index.php.

There are common parameters (like folder, view, username, password) and data specific parameters (like begin, end).
Navigating through the tree, you will see that every dataset is placed in a folder. Folders can be specified as a number or a string:

e.g. folder=10 or folder=/Workspace/Mails/

You can find out the folder's ID by clicking the folder in the tree and analyzing the URL in the browser. That's the same for views. Every folder can have several views presenting the data. Most folders have the views "display" and "details". "Display" uses one row for every dataset, "details" presents the datasets in more details with one row for every property of a dataset.
If you don't specify a folder, the folder you last visited will be used. That's the same for a view.

Note: Starting with 0.640, you can view several folders by referencing folder titles with "*" and modules with "!<module-type>":

e.g. folder=/Workspace/Personal projects/*/!tasks

Note: Starting with 0.623, you can also reference an anchor (e.g. a user's home folder) or the module type:

e.g. folder=^home_jdoe or folder=/Workspace/Personal Folders/jdoe/
e.g. folder=^home_jdoe/!emails or folder=/Workspace/Personal Folders/jdoe/E-Mails/

Syntax: folder=^<anchor> or folder=^<anchor>/!<module-type>

Note: Folder strings also work with mountpoints.
When fetching data from a different source (like a news feed program), you also need to provide your credentials within the URL:

e.g. username=myusername&password=mypassword

All the parameters are added to the URL and separated with a "&". The first parameter is introduced with a "?". Also you need to specify the export format:

export=htmlHTML
export=csvCSV
export=xmlXML
export=rssRSS
export=icalendariCalendar
export=vcardvCard
export=ldifLDIF
export=calcSpreadsheet
export=writerText document
export=flexigridFlexigrid component


An example URL can look like this:

http://your_server/sgs/bin/index.php
?folder=/Workspace/System/Events/
&view=display
&export=rss
&username=admin
&password=mypassword

Note: To make it more readable I added line-breaks. Normally you need to write the URL in one line in your browser.

The example exports data for a news feed program. The export format used is RSS. Display is chosen as the view. The folder is /Workspace/System/Events/. Normally only a super administrator (default: user "admin") is able to read the events. Therefore we switch from anonymous access to a highly privileged user and supply username and password in the URL. By default you will see all events happened today. This can be changed with the "markdate" parameter.

markdate=dayshows events from today
markdate=weekshows events from the current week
markdate=monthshows events from the current month
markdate=yearshows events from the current year
markdate=allshows all events with no restriction to date intervals


You can define a custom start date, use "today":

e.g. today=01/02/06use 2nd of January 2006 as today
e.g. today=today +2 daysuse the day after tomorrow (see relative date formats)


An example URL to export events for the year 2006 to rss:

http://your_server/sgs/bin/index.php
?folder=/Workspace/System/Events/
&view=display
&export=rss
&today=01/01/06
&markdate=year
&username=admin
&password=mypassword

Note: To make it more readable I added line-breaks. Normally you need to write the URL in one line in your browser.


Filters


Entries can be filtered individually by adding a filter to the URL.

Filter syntax:

field|operator|value

Filter chaining (get datasets that match all filters):

field|operator|value||field2|operator2|value2||field3|operator3|value3

Operators:

eqA equal B
neqA not equal B
ltA lesser than B
gtA greater than B
likeA contains B
nlikeA not contains B
startsA starts with B


Example: get all appointments in a folder with a special organizer

http://your_server/sgs/bin/index.php
?folder=/Workspace/System/Events/
&view=display
&export=rss
&today=01/01/06
&markdate=year
&username=admin
&password=mypassword
&filters=organizer|eq|johndoe


Find


The find syntax can be used to find assets in folders. This is an easy way to get a structured search over all folders.

Basic syntax

find=table|field=value[,field2=value]

Example: find a task with closed=0 (not closed) and subject equal 'test'

index.php
?view=display
&find=simple_tasks|closed=0,subject=test

Example: find a contact with email containing '@doecorp.com'

index.php
?view=display
&find=simple_contacts|email~@doecorp.com


Extended syntax: limit the number of results

index.php
?view=display
&find=asset|table|limit|field=value[|field2=value2]

Example: find one contact with email containing '@doecorp.com'

index.php
?view=display
&find=asset|simple_contacts|1|email~@doecorp.com


Syntax: combining two criteria

find[]=assets|table|limit|field=value
&find[]=assets|table|limit|field2=value2

Example: find all tasks assigned to John and Mary (no limit)

index.php
?view=display
&find[]=assets|tasks||responsibles~johndoe
&find[]=assets|tasks||responsibles~marydoe

Note: To match values in select fields, you need to use the containing operator "~" or enclose the value in "¦", e.g. field~value or field=¦value¦


Short syntax for finding an asset by its ID

find=type|id

Example: find a task with ID 201

index.php
?view=display
&find=tasks|201

Note: All tables can be written as "simple_type" or just "type", e.g. "simple_tasks" or "tasks".


Syntax: find a folder

find=folder|simple_sys_tree|1|field=value

Example: find one folder named "Demo"

index.php
?view=display
&find=folder|simple_sys_tree|1|ftitle=Demo


Other parameters


Return entries with a special order:

orderbyorder entries by a special field
orderasc / desc: order ascending, descending

Example: show newest entries first, order by created descending

http://your_server/sgs/bin/index.php
...
&orderby=created
&order=desc


Limit the number of entries to return:

limitlimit number of entries returned
pagereturn a certain page of items

Example: return 10 entries beginning with page 2, gives items 11 to 20

http://your_server/sgs/bin/index.php
...
&limit=10
&page=2


Export only datasets with a special ID:

item[]specify a dataset ID

Example: return datasets with IDs 101 and 201

http://your_server/sgs/bin/index.php
...
&item[]=101
&item[]=201


Hide some fields from the output:

hide_fieldsspecify a comma separated list of fields

The name of a field corresponds to the field name in the database.

Example: return a view without the fields "Description" and "Status"

http://your_server/sgs/bin/index.php
...
&hide_fields=description,status


Add default values to a form in edit/new views:

index.php
?folder=/Workspace/Demo/Tasks/
&view=new
&defaults={"subject":"Hello!", "description":"Hello World!\nSecond line"}

Sets the following default values (JSON encoding):

Subject: Hello!
Description: Hello World!<line break>Second line


Parameters for downloading, locking and unlocking files


In Simple Groupware multiple files can be assigned in one dataset. Files are saved in the file system and referenced by the filename in the database. Columns referenced by simple_type "files" in sgsML can carry one or more filenames separated by the pipe symbol "|". Datasets are identified by the "item" parameter, columns are referenced by the field parameter and the position inside a column is described by "subitem" (using numeric positions like 0,1,2,etc.).

download.php allows the following parameters to download a file:

foldersee above
viewsee above
itemdataset Id
fielddefines the column name in the dataset where the filename is stored (default: filedata)
subitemdefines the position inside the column element (starting with 0)
disponoinline = download file as attachment, otherwise view in browser
image_width, image_heightnumeric values in pixel used to resize images before downloading them

Example:

http://your_server/sgs/bin/download.php
?folder=3601
&view=details
&filename=calc.xls
&field=filedata
&item[]=101
&subitem=0
&dispo=noinline


files.php allows the following parameters to lock or unlock a file:

foldersee above
viewsee above
itemdataset Id
fielddefines the column name in the dataset
where the filename is stored (default: filedata)
subitemdefines the position inside the column element
(starting with 0)
actioncan be "lock" or "unlock"
outputcan be empty to return HTTP error codes (204=success)
or "sh" to get shell output (bash) or "vbs" to
a message box output (visual basic script).


Parameters for system consoles (PHP, SYS, SQL)


The system consoles are small tools to execute any kind of PHP, SQL or shell command directly within Simple Groupware.

console=phpPHP console
console=sysSystem console (shell like)
console=sqlSQL console
code=<data>PHP, SQL or shell command
no_guihide the GUI, show only results

An example URL can look like this:

https://your_server/sgs/bin/console.php
?console=sql
&no_gui
&code=select * from simple_sys_tree
&username=admin
&password=secret

Note: The system consoles are only available for the super administrator. The no_gui parameter was added in version "0.402".


Parameters for the Simple Groupware setup


The setup contains 2 steps: First, the source code gets combined with the translations. And second, the database and some directories get created and populated. The "language" parameter is defined as a short country string, e.g. "en" for English, "de" for German, "es" for Spanish, "fr" for French, etc.

The first step is run with:

http://your_server/sgs/src/index.php?lang=<language>


The second step works like this:

http://your_server/sgs/src/index.php
?install
&language=<language>
&accept_gpl=yes
&admin_user=<admin_username>
&admin_pw=<admin_password>
&db_type=<database_type>
&db_host=<database_hostname>
&db_name=<database_name>
&db_user=<database_username>
&db_pw=<database_password>

The database type is defined by the name of the PHP module: "mysql" for MySQL, "oci8" for Oracle and "pgsql" for PostgreSQL.


Parameters for previewing Wiki content


Content from the Wiki module can be previewed with:

http://your_server/sgs/bin/preview.php
?data=<wiki content>


Parameters for creating bar charts


Bar charts (like those in /Workspace/System/Statistics) can be created by using these parameters:

typebar
statchart title
styletheme
datacomma separated data items
labelscomma separated label items
heightheight in pixel
widthwidth in pixel

Example:

http://your_server/sgs/bin/preview.php
?type=bar
&stat=Example
&style=core
&width=550
&height=175
&data=1,2,3,4,5
&labels=a,b,c,d,e


Other functions


These parameters are used for downloading layout components, including HTTP cache headers and browser specific processing.

Download open search profile:

<sgs-url>/bin/images.php?search


Download CSS style sheet:

css_styletheme
browserbrowser name

Example:

<sgs-url>/bin/images.php
?css_style=core
&browser=firefox


Download icons:

imagefilename
colorcolor
cfolder<empty>/adapt
tree_icons0/1

Example:

<sgs-url>/bin/images.php
?image=contacts1
&color=B6BDD2
&cfolder=
&tree_icons=1


Download Javascript functions:

<sgs-url>/bin/images.php 
?functions=dlgeneral functions
?functions_edit=dlnew/edit functions
?functions_sql=dlsql auto complete functions


Download Javascript menu functions:

<sgs-url>/bin/images.php 
?menu=dlmenu
?menu_small=dlminimized menu


Using modules and keyboard shortcuts

<< contents

This section is a description of some special modules and some actions that are automatically triggered.


Portal


A Portal is a module in Simple Groupware. So every folder can be a portal. By default the homepage of a user profile is a portal (see the Folder templates for details about profiles). The datasets in a portal contain URLs. These pages will be embedded in the "Display" view.

For example you can use a portal to summarize folders within Simple Groupware or include other webpages and resources. See "Workspace / Demo / Portal" in your Simple Groupware installation for a summary of folders showing RSS feeds.

So when viewing a portal folder in the "Display" view, you'll see the contents of the pages you defined. In the title there are links for "+" and "-" which can be used to make the frame of the embedded content bigger or smaller in vertical size. An URL can be located on the Internet or your local Intranet. Internal URLs that point to Simple Groupware folders can be also used.

The "Full width" parameter allows the page to take the full width instead of being displayed with two other pages in the same row. The "Height" parameter takes the initial height of the included page, e.g. "210" for a height of 210 pixels.


Some examples for internal URLs:

  • index.php?folder=9701&view=display

    This URL points to the folder number 9701 and the view display.
  • index.php?folder=/Workspace/Organisation/Users&view=display

    This one points to the folder "/Workspace/Organisation/Users" (referenced by the position in the tree).
  • index.php?folder=9401&view=display&markdate=custom&today=last monday&tomorrow=monday 23:59

    This one points to the folder number 9401 and the view display. The folder is a calendar and is opened with a custom date range to show the appointments beginning from last Monday and ending with next Monday.
  • Google Universal Gadgets: e.g.
    <script src="http://gmodules.com/ig/ifr?url=http://www.google.com/ig/modules/..."> </script>

    should be as URL:
    http://gmodules.com/ig/ifr?url=http://www.google.com/ig/modules/...
  • more information about building Simple Groupware URLs can be found here.


Calendar


Recurrences are used to define appointments that occur every day, every week, every month or every year.
By default, a recurrence never ends. This can be limited by a special end date ("repeat until") or a special number of occurrences ("repeat count"). If an appointment only takes place every second day (week, month, year), you can set the "repeat interval" to 2. If it occurs every third or forth period, set the interval to 3, 4, etc. You can also exclude specials days from the recurrence by adding these days as "repeat exclusions".
See the User Manual for more information about "Calendar recurrences" and "Calendar collision testing".


Users


This module contains all user accounts. The default folder is "/Workspace/Organisation/Users", but there can be any number of folders for user accounts. The view "Calendar" shows the birthdays and anniversaries of the users. From there, these events can be copied to a calendar folder.
When creating a user, a default folder structure for users is created under "Workspace/Personal folders/<user-name>". Also a folder is created in the local file system under "<sgs-dir>/simple_store/home/<user-name>". This folder can be accessed by the user from "Workspace/Personal folders/<user-name>/Files/Import".
User accounts can be activated or deactivated (see the views "Active" and "Inactive").
When a user is deleted, the account gets deactivated and moved to "Workspace/System/Trash". Also the user gets removed from all groups.
When a user logs in, the status in its data record is set to "online". As soon as he hits the "Logout" button, the status is set to "offline". The status only gets changed if the current status is not "out of office".
More information about users, groups and permissions can be found here.


Groups


This module contains all groups (a set of users). The default folder is "/Workspace/Organisation/Groups", but there can be any number of folders for groups.
Groups can be activated or deactivated (see the views "Active" and "Inactive"). When a group is deleted, the group gets deactivated and moved to "Workspace/System/Trash". Group memberships of a user are refreshed when a user logs into the system.
More information about users, groups and permissions can be found here.


Contacts


The view "Calendar" shows the birthdays and anniversaries of the contacts. From there, these events can be copied to a calendar folder.


E-mails


New E-mails are sent directly to the recipient(s) when the data record gets saved. E-mails are saved directly in the current folder (not in a special Sent folder).


Departments


When creating a department, a default folder structure for departments is created under "Workspace/Personal department/<department-name>". Also a group named "department_<department-name>" is created with the members of the department.
When the members of a department are changed, the members of the corresponding group also get updated. When the members of the corresponding group are changed, the members of the department also get updated (two-way sync).
When a department gets deleted, the corresponding folder structure under "Workspace/Personal department" gets moved to "Workspace/System/Trash". The group named "department_<department-name>" gets de-activated.


Projects


When creating a project, a default folder structure for projects is created under "Workspace/Personal projects/<project-name>". Also a group named "project_<project-name>" is created with the "internal participants" of the project.
When the "internal participants" of a project are changed, the members of the corresponding group also get updated. When the members of the corresponding group are changed, the "internal participants" of a project also get updated (two-way sync).
When a project gets deleted, the corresponding folder structure under "Personal projects" gets moved to "Workspace/System/Trash". The group named "project_<project-name>" gets de-activated.


Timesheets and Expenses


When a user sets an entry as "Completed", his write permissions are removed from the entry and all users belonging to the group "admin_payroll" are given read and write permissions.
After validating the entry, payroll administrators are able to set a "Booking number" to the entry and change the "status" to "confirmed" or "booked". Normal users are not able to set the status to "confirmed" or "booked".


Users / Groups

<< contents

Administrate Users


After the installation you are able to log in as the super administrator. The username and password is "admin", "admin" by default. You can (and should) change this in the setup.
To get started, open your browser and go to your Simple Groupware location, e.g. http://myserver/sgs/index.php. You are now automatically logged in as user "anonymous". To change this, click on Login/-out in the top menu. Type in your credentials. After clicking "Login" the window is closed and you get redirected to your last page authenticated as the requested user.

The setup does not create any user accounts by default. To create a new user go to "Workspace / Organization / Users" in the tree on the left side. Click on "New" in the top/middle area. Now let's enter the details for the new user. The username should have at least 3 characters (letters and numbers), the password 5 characters. Please also make sure to provide a valid e-mail address (all the other fields are optional). Next specify the SMTP connection to be used for sending mails (Tab: Account):

Syntax:
username:password:port:tls@hostname
(port, tls, username and password are optional)

If username or password contain the "@" character, replace it with "%%".

Finally choose "Create" and the new user and its profile are saved. For more information about this profile, see Folder templates.

Note: If you forgot the super administrator password, you can delete the file "<sgs-dir>/simple_store/config.php" to start the setup again. The super administrator does not have an entry in the table "simple_sys_users".

Note: After the login, users get redirected to their home directory under "Workspace / Personal folders". To change the redirection, simply set a new folder id under "Workspace / Organization / Users -> Tab: Account -> Field: Home folder id".

Note: When you create a new folder with e-mails as module, all new created mails are automatically sent using this SMTP connection.

Note: To use the credentials of the current user for the SMTP account, you can specify "%username%" and "%password%" as username/password.

Note: To read mails via the IMAP or POP3 protocol, you need to create a new folder and set a mountpoint, for details see Data Handlers.

To assign more than one e-mail address to a user, simply go to "Workspace / Organization / Mail identities" and create a new mail identity for the user. Specify the new e-mail address (e.g. john.doe@doecorp.com), the name (John Doe), the SMTP connection string (if it is different from the one defined in "Workspace / Organisation / Users") and assign the user to the new mail identity. A mail identity can be used for more than one user if you need identities for more than one person.

To send e-mails as super administrator, you'll need to add a mail identity for that user.

To make changes to an existing user, mark the user (by clicking on it) and click edit in the top/middle area.
Note: The username is used as an unique identifier for every user, so it cannot be changed.

To change the password when logged in, click "Main menu / Change settings" in the top menu. (The password for the super administrator can only be changed in the setup settings: To do this, navigate to "/Workspace/System" and click "Change Setup settings").

To change the status when logged in, click "Main menu / Change settings" in the top menu. (The status is displayed in the users list and indicates if the user is online, offline or out of the office.) Also you can configure the day start and end time for your calendar.

To assign different time zones to different users, edit the user and set the desired time zone in the "Account" tab. The default time zone can be set in setup settings.

To log out click Login/-out in the top menu. To destroy your session data (e.g. the last folder / view) click on "Main menu / Close session" in the top menu.

Deleted users will be set to inactive and moved to /Workspace/System/Trash. From there you can delete them forever or restore them using cut/copy/paste. The user profile also gets moved to the trash folder. Lookups to the deleted user will be still active for the super administrator since he has access to the trash folder.

Note: When restoring folders with cut/copy/paste, you'll need to restore the folder permissions manually for these folders.


System monitoring


Every time an (un)successful login occurs, an event is generated and displayed in the events module (inside Simple Groupware, go to "Workspace / System / Events"). If 4 unsuccessful logins occur within 30 minutes, the machine gets blocked for 15 minutes. For more information about system events, see System monitoring.


Administrate Groups


Groups are similar to users. A user can be a member of several groups. But a group can't be a member of other groups. This behavior has been chosen to avoid confusing the system administrators with hierarchical relationships and groups.

To create a new group go to "Workspace / Organization / Groups" in the tree on the left side. Click on "New" in the top/middle area. The rest is the same as for users.

Deleted groups will be set to inactive and moved to /Workspace/System/Trash. From there you can delete them forever or restore them using cut/copy/paste. Lookups to the deleted group will be still active for the super administrator since he has access to the trash folder.

Default groups for projects and departments: When creating a new department, a group with the name "department_<department>" will be created automatically containing the "members" of the department. The folders under "Personal department" also get read and write permission for the group "department_<department>".
When creating a new project, a group with the name "project_<project>" will be created automatically containing the "internal participants" of the project. The folders under "Personal projects" also get read and write permission for the group "project_<project>".
For more information about the automatic creation of folder structures, see Folder templates.

Note: Setting the fields manager, external participants in departments or projects has no effect on folder permissions and group memberships.

Note: Group memberships are only refreshed when a user logs in.


Folder permissions


Giving rights is also quite simple: Rights can be defined for every folder. Creating a new folder, it inherits the rights from its parent. All rights are positive which means if the right is set, the user or the groups gets access. If the right is not set, the access is denied. Possible rights are "read", "write" and "admin".
To set the rights for a special folder, the current user needs to have "admin" rights. The super-administrator (by default username "admin") has automatically all rights on all folders. Just click the top menu "Folder" and choose "Rights: Show" or "Rights: Edit" to view or change the rights on the current folder. Assign the needed rights and click "Save". If you want to apply the rights of the current folder to all its subfolders, just use "Apply rights to subfolders" in the folder menu. Please note that only those folders are affected, the current user has admin privileges on. There is no automatic inheritance for permissions and there are no positive / negative permissions (as known from NTFS).

When editing rights you can also set a folder quota to restrict users from filling your disks. The folder quota is defined in MB and restricts file uploads in the current folder and all its sub-folders.

Access can be also defined on a per-view basis (Display, Details, Edit, New, etc.). When editing rights for a special folder, you can also set special permissions in the fields "View access (users)" and "View access (groups)". The syntax is:

View access (users)

Syntax: |<view[,view2]>:<right>:<username[,username2]>|

Examples:
|freebusy:read:anonymous|
|freebusy:read:anonymous|details:no_read:anonymous|


Group access (groups)

Syntax: |<view[,view2]>:<right>:<groupname[,groupname2]>|

Examples:
|freebusy:read:internals|
|freebusy:read:internals|details:no_read:guests|

Right: read, no_read, write, no_write

Using view permissions, it is possible to let users create or edit assets without allowing them to rename the folder or create a subfolder.

Note: View access does not influence Cut/Copy/Paste or Delete operations.

Note: To apply the rights of the current folder to all its sub-folders, click "Rights" and "Apply rights to sub-folders" on the options pane below the tree on the left side.

Note: If access is provided for user "anonymous", all users will have access to the folder. If "anonymous" is removed from read or write access and there is no other permission set, then only the super administrator will be able to access the folder. To enable/disable anonymous logins, see setup settings.


Default folder permissions


The default folder structure (with demo folders) has the following permissions set by default:

PathAccessUser or Group
/Workspace/readanonymous
/Workspace/Demoread, writeanonymous
/Workspace/Personal foldersreadanonymous
/Workspace/Personal folders/user-xread, writeuser-x
(created automatically with new user)
/Workspace/Personal department/dep-yread, writegroup: department_dep-y
(created automatically with new project)
/Workspace/Personal projects/proj-zread, writegroup: project_proj-z
(created automatically with new project)
/Workspace/Newswritegroup: admin_news
/Workspace/Surveyswritegroup: admin_surveys
/Workspace/Contactswritegroup: admin_contacts
/Workspace/Contacts/Contact activitiesread, writegroup: admin_contacts
/Workspace/Calendarwritegroup: admin_calendar
/Workspace/Forumread, writeanonymous
/Workspace/Fileswritegroup: admin_files
/Workspace/Projectswritegroup: admin_projects
/Workspace/Booksmarkswritegroup: admin_projects
/Workspace/Helpdeskread, writegroup: admin_helpdesk
/Workspace/Accountingwritegroup: admin_payroll
/Workspace/Accounting/Expenseswriteanonymous (with asset permissions)
/Workspace/Accounting/Time sheetswriteanonymous (with asset permissions)
/Workspace/Inventoryread, writegroup: admin_inventory
/Workspace/Organisationwritegroup: admin_organisation
/Workspace/Systemread, writesuper administrator
/Workspace/Extensionsreadanonymous

Also, read access for "anonymous" (everyone) is given to:

  • /Workspace/Calendar
  • /Workspace/News
  • /Workspace/Surveys
  • /Workspace/Contacts
  • /Workspace/Files
  • /Workspace/Projects
  • /Workspace/Bookmarks
  • /Workspace/Organisation

Note: To get an overview of all folder permissions, you can log in as the super administrator and click "Permissions" in the administration overview page.


Disable modules


In addition to folder permissions, individual modules and mountpoints can be disabled for all users in setup settings. Afterwards, these modules can be re-enabled for certain users under "Workspace / Organization / Users -> Tab: Account -> Field: Allow disabled modules".


Asset permissions


Apart from folder permissions, there can be also asset permissions based on the module assigned to the folder. Using asset permissions, people with access to a folder can be restricted to read or create/edit assets. There can be three different types of asset permissions:

"Full" means read and write permissions for assets, with default set to anonymous.
"Owner write" means write permissions enabled for assets, with default set to the creator.
"Owner read" means read permissions enabled for assets, with default set to the creator.

Some examples for modules using asset permissions:
The files and cms modules use "full", the forum module uses "owner write", the timesheet and expenses modules use "owner read".

In the GUI, asset permissions are presented as a "Permissions" tab in the new/edit view of an asset.


Session handling


Every user has a session where some settings are stored. These settings can be stored for a folder, for a certain view in a folder, for a view in a module or global for every case. Each session is identified by a session_id and bound to the client IP address. The session_id is regenerated every time a login is performed. If a user is already logged in, the session gets copied. A session gets invalidated when a user is inactive for more than 30 minutes.

The settings in detail:

  • Global: username, client IP address, current folder, current theme, group memberships, read messages for POP3 / IMAP (max. 100), server id (used for creating unique dataset ids), allowed paths in the filesystem, form data tickets, cut-copy-paste data, folder states (open/closed), calendar day begin/end, tree type (folders, categories), tree page (if tree contains 100+ items), tree visible, data visible (calendar)
  • Per folder: calendar view (day, week, month, year, custom, all), calendar week start, calendar today / tomorrow, search string, selected page (datasets), current view, current folders (in categories mode)
  • Per folder+view: selected items, dataset filters
  • Per module+view: form finished (internal), dataset order/group by, dataset limit

Clicking "[All]" in the views removes session entries for folder+view, search string and folders. Clicking "Reset view" in the top menu removes session entries for folder and module+view and folder.


Backup / Restore

<< contents

System backup


Simple Groupware stores its data on the hard disk and the database. There are a lot of backup and restore techniques but I think this one should go with most of the cases.

Create a backup of the MySQL database:
<open a terminal>
mysqldump --add-drop-table --flush-logs --lock-tables --complete-insert --default-character-set=utf8 -r <output-file> -h <server> -u <username> -p <database>

Example:
mysqldump --add-drop-table --flush-logs --lock-tables --complete-insert --default-character-set=utf8 -r /backup/sgs.sql -h localhost -u root -p sgs_0_2
gzip /backup/sgs.sql

Create a backup of the PostgreSQL database:
<open a terminal>
pg_dump --clean --inserts --column-inserts -f <output-file> -h <server> -U <username> -W <database>

Example:
pg_dump --clean --inserts --column-inserts -f /backup/sgs.sql -h localhost -U postgres -W sgs_0_2
gzip /backup/sgs.sql

Create a backup of the Oracle database:
<open a terminal>
exp <username>@<database> file=<output-file> log=<log-file>

Example:
exp sgs_user@XE file=/backup/sgs.dmp log=/backup/sgs_backup.log

This creates a backup file containing all data needed to restore the database contents. Mysqldump is a database backup utility bundled with MySQL. Pg_dump is a database backup utility bundled with PostgreSQL. Exp is a database backup utility bundled with Oracle database.

Note: After creating the database backup, make sure that the output file is not empty.

Create a backup of the files stored on the hard disk:
<open a terminal>
tar --create --verify -f <output-file> --exclude 'simple_cache/*/*' -C <path-to-sgs> ./

Example:
tar --create --verify -f /backup/sgs.tar --exclude simple_cache/*/* -C /var/www/localhost/sgs ./
gzip /backup/sgs.tar

Tar is an archiving utility. The windows version can be downloaded from here.

Note: After creating the hard disk backup, make sure that the output file is not empty.


Save your backup on Amazon S3


Get your "Access Key" and "Secret Key" from the AWS account page.

Install and configure s3cmd on your server: (e.g. Debian)
apt-get install s3cmd
s3cmd --configure

Create a new bucket:
# choose a world-wide unique name, e.g. sgsbackup-42
s3cmd mb s3://sgsbackup-42

Upload your backup file to S3:
# normal upload
s3cmd put sgs.tar.gz s3://sgsbackup-42

# with GPG encryption
s3cmd -e sync sgs.tar.gz s3://sgsbackup-42/sgs.tar.gz.gpg

# with reduced redundancy option
s3cmd -rr sync sgs.tar.gz s3://sgsbackup-42

Download your backup file from S3:
s3cmd ls s3://sgsbackup-42
s3cmd get s3://sgsbackup-42/sgs.tar.gz

Check your S3 backups at: https://console.aws.amazon.com/s3/home

More information about Amazon Simple Storage Service (Amazon S3) can be found here


System restore


After having done several backups it is very important to know how to restore them. Here is my favorite method:

Restore the MySQL database using the sql dump:
<open a terminal>
mysql --default-character-set=utf8 -p -u <username> -h <server> -D <database> < <input-file>

Example:
mysql --default-character-set=utf8 -p -u root -h localhost -D sgs_0_2 < /backup/sgs.sql

Restore the PostgreSQL database using the sql dump:
<open a terminal>
psql -q -W -U <username> -h <server> -d <database> -f <input-file>

Example:
psql -q -W -U postgres -h localhost -d sgs_0_2 -f /backup/sgs.sql

Restore the Oracle database using the dump:
<open a terminal>
imp <username-new>@<database> file=<input-file> log=<log-file-new> fromuser=<username-old> touser=<username-new>

Example:
imp sgs_user_new@XE file=/backup/sgs.dmp log=/backup/sgs_restore.log fromuser=sgs_user touser=sgs_user_new

This restores the database from the contents of the backup file. Mysql is a database restore utility bundled with MySQL. Psql is a database restore utility bundled with PostgreSQL. Imp is a database restore utility bundled with Oracle database.

Note: If you restore your backup to a different database, make sure to change the Simple Groupware config file (located at simple_store/config_<version>.php).

Restore the files using the tar file:
<open a terminal>
cd <path-to-sgs>
tar --extract --verbose -f <input-file>

Example:
cd /var/www/localhost/sgs
tar -k --extract --verbose -f /backup/sgs.tar

Note: This will not overwrite anything. Make sure that the target directory and the target database are empty.


Deleted datasets


All deleted datasets and all deleted folders are moved to /Workspace/System/Trash. From there you can delete them forever or restore them using cut/copy/paste.

Note: Lookups to the deleted item will be still active for the super administrator since he has access to the trash folder. E.g. when you delete a user, the select boxes will still show the username for the super administrator.

Note: The trash only includes datasets deleted in the database. For example, deleted mails in an IMAP folder won't appear in the trash folder.


Deleted files


All deleted files are moved to the folder "<sgs-dir>/simple_store/trash" (e.g. edit an asset, click the Delete icon and Save in the form). Within Simple Groupware, you can access these files in "Workspace/System/Trash/files/trash".

Note: The trash folder only includes files deleted from datasets. For example, deleted files in a CIFS folder or a folder in the local file system won't appear in the trash.


System tasks

<< contents

The System task page contains all kinds of administrative tasks and can only be accessed be the super administrator. Therefore, login as super administrator and navigate to "/Workspace/System".


Web File Browser
The Web File Browser offers you a web-based file browser. You can make changes to the Simple Groupware folder and its sub-folders. E.g. you can use it to upload files into the import folder or change source files. The functionality is similar to an FTP account, but it is running under the Apache user.

SYS Console
The SYS Console offers you to run command-line programs directly in the browser. Like a terminal you see the output of a command. Important administrative commands are listed in a table at the end of the page. The functionality is similar to a terminal.

SQL Console
The SQL Console offers you to run SQL queries directly in the browser. Database selection and authentication is done automatically. Several keyboard shortcuts make it faster to run the most common queries.

PHP Console
The PHP Console offers you to directly execute PHP without uploading any files. The code is directly executed in the window, the result is presented in the same window.

Switch maintenance mode
Active: All users (except super administrator) are rejected, logins are also rejected.
Inactive: All users can navigate, logins are allowed.

Backup current folder
Simple Groupware also offers an internal system backup method. With this method you can quickly create backups of special folders. Login as super administrator, go to a folder and click "Main menu / Backup current folder" in the top menu. This creates a backup of the current folder and all its sub-folders. The backup is stored in /Workspace/System/Backups. There you can restore and download the backup.

Caching in general
Caching is used to increase the page's speed when performing slow operations. To limit the size on your disk you can clear these cached from time to time. Instead of clearing them all separately you can run the setup again.
Note: To clean caches you need to be logged in as super administrator.

Clean cache
Cleans up the whole cache by deleting cache files older than 30 days (or 1 day depending on the cache type). Lockings for documents are removed if they are older than 1 day.

Output cache
To increase performance the templates for the tree, tabs, etc are cached. If you make changes to templates/*, empty the cache. Also the HTML-output is cached, so it is recommended to clean this up from time to time to avoid wasting too much disk space. Also charts and resized images are being cached. If you make changes to the API or the templates, empty the cache.

Schema cache
To increase performance every module's schema is cached. If you make changes to the xml-functions, empty the cache.

Schema data cache
To increase performance when reading from external data sources, external files are cached. You should empty this cache once a month.

Debug-dir cache
When the database is unavailable all errors are logged to the debug cache (simple_cache/debug/*). Emptying this cache depends on you.

CMS cache
If pages have static page caching activated, the HTML files will be stored in the CMS cache. Every change of a CMS template will create new static files. You should empty this cache once a month.

IP cache
Every client activity is monitored with the IP address. You should empty this cache once a month.

Upload cache
Before files are moved to the data store (simple_store) they are kept in the cache (simple_cache). If the dataset is not finally committed to the database these files remain in simple_cache. You should empty this cache once a month.

E-mail cache
Attachments are copied to the cache before a user can download them. You should empty this cache once a month. Also folder contents and e-mail structures are cached using "schema data cache".

Locking cache
The locking cache contains a list of datasets that were edited recently and a list with all locked documents. You should remove all locks once a month.

Sessions cache
When a user is inactive for a longer time or finishes his session with the logout, the session data remains in the database. You should remove all sessions once a month.

Clear events
Delete all events from "/Workspace/System/Events". Contains events like PHP and database errors, user logins and other notifications.

Clear statistics
Delete all statistic datasets from "/Workspace/System/Statistics". Contains statistics for page requests, uploads, downloads, etc.

Clear trash
Deletes all contents completely from "/Workspace/System/Trash". The "Trash" folder contains all deleted folders, assets and attachments. When the trash gets emptied, accidental deletes can only be restored from a system backup.

Clear notifications
Deletes all entries from "/Workspace/System/Notifications" which are already delivered. The "Notifications" folder contains all notifications from appointments, tasks, birthdays, etc.

Optimize tables
This function analyzes and optimizes all tables in the database. Free data gets deleted and the query optimizer gets trained.

Rebuild search index
All datasets need to be indexed in the search index in order to be present in search results. This normally happens automatically, except when you're changing the contents directly in the database without Simple Groupware.

Run the setup again
This deletes the configuration in "<sgs-dir>/simple_store/config.php" and runs the setup again. The setup process clears all caches and all sessions and rebuilds the search index. If you made any changes in "change setup settings", these changes will be lost and need to be done again. That way the username / password for the super administrator will be cleared and needs to be set again.

Note: To run the setup again you'll need to be logged in as super administrator or delete the configuration file "<sgs-dir>/simple_store/config.php" on the local file system.

Change setup settings
Here you can tweak some settings and behaviors from Simple Groupware. Most important ones are authentication modes and database connection settings. E.g. if you need LDAP authentication, this is the right place to go.
Moreover, you can set the default theme, the standard mail footer, the default week start, etc. for details, see Configuration.


Running system tasks from cron


To run a system task automatically from cron, you can use:

*/5 * * * * curl -s -I "http(s)://your_server/sgs-dir/bin/index.php?action_sys=<action>&username=<admin-username>&password=<admin-password>" >>/tmp/cron_sgs_tasks.log

where <action> is:

  • clean_events (Clear Events)
  • clean_trash (Clear Trash)
  • clean_statistics (Clear Statistics)
  • clean_cache (Clean Cache)


System configuration

<< contents

The system configuration is a small form which lets you change some system parameters. These parameters include the database credentials, authentication modes, settings for debugging, parameters that influence caching, settings for the virus scanner, etc. In order to make changes to these parameters, log in as super administrator, navigate to "/Workspace/System" and choose "Change setup settings".

Note: The System configuration can only be accessed by the super administrator.


Authentication / Authentication mode


Authentication mode defines how to verify user credentials (username, password):

  • The default is "SQL", which uses the database table "simple_sys_users" to validate usernames and password.
  • "Apache based" uses Apache's built-in authentication. This can be a database, an .htaccess file, etc.
  • For NTLM, see NTLM
  • For LDAP, see LDAP / Active Directory
  • Google Apps can be used to authenticate against a Google account. A domain can be added to restrict the login to a special domain used with Google Apps.
  • Using IMAP or SMTP as authentication mode, tries to validate user credentials against a mail server. You need to provide a hostname or an IP address, port and SSL/TLS are optional. Example: mailserver:993:ssl


Other settings

  • Admin Username / Password: The username / password of the super administrator. The super administrators have access to all folders, can directly manipulate the database or execute system commands.
  • Admin Username / Password (2): The username / password of the second super administrator (optional).
  • Enable automatic user creation: Using an authentication mode different from SQL, every user still needs an account within Simple Groupware. You can create these accounts manually or check the option "Enable automatic user creation" to let Simple Groupware create the user's account automatically, when he logs in for the first time.
  • Require admin access to set mountpoints: If enabled, users will need the "admin" right assigned to the folder in order to create, edit or remove a mountpoint. A mountpoint is a definition for an external data source that can be bound to a special folder (e.g. IMAP, POP3, CSV, CIFS, etc.). See the data handlers for more information about mountpoints.

    Note: If a user changes the password of an account used in a mountpoint, the password also needs to be changed in the mountpoint definition.
  • Disable basic authentication: In some configurations, basic authentication from the web server is handled over to PHP (normally configured in a .htaccess file). Simple Groupware also uses basic authentication in case there is no session available (e.g. WebDAV or direct file downloads). By activating this setting, Simple Groupware only uses credentials provided in the login form.
  • Enable anonymous access: Enables or disables anonymous access to Simple Groupware. That means users will be able to get access without entering a username or a password. Access will be given to all folders that have read/write permissions set for user "anonymous".
  • Enable anonymous CMS: Enables or disables anonymous access to the CMS. That means users will be able to access contents of the CMS module without entering a username or a password. Access will be given to all folders and assets that have read/write permissions set for user "anonymous".
  • Disabled modules: Disables modules and mountpoints for all users. By default, all modules are enabled and all mountpoints can be set with "admin" permissions on a folder. Selected modules are disabled, non-selected modules are enabled.
  • Enable self registration: Allows everyone to create new accounts directly on the login screen. New accounts are placed by default under "/Workspace/Organisation/Users".
  • Self registration needs confirmation by an administrator: When registering for a new account on the login screen, the user account will be disabled. By default, all new user accounts are activated. To get notified when new registrations come in, you can add a notification to the "Users" folder: Go to "/Workspace/Organisation/Users", click Folder->Options in the top menu, fill the field "Notification".


E-mail reminders


Simple Groupware can automatically send e-mail reminders for upcoming events like birthdays, anniversaries, appointments, password or account expiries, open tasks and open contact activities. All reminders are sent via e-mail. The mail recipients for each dataset are defined in its notification field. All jobs are scheduled Monday to Friday at 5pm.


The default configuration sends these reminders

  • Users: Password or account expires in the next 5 days
  • Users: Birthday or anniversary is in the next 2 days
  • Contacts: Birthday is in the next 2 days
  • Contact activities: Begin is in the next 2 days or activity is open
  • Tasks: Begin is in the next 2 days or task is open
  • Calendar: Appointment starts in the next day or starts in x minutes, where x is defined in the reminder field of the appointment


Activate the reminders

Please configure your system to run the script at "http(s)://your_server/sgs-dir/bin/cron.php" every 5 minutes (e.g. by using cron and wget). Also a mail identity for the user "cron" is required for sending out the mails. Crontab example:

*/5 * * * * wget -q -O /tmp/sgs_cron.log http(s)://your_server/sgs-dir/bin/cron.php

Note: The cron script can be debugged by running it manually with "cron.php?debug".

Note: Setting up scheduled tasks with Windows Server 2003 is described here. A Win32 version of wget can be found here, information about using cron with Linux/Unix can be found here.


Setup settings

  • SMTP mail reminder: When sending out mails as reminder, this text will be used in the subject.
  • SMTP mail notification: When sending out mails for notification, this text will be used in the subject.
  • Use the mail() function for sending mails: When enabled, mails are sent with the system's sendmail command. For Windows, the SMTP connection configured in php.ini will be used. The mail function does not require any authentication, so if enabled, any user can send mails. Also there is no confirmation if the mail is stored in the queue.
  • Use the syslog() function for logging events: When enabled, system events are sent to the system's syslog. For Windows, the Windows Event Log will be used. When disabled, all events are stored under "/Workspace/System/Events" (default).


Virus scanner


There are three options to set: The first one is the path and the program name of the virus scanner (e.g. /usr/scanner/scan or c:/scanner/scan.exe), the second one defines the parameters (e.g. /ANALYZE /PANALYZE) and the third one is an output filter used to reduce the output of the virus scanner.

The third parameter contains a string that is searched in the output. If it is found, the output will only show the line beginning with the end of the string specified.

The second parameter contains the parameters for the virus scanner. Often virus scanners only provide an exit code and write the details into a report file. You can use the wildcard "@file_error@" to let Simple Groupware specify a temporary file and parse the contents of this file with the display filter defined in the third parameter.


Example for BitDefender scanner (win32)

  • Virus scanner: C:/Program Files/common files/softwin/bitdefender scan server/bdc.exe
  • Parameters: /arc /mail >@file_error@
  • Display filter: infected:

All BitDefender products integrate the command-line option. You can even run the signature update from the command-line by using "bdc.exe /update".


Example for McAfee command-line scanner (win32)

  • Virus scanner: c:/sdat4795/scan.exe
  • Parameters: /ANALYZE /MANALYZE /PANALYZE /MAILBOX /MIME /NOBOOT /NOMEM /PROGRAM /UNZIP /REPORT @file_error@
  • Display filter: Found:


Example for ClamWin command-line scanner (win32, free)

  • Virus scanner: D:/Program Files/ClamWin/bin/clamscan.exe
  • Parameters: -d "D:/Documents and Settings/All Users/.clamwin/db" -i --no-summary --detect-broken=yes >@file_error@
  • Display filter: FOUND


Example for ClamAV scanner (Linux, free)

  • Virus scanner: clamscan
  • Parameters: -i --no-summary --detect-broken=yes >@file_error@
  • Display filter: FOUND


Example for BitDefender scanner (linux)

  • Virus scanner: /usr/bin/bdc
  • Parameters: --arc --mail --disinfect >@file_error@
  • Display filter: infected:


Example for F-Prot command-line scanner (linux)

  • Virus scanner: /usr/local/bin/f-prot
  • Parameters: -packed -server -disinf -archive=10 -ai -silent -report=@file_error@
  • Display filter: Infection:


Database settings


  • Database Hostname / IP: The hostname or IP address of the database server.
  • Database User / Password: The username / password used to connect to the database server.
  • Database Name: The name of the database on the database server.


Other settings


  • Application title: The application title is a text displayed in the page title of every page.
  • CMS homepage title: The page title displayed in the CMS under "<sgs-dir>/bin/cms.php".
  • Default page in the CMS: When viewing the CMS frontend (cms.php?page=...), the starting page is identified by this page name.
  • Real URL format in the CMS: Normally all URLs look like "cms.php?page=<page>". Using "/cms/" as format changes all URLs to sth like "/cms/<page>". In order to get the redirects working, an .htaccess file is required.
  • SMTP mail footer: When sending out mails with the SMTP module, this text will be automatically put at the end of every mail. The default is "Sent with Simple Groupware" but you can change it to your needs (disclaimer, advertising, etc.).
  • Enable external mail client for "mailto:" links: If enabled, clicking a mail address or a mailto: link will open the default email program on the client (Thunderbird, Outlook, etc.). If disabled, a Simple Groupware form will come up to compose a new mail.

    Note: To use "mailto:" links with your favorite mail client, the "mailto" protocol needs to be registered on the client machine. You can test this under windows by using Start->run and "abc@def.com".
  • Use Debian binaries: Most hosting companies use Debian on their servers, but they don't install packages like catdoc, xpdf or unzip. Also sometimes the packages are installed, but the webpage is running in a chroot environment which forbids to execute these binaries. Using this option, you can directly use Debian binaries included in the "Debian binaries" extension. This extension is available in the extension manager.

    Note: These packages may not be the latest versions, so you should only use them in combination with a virus scanner.
  • Force SSL (force_ssl): Forces secure communication between the client and the server. All connections using http://<sgs-server> are automatically forwarded to https://<sgs-server>.
  • Check DoS Attacks: When the Denial of Service detection is activated, client machines requesting more than 2 pages per second receive a delay for 1 second.
    Note: Clients may be delayed although the server CPUs are not on their limit.
    So if you're using another load balance / protection system or if you only have a small number of users you can trust, you can turn this off. Also when using the Simple Groupware Client, syncing datasets will be faster when this setting is off.
  • Compress output: Automatically compress the pages. This is very useful when clients are connected with Modem or ISDN lines.
  • Cache output: Caches all pages to the hard disk. This takes more disk space but speeds up output rendering. That's very useful if you have lots of anonymous access.
  • Use APC for session storage: Use the Alternative PHP Cache for storing user sessions. This makes page requests faster but requires load balancers to route to the same machine. If the cache size is too small, sessions might be dropped although the maximum login timeout is not reached.
  • Default theme: That's the default theme that is set for the first login of a user. This setting will also be used for anonymous users.
  • Week start: This setting defines the starting day of the week (normally Sunday or Monday). That's the default setting for all users. After changing this value, you might also need to clear the session cache
  • Time zone: If the server's default time zone is different from your location, use this setting to change the default time zone for all users. Valid time zones are listed here
  • Session name in cookie: identifier for the session id parameter in the cookie. Should be different for different installations on the same server.
  • Sync4j database path: The location of the Sync4j filesystem database (e.g. D:/Program Files/Funambol/ds-server/db/ for Windows)
  • Sync4j remote delete items: Check this item to allow Sync4j to delete items remotely. Then, deleting items on a mobile device will also delete these items in Simple Groupware.
  • SIMPLE_CACHE: The temporary directory that is used for storing caches. The default is "../simple_cache" which points to "<sgs-dir>/simple_cache".
  • SIMPLE_IMPORT: Contains a comma separated list of directories which can be used for importing files. Directories can be relative (e.g. ../import/) or absolute (/usr/local/..., c:/import/). After changing the value, please logout and login again. The default is "../import/" which points to "<sgs-dir>/import/".
  • CHMOD_DIR: Sets the default permissions for new directories. The default value is 777 (read/write permissions for everyone) to make access from (S)FTP with different usernames easier. Changing this value does not affect existing directories.
  • CHMOD_FILE: Sets the default permissions for new files. The default value is 666 (read/write permissions for everyone) to make access from (S)FTP with different usernames easier. Changing this value does not affect existing files.


Debug settings


  • DEBUG:
    All requests are written to "<sgs-dir>/simple_cache/debug/capture.txt"
    Output caching using HTTP headers is disabled
    Denial of Service protection is disabled
    Memory usage gets displayed in the page title
    Schema_data cache invalidation is displayed at the top of a page
    "Enable automatic user creation" is also active for SQL as authentication mode.
  • DEBUG_SQL: When activated, all database queries are written to "<sgs-dir>/simple_cache/debug/sql.log".
  • DEBUG_SQL_FULL: When activated together with DEBUG_SQL, all database queries and their back-traces will be written to "<sgs-dir>/simple_cache/debug/sql.log".
  • DEBUG_IMAP: When activated, the IMAP communication is presented directly on the web page output (applied to all users).
  • DEBUG_POP3: When activated, the POP3 communication is presented directly on the web page output (applied to all users).
  • DEBUG_SMTP: When activated, the SMTP communication is presented directly on the web page output (applied to all users).
  • DEBUG_WEBDAV: When activated, the WebDAV communication is logged to "<sgs-dir>/simple_cache/debug/debug.txt".
  • DEBUG_JAVA: When activated, exceptions from the PHP / JavaBridge are presented in detail on the web page output (applies to CIFS data handler).


Timeouts / Limits


  • Maximum number of assets per page: Defines the maximum number of datasets to display on one page. Values higher than 100 might need bigger settings for "memory_limit" and "max_execution_time" in your "php.ini".
  • Login / session timeout: The maximum time in seconds a session stays active without any action from the user. The default value is 30 minutes (=1800 seconds). Every action from the user makes the session again active for another 30 minutes.
  • Folder refresh period: Number of seconds to wait until checking if the current folder was changed (new/deleted/changed assets). A higher value saves resources on the server.
  • LOCKING: When two users open a dataset in the edit view, a notification is displayed for the second user. This notification is displayed for 15 minutes (=900 seconds) after the first user enters the edit mode.
  • CSV_CACHE, BOOKMARKS_CACHE, ICALENDAR_CACHE, RSS_CACHE, VCARD_CACHE, XML_CACHE, IMAP_CACHE, LDAP_CACHE: Time in seconds that is used for caching external data sources.
  • IMAP_LIST_CACHE, IMAP_MAIL_CACHE, POP3_LIST_CACHE, POP3_MAIL_CACHE: Time in seconds that is used for caching mail listings and mail bodies.
  • GDOCS_LIST_CACHE, GDOCS_CACHE: Time in seconds that is used for caching file listings and folder structures.
  • GDOCS_PREVIEW_LIMIT, CIFS_PREVIEW_LIMIT: Limit in bytes to download files for previewing contents.
  • OUTPUT_CACHE: Time in seconds that defines how long output pages are kept in the cache before recaching them.
  • INDEX_LIMIT: The maximum amount of bytes that are stored in the database for searching datasets. The default value is 16kb (=16384 bytes).
  • FILE_TEXT_CACHE: Time in seconds that is used for caching contents of file previews (e.g. for .pdf, .doc, .ppt, etc.). The default is 180 days.
  • FILE_TEXT_LIMIT: The maximum amount of characters that are shown in the file previews (e.g. for .pdf, .doc, .ppt, etc.). The default value is 3000 characters.
  • max_execution_time (from php.ini): Maximum time in seconds that a PHP script can take to run and build the page (default is 30 seconds).
  • memory_limit (from php.ini): Maximum amount of memory a PHP script can take to run and build the page (default is 8M which stands for 8 megabytes). This setting needs to be enabled when compiling PHP. Note that this is disabled by default for the Windows binaries.
  • Invalid file extensions: Comma separated list of file extensions that are not allowed when uploading and downloading files. For example "exe" blocks uploads and downloads for "xy.exe".


System monitoring

<< contents

Simple Groupware has a built-in monitoring system which takes care of system problems. For example every time an (un)successful login occurs, an event is generated and displayed in the events module.
Also slow pages, slow queries, query errors or PHP errors are monitored. For better reconstructing errors, a stack trace is included in the details view.
If a quota is reached somewhere, this also results in a new event.

You can find all messages within the events module which is located at:
"Workspace / System / Events"

Note: A query is classified as a slow query if it takes more than 0.5 seconds. A slow page takes more than 2 seconds to come up.

All errors are written to "<sgs-dir>/simple_cache/debug/error.txt" first. Then the system writes the messages to the database and removes them from the text file. In case the database is not available, the messages remain in "error.txt". If the size of this file exceeds 2 MB, the system stops with the message "Can't process the error logfile, too large". Then, it is recommended to check the file manually and move it to another location in your system.


Folder templates

<< contents

Folder templates are used to automatically create folder structures for new users, new projects and new departments.
All folder templates are placed as XML files in "bin/modules/core/". During the installation, the main folder structure is read from "folders.xml" (or "folders_minimal.xml", "folders_small.xml" without demo folders). User profiles are created from "users.xml". Department profiles use "departments.xml" and projects use "projects.xml".
Every template has a nested set of "<folder>...</folder>" tags. All folders have a name and a module type. Additionally mountpoints, rights and a data import file can be specified. Data import files use the CSV format with column names in the first line or XML using column names as tags inside an "asset" tag. If a folder has no rights specified, it uses the rights of its parent. To refer to a field of a new dataset (e.g. user, project, department), the column is wrapped with "@" characters, e.g. to refer to the username as folder name, use: name="@username@". Typical attributes are:

AttributeDescriptionExample
nameName of the folderFiles
typeModule assigned to the folderfiles
anchorUnique identifier for the folderhome_@username@)
rread_groupsGroups with read permissiongroupname_a|groupname_b
rwrite_groupsGroups with write permissiongroupname_a|groupname_b
rread_usersUsers with read permissionusername_a|username_b
rwrite_usersUsers with write permissionusername_a|username_b
radmin_usersUsers with admin permissionusername_a|username_b
rexception_usersUsers with exceptional permissions for viewsfreebusy:read:anonymous
rexception_groupsGroups with exceptional permissions for viewsfreebusy:read:anonymous
dataData import file in CSV or XML formatmodules/core/departments_portal.xml
default_valuesDefault values used when creating a new asset or moving/copying an asset to the folder (inheritance to subfolders without default values)project=pr1
mountpointSets a mountpoint for the current folderfs:../simple_store/home/@username@/

Note: If a folder does not have a permission attribute (e.g. rread_users), the permissions from the parent folder will be used.

Examples:

Inline data import:

<folder name="Contacts" type="contacts">
  <assets>
    <asset>
      <lastname>Doe</lastname>
      <firstname>John</firstname>
      <contactid>JDO</contactid>
      <company>DoeCorp</company>
    </asset>
    <asset>
      <lastname>Doe</lastname>
      <firstname>Mary</firstname>
      <contactid>MDO</contactid>
      <company>DoeCorp</company>
    </asset>
  </assets>
</folder>

XML data import:

<folder name="Contacts" type="contacts" data="../import/data_contacts.xml">
</folder>

data_contacts.xml:

<assets>
  <asset>
    <lastname>Doe</lastname>
    <firstname>John</firstname>
    <contactid>JDO</contactid>
    <company>DoeCorp</company>
  </asset>
  <asset>
    <lastname>Doe</lastname>
    <firstname>Mary</firstname>
    <contactid>MDO</contactid>
    <company>DoeCorp</company>
  </asset>
</assets>

CSV data import:

<folder name="Contacts" type="contacts" data="../import/data_contacts.csv">
</folder>

data_contacts.csv:

lastname,firstname,contactid,company
Doe,John,JDO,DoeCorp
Doe,Marty,MDO,DoeCorp

When creating a new department, the default folder structure for departments will be created under "Workspace / Personal department". Also a new group with the name of the department will be created under "Workspace / Organisation / Groups". Initially this group is empty and all its members have read and write access on the new folder structure for the department. The members of this group are independant from any settings made in the department dataset (manager / second manager, members).

When creating a new project, the default folder structure for projects will be created under "Workspace / Personal projects". Also a new group with the name of the project will be created under "Workspace / Organisation / Groups". Initially this group is empty and all its members have read and write access on the new folder structure for the project. The members of this group are independant from any settings made in the project dataset (manager, internal / external participants).

When creating a new user, the default folder structure for users will be created under "Workspace / Personal folders". Initially the new user has read and write access on his personal folders. Also when creating a new user, a new folder named "<sgs-dir>/simple_store/home/<username>" will be created on the hard disk.
This folder can be directly accessed within Simple Groupware under "Workspace / Personal folders / <username> / Files / Import / <username>". The idea behind this is to use it for Samba shares or symbolic links to home directories.


LDAP / Active Directory integration

<< contents

LDAP / Active Directory


Normally Simple Groupware authenticates all users against a table in the database containing the usernames/password pairs. This table is named "simple_sys_users".
But Simple Groupware can also use LDAP or Active Directory (AD) services for user authentication.

To enable LDAP, open your webbrowser with the Simple Groupware page and log in as super administrator (username "admin" by default). Navigate to "/Workspace/System" and choose "Change setup settings". Choose "LDAP" as authentication mode and specify the IP address of your LDAP or AD server (secure connections use "ldaps://server/", unencrypted connections use "server"). By default, the connection is done to port 389. When using "ldaps://server/", port 636 will be used instead.

Using Active Directory, you need to specify the windows domain which is added to the username for the authentication (for example when the domain is set to "mydomain.local", the username "administrator" is changed to "administrator@mydomain.local", note that this field should be empty for LDAP).

In order to handle authentication, an entry point in the LDAP directory tree is required. This entry point is called a base DN and Simple Groupware tries to detect it automatically by using NamingContexts (this was successfully tested with openLDAP and Active Directory). However if this technique is not working for you or you want to choose a different "base DN", then you can specify another value in the "base DN" field.

Using LDAP you can use anonymous connections to resolve the DN of a user or provide the necessary credentials which allow searching the LDAP tree (user DN and password). The username is searched by default in the "uid" attribute within LDAP (can be changed in setup settings). For Active Directory, this attribute is automatically set to "sAMAccountName".

Also every user still needs an account within Simple Groupware. You can create these accounts manually or check the option "Enable automatic user creation" to let Simple Groupware create (or update) all accounts automatically. After making changes to setup settings, click "Save" and you're done. Automatic creation uses these fields from LDAP/AD to create or update accounts in Simple Groupware:

LDAP / ADSimple Groupware
sAMAccountName / <user-defined>username
mailemail
snlastname
givennamefirstname
telephonenumberphone
mobilemobile
pagerpager
fax / facsimiletelephonenumberfax
ipphoneskype
street / streetaddressstreet
postalcodezipcode
lcity
ststate
ccountry
departmentdepartment
descriptionjobdesc
wwwhomepagehomepage
<user-defined>location

Automatic user creation does not include group memberships. You can create these groups manually or (beginning with Simple Groupware 0.310) check the option "Use LDAP Groups" together with "Enable automatic user creation" to let Simple Groupware create (or update) all users and groups automatically. After making changes to Setup settings, click "Save" and you're done. When a user logs into Simple Groupware, his user account and his groups are automatically created (or updated) within Simple Groupware. The attribute used to identify group memberships is by default "memberOf", but can be changed in setup settings.

Note: Nested groups (groups as member of other groups) are not replicated from LDAP/AD to Simple Groupware.

Note: The super administrator is not authenticated over LDAP/AD. It still uses the username and password defined during Setup. The super administrator username/password can also be changed using "Change setup settings".


NTLM


Normally Simple Groupware authenticates all users against a table in the database containing the usernames/password pairs. This table is named "simple_sys_users".
But Simple Groupware can also authenticate against a Windows / Samba / NetApp server using NTLM. That means Active Directory can be used, but is not necessary.

To enable NTLM, open your webbrowser with the Simple Groupware page and log in as super administrator (username "admin" by default). Navigate to "/Workspace/System" and choose "Change setup settings". Choose "NTLM" as authentication mode and specify the IP address of your CIFS server. By default, the connection is done to port 445.
If you want to allow special users or groups to access Simple Groupware, add a share that gives only these persons the right to "list folder contents". The share syntax is "smb://<server-ip>/<share-name>". Please also make sure that the PHP/Java Bridge is installed on your system.

Every user still needs an account within Simple Groupware. You can create these accounts manually or check the option "Enable automatic user creation" to let Simple Groupware create all accounts automatically.

After making changes to Setup settings, click "Save" and you're done.

Note: Simple Groupware uses the jCIFS library. This library is not yet fully compatible with the latest Windows Server 2003 SP2 / 2008, therefore you'll need to disable "SMB signing" if Single sign-on is activated (and reboot the server afterwards):
Local Security Settings / Local Policies / Security Options / Microsoft network server: "Digitally sign communications (always)" -> disabled
Local Security Settings / Local Policies / Security Options / Microsoft network server: "Digitally sign communications (if client agrees)" -> disabled

In case the settings cannot be changed, you may try to modify them directly in the Windows registry (run regedit.exe):

HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\LanmanServer\Parameters
enablesecuritysignature -> 0
requiresecuritysignature -> 0


Note: The super administrator is not authenticated over LDAP/AD. It still uses the username and password defined during Setup. The super administrator username/password can also be changed using "Change setup settings".


SOAP Server

<< contents

Beginning with Simple Groupware 0.6x, a full SOAP server is included. To get all available functions, open this URL in your browser:

http(s)://<sgs-server>/<sgs-dir>/bin/soap.php

Example Output:

Simple Groupware & CMS Simple Groupware Soap/Ajax Functions

/**

 * Returns the method's input arguments
 * 
 * @return mixed Returns the methods input arguments
 */

get_echo( )

/**

 * Returns assets from the database
 * 
 * @param int|string $folder Folder ID or String (/Workspace/.../)
 * @param string $view View name (e.g. display, details)
 * @param string $fields field1,field2 or * (optional)
 * @param string $order field-name asc|desc (optional)
 * @param int|string $limit Numeric limit or offset,limit (optional)
 * @param array $items Asset-IDs (optional)
 * @return array Array with associative Arrays for each asset found
 */

asset_get_rows( $folder, $view, $fields=*, $order=, $limit=, array $items=Array )


To start your own implementation of a SOAP client, you can use the following code.


Read some datasets from a folder


header ( 'Content-Type: text/html; charset=utf-8' );

try {

	// Connect
	$client = new sgsSoapClient();

	// Try to read some assets
	$folder = '<folder-id>';
	$view = 'display';
	print_r( $client->asset_get_rows( $folder, $view ) );

}
catch ( SoapFault $e ) {

	// output error messages, trace information
	echo 'Error: <pre>';
	echo $e->getMessage(), "\n\n";
	echo $e->getTraceAsString(), "\n\n";
	echo htmlspecialchars( $client->getDebugInformation(), ENT_QUOTES );
	echo '</pre>';

}


Create a new dataset (e.g. a task)


header ( 'Content-Type: text/html; charset=utf-8' );

try {

	// Connect
	$client = new sgsSoapClient();

	// Try to create an asset
	$folder = '<folder-id>';
	$view = 'new';

	$data = array(
		'subject' => 'Example task',
		'begin' => '01/01/2010',
		'ending' => '01/02/2010',
	);

	// Success: returns the ID
	// Failure: returns an array:
	//   Array( field_name => Array( Array( field_displayname,
// error_message ),... ), ... ) print_r( $client->asset_insert( $folder, $view, $data ) );

}
catch ( SoapFault $e ) {

	// output error messages, trace information
	echo 'Error: <pre>';
	echo $e->getMessage(), "\n\n";
	echo $e->getTraceAsString(), "\n\n";
	echo htmlspecialchars( $client->getDebugInformation(), ENT_QUOTES );
	echo '</pre>';

}


Change an existing dataset (e.g. a task)


header ( 'Content-Type: text/html; charset=utf-8' );

try {

	// Connect
	$client = new sgsSoapClient();

	// Try to create an asset
	$folder = '<folder-id>';
	$view = 'edit';
	$id = '8101';

	$data = array(
		'subject' => 'Example task changed',
		'begin' => '01/15/2010',
		'ending' => '01/17/2010',
	);

	// Success: returns the ID
	// Failure: returns an array:
	//   Array( field_name => Array( Array( field_displayname,
	//   error_message ),... ), ... )
	print_r( $client->asset_update($folder, $view, $data, $id ) );

}
catch ( SoapFault $e ) {

	// output error messages, trace information
	echo 'Error: <pre>';
	echo $e->getMessage(), "\n\n";
	echo $e->getTraceAsString(), "\n\n";
	echo htmlspecialchars( $client->getDebugInformation(), ENT_QUOTES );
	echo '</pre>';

}


sgsSoapClient class


/**

 * Simple Groupware SOAP Client Example
 *
 * @author Simple Groupware Solutions Thomas Bley
 */

class sgsSoapClient
{

	/**
	 * Default server URL
	 * 
	 * @var string
	 */
	private $_url = 'http(s)://<sgs-server>/<sgs-dir>/bin/soap.php';

	/**
	 * Default server username
	 *
	 * @var string
	 */
	private $_username = '<username>';

	/**
	 * Default server password
	 *
	 * @var string
	 */
	private $_password = '<password>';

	/**
	 * Soap client object
	 *
	 * @var object
	 */
	private $_client = null;

	/**
	 * Connect to Soap server
	 * 
	 * @param string $url Soap server URL
	 * @param string $username Username
	 * @param string $password Password
	 */
	public function __construct( $url = null, $username = null,
		$password = null )
	{
		if ( $url !== null ) {
			$this->_url = $url;
		}
		if ( $username !== null ) {
			$this->_username = $username;
		}
		if ( $password !== null ) {
			$this->_password = $password;
		}

		$this->_client = new SoapClient ( null, array(
			'location' => $this->_url, 'uri' => '',
			'trace' => true,
			'login' => $this->_username,
			'password' => $this->_password ) );

		$this->testGetEcho();
	}

	/**
	 * Makes a remote soap call
	 *
	 * @param string $name Soap function name
	 * @param array $arguments Soap function arguments
	 */
	public function __call( $name, $arguments )
	{
		return $this->_client->__soapCall( $name, $arguments );
	}

	/**
	 * Verifies the server functionality over the echo function
	 */
	public function testGetEcho()
	{
		$text = array( 'test text', 'test text 2' );
		$result = $this->_client->get_echo( $text[0], $text[1] );

		if ( $text !== $result ) {
			throw new Exception( 'get_echo result mismatch:'.
			' result: '.
			print_r( $result, true ) . ' expected: '. 
			print_r( $text, true ) );
		}
	}


	public function getDebugInformation()
	{
		return print_r( array(
			'request_headers' =>
			$this->_client->__getLastRequestHeaders (),
			'request' => $this->_client->__getLastRequest (),
			'response_headers' =>
			$this->_client->__getLastResponseHeaders (),
			'response' => $this->_client->__getLastResponse ()
		), true );
	}

}


Run SOAP functions from the PHP console


Instead of using the Simple Groupware SOAP Server, you can use all commands directly from the built-in PHP console:

To run SOAP functions from the console, you need to replace "$client->" with "ajax::".

Example: create a new task from the PHP console

Login as the super administrator, click "PHP console" on the administration page and enter this code:

$folder = '2101';
$view = 'new';
$data = array(

	'subject' => 'Example task',
	'begin' => '01/01/2010',
	'ending' => '01/02/2010',

);
print_r( ajax::asset_insert( $folder, $view, $data ) );

Then click "Execute" and you're done.

Note: All folders can be referenced also as a path, e.g. instead of '2101', you can also use '/Workspace/Demo/Tasks'.


Run SOAP functions with Perl


Here is a sample code that can be used with "SOAP::Lite":

#!perl -w
use SOAP::Lite;
use Data::Dumper;

my $result = SOAP::Lite
-> proxy('http://<sgs-server>/<sgs-dir>/bin/soap.php?username=<username>&password=<password>')
-> get_echo("test","test2")
# -> asset_insert("1101", "new", {subject=>'test', ':'=>undef})
-> result;

print Dumper($result);


Run SOAP/Ajax functions with Curl


Here are some examples that can be used with curl on the commandline.
Syntax:

curl -H "X_REQUESTED_WITH: XMLHttpRequest" -X POST -d "[<parameters>]" http://<sgs-server>/<sgs-dir>/ajax.php?username=<username>&password=<password>&function=<function-name>

Example "asset_get_rows":

curl -H "X_REQUESTED_WITH: XMLHttpRequest" -X POST -d "[1201]" http://<sgs-server>/<sgs-dir>/ajax.php?username=<username>&password=<password>&function=asset_get_rows

Example "asset_insert":

curl -H "X_REQUESTED_WITH: XMLHttpRequest" -X POST -d "[1201,\"new\",{\"firstname\":\"John\",\"lastname\":\"Doe\"}]" http://<sgs-server>/<sgs-dir>/ajax. php?username=<username>&password=<password>&function=asset_insert

Note: Input and output parameters need to be encoded with JSON.


Customization

<< contents

This is a short tutorial about customizing Simple Groupware to your needs. If you have any further questions, please use the Forum.


Folder structure


bin/translated source files, will be filled automatically by the setup, for contents see "src/".
  
custom/folder for individual customizations (see persistent changes)
  
docs/changelog, information about the included libraries and the package contents
-- map/contains a map showing the call structure of the functions in the code (can be viewed with http://<your-server>/<sgs-dir>/docs/map/graph.php)
  
import/folder to import files into the tree using mountpoints
lang/translation files used to localize Simple Groupware to different languages
  
simple_cache/cache directories used to store temporary information
simple_store/uploaded files, attachments (esp. emails module), user directories, backups, lock files, and the system configuration file (config.php)
  
src/system tools (console, file browser), scripts to download files, get data for search boxes and chat, preview content (wiki, charts)
-- core/code directory for core functions (assets, import, export, triggers, folders, xml, input validation), setup, setup settings
-- ext/background images, icons, layout components (calendar, HTML editor, spreadsheet editor, etc.), Javascript files (user interface)
-- lib/external libraries for handling mails, templates, archives and images (e.g. Smarty, PmWiki, Pear, vCard parse, Text_Wiki)
-- modules/folder templates, libraries for the data handlers, user modules, system modules
-- templates/Smarty templates, stylesheets (user interface)
-- tools/binary tools to get plain text summaries for documents, resize images (win32) and other programs like the PHP/Java bridge

Language files are not parsed by Simple Groupware for every page request. Therefore there are two folders containing the sources and the translated sources: "src/" and "bin/". After the installation, only the "bin/" folder will be used by the system, so all changes should be made here.

In essence, Simple Groupware is a PHP application which stores the user's data, including the folder tree structure, in a database (SQL server). All kinds of attachments are stored in "<sgs-dir>/simple_store/".


Database structure


Apart from a few special modules, each module has an associated table in the database that holds that module's data. For example, each "contact" is a record in the "simple_contacts" table, each HTML document is a record in the simple_htmldocs table and so on.

Each module has a corresponding sgsML file which defines the fields within that module's table (see <sgs-dir>/modules/schema/*.xml). The sgsML file also specifies the user interface to be used to display and edit each field, e.g. text, date, drop-down list, etc. For example, the Contacts module is defined in "<sgs-dir>/bin/modules/schema/contacts.xml".

Every dataset automatically contains common fields like created (creation time), created by (originator), lastmodified (modification time), lastmodifiedby (editor), id (unique identifier), dsize (size of the dataset including files).

The folder tree is represented by its own table in the database (named simple_sys_tree). This table contains one record for each folder with an ID field giving the unique folder number. The tables for the other modules have a "folder" field which references the ID of the "folder" in which each record resides. For example, "simple_sys_tree" has a 1:n relationship to "simple_contacts".

Some system tables in detail:


simple_sys_tree: contains the folders in the tree

Field(s)Description
idunique ID of the folder
ftitlename of the folder
ftypemodule assigned to the folder, e.g. "sys_users" for "schema_sys/users.xml", "blank" if none
fmountpointdescribes mountpoint information if available (see data handlers)
lft, rgt, flevel, parentdescribe the position of the folder in the tree
rread_users, rread_groups, rwrite_users, ...describe the permissions assigned to users and groups
rexception_users, rexception_groupsdescribes exceptional permissions assigned to users and groups
fcount, fchcountnumbers of datasets in the folder, in its subfolders
fsizecount, fchsizecountsize of datasets in the folders, in its subfolders
fquotamaximum folder size in MB
anchorif the folder has a function, e.g. a user's home directory, project directory, etc.
default_valuesDefault values for new assets, e.g.
field1=value1
field2=value2


simple_seq_*: contains the highest ID for a special table, required for creating new (unique) IDs

simple_blank: empty table used by the default module ("schema/blank.xml")


Change the "<simple> Groupware" logo and link in the upper right corner


The logos can be changed by placing new files at "custom/ext/images/<new_file>.gif". Then copy "bin/templates/core_css.conf" to "custom/templates/core_css.conf", and edit the new file, replace:
logo = ext/images/logo.gif
logo_link = http://www.simple-groupware.de
logo_login = ext/images/sgs_logo.gif

with:
logo = ext/images/<new_file>.gif
logo_link = http://<your-homepage> logo_login = ext/images/<new_file>.gif

When finished, make sure to clear the output cache.


Change the background in the login screen


The image can be changed by placing a new file at "custom/ext/images/bg_bridge.jpg".


Remove the copyright in the lower right corner and the login screen


This is not allowed. (see this article from PHP-Nuke)


Change the webpage icon next to the URL in the browser


The icon can be changed by placing a new file at "custom/ext/images/favicon.ico". If you need a free icon editor, I reommend IcoFX.


Change the top menu


The top menu is defined at the end of "bin/ext/js/functions.js". To make changes, copy "bin/ext/js/functions.js" to "custom/ext/js/functions.js" and edit the new file. There are some functions to control the menu structure:

menu_begin()initializes the top menu
menuitem()creates a new menu item in the first level and is followed by the smenu_begin() function
smenu_begin()initializes the second menu level which gets finished by the smenu_end() function
smenuitem()creates a new menu item in the second level, parameters are the description and the Javascript action that should take place
sWin()opens a URL in the same window
nWin()opens a URL in a new window
smenu_hr()creates a new line in the second level
smenu_end()finishes the second menu level
menubutton()creates a new menu button in the first level, does not open a menu in the second level
menu_end()finishes the top menu

Example for a new menu entry:

menu_begin();
...
menuitem("My Company");
smenu_begin();
smenuitem("Intranet","sWin('http://my_company/intranet')");
smenuitem("Other page","nWin('http://other_page')");
smenu_end();
...
menu_end();


Changing templates


All templates are written with the Smarty Template Engine and are stored at "bin/templates/*.tpl". The templates will be compiled to PHP and stored at "simple_cache/smarty/". The Smarty manual can be found here.

To make changes to a template file, copy "bin/templates/<template_file>" to "custom/templates/<template_file>" and edit the new file.

When finished, make sure to clear the output cache. To let this happen automatically, see the DEBUG parameter below.


Changing themes, styles and formats


Themes are stored at "bin/templates/core_css.conf". Every theme is initiated with "[theme_name]" and contains some variables in "field = value" pairs. The values contain typical CSS colors and font definitions. The first section is not initiated by a "[theme_name]" and contains common variables that belong to all themes. That means that all variables in a theme section override the common variables. By default, every user gets the "core" theme. This can be changed in setup settings.

To make changes, copy "bin/templates/core_css.conf" to "custom/templates/core_css.conf" and edit the new file.

To create your own theme, it is recommended to expand the "[core]" section. Smaller changes like the "logo" or the "logo_link" can be also made to the common variables in the first section.

Simple Groupware can automatically change the colors of the folder icons in the tree. This is configured by the field "folder" which can be filled with "adapt" to activate this function.

A background image can be also added to the user interface by filling the variable "bg_full" with a filename that is located at "custom/ext/images/".

Other styles can be set in the cascading style sheet located at "bin/templates/core.css". To make changes, copy "bin/templates/core.css" to "custom/templates/core.css" and edit the new file.


Translation / localization


If You want to translate or localize Simple Groupware for Your language, please click here.


Create a new sgsML module


Creating a new module is basically creating a new sgsML file in "<sgs-dir>/custom/modules/schema". The simplest way is to copy the xml file of an existing module that is similar to what you want, open it in a text editor then add and delete field definitions as required. E.g. copy "<sgs-dir>/bin/modules/schema/contacts.xml" to "<sgs-dir>/custom/modules/schema/contacts2.xml". The sgsML tutorial gives an example and there is also a reference guide available.

Note: To be able to assign new modules to folders, remember to register the module in "custom/modules/schema/modules.txt" (can be copied from "bin/modules/schema/modules.txt").


Customize modules


All modules in Simple Groupware are defined in their own language called sgsML (Simple Groupware Solutions Markup Language). A tutorial is available here.


Use PHP functions to display content in a view


It is possible to load the content of a folder from a PHP function. All content is defined and interpreted in Smarty templates. So it normally looks like this in a module:

<view name="display" displayname="Display" template="display">
</view>

This uses the template "<sgs-dir>/bin/templates/asset_display.tpl" in the view "Display". To load the data from a PHP function, just use:

<view name="display" displayname="Display" function="get_my_data">
</view>

When creating a new module it should look like this:

<table modulename="Custom PHP include" default_view="display" default_sql="no_select" schema_mode="static" load_library="../custom/core/classes/custom.php">

  <view name="display" displayname="Display" function="get_my_data">
</view> <field name="id" simple_type="id" displayname="{t}Id{/t}"> </field>

</table>

This loads the data from a function named "custom::get_my_data" which can be placed in "<sgs-dir>/custom/classes/core/custom.php" (load_library attribute). So you need to create the PHP file "custom.php" and write the function into it, e.g.:

class custom {

  public static function get_my_data($folder, $view, $params) {
    $output = "<b>Hello World</b><br/>";
    $output .= "...<br/>";

    /* Smarty can be also used here (templates are in templates/*):
     *
     * $output .= sys::$smarty->fetch("custom.tpl");
     */

    // use echo $output to avoid output filtering for bad HTML and Javascript
    return $output;
  }

}

Note: All modifiers, formatters, triggers and selectors can be also added to the "custom" class.

Note: For security reasons, Simple Groupware automatically filters the output for Javascript and dynamic HTML elements. To avoid this, use "echo $output;" instead of "return $output;".

Note: To be able to assign new modules to folders, remember to register the module in "custom/modules/schema/modules.txt" (can be copied from "bin/modules/schema/modules.txt").


Make changes persistent over new releases and updates


All kinds of changes to the code, new files, images etc. can be made persistent over new releases.

During the update process, all files of the old release are moved to "<sgs-dir>/old", except those contents from the custom folder (<sgs-dir>/custom). Then the new files get extracted. Next, the setup process takes the language file (<sgs-dir>/lang) and the sources (<sgs-dir>/src), and merges both into the bin folder ("<sgs-dir>/bin").

Individual changes to the source code can be made in "<sgs-dir>/custom/customize.php". The following commands can be used to change the Simple Groupware code base:

  • Append code:
    setup::customize_replace($file,$code_before,$code_before.$append_code);
  • Replace code:
    setup::customize_replace($file,$code_old,$code_new);
  • Remove code:
    setup::customize_replace($file,$code_remove,"");

This is a very low-level technique, but it enables you to change PHP files as well as Javascript files, Smarty templates or other files.


Examples:

Create two modules under "<sgs-dir>/custom/modules/schema/new_module.xml" and "<sgs-dir>/custom/modules/schema/news2.xml".

Copy "<sgs-dir>/bin/modules/schema/modules.txt" to "<sgs-dir>/custom/modules/schema/modules.txt" and add these lines:

new_module|My new module
news2|News2

As an alternative to the "custom/" directory structure, you can use the customization functions which are called in the update or installation process, add the modification commands to "<sgs-dir>/custom/customize.php" (\n = line break):

// add a new module to module list
setup::customize_replace("modules/schema/modules.txt", "wiki|Wiki",
"wiki|Wiki\nnew_module|My new module");

// replace a module in the module list
setup::customize_replace("modules/schema/modules.txt", "\nnews|News","\nnews2|News2");

// remove a module from the module list
setup::customize_replace("modules/schema/modules.txt", "\nwiki|Wiki","");

// use text areas instead of wiki areas in the news module
setup::customize_replace("modules/schema/news.xml", "simple_type=\"wikiarea\"",
"simple_type=\"textarea\"");

Tip: Never forget to document your changes!


"custom/" directory structure


Beginning with Simple Groupware 0.620, there is an additional way to make changes persistent over new releases. Custom modules and functions can be easily persisted with the "custom/" directory structure. This directory structure is included in many operations automatically, so nothing needs to be copied in the update or setup process. E.g. having "<sgs-dir>/custom/modules/schema/tasks.xml" will be automatically used instead of "<sgs-dir>/bin/modules/schema/tasks.xml".

Here are some structures that can be overridden with the "<sgs-dir>/custom/" folder:

  • sgsML modules: modules/schema/*.xml, modules/schema_sys/*.xml
  • Folder templates (runxml trigger): modules/core/*.xml
  • Modules list: modules/schema/modules.txt, modules/schema_sys/modules.txt
  • Copy/paste schema mappings: modules/schema/mappings.txt
  • Writable popups: modules/core/popup_write.txt
  • Images / icons: ext/icons/*, ext/images/*, ext/modules/*, ext/cms/*
  • Custom class: core/classes/custom.php
  • Folder specific schema: modules/schema/*.xml.<folder_id>
  • Differential schema: modules/schema/<module>/<diff-name>.xml

Examples:

You can copy "<sgs-dir>/bin/modules/schema/tasks.xml" to "<sgs-dir>/custom/modules/schema/tasks.xml", then remove or add fields. The changed module will be automatically used in favor of the original module.

To use the changes only in a specific folder, you can copy "<sgs-dir>/bin/modules/schema/tasks.xml" to "<sgs-dir>/custom/modules/schema/tasks.xml.<folder_id>" , then remove or add fields. The changed module will be automatically used in favor of the original module in folder <folder_id>.

Instead of copying the whole tasks module to the custom directory structure, you can define a differential schema for the tasks module. E.g. create a new file "<sgs-dir>/custom/modules/schema/tasks/my_diff.xml". There can be several differential schema files which are merged in alphabetic order of the filename. Please note that "<field>" or "<view>" tags get overwritten when the "name" attribute is identical. To insert a new "<field>" before another existing "<field>", just add a "before" attribute to the new "<field>" representing the name attribute of the following "<field>". Instead of creating a new file, you can also store the differential schema in the database, see the Customization FAQs for an example.

Custom functions like validators, formatters, modifiers and selectors can be (re-)placed in "<sgs-dir>/custom/core/classes/custom.php":

custom/modules/schema/some_module.xml:

<table name="some_module" ... load_library="../custom/core/classes/custom.php">

  <view name="display" displayname="{t}Display{/t}" function="my_view" />
<field ...>
<filter views="all" function="my_filter"/>
</field>

</table>

custom/core/classes/custom.php:

class custom {

  static function my_view($folder, $view, $params) {
return "Hello world!";
} static function my_filter($val) {
...
}
}

Using this customization method helps you to:

  • keep your changes separated to the standard Simple Groupware code
  • persist your changes when doing an update


Debugging


For debugging the code, you can use these functions:

debug_html($var) gives out the contents of a variable and stops the script

debug_html(array($var1,$var2)) gives out the contents of 2 variables and stops the script

debug_queries() gives out all queries that were executed by the request and stops the script

print_r($var) gives out the contents of a variable

print_r(func_get_args()) gives the input parameters for the current function

print_r(array($var1,$var2)) gives out the contents of 2 variables

debug_file($var) writes the contents of a variable to "<sgs-dir>/simple_cache/debug/debug.txt"


In Smarty templates, you can use:

{$var|@print_r} gives out the contents of a variable

{$var|@debug_file} writes the contents of a variable to "<sgs-dir>/simple_cache/debug/debug.txt"


Search the code for a function: grep -rn "function somefunc" /<sgs-dir>/


Customization FAQ


See this page for the Customization FAQs.


General


If you change any images or icons, you may need to empty the browser cache to see the new image.
When changing templates or CSS files, make sure to clear the output cache and the browser cache.

Note: In order to get images in the "custom/" directory working, your Apache server needs to have the module "mod_rewrite" installed and running. Also ".htaccess" files need to be enabled with the "AllowOverride FileInfo" statement in "httpd.conf".

Note: If the DEBUG mode is enabled in setup settings, the templates will be automatically refreshed and the browser caching for CSS files will be disabled.


Customization FAQs

<< contents

Here are the most frequently asked questions concerning customization of Simple Groupware. General information about customizing can be found here.


How can I generate reports with or from Simple Groupware?


You can use the custom PHP include module to create a PHP based report, see this page.

You can also use a SQL query with sgsML, for example "<sgs-dir>/bin/modules/ schema_sys/nosql_processes.xml" (the query is in the "default_sql" attribute).

Another option might be to query the database directly with Eclipse Birt, Crystal Reports, JasperReports, etc.


How can I set individual permissions on each contact, bookmark, etc.?


You can edit the corresponding module, e.g. "<sgs-dir>/bin/modules/schema/contacts.xml", and replace:

<table ...

with:

<table enable_asset_rights="full" ...

This gives a new tab in the "edit" and "new" views to set additional permissions only affecting the corresponding dataset. The defaults are "read" and "write" permissions for everyone (anonymous). To set the defaults to the current username, you can use "owner_read" instead of "full". To enable only individual write permissions, you can use "owner_write" instead of "full".


How can I change a module only for a special folder?


You can edit the folder in "/Workspace/System/Tree" and fill the "Custom schema" field with some new sgsML describing the changes.

For example, customize a task folder:

 <?xml version="1.0" encoding="utf-8"?>
 <table>

   <!-- Add new view for high priority tasks -->
   <view name="highprio" displayname="High priority" template="display"
     where="(priority='immediate' or priority='urgent')" before="details">
   </view>

   <!-- Add second description field -->
   <field name="description2" displayname="Description 2" simple_type="textarea"
     before="url">
    <notin views="display|display2|calendar"/>
   </field>

   <!-- Disable project and milestone fields -->
   <field name="project"/>
   <field name="milestone"/>

   <!-- Change description label -->
   <field name="description" displayname="My custom label"
     simple_type="textarea">
     <notin views="display|display2|calendar"/>
   </field>
 </table>

The custom schema acts as a differential schema gets automatically merged with the schema defined by the corresponding module. So you can add new fields, change existing fields, hide fields, add new views, etc.


How can I put all datasets of a big folder into a separate table in the database? (better performance)


You can edit the folder in "/Workspace/System/Tree" and fill the "Custom schema" field with some sgsML referencing the new table. Then move all relevant datasets from the old table to the new one.

For example, move a E-mail folder:

 <?xml version="1.0" encoding="utf-8"?>
 <table name="simple_emails_2">
 </table>

In the SQL console run:

INSERT INTO simple_emails_2 SELECT * FROM simple_emails WHERE folder=<folder-id>;

and:

DELETE FROM simple_emails WHERE folder=<folder-id>;

Note: Folder merging does not work across different tables.


How can I forbid folder deletion but keep rights on creating, editing and deleting elements?


You can change the required rights from "write" to "admin" in "<sgs-dir>/bin/ajax.php" (server-side) and from "rights_writeable_folder" to "rights_admin" in "<sgs-dir>/bin/ext/js/functions.js".

replace:

static function folder_delete($folder) {
self::_require_access($folder, "write");

with:

static function folder_delete($folder) {
self::_require_access($folder, "admin");

replace:

if (!no_folder_operations && rights_writeable_folder) {
...
smenuitem("{t}Delete incl subfolders{/t}","folder_delete()");

with:

if (!no_folder_operations && rights_admin) {
...
smenuitem("{t}Delete incl subfolders{/t}","folder_delete()");


Extension Development

<< contents

To start with an own extension, it's recommended to check the latest example module available here. All the other extensions can be downloaded without the extension manager here. An extension can include several modules based on sgsML, differential schemas, images, readme files, installation and un-installation procedures, folder structures, etc.

Most of the functionality of a module is built with sgsML. All relevant manuals about sgsML can be found here. Documentation about the extension manager can be found here.

To test and develop a module, it's recommended to put all files under "<sgs-dir>/custom/" and create the "tar.gz" archive from there.


An example folder structure of an extension can look like this:

 tar -ztf SimpleGroupware_Example_0.2.tar.gz
 example/
 example/folders.xml
 example/install.php
 example/modules.txt
 example/package.xml
 example/readme.txt
 example/uninstall.php
 example/update.php
 modules/schema/example.xml


The description of a package is defined in the file package.xml, for example:

 <package>
 <name>example</name>
 <filename>SimpleGroupware_Example_0.2.tar.gz</filename>
 <require_version>0.640</require_version>
 <title>Example 0.2</title>
 <php_version>5.1</php_version>
 <size>10240</size>
 <description>
 Example is a demonstration module for handling bookmarks.
 It is similar to the normal bookmarks module, but does not contain categories.
 A new folder "Example" is created under "/Workspace/Extensions/".
 <![CDATA[
 License: <a target="_blank" href="docs/licenses/gpl_license.txt">
 GNU GPL v2</a>
 Author: Copyright (C) 2010 by Example Author
 ]]>
 </description>
 </package>

The tags are described as follows:

  • "name" contains a unique name of the module which is also used for the main folder of a module.
  • "filename" sets the filename of the package, finally available on
    "http://sourceforge.net/projects/simplgroup/files/simplegroupware_modules/<name>/<filename>".
  • "size" should be the size of the uncompressed "tar" file of the package in bytes.
  • "require_version" describes the minimum version of Simple Groupware that is required to run the module.
  • "php_version" has the minimum PHP version which is required to run the module.
  • "title" will be displayed in the list of packages in the extension manager.
  • "description" holds a multi-line description about the package, it's license and the copyright.


Other important files in the main folder of the module (optional):

  • install.php: gets executed during installation
  • uninstall.php: gets executed during un-installation
  • update.php: gets executed during update
  • modules.txt: extends list of modules, used to create or rename folders
    (one line per entry, syntax: <module name>|<module displayname>)
  • sys_modules.txt: extends list of administrative modules, used to create or rename folders
  • folders.xml: creates folders automatically during the installation (see folder templates)
  • readme.txt: is displayed during the installation


Translations

All files of an extension are translated automatically during the installation. To get strings translated, just use the normal translation blocks, e.g. "{t}Name{/t}". If possible, all extensions should be coded in English. Modules in other languages can be also published, but may be less interesting for the world-wide community. Translation files are not included directly in an extension. They are available within a separate extension containing all translations for all modules.


Release management

Similar to other application stores, all extensions get reviewed before being published. That way, people without programming skills can install extensions without fearing security or stability problems. To build a release, create an archive and upload it to the patch tracker. After the review, the module gets uploaded to the sourceforge repository and is available for everyone through the extension manager.


Interesting extensions

  • example: recommended for getting started (download)
  • private_items: example for differential schemas (download)
  • mini_tasks: example for creating a new module from an existing module (download)


Translation / localization

<< contents

Simple Groupware is written in English and contains translations for German, Arabic, Brazil/Portuguese, Greek, Croatian, Czech, Danish, Dutch, Ukrainian, French, Hungarian, Indonesian, Italian, Russian, Polish, Slovak, Spanish, Swedish, Turkish and Chinese (Simplified). Translations include the wording and date/time formats.

This is a small guide to help you building your own translations and getting your language into the next release of Simple Groupware.

  • To start with the translation into your language, please download the latest release of Simple Groupware (here).
  • Extract the archive.
  • You'll find a directory named "lang" in the root. Inside this directory all language files are kept.
  • Every language has one file. In this file all strings that should be translated are kept, including those from PHP scripts, XML modules, Javascript files, HTML templates, etc.
  • To start with your translation, make a copy of master.lang and specify a name corresponding to your language (e.g. de.lang for German).
  • Inside the language file, every original item and every translated item is placed on a separate line.
  • The original language is English. The English items are written inside translation tokens {t} and {/t} (e.g. {t}Sentence to translate{/t})
  • The next line after the original English item will contain your translation
  • The line after your translation is left empty.
  • If you don't want to translate an item and use the English term instead, copy the English translation in the translation line.
  • In addition to words and sentences, also date and time settings can be translated into your language.
  • The exact expressions (e.g. m/d/Y) can be found under (http://www.php.net/date)
  • E.g. "g:i a" shows hours and minutes in the 12 hour style, using the translation "H:i" gives the 24 hour style.
  • When you're finished, please upload your language file to the forum. If you have any questions, feel free to mail me.
  • It will be available with the next release and published under the GNU GPLv2 license.

Tip: You might also get some help with the translation by using Google Translate. Therefore open Google Translate and upload the language template from "<sgs-dir>/lang/master_google_translate.lang.html".

Note: Simple Groupware automatically tries to detect the charset. If your language file is using UTF-8, it needs a BOM header at the beginning to be included correctly. I recommend Notepad++ as editor for creating or changing language files.

Note: Language files are not parsed by Simple Groupware for every page request. Instead they are compiled into the php code in order to increase the performance.
If you want to test your new language file, empty the directory "<sgs-dir>/bin/" and delete the file "<sgs-dir>/simple_store/config.php". Then open your browser with http://your_server/sgs_dir/src/index.php?lang=<your-country-extension>, e.g. http://localhost/sgs/src/index.php?lang=de to process the German translation file de.lang and run a new installation.

Important: Please commit your translation items as soon as you have created them in order to avoid duplicates and redundant work of others.


Speedup techniques

<< contents

Tree optimization
The tree is accelerated with a modified pre-order algorithm which makes it possible to get the right slice of the tree using one single query without recursion.

Output compression
The HTML output is automatically compressed. There is no need for any Apache modules. This reduces the bandwidth by factor 10-15 and results in page sizes around 4-8 KB (suitable for Modem and ISDN lines).

Static content caching
Some files like icons, CSS sheets or Javascript files are requested with every click made by the user. But the browser doesn't know that the files are always the same and only caches them for a certain predefined time. To avoid transferring these files again and again, a caching algorithm is used to tell the browser that his old file is still the latest one.

Output caching
Additional to the output compression, the whole output is cached to disk. So when the data hasn't changed, the output doesn't need to be generated again and again.

Object caching
All the sgsML modules are cached as serialized objects to the disk. Therefore they don't need to be parsed and processed every time. Thus time-expansive operations like synchronizing with the metadata from the database only needs to be done when the modules changes.

Smarty optimization
Simple Groupware contains an optimized version of the Smarty template engine. It is tuned to replace loop inclusions (which are a real time killer) with one single inclusion.

Caching external data sources
Accessing external data sources can be very slow (e.g. IMAP, iCalendar, RSS), especially when the network bandwidth is low, the data source is slow or there too many requests outstanding. Therefore all external data sources are cached with a TTL-based caching algorithm.

Image caching
Generating charts directly on the server is a slow process. Oftentimes users request the same chart from the server again and again. A special hashing algorithm is used to avoid generating the same chart twice.


Performance monitoring
Simple Groupware has built-in performance monitoring. When a page cannot be rendered in a specified time or the database response is too slow, an event is generated and displayed in the events module (inside Simple Groupware, go to Workspace / System / Events).

System monitoring
Every time a database query fails or an unexpected PHP error occurs, an event is generated and displayed in the events module (inside Simple Groupware, go to Workspace / System / Events).


Roadmap

<< contents

Simple Groupware 0.8x features

  • New modules: quiz, bookings (cars, rooms, beamers), knowledge base, blogs, attendance and time management, Resource module, HR module (application/approvals, etc.)
  • New data handlers: S3, Dropbox
  • iCalendar server via WebDAV for writing, CardDAV / CalDAV support
  • Add email signatures to identities
  • calendar: automatic collision testing
  • Bookmark syncing with Firefox
  • Workflow engine for document approvals
  • Integrate XMPP (Jabber/Google Talk) client
  • Improve statistics: show total pageviews, average pageviews per day, number of files, size of files, biggest folders, etc.
  • Filter values with a single click
  • Add Sales Campaigns, Sales Leads, Sales Opportunities, Sales Orders
    Campaigns generate leads which turn into opportunities and eventually orders
  • Save filters per folder
  • Modifiers for files like format conversion for images, compressing files, (de)crypt files, copy attachment(s) from e-mail to files/fs, etc.
  • Add option to open new/edit views in the preview pane
  • Configuration tool for ISPs to create several instances using information from LDAP
  • Automatically fetch mails, contacts into the Simple Groupware tree
  • IMAP group emails by thread
  • IMAP recursive folder search (low priority)
  • support for other webservers like lighttpd
  • Anything more ? (please use the Contact form)


Note: There are no fixed timetables for features or releases.


Simple Groupware 0.7x features

  • New modules: intranet, vacation, absent days, milestones, timesheet, surveys, HR module (leave management, employee records, etc.)
  • Modifiers for files like virus checking
  • New data handlers: Google docs
  • Install extensions without internet connection
  • support for other webservers like nginx
  • image preview for PDF files
  • new uploader for XLS files
  • lightbox for the gallery module
  • GUI based customization for sgsML fields
  • vertical preview pane
  • APC for caching and sessions


Simple Groupware 0.6x features

  • Layout: fix save buttons and paging bar to page bottom
  • Option to add a second super administrator
  • Expand simple_type "file" to import existing files from local/public store instead of upload
  • Embed Simple Groupware content into CMS pages (similar to Ai recipe)
  • compose html mails
  • Option to rate entries
  • Drag and drop of e-mails and files
  • don't show passwords in cleartext on the screen
  • Single-click edit: reverse a checkbox
  • Imap: create / delete / rename folders
  • Auto-calculation for contact IDs
  • Implement folder notifications (receive emails about all changes in a folder)


Simple Groupware 0.5x features

  • Select items with doubleclick in popups for new/edit forms
  • short, simple URLs that refer to Companies, Contacts, Calendars, etc.
  • Add cancel button to new/edit page (Go back without saving)
  • Add permissions for special views in a folder
  • Customize home folder to redirect after login
  • Copy folder structures using copy/paste just like cut/paste in the options menu in the tree
  • display html mails


Simple Groupware 0.4x features

  • Expand global search function: Add searching in all items of a special module (next to searching all subfolders)
  • Make import folder(s) configurable in setup settings
  • Add special directories for customized files
  • Double-click in display: open details view
  • Ajax-Refresh for new/edit view on creating new items in popups
  • Expand simple_type "file" to import files from a URL instead of upload

Simple Groupware 0.2x / 0.3x features

  • New modules: expenses, tts (issue ticket system), notes, forum, spreadsheets
  • Document check-out/-in and a view that shows files currently locked
  • Automatically add contact birthdays into calendar
  • E-mail notification for deadlines of calendar events / tasks
  • E-mail notification for changes in certain datasets
  • SyncML support for tasks, notes, calendar events, contacts
  • Document calendar usage (esp. recurrences: repeat interval / repeat count, etc.)
  • Import Oulook calendar from a csv file
  • Show free/busy view of a calendar
  • Task dependencies (e.g. Task A must be finished to start Task B)
  • New modifiers to show a preview of important files (.pdf, .doc, .sxw, etc.)
  • Enable functions for adding additional datasets depending on the result from the database (e.g. summing up a column)
  • Write a new module for storing bookmarks of special folders in a folder
  • Improve calendar: add colors to events
  • Add schema for creating department folders automatically (with contacts, mails, etc.)
  • Write a new module for storing photos and a template for showing n-pictures per row


sgsML Tutorial

<< contents

This is a small tutorial intended to help you to understand and develop web applications with sgsML.


Introduction


For many years now I'm writing web applications. Using PHP, Java, HTML, CSS, Javascript in combination with MySQL, Oracle, MsSQL, etc. always struggling with the complexity of web applications. Making changes in one point always influences many other parts of the program. Often applications have several thousand lines of code (or even more). Searching bugs or making daily changes like adding fields takes a lot of time because you need to test the whole application again. Since time is rare and deadline are sharp, it's time to optimize the common web application architecture.

Looking at bigger programs with many web applications, people start writing frameworks for common functions, managing users and parts of the user interface. But these frameworks are often very limited in functionality or require too much time to learn. Using a small framework, you still need to deal with the full complexity of coding PHP, Java, HTML, etc. Moreover when working in bigger teams with a small framework, everyone writes its own specializations for his part. This creates a unmanageable lack of consistency and increases costs for adding new functionality and fixing bugs. Therefore many companies create bigger frameworks to prevent programmers from getting too individual with their code. With Java this is enforced using object-oriented programming (maybe also with PHP in the future). But I think that all these concepts are still too difficult to learn and understand in short time.

That's why I created a new programming language only intended for web applications. You might ask: Hey, are you just creating another language with the intention to replace all the others? The answer is no. The other languages are still used, but in a different way. This is important to understand, because today programming languages are so complex in usage and syntax, and this gets harder every year.


So what is different when working with sgsML?


You no longer need to be the super nerd of a programming language. Now you can create good web applications without having learned programming for ten years. To build web applications with sgsML it is enough if you can write functions with 5 to 10 lines of code. You no longer write functions to store or load data in the database. You no longer write GUI components just like HTML editors, spreadsheets or data selectors. How can this work?
The name sgsML already indicates a relation to XML. To produce applications written in sgsML, XML version 1.0 has been chosen as the syntax for sgsML files. This format is easier to read and interpret than many other formats (e.g. ini, CSV, CSS, etc.). As said before we are talking about sgsML files, meaning that one module (e.g. companies or appointments) is written into one file with the extension ".xml".


Types


With sgsML a field is generally defined by its type. This can be a text, a date, a number, etc. So when you define a field as text with sgsML, Simple Groupware creates this field in the database with the correct type and size in the corresponding table. Furthermore Simple Groupware already knows how to display this field (You only have to decide between a horizontal or a vertical view) including sorting, searching, etc. Additionally, forms to create or edit this field inside a dataset are created automatically for you.

Syntax: Types are declared with simple_type="type" where type is one of int, float, text, password, id, hidden, select, wikiarea, codearea, textarea, htmlarea, checkbox, files, date, time, datetime ... for a complete list, see src/modules/schema/!examples.html.


Validators


To be able to validate inputs made by a user you are able define functions that take care of this. E.g. you define a field as type text and also declare that it has to be validated with the two functions myvalidate1 and myvalidate2. When a user wants to save a new dataset these two functions are called with the value of the field as a parameter and you only have to return a true/false-like answer to tell the program that the input is valid or not. You don't have to care about displaying the form again, mark the field with color red, display the error message to the user, etc. This is all done for you automatically. These 2 functions are normally pretty easy and so small that even beginners can write them very quickly (they don't need any knowledge about the database, or HTML forms with heavy usage of Javascript). To make these functions smaller in size, you can define more than one functions for the validation of a field. This also helps you reuse functions (-> you automatically produce reusable code).
E.g. you want a field to be a positive number: Just write one function "is_numeric" that controls if the value is a number and a second one called "is_positive" that tests if it is positive.
Of course, validating a German, English or ISO formatted date requires some work. Therefore a large number of functions for validating dates, strings and numbers is already shipped with Simple Groupware by default.

Syntax: To collect these functions in a central place, all validators are stored in core/functions_user.php and have a "validate_" prefix, e.g. "validate_is_numeric". To define a validator in a sgsML file, write <validate function="is_numeric"/> between the <field>-tags to validate the field with the function validate_is_numeric.


Filters


Reading carefully you have read that Simple Groupware automatically displays your fields. But oftentimes you want to display fields differently from the value stored in the database. This is no conflict since you can define filters that change the value of a field before being displayed. This is elementary when working with dates. E.g. your database is configured for English dates, but you want to display them in German. Or you want to crop long texts to only show the first 20 words. Similar to validators you assign a function to the field that performs the filtering operation. This function takes the value of the field as input and returns the filtered value back to the program. This is also very easy for beginners who don't need to care where the field is displayed or where the value comes from. As said Filters are similar to Validators, which means you can make the functions smaller in size by defining more than one function for the filtering process of a field. This also helps you reuse functions (-> you automatically produce reusable code).
E.g. you want a date field to be presented as a German date, take a look at the following code:

<filter views="all" function="dateformat||m/d/Y"/>

This illustrates you the syntax of a filter and also the syntax for applying parameters to your functions (simply add a "|" to separate the parameters). To make working with dates easier for you, the function to format dates is already shipped with Simple Groupware. The first parameter takes a verbal date modification, e.g. now + 1 month which returns the date increased by 1 month. The second parameter defines the format of the date.
An overview of the format parameters can be found at http://www.php.net/date. Examples dealing with modifications of dates are here: http://www.php.net/strtotime.

Syntax: To collect these functions in a central place, all filters are stored in core/functions_user.php and have a "modify_" prefix (because they modify data), e.g. "modify_dateformat". To define a filter in a sgsML file, write <filter views="all" function="truncate|20"/> between the <field>-tags to truncate the field to a maximum of 20 characters with the function modify_truncate. (The "views=all" parameter indicates that this filter is used with every view and will be discussed later) Other functions are included to help you to manage files, URLs, source code highlighting, etc.

Note: for being neutral the date is stored in the database as timestamp (=an integer value).

Store and Restore


Being as simple as possible, Simple Groupware automatically stores/reads data to/from the database. But sometimes you want to store inputs made by the user differently from the original value. E.g. the user types a date with a German formatting, but in the database it has to be a timestamp. Or you want to store URLs without a leading http:// in the database.
Similar to validators and filters, functions used for storing the input get the value from the form as the first parameter and return the modified value back to the program. You don't have to care how the value is transferred from the form to your function. This makes things much easier, e.g. file uploads require big error handling routines that would boost up your code unnecessarily. When modifying data before writing into the database, it is clear that there must be a re-transformation when being read from the database. This re-transformation is called restore. That's why there are restore functions, that are identical to filter functions regarding structure and functionality.
Thus, writing store and restore functions is as easy as validators or filters. To reduce your functions in size you can also define multiple store or restore functions.

Syntax: To collect these functions in a central place, all store and restore functions are kept in core/functions_user.php and have a "modify_" prefix (because they modify data), e.g. "modify_datetime_to_int" converts a date given as string to a timestamp using integer representation. To define a store or restore function in a sgsML file, write <store function="datetime_to_int"/> and <restore function="dateformat||d.m.Y"/> between the <field>-tags to work with a date-field using the functions modify_datetime_to_int and modify_dateformat.
As told before, Simple Groupware already knows a type called "date". Therefore you only need restore/store functions when defining your date-field with type "int". Using type "date" this is done automatically for you.

Note: The store functions are called after those used for validating the input.

Note: The restore functions are called before those used for filtering values from the database.


Data sources


Often it is necessary to build fields that already contain a set of data from which the user can choose the right values. E.g. this is a typical behavior for select-boxes. When writing an address book you might like to implement a field containing the gender of a person. The preferred values are male and female. The type "select" defines a select-box in Simple Groupware. To define the preferred values you use the <data> construct in sgsML, e.g. <data values="male|female"/> Using more than one value, separate each with a "|". You can also define more than one <data> construct inside the <field>-tag.
The method shown before is used for including static data. But in reality, these values are often dynamic and need to be fetched from a special data source. To get these values you can define a function that searches the right values for you and returns them as an array. You don't have to care about transferring these values to forms or to the relevant components, this is done automatically for you. Simple Groupware automatically calls your function when it needs the data. Instead of the values-parameter you use the function parameter to tell it what function to call. E.g. you want to show a list of companies in your address book or predefined values:

<data function="dbselect|simple_companies|companyname,companyname||companyname asc|10"/>
<data values="male|female"/>

To get these values you call the function dbselect which selects data from the database. To reduce this list we only want 10 items (parameter 5), if there are more, a search box is used to select relevant values. All companies have to be listed sorted by the name of the company (=companyname) alphabetically (asc=ascending) (parameter 4). As the table "simple_companies" (parameter 1) can have more than one field we tell the function to use the field "companyname" (parameter 2). Parameter 3 is not used in this case. With parameter 3 you can reduce the list of companies with an sql-where clause, e.g. "companyname like 'a%'" to get all companies starting with "a".

Syntax: To collect these functions in a central place, all data functions are kept in core/functions_user.php and have a "select_" prefix (because they select data), e.g. "select_dbselect" can be used to get data from the database.
To define a data construct in a sgsML file, write <data function="getmydata"/> between the <field>-tags to call the function "select_getmydata". Here dbselect is illustrated because it is the most common function to get data from the database.

Note: To reduce the size of your functions you can define multiple <data function=> constructs between the <field>-tags.


Tables


When looking at tables we see rows, columns. Our rows are assets, every column is a field (similar to database design). <table></table> is the main tag used in sgsML and includes all the others (e.g. fields, views, etc.). With the table tag you define the name of the module, e.g.

<table modulename="Contacts"></table>

With a table you also define how the fields should be treated:
What is the column the list or assets should be sorted by?
What order should be used?
How many items should be displayed on one page?
Should the results be groups by a special column?
e.g.:

<table modulename="Contacts" orderby="lastname" order="asc" groupby="categories" limit="20"></table>

Of course, these are only the default values you suggest to the user. He can later choose on his own if he needs different settings.


Fields


All fields are defined inside the <table>-tag. A field can be seen as a column in a database, e.g. Last name, Street, Country in an address book. Every field has a type, in sgsML the type is called "simple_type". A type can be a normal string (simple_type is "text") or a collection of lines (simple_type is "textarea"). There are even exotic types like "htmlarea" which represents lines formatted with HTML, or different types for using passwords, dates, times, datetimes, files, wikis, etc.
Every field has a name to be identified by the program. This is similar to column definitions in databases. Besides the internal name used by the program every column can contain a displayname which is the name displayed to the user.
E.g. the name of a field can be "lastname", the displayname is "Last name". To separate these two has a lot of advantages:
The name used by the program is limited to numbers and characters, whereas displayname can contain all kinds of special characters or it can be translated into many languages without changing the internal name used by the program. This creates consistency when using internationalization with Simple Groupware.
Fields can be declared as unique, meaning that there can be no other asset having the same value within this field. To decide between required and optional fields, every field can be defined as "required", but is "optional" by default.
As written before, fields can be validated using validators, their data can be defined by some data sources and they can be modified before / after storing them in the database.

Some examples:

contacts.xml:

<field name="lastname" displayname="Last name" simple_type="text" required="true" />

<field name="zipcode" displayname="Zipcode" db_size="6" simple_type="text">
<validate function="numeric"/>
</field>

<field name="description" displayname="Description" simple_type="textarea" simple_size="4" />


Views


The next element inside the sgsML language is a "view". At first "views" are groups of fields. E.g. you show "first name" and "last name" of a person in the view "display" and the field "address" and "description" in the view "details". But views can do a lot more: views are also used to edit and create assets. Since defining forms (for editing and creating assets) is not always easy and oftentimes requires Javascript usage, Simple Groupware creates all the forms automatically for you. So you only define a field as an html-editor (simple_type "htmlarea") and you're done.
To present several fields, sgsML differs between the orientation in which a group of fields is presented: The horizontal view (sgsML "display") is a list where every field has one column (this is how Windows Explorer lists files). The second one is called "details" (vertical orientation) and presents every field as one line, meaning the first column is the name of the field and the second column contains the value of it. Both orientations have advantages and disadvantages, so you can decide on your own which one you use for what case: define template="display" or template="details" in the view-tag and you're done. Note: When naming a view "foobar", the template "asset_foobar.tpl" will be used. Using the attribute template="display" in the view tag overrides this automatic mapping.

When looking with web applications you often see a list of assets (horizontal orientation) and a "Details" button at the right side to switch to the vertical one for a selected row. If you need this behavior depends on you own, simply add a showinsingleview="true" as attribute to the details-view and you're done (sgsML defines the rows of a table as single view, the headline above is the "normal" view, thus "singlebuttons" are buttons displayed at the right side of every asset).
Similar to tables, views can have their own "order", "orderby", "limit" statements which override those defined by the table.
Other tags are "image_width" and "image_height" (both or only one of them) which enable you to automatically resize images (simple_type "files", images are detected automatically when extension is gif/jpeg/png). This is very useful when bandwidth is low.
Another way views can be used is to reduce the number of assets by a "where" clause, e.g. "lastname like 'a%'" to get all persons starting with "a" (this functionality is similar to views in databases using SQL-Views).
To group fields to special views, you define constructs like "notin" (exclusion method) or "onlyin" (inclusion method) inside the <field>-tags.

Some examples:

contacts.xml:

<view name="display" displayname="{t}Display{/t}" groupby="category" />
<view name="details" displayname="{t}Details{/t}" showinsingleview="true" />

users.xml:

<view name="display" displayname="{t}Active{/t}" where="activated=1" />
<view name="details" displayname="{t}Details{/t}" image_width="200" image_height="100" showinsingleview="true" />


Tabs


The last construct used by sgsML are tabs. Tabs are similar to views: They group fields and enable you to quickly switch from one group to another without overloading the screen. A view is static: This means when you click on a view, the program takes the required fields from the databases and presents the results to you. In contrast, tabs are subordinated to views. A view can contain several tabs, every tab is visible in every view (sounds a bit difficult at the first shot, but gets clearer when writing the first application).
Tabs are dynamic: E.g. you click on one view containing 5 tabs, all fields for the 5 tabs are loaded from the database and put into the (HTML-)output. To avoid overloading the screen, tabs use Javascript to make sure that only one tab is visible at once. When clicking another tab, the old one is hidden and the other is made visible. To assign fields to tabs, simply use <field ... simple_tab="mytab">.

Here is an example:

<tab name="general" displayname="{t}General{/t}" />
<tab name="details" displayname="{t}Details{/t}" />

<field name="description" displayname="{t}Description{/t}" simple_type="textarea" simple_size="4" simple_tab="details" />


Deploy your applications with sgsML


Finally after writing your first sgsML application you will surely want to deploy it to your Simple Groupware installation. Therefore every module is a web application and stored in one .xml file. Simple Groupware distinguishes between two types of modules: Normal modules and system modules.
System modules are very special modules providing access to other data sources (e.g. the filesystem, other databases, IMAP, iCalendar, etc.) or providing system functionality (folders, statistics, events, search functionalities, session handling, etc.). A module is a system module if Simple Groupware cannot run without it. (There are even some modules like users and groups where this border cannot be clearly pulled, these modules remain system modules since you can't work without it). System modules are kept under "modules/schema_sys". If a module doesn't represent a schema from a table with data in the database than it carries a "nodb_" prefix in the filename (e.g. the filesystem has a schema, but it is not a schema from a table with data in the database). A module that is marked as "nodb_" needs to get its data from another data source. Therefore it uses its own functions for getting and setting data. These functions are very simple and are automatically called by the sql-handler of Simple Groupware. These functions are stored in modules/lib/* and are all following the Simple Groupware API. When learning sgsML you should try to understand system modules at last.
The Simple Groupware folder structure has two branches: src/ and bin/. If you install with language English, German, etc. all files from src/* are translated and written to bin/* during the setup process. Therefore if you installed with English or German, place your .xml file in bin/modules/schema/. If you installed with Developer as language, place your .xml file in src/modules/schema/.
Note: To be able to select a module in the list when creating a new folder, you need to add the module to "modules/schema/modules.txt". Every line in this file contains the module's name and the string that is displayed in the web-interface.
Note: Every .xml file defines a structure of a table in the database. The name of the table is automatically set by the filename and "simple_" as prefix. E.g. the table name for schema/tasks.xml is set to simple_tasks. If the module is a system module, the prefix will be "simple_sys_". E.g. the table name for schema_sys/users.xml will be simple_sys_users. The "modulename" attribute is only the name displayed above the tree on every page.


Translations


With Simple Groupware you can translate everything: It doesn't matter if the strings that should translated are inside XML, PHP, Html, sgsML, etc. Every string that needs to be translated is covered with {t} and {/t}. E.g. to make "username" translatable, use it as "{t}username{/t}". That's the same using sgsML. Examples for translations inside sgsML are display-names for fields, date formats as validation / store parameters, etc. The translation process is done during the setup. So you select a language and all files from the src/ directory are translated into the bin/ directory. When installing with Developer as language, the translation isn't done. All files reside in src/ and when viewing the output, {t} and {/t} are automatically removed. So using Simple Groupware as "Developer" you always get untranslated English values in the output.
Note: If you don't need translations, you won't need to add "{t}" and "{/t}".

Examples


blank.xml:

<table modulename="{t}Blank{/t}" default_view="display" default_sql="no_select">
<view name="display" displayname="{t}Display{/t}" />
<field name="id" simple_type="id" displayname="{t}Id{/t}" />
</table>

This module has the name blank. It will be displayed as {t}Blank{/t} where "{t}Blank{/t}" will be translated using the language files. As we defined one view (display), the default view is also display. The view "display" will be displayed as the translation of {t}Display{/t}. In this example we have one field called "id" with the simple_type of "id" meaning this field will be used as a primary key for the table. Also there is a default_sql statement: This overrides normal (automatic) SQL select statements. When using no_select, there will be no select statement being done. In this example we want the SQL statement to be done automatically, so we strip the default_sql attribute.

Now, let's make a second field called "Last name". Since every person should have a last name we want it to be required every time a new person is created or edited. Last name is a string and therefore we use simple_type "text" which is used for all strings that don't require line breaks. Last name should be named "lastname" in the program and displayed as the translation of {t}Last name{/t}.

blank.xml:

<table modulename="{t}Blank{/t}" default_view="display">
<view name="display" displayname="{t}Display{/t}" />
<field name="id" simple_type="id" displayname="{t}Id{/t}" />
<field name="lastname" displayname="{t}Last name{/t}" simple_type="text" required="true" />
</table>

Adding "first name" is done the same way:

<field name="firstname" displayname="{t}First name{/t}" simple_type="text" required="true" />

To help you finding your entries we want to sort them by lastname (default is Id). Therefore we expand the table statement with two attributes:

orderby="lastname" order="asc"

Orderby defines the field we want to sort by and asc means that the entries should be sorted ascending (instead of desc for descending). Having more than 100 entries makes the list very long, so we want to distribute the entries to several pages. To do this, only set a limit to the table:

limit="20"

To help you to remember the relationships to these assets we add a new field called description:

<field name="description" displayname="{t}Description{/t}" simple_type="textarea" simple_size="4" />

The field description will be displayed as the translation of {t}Description{/t}. The type used here is "textarea" which is similar to the "textarea" component used in HTML. Thus we have a text which can be longer than one line. Here simple_size indicates that textarea has a height of 4 rows.

Now we have:

blank.xml:

<table modulename="{t}Blank{/t}" default_view="display" orderby="lastname" order="asc" limit="20">
<view name="display" displayname="{t}Display{/t}" />
<field name="id" simple_type="id" displayname="{t}Id{/t}" />
<field name="lastname" displayname="{t}Last name{/t}" simple_type="text" required="true" />
<field name="firstname" displayname="{t}First name{/t}" simple_type="text" required="true" />
<field name="description" displayname="{t}Description{/t}" simple_type="textarea" simple_size="4" />
</table>

To rename our module from blank to "My Addresses", use ...

myaddresses.xml:

<table modulename="{t}My Addresses{/t}" default_view="display" orderby="lastname" order="asc" limit="20">
<view name="display" displayname="{t}Display{/t}" />
<field name="id" simple_type="id" displayname="{t}Id{/t}" />
<field name="lastname" displayname="{t}Last name{/t}" simple_type="text" required="true" />
<field name="firstname" displayname="{t}First name{/t}" simple_type="text" required="true" />
<field name="description" displayname="{t}Description{/t}" simple_type="textarea" simple_size="4" />
</table>

... and rename the file from "src/modules/schema/blank.xml" to "src/modules/schema/myaddresses.xml" if you installed Simple Groupware with language "Developer". If you installed it with English or German, rename the file from "bin/modules/schema/blank.xml" to "bin/modules/schema/myaddresses.xml".

Now we only have a simple view that can display entries. To enable you to create new entries, add the following attribute to the table tag:

enable_new="true"

This automatically adds the "New" view with the rights attributes.
To allow you to edit and delete existing entries, add these attributes to the table tag:

enable_edit="true" enable_delete="true"

This automatically adds the "Edit" view and the "Delete" buttons.
With Simple Groupware you assign one module to every folder. Therefore you may want to be able to delete all entries in the folder. To do this we use the "empty" attribute:

enable_empty="true"

This automatically adds the "Empty" button.

myaddresses.xml:

<table modulename="{t}My Addresses{/t}" default_view="display" orderby="lastname" order="asc" limit="20" enable_new="true" enable_edit="true" enable_delete="true" enable_empty="true">
<view name="display" displayname="{t}Display{/t}" />
<field name="id" simple_type="id" displayname="{t}Id{/t}" />
<field name="lastname" displayname="{t}Last name{/t}" simple_type="text" required="true" />
<field name="firstname" displayname="{t}First name{/t}" simple_type="text" required="true" />
<field name="description" displayname="{t}Description{/t}" simple_type="textarea" simple_size="4" />
</table>

To deploy your new web application, make sure that the module is stored in "src/modules/schema/myaddresses.xml" (Developer language) or "bin/modules/schema/myaddresses.xml" (English, German, etc. language).
Inside Simple Groupware, take a look at the tree. Go to a folder where you want to place the new application, e.g. click "Workspace". Below the tree, click "Options", enter a new folder name to the "New folder" form, choose "myaddresses" in the list and click Ok. This is all: The new module is running now!
Note: The modules in the list contain the filenames without the extension (.xml), not the modulename-attribute. Therefore you see "myaddresses" in the list instead of "{t}My Addresses{/t}".

To improve "My Addresses" we add some more fields:

<field name="street" displayname="{t}Street{/t}" simple_type="text" />
<field name="zipcode" displayname="{t}Zipcode{/t}" db_size="6" simple_type="text">
<validate function="numeric" />
</field>
<field name="city" displayname="{t}City{/t}" simple_type="text" />

All three are of type "text", but the zip code should be validated by some constraints: The first validation is done with db_size=6 which means that the field may not be longer than 6 characters. Since zip codes are numeric (in Germany) we add the validator "numeric" (when creating or editing a new asset the function "validate_numeric" is called). If your zip codes are not numeric, leave this step out.

But the "Display" quickly gets overloaded with fields. Thus we create a new view called "Details".

<view name="details" displayname="{t}Details{/t}" showinsingleview="true" tfield_1="firstname" tfield_2="lastname" />

We decide that Id and description are less important than the other fields and should be displayed in the second view "Details". Also the fields "lastname" and "firstname" should be displayed as a caption in the first line of the details view (indicated with the attributes "tfield_1" and "tfield_2").

This means we add new limitations to the fields:

<notin views="display" />

Notin tells the program not to display the field in the view "display". Notin uses "views" as attribute which means that you can add several views here using views="view1|view2" separated with "|".


Summarizing our activities


myaddresses.xml:

<table modulename="{t}My Addresses{/t}" default_view="display" orderby="lastname" order="asc" limit="20" enable_new="true" enable_edit="true" enable_delete="true" enable_empty="true">
<view name="display" displayname="{t}Display{/t}" />
<view name="details" displayname="{t}Details{/t}" showinsingleview="true" tfield_1="firstname" tfield_2="lastname" />
<field name="id" simple_type="id" displayname="{t}Id{/t}">
<notin views="display" />
</field>
<field name="lastname" displayname="{t}Last name{/t}" simple_type="text" required="true" />
<field name="firstname" displayname="{t}First name{/t}" simple_type="text" required="true" />
<field name="description" displayname="{t}Description{/t}" simple_type="textarea" simple_size="4">
<notin views="display" />
</field>
<field name="street" displayname="{t}Street{/t}" simple_type="text" />
<field name="zipcode" displayname="{t}Zipcode{/t}" db_size="6" simple_type="text">
<validate function="numeric"/>
</field>
<field name="city" displayname="{t}City{/t}" simple_type="text" />
</table>

When saving changes to the xml file you only need to hit the "Refresh" button in your browser to make Simple Groupware apply your changes.

Examples (continued)


To make the description field more usable we change simple_type from textarea to htmlarea:

simple_type="htmlarea"

Hit refresh and you have a complete HTML editor!

Another way to avoid overloading of the display view is using simple_tabs.

So we define two tabs, one for general information, the other one for the details (both displayed with the translation from the language file):

<tab name="general" displayname="{t}General{/t}" />
<tab name="details" displayname="{t}Details{/t}" />

The difference between "views" and "tabs" is the time when the information is loaded. With views, only the information for the current view is loaded. Using tabs all the information is loaded, but hided using Javascript until you hit the tab. Switching between tabs is much faster because you have already loaded all the information in your browser, but loading the page takes longer at the beginning.

The same example using tabs instead of views looks like this:

myaddresses.xml:

<table modulename="{t}My Addresses{/t}" default_view="display" orderby="lastname" order="asc" limit="20" enable_new="true" enable_edit="true" enable_delete="true" enable_empty="true">
<view name="display" displayname="{t}Display{/t}" />
<tab name="general" displayname="{t}General{/t}" />
<tab name="details" displayname="{t}Details{/t}" />
<field name="id" simple_type="id" displayname="{t}Id{/t}" simple_tab="details" />
<field name="lastname" displayname="{t}Last name{/t}" simple_type="text" required="true" />
<field name="firstname" displayname="{t}First name{/t}" simple_type="text" required="true" />
<field name="description" displayname="{t}Description{/t}" simple_type="htmlarea" simple_size="4" simple_tab="details" />
<field name="street" displayname="{t}Street{/t}" simple_type="text" />
<field name="zipcode" displayname="{t}Zipcode{/t}" db_size="6" simple_type="text">
<validate function="numeric" />
</field>
<field name="city" displayname="{t}City{/t}" simple_type="text" />
</table>

To add a gender selectbox with the values male, female, use:

<field name="gender" displayname="{t}Gender{/t}" db_size="10" simple_type="select" simple_size="1" simple_tab="details">
<data values="{t}male{/t}|{t}female{/t}"/>
</field>

The field gender has a maximum of 10 characters, is displayed as a selectbox (simple_type select) and the user can select 1 item (instead of multiple items).

Since every address has relations to other addresses we finally add a field to store these relationships:

<field name="isrelatedto" displayname="{t}Is related to{/t}" simple_type="select" simple_size="3" is_linked="simple_myaddresses|details|lastname" multiple="&lt;br&gt;" simple_tab="details" allow_custom="true">
<data function="dbselect|simple_myaddresses|lastname,lastname||lastname asc|10"/>
</field>

The field isrelatedto is displayed with the translation of {t}Is related to{/t}. The simple_type is a selectbox with a height of 3 lines, allowing the user to select multiple items. In the display these items are separated by "<br>" (= new line). The user can also type in his own items which is declared by allow_custom=true. To get the data from the selectbox we use the select_dbselect function which does something like "select lastname from simple_myaddresses order by lastname asc limit 10". If there are more than 10 items, the user can select them by using a search box. This field is also shown in the details tab. Furthermore when displaying the items of this field we want these items to be links. When a user clicks them the referenced address should be displayed. This behavior is achieved by using the "is_linked" attribute. The first parameter names the table, the second the view we want to see in the popup and the third defines the field to choose from.


The complete code of the example


myaddresses.xml:

<table modulename="{t}My Addresses{/t}" default_view="display" orderby="lastname" order="asc" limit="20" enable_new="true" enable_edit="true" enable_delete="true" enable_empty="true">
<view name="display" displayname="{t}Display{/t}" />
<tab name="general" displayname="{t}General{/t}" />
<tab name="details" displayname="{t}Details{/t}" />
<field name="id" simple_type="id" displayname="{t}Id{/t}" simple_tab="details" />
<field name="gender" displayname="{t}Gender{/t}" db_size="10" simple_type="select" simple_size="1" simple_tab="details">
<data values="{t}male{/t}|{t}female{/t}"/>
</field>
<field name="lastname" displayname="{t}Last name{/t}" simple_type="text" required="true" />
<field name="firstname" displayname="{t}First name{/t}" simple_type="text" required="true" />
<field name="description" displayname="{t}Description{/t}" simple_type="htmlarea" simple_size="4" simple_tab="details" />
<field name="street" displayname="{t}Street{/t}" simple_type="text" />
<field name="zipcode" displayname="{t}Zipcode{/t}" db_size="6" simple_type="text">
<validate function="numeric"/>
</field>
<field name="city" displayname="{t}City{/t}" simple_type="text" />
<field name="isrelatedto" displayname="{t}Is related to{/t}" simple_type="select" simple_size="3" is_linked="simple_myaddresses|details|lastname" multiple="&lt;br&gt;" simple_tab="details" allow_custom="true">
<data function="dbselect|simple_myaddresses|lastname,lastname||lastname asc|10"/>
</field>
</table>

Note: Using translations normally takes more time, so it is on you to use them or not.


Screenshots of myaddresses.xml



Search functionality


All your data will automatically be searchable. If simple_type is files, each file will be indexed using the binary tools (catdoc, xlhtml, ImageMagick, Xpdf, UnZip, gzip, tar). These tools are included as windows binaries, if using Linux/Unix you need to install these packages from your distribution (see Installation).


Summary


To demonstrate the efficiency of Simple Groupware and sgsML:

  • We have written a complete web application including 9 fields with only 26 lines of code.
  • You can create / edit / delete assets. With the built-in tree of Simple Groupware you can create different folders for special groups of addresses.
  • All your changes are logged in the history.
  • And maybe the most important benefit all the values are already searchable via the global search function. (You can even try using phonetic searches!)

I hope you got a first introduction into the world of sgsML and already understood most parts of it.
For more examples, see the "src/modules/schema" directory (including examples using files, dates, codeareas, wikiareas etc.).
To go deeper into sgsML there is "src/modules/schema_sys" (containing the Simple Groupware system modules and handlers for external data sources).
This is only a small tutorial describing the basic ideas and elements behind sgsML. If you write your own modules, and there is something not working or not clear, feel free to mail me.

Enjoy Simple Groupware!


sgsML Reference Guide

<< contents

This guide describes all aspects of sgsML. Starting from tags and attributes to custom trigger functions, modifiers, formatters and validators.

sgsML is the abbreviation for Simple Groupware Solutions Markup Language, and represents a programming language that enables quick customization and creation of powerful web applications.

A small introduction to sgsML can be found here. The FAQs for sgsML are collected here.

This page contains all basic attributes and tags. All extended attributes are described here.

Note: sgsML always needs to be valid XML

Beginning with release 0.720, fields can be created and changed directly in the GUI. Simply log in as the super administrator and navigate to "/Workspace/System/Customize/Fields". There you can create rules to be applied to existing fields or rules to create new fields. One dataset is one rule which gets applied to one field.


sgsML elements


1) Views: containing New, Edit, Edit as new
2) View buttons: containing Cut-Copy-Paste, Delete, Purge
3) Tabs, 4) Single buttons, 5) Quick add, 6) Assets, 7) Groups, 8) Fields, 9) Module

Simple Groupware sgsML elements
sgsML elements


Tag structure


Other topics



<table> tag


Table is the first tag in the structure and contains general information about the module. All other tags are nested under the "table" tag.

Example:

<table modulename="{t}Tasks{/t}" default_view="display" orderby="ending" order="asc" limit="20" enable_new="true" enable_edit="true" enable_delete="true" enable_empty="true">


Basic attributes:

  • modulename: Name of the module, displayed in the GUI.
    required: yes
    translatable: yes
    example: modulename="{t}Contacts{/t}" or modulename="Contacts"
    used in: contacts.xml (and more)
  • default_view: Name of the default view shown when opening the folder. If undefined, first view will be used.
    example: default_view="display"
    used in: contacts.xml (and more)
  • orderby: Name of the field that sets the default sorting of the assets. If undefined, assets are unsorted by default.
    example: orderby="lastname"
    used in: contacts.xml (and more)
  • order: Defines the order (ascending or descending) used in the default sorting of the assets. If undefined, ascending will be used.
    possible values: asc, desc
    example: order="asc"
    used in: contacts.xml (and more)
  • limit: Defines the maximum number of assets to display on a page. If undefined, 20 will be used.
    example: limit="30"
    used in: contacts.xml (and more)
  • groupby: Defines a field name which is used to group the assets. If undefined, assets are not grouped.
    example: groupby="category"
    used in: search.xml
  • group: Defines the order (ascending or descending) used to sort the groups of assets. If undefined, group names will be sorted ascending.
    possible values: asc, desc
    example: group="asc"
    used in: ---
  • enable_new: Adds "new" and "edit_as_new" views and a "paste" button to the module. If undefined, creating new assets will not be possible.
    example: enable_new="true"
    used in: contacts.xml (and more)
  • enable_new_only: Adds a "new" view and a "paste" button to the module. If undefined, creating new assets will not be possible.
    example: enable_new_only="true"
    used in: nodb_backups.xml, nodb_fs.xml (and more)
  • enable_edit: Adds an "edit" view to the module. If undefined, editing assets will not be possible.
    example: enable_edit="true"
    used in: contacts.xml (and more)
  • enable_delete: Adds buttons "delete" (with trash) and "cut" to the module. If undefined, it is not possible to delete or cut/paste assets.
    example: enable_delete="true"
    used in: contacts.xml (and more)
  • enable_purge: Adds buttons "delete" (without trash) and "cut" to the module. If undefined, it is not possible to delete or cut/paste assets.
    example: enable_purge="true"
    used in: events.xml, session.xml (and more)
  • enable_empty: Adds "empty folder" (with trash) button to the module. If undefined, it is not possible to delete all assets in a folder at once.
    example: enable_empty="true"
    used in: contacts.xml (and more)
  • enable_purgeall: Adds "empty folder" (without trash) button to the module. If undefined, it is not possible to delete all assets in a folder at once.
    example: enable_purgeall="true"
    used in: events.xml, session.xml (and more)
  • where: Adds an additional where condition to all select queries. If undefined, only default where statements are added (e.g. "folder in (@folders@)", "id in (@item@)")
    ---
    example: where="created < DATE_SUB(NOW(), INTERVAL 1 HOUR)" (MySQL)
    example #2: where="(private='0' or createdby=@username@)"
    used in: private_items.diff.xml (and more)
  • disable_quick_add: Disables the "quick add" button at the end of the views. If undefined, new assets can be created with a single line of comma-separated values, representing the required fields and values.
    useful for: too many required fields, values need to match complex select lookups
    example: disable_quick_add="true"
    used in: contactactivities.xml, expenses.xml (and more)
  • quick_add: Comma separated list of field names to require in the quick add function. If undefined, all fields with the "required" attrbute set to "true" will be used.
    example: quick_add="pagename,title,data"
    used in: cms.xml, contacts.xml (and more)


<view> tag


View is the second tag in the structure and contains information about views in the module. Views in sgsML are similar to views in databases (groups of fields with a special where condition).

Example:

<view name="display" displayname="{t}Open{/t}" groupby="category" where="closed=0" />


Basic attributes:

  • name: Defines an alpha-numeric identifier of a view.
    required: yes
    example: name="display"
    used in: contacts.xml (and more)
  • displayname: Name of the view, displayed in the GUI. If undefined, the "name" attribute will be used instead.
    translatable: yes
    example: displayname="{t}Display{/t}"
    used in: contacts.xml (and more)
  • orderby: Name of the field that sets the default sorting in the current view of assets. If undefined, assets are sorted by the "orderby" attribute in the "table" tag (or unsorted if not present).
    example: orderby="ending"
    used in: helpdesk.xml
  • order: Defines the order (ascending or descending) used in the default sorting in the current view of assets. If undefined, assets are sorted by the "order" attribute in the "table" tag (or ascending if not present).
    possible values: asc, desc
    example: order="desc"
    used in: helpdesk.xml
  • limit: Defines the maximum number of assets to display on a page in the current view. If undefined, the "limit" attribute in the "table" tag will be used (or 20 if not present).
    example: limit="20"
    used in: cms.xml (and more)
  • groupby: Defines a field name which is used to group the assets in the current view. If undefined, assets are grouped by the "groupby" attribute in the "table" tag (or ungrouped if not present).
    example: groupby="category"
    used in: bookmarks.xml, contacts.xml (and more)
  • group: Defines the order (ascending or descending) used to sort the groups of assets in the current view. If undefined, group names will be sorted by the "group" attribute in the "table" tag (or ascending if not present).
    possible values: asc, desc
    example: group="asc"
    used in: ---
  • where: Adds an additional where condition to all select queries to the current view. Where conditions are merged with the "where" attribute in the "table" tag. If undefined, only default where statements are added (e.g. "folder in (@folders@)", "id in (@item@)")
    ---
    example: where="activated=1"
    example #2: where="closed=0"
    used in: tasks.xml, helpdesk.xml, events.xml (and more)
  • showinsingleview: Shows a link to the current view for each asset. Recommended for "Details" or "Edit". If undefined, views will be only visible in the views bar.
    example: showinsingleview="true"
    used in: bookmarks.xml, notes.xml (and more)
  • show_preview: Shows previews of images and other files. If undefined, only filenames, sizes and modification dates are shown in the view.
    example: show_preview="true"
    used in: contacts.xml, tasks.xml (and more)
  • image_width, image_height: Shows image thumbnails or other previews with a maximum width or height in pixels. If undefined or "show_preview" is not set for the current view, thumbnails will not be resized.
    example: image_width="250" image_height="200"
    used in: gallery.xml, notes.xml (and more)
  • template_mode: Customizes the details template (templates/asset_details.tpl). The value "noheader" shows the template without field names on the left side. The value "small" shows only fields with non-empty values. And "flat" shows fields with non-empty values, and names in a separate row. If undefined, field names are on the left, values on the right.
    valid values: small, flat, noheader
    example: template_mode="flat"
    used in: notes.xml, faq.xml (and more)
  • tfield_1, tfield_2: Defines two fields shown in the headline of an asset in the details template (templates/asset_details.tpl) or a calendar view (day.tpl, month.tpl, gantt.tpl). The fields are identified by the "name" attribute". If undefined, only the first field of the view with required="true" will be shown in the headline.
    example: tfield_1="firstname" tfield_2="lastname"
    used in: contacts.xml, tasks.xml (and more)
  • showonly: Shows only a selection of fields in the current view. If undefined, all fields of a module are visible in a view. The "fields" attribute contains field names, separated by "|".
    example: showonly="subject|headers"
    used in: emails.xml, users.xml
  • enable_asset_rights: Enables individual permissions for every asset. The value "full" creates a new tab for read and write permissions (users and groups) with the default set to "anonymous". The value "owner_read" creates a new tab for read and write permissions with the default set to the current username. And the value "owner_write" creates a new tab for write permissions with the default set to the current username. If undefined, only folder permissions are used to read and write assets.
    valid values: full, owner_read, owner_write
    example: enable_asset_rights="full"
    used in: files.xml, forum.xml, timesheets.xml (and more)
  • changeseen: Enables seen and unseen states for each asset. Default state is unseen (marked with bold characters). The asset gets marked as seen when the first user opens it in a view which has the "changeseen" attribute set.
    example: changeseen="true"
    used in: emails.xml, nodb_imap.xml (and more)


<tab> tag


Tab is the third tag in the structure and contains groups of fields in the module. Tabs in sgsML are similar to tabs in browsers (windows/views contain tabs). Fields are assigned to tabs with the "simple_tab" attribute. Fields without a "simple_tab" attribute are assigned to the first tab. Tabs can be hidden with the "hide_tabs" or "disable_tabs" attributes.

Example:

  <tab name="general" displayname="{t}General{/t}" />


Attributes:

  • name: Defines an alpha-numeric identifier of a tab.
    required: yes
    example: name="general"
    used in: contacts.xml, tasks.xml (and more)
  • displayname: Name of the tab, displayed in the GUI. If undefined, the "name" attribute will be used instead.
    example: displayname="{t}General{/t}"
    used in: contacts.xml, tasks.xml (and more)


<viewbutton>, <singlebutton> tag (optional)


Viewbutton and singlebuttons are optional tags in the structure and define additional buttons in a module. View-buttons will be added to the view bar and can be applied to more than one asset. Single-buttons will be added to each asset and only affect one asset.
The "name" attribute serves as a unique identifier.
The "displayname" attribute is the name of the button displayed in the GUI.
The "views" attribute contains view names to apply the filter to, separated by "|".
The "onclick" attribute describes the Javascript function to execute when the button is clicked.
The "icon" attribute can be used to set an icon for the link (located under "ext/icons/").
The "right" attribute sets the permissions required to show the button ("read", "write", "admin").

The "condition" attribute sets the condition(s) required to show a single-button. Operators can be "eq" (equal),"neq" (not equal),"lt" (less than ),"gt" (greater than),"like","nlike" (not like),"starts" (starts with) and "oneof" (one of).
Syntax: field|op|value[||field2|op2|value].
Example: condition="status|oneof|ok,fail||closed|neq|0
Example #2: condition="completed|eq|1||status|oneof|closed,canceled"

useful for: custom actions
used in: calendar.xml, tasks.xml (and more)

Examples:

<viewbutton name="custom1" displayname="{t}Custom action{/t}" onclick="ajax('myclass::ajax_myfunc', [tfolder, tview, asset_get_selected_items(true)], locate_folder);" right="write" />

<singlebutton views="display|calendar" name="close" displayname="{t}Close{/t}" onclick="asset_update({closed:'1'},'@id@');" condition="closed|neq|1" right="write" icon="accept.gif" />

<singlebutton views="display" name="take_over" displayname="{t}Take over{/t}" onclick="asset_update({responsibles:sys.username},'@id@');" right="write" icon="user_add.gif" />


<field> tag


Field is the fourth tag in the structure and contains information about fields in the module. Fields in sgsML are similar to fields in a database table (including data types, length and constraints).

Example:

  <field name="email" displayname="{t}E-mail{/t}" simple_type="text">
    <validate function="email"/>
    <link value="@ext/norefer.php?url=@email@" icon="link_mail.gif"/>
  </field>


Basic attributes:

  • name: Defines an alpha-numeric identifier of a field.
    required: yes
    example: name="lastname"
    used in: contacts.xml (and more)
  • displayname: Name of the field, displayed in the GUI. If undefined, the "name" attribute will be used instead.
    example: displayname="{t}Last name{/t}"
    used in: contacts.xml (and more)
  • simple_type: Type of the field, used to present a field in views and forms.
    example: simple_type="text"
    used in: contacts.xml, tasks.xml (and more)
    possible types:
    • text: normal text input (one line)
    • textarea: text input (multiple lines)
    • checkbox: input only yes or no
    • files: upload files
    • date: select a date
    • time: time input
    • datetime: input date and time
    • select: select box (needs <data> tag)
    • dateselect: select several dates
    • rating: choose a rating with stars (added in 0.662)
    • int: numeric input
    • float: float numbers
    • pmwikiarea: text input, PmWiki markup
    • wikiarea: text input, text_wiki markup
    • htmlarea: HTML input
    • spreadsheet: spreadsheet component
    • graphviz: text input (Graphviz markup)
    • codearea: source code widget
    • id: unique identifier
    • password: password input
  • required: Requires a non-empty input value when creating or editing an asset. If undefined, the input value can be empty.
    example: required="true"
    used in: contacts.xml (and more)
  • is_unique: Requires the field to have a unique value. If undefined, the input value of the current field can exist more than once in assets belonging to the same module.
    example: is_unique="true"
    used in: contacts.xml (and more)
  • sum, avg: Sums up all values or builds the average of the current field at the bottom of the page. If undefined, there will be no additional line at the bottom displaying sums or averages.
    example: sum="true", average="true"
    used in: expenses.xml, projects.xml (and more)
  • simple_default: Defines a default input value used when creating a new asset. If undefined, the input value will be empty by default.
    example: simple_default="1"
    used in: tasks.xml, calendar.xml (and more)
  • simple_tab: Defines a name of a tab where the field is placed in. If undefined, the field will be placed in the "general" tab.
    example: simple_tab="address"
    used in: contacts.xml, tasks.xml (and more)
  • simple_size:
    For simple type "select" and "dateselect", it defines the height of the select box (number of lines). If the value is greater than 1, multiple elements can be selected. If undefined, the default height is 3 lines.
    For simple type "rating", it defines the maximum number of stars in the rating field. If undefined, the maximum is 5.
    For simple type "files", it defines the maximum number of files that can be uploaded to the field in one asset. If undefined, an unlimited number of files can be uploaded.
    example: simple_size="1"
    used in: contacts.xml, tasks.xml (and more)
  • simple_file_size: Sets the maximum file size in bytes for a "files" field. Values can be given in units "M" (megabytes) and "K" (kilobytes). If undefined, files can be uploaded to a maximum configured in "php.ini". Relevant parameters in "php.ini" are "post_max_size" and "upload_max_filesize".
    example: simple_type="files" simple_file_size="5M"
    used in: contacts.xml, tasks.xml (and more)
  • separator: Defines a separator used to display fields containing multiple values (simple type files, select, dateselect and multitext). If undefined, the separator will be set to ", ". Beginning with version 0.645, the default is "\n".
    example: separator="\n"
    used in: contacts.xml, tasks.xml (and more)
  • nowrap: Disables automatic text wrapping. If undefined, long texts will be automatically wrapped to the next line.
    useful for: date/time fields
    example: nowrap="true"
    used in: tasks.xml, calendar.xml (and more)
  • allow_custom: Applies to simple type "select". Allows the user to enter custom values not offered by the select box.
    example: allow_custom="true"
    used in: contacts.xml, tasks.xml (and more)
  • width: Sets the width of a field in the view. If undefined, all fields will be distributed on the table automatically by the browser. The minimum width is set to 40 pixels per field. Values can be set in "px", "em", "%".
    example: width="50%"
    used in: bookmarks.xml, events.xml (and more)
  • height: Sets the height of a field in the view. If undefined, the height will be defined by the content of the field. Values can be set in "px", "em", "%".
    example: height="300px"
    used in: notes.xml, gallery.xml (and more)


<field> tag: Basic sub-tags (optional)


  • <link>, <linktext>: Adds a link to the current field. The link can be placed before the current value (<link> tag) or directly in the current value (<linktext> tag). Variables like @folder@, @id@ or @field_name@ automatically get replaced with their current values. The link can be added to all views or some views specified in the "views" attribute, separated by "|".
    When the "value" attribute starts with a "#", the link is opened in the horizontal preview pane. When the "value" attribute starts with a "%", the link is opened in the vertical preview pane on the right side. When the "value" attribute starts with a "@", the link is opened in a new browser window. The "icon" attribute can be used to set an icon for the link (located under "ext/icons/"). URL parameters are described here.
    ---
    example: <link value="@ext/norefer.php?url=@url@"/>
    example #2: <linktext views="display" value="#index.php?folder=@folder@&view=details&iframe=1&item=@id@"/>
    example #3: <link value="skype:@skype@?userinfo" icon="phone.gif"/>
    used in: contacts.xml, tasks.xml

  • <filter>: Calls a PHP method to modify the output of a field in a view. There can be multiple <filter> tags inside a <field> tag. Method parameters can be added, separated by "|". Default class is "modify", can be changed with prefix "classname::". Filters can be applied to all views or some views specified in the "views" attribute, separated by "|". The "type" attribute (optional) can be set to "_fgstyle" to set a foreground CSS attribute or "_bgstyle" to set a background CSS attribute.
    ---
    translatable: yes
    useful for: modifying output of a field
    example: <filter views="all" function="shortdatetimeformat"/>
    example #2: <filter views="all" function="percent"/>
    example #3: <filter views="display" function="shortmessage|100"/>
    example #4: <filter views="all" function="dateformat||{t}m/d/Y{/t}"/>
    example #5: <filter views="display|details" function="myclass::validate_url"/>
    used in: contacts.xml, tasks.xml (and more)

    linkselect: Appends the value of a field with a couple of links pointing to other records in the database. Links are separated with a <separator> string. Two fields are selected from a table: The first field is used as the ID of the record to be linked. The second field serves as the text for the link. Variables like @field_name@ automatically get replaced with their current values in the where field. The maximum number of links is 100 by default and can be changed with the <limit> parameter.
    ---
    syntax: <filter views="<views>" function="linkselect|<separator>|<table>|<key-column>,<value-column>|<where>|<order-by>|<limit>"/>
    example: <filter views="all" function="linkselect|, |simple_intranet|id,pagename|folder=@folder@ and mainpage='0'|pagename"/>

    showselect: Similar to linkselect, but it only presents values without links.
    ---
    syntax: <filter views="<views>" function="showselect|<separator>|<table>|<key-column>,<value-column>|<where>|<order-by>|<limit>"/>
    example: <filter views="all" function="showselect|\n|simple_tasks|'',concat('Average: ';round(avg(progress)*100);'%')|project=@projectname@|"/>

  • <data>: Defines the list of options used in simple type "select". There can be multiple <data> tags inside a <field> tag. Can be a list of values, separated by "|" (attribute "values").
    Can also be a list of key-value pairs, separated by "_##_" and "|" (see example #2). The "reverse" attribute can be used to translate keys in normal views to values.
    Can be a PHP method which returns the list. Method parameters can be added, separated by "|". Default class is "select", can be changed with prefix "classname::".
    The "title" attribute is optional and can be used to describe multiple <data> blocks in the form.
    ---
    translatable: yes
    used in: contacts.xml, tasks.xml (and more)
    examples:
    <data title="Companies" values="low|normal|urgent"/>
    <data reverse="true" values="0_##_{t}low{/t}|1_##_{t}normal{/t}|2_##_{t}urgent{/t}"/>
    <data function="dbselect|simple_companies|id,companyname||companyname asc|10"/>
    <data function="dbselect|<table>|<key-column>,<value-column>|<where>|<order-by>|<limit>|<no_permisions>"/>
    <data function="dbselect|(select a.* from table1 a, table2 b where a.id=b.id) c|<key-column>,<value-column>||<order-by>|<limit>"/>
    <data function="dbselect|simple_sys_users|username,concat(lastname;'; ';firstname)||lastname asc|10"/>
    <data function="myclass::mymethod|params..."/>

    Note: For the "dbselect" function, all permissions are checked automatically. Datasets from external tables not related to Simple Groupware will only show up if the 6th parameter is set to "no_permissions". Permissions are checked against the table "simple_sys_table".

    Note: To use the "concat" function (SQL) in <value-column>, replace "," with ";", e.g. concat(lastname;' ';firstname)

    Note: When there a more entries than <limit>, the result is empty and the user is forced to use the search function. The <limit> parameter is used as a maximum amount of entries to fetch.

  • <validate>: Calls a PHP method to validate the current field before saving it to the database. There can be multiple <validate> tags inside a <field> tag. Method parameters can be added, separated by "|". Default class is "validate", can be changed with prefix "classname::".
    ---
    translatable: yes
    useful for: validating user input
    example: <validate function="numeric"/>
    example #2: <validate function="email"/>
    example #3: <validate function="url"/>
    example #4: <validate function="regexp|/^[0-9]+$/|ID must be numeric"/>
    example #5: <validate function="myclass::validate_url" />
    used in: contact.xml, tasks.xml (and more)

  • <notin>, <onlyin>: Not-in removes the current field from some views. Only-in shows the current field only in some views. If undefined, all fields of a module are visible in a view. The "views" attribute contains view names, separated by "|".
    ---
    useful for: remove fields from views
    example: <notin views="display"/>, <onlyin views="details|calendar"/>
    used in: contacts.xml, tasks.xml (and more)

  • <description>: Adds a description to a field in "new", "edit" and "edit as new" views. The attribute "title" is the text of the link. The attribute "hint" is the tooltip shown for the link. The attribute "value" is the Javascript code which gets executed when the link is clicked. The attributes "title" and "hint" are optional.
    example: <description title="Help" hint="Click here for help." value="alert('minimum = 15 secs');"/>
    used in: contact.xml, tasks.xml (and more)


Note: Custom classes can be put under "custom/core/classes/" (will be tried first) or "ext/core/classes/" (reserved for extensions). E.g. "class mymethods {}" in "custom/core/classes/mymethods.php".

Note: Showing a field in a view is evaluated by the following order: notinall (attribute in <field>), notin (tag in <field>), onlyin (tag in <field>), showonly (attribute in <view>)

Note: In Simple Groupware, translatable strings are marked with "{t}", "{/t}". For example "{t}Open{/t}" will be translated to "Offen" in German.


Automatic system fields (hidden by default)


  • id: Numeric unique identifier for an asset (primary key). Consists of asset ID and server ID (2 decimals), e.g. 201 for asset ID 2 and server 01.
  • folder: ID of the folder that contains the asset (reference to simple_sys_tree).
  • created: Unix timestamp pointing to the time when the asset was created.
  • lastmodified: Unix timestamp pointing to the time when the asset was last modified.
  • createdby: Username of the user who created the asset.
  • lastmodifiedby: Username of the user who did the last modification.
  • dsize: Numeric value indicating the size (bytes) of the files attached to the asset.
  • history: Text field to track information about who changed what data and which fields of an asset.


PHP method signatures


  • Filter method
    Example: <filter views="display" function="myclass::my_filter_method|100|abc"/>
    Signature: static function my_filter_method( $value, $params, $row )

    Parameters:
    $value: Value to filter (string)
    $params: input parameters, array(100, 'abc')
    $row: current asset, array(field_name => array('data'=>array(...), 'filter'=>array(...)), ...)
    [data = unfiltered values, filter = filtered values]
    Return: string (filtered value)


  • Validate method
    Example: <validate function="myclass::my_validate_method|100|abc"/>
    Signature: static function my_validate_method( $value, $params, $field )

    Parameters:
    $value: Value to validate (string)
    $params: input parameters, array(100, 'abc')
    $field: current sgsML field, array("NAME"=>"...", "DISPLAYNAME"=>"...", ...)
    Return: string empty (valid value) or error message (invalid value)


  • Data method
    Example: <data function="myclass::my_data_method|100|abc"/>
    Signature: static function my_data_method( $params )

    Parameters:
    $params: input parameters, array(100, 'abc')
    Return: array( Key => Value, Key2 => Value2 )
    [User sees values in the form, keys will be stored in the database]


Templates


The following templates are included:

  • admin: Used to display the admin overview page under "/Workspace/System".
    location: templates/asset_admin.tpl
    additional attributes: none
    used in: nodb_admin.tpl
  • display: Used to display assets with one line per asset.
    location: templates/asset_admin.tpl
    additional attributes: none
    used in: contacts.xml, tasks.xml (and more)
  • details: Used to display assets with one line for every field.
    location: templates/asset_admin.tpl
    additional attributes: tfield_1, tfield_2, template_mode ("view" tag)
    used in: contacts.xml, tasks.xml (and more)
  • edit: Form used to edit and create assets with one block for every asset.
    location: templates/asset_edit.tpl
    additional attributes: none
    used in: sgsml.php (attributes: enable_new, enable_edit, enable_edit_as_new)
  • free: Used to display assets in rows and columns with one block for every asset and several blocks per row. Number of blocks per row defined in "cols" attribute.
    location: templates/asset_free.tpl
    additional attributes: cols, row_height ("view" tag)
  • portal: Used to display URLs in iframes with one block for every asset and several blocks per row. Number of blocks per row defined in "cols" attribute.
    location: templates/asset_portal.tpl
    notes: does not support tabs
    additional attributes: cols ("view" tag)


CMS templates: Used in the CMS (cms.php) to display pages. Templates can be selected for every asset in the CMS module.

  • pmwiki.tpl: Default template used to display a page.
    location: cms/pmwiki.tpl
  • pmwiki_rtl.tpl: Default template with right-to-left layout.
    location: cms/pmwiki_rtl.tpl
  • rss.tpl: Special template used to display a RSS feed of the latest pages updated. Includes only pages with the flag "Include in RSS feed" set.
    location: cms/rss.tpl
    URL: cms.php?rss
  • sitemap.tpl: Special template used to display a XML stream of the latest pages updated. Includes all pages.
    location: cms/sitemap.tpl
    URL: cms.php?sitemap


Module naming


All modules are located at "modules/schema*". The folder "schema" contains modules for all users. The folder "schema_sys" contains all administrative modules. All modules are named with "<module_name>.xml". Filenames can contain a "nodb_" prefix to indicate that the database schema will not be processed, meaning NO automatic creation of tables and fields.


Extensions


sgsML can be also used in extensions. For getting started, it is recommended to take a look at the example extension which can be downloaded here.


Examples


Here are some example modules:

Without translation:


Release changes


  • v0.732: added tfield_1, tfield_2 for calendar views
  • v0.722: added vertical preview pane for the "<link" and "<linktext"
  • v0.707: added "no_permissions" parameter for the "dbselect" function
  • v0.701: added "condition" attribute to "singlebutton" tag
  • v0.662: added "reverse" attribute to "data" tag
  • v0.662: added simple type "rating"
  • v0.646: renamed "nosql_" prefix for filenames to "nodb_"
  • v0.645: renamed "multiple" attribute to "separator"
    ("multiple" will continue to work)
  • v0.645: changed default value for "multiple" attribute to "\n"


sgsML Extended Attributes

<< contents

This page contains all extended attributes and tags for sgsML. All basic attributes are described here.

Note: All extended attributes and tags are optional.


Tag structure



<table> tag: extended attributes


  • load_library: Loads an additional library in the bootstrap. The base path is "<sgs-dir>/bin/" or "<sgs-dir>/src/".
    useful for: modules that need a PHP library
    example: load_library="lib/pmwiki/pmwiki.php"
    used in: cms.xml, nodb_pmwiki.xml
  • load_css: Loads an additional stylesheet in the head section of the page. The base path is "<sgs-dir>/bin/" or "<sgs-dir>/src/".
    useful for: modules that need a custom stylesheet
    example: load_css="ext/cms/styles.css"
    used in: cms.xml, nodb_pmwiki.xml
    available since: 0.643
  • name: Defines a table name which overrides the normal table name in all queries. If undefined, the module name will be used as the table name.
    useful for : overwriting the default table name
    example: name="simple_sys_tree"
    used in: nodb_rights_edit.xml
  • custom_name: Defines a table name or a sub-query which overrides the normal table name in all "select" queries. If undefined, the module name will be used as the table name.
    useful for: map data into another (sub-)schema
    example: custom_name="simple_contacts_archive"
    used in: search.xml, nodb_calendar_contacts.xml
  • default_sql: Defines a default query used to retrieve assets. If undefined, a select query is automatically built by the "fields" and "where" statements assigned to a view. Variables like @folder@ or @table@ automatically get replaced with their current values.
    By default, only assets of the current folder are shown in the current view. So if a "default_sql" query returns a "folder" field with a different ID, assets are not shown because the access is denied. You can bypass the folder check by adding the attribute "nosqlfolder" with the value "true".
    ---
    special values: no_select (don't run selects)
    example: default_sql="show full columns from @table@" (MySQL)
    used in: nodb_structure.xml, nodb_admin.xml (and more)
  • template: Defines the default Smarty template, used to render the views. If undefined, each view needs to define it's own template attribute or uses the view's name to set a template implicitly.
    useful for: refer to a different template without changing the view name
    example: template="display" (for templates/asset_display.tpl)
    used in: nodb_schema.xml, nodb_rights.xml (and more)
  • no_search_index: Disables the search indexer for the module. If undefined, all new or changed assets will be put into the search index. Modules that contain "_nodb_" in the filename are automatically excluded.
    example: no_search_index="true"
    used in: search.xml, session.xml (and more)
  • disable_*: Disables automatic views, buttons or fields in the module. If undefined, some special views, buttons and fields are automatically added to the module.
    Notification and summary allow people to get notified about changes.
    Bgcolor allows to mark assets with a background color as label.
    attribute names for views: disable_{history|index|schema|search|copy|structure|rights}
    attribute names for buttons: disable_{paste|copy|cut}
    attribute names for fields: disable_{bgcolor|notification}
    example: disable_history="true"
    used in: session.xml
  • enable_calendar: Enables the calendar box above the tree. Contains relevant fields for time frame selection, can be only field (created), two fields (begin, end) or nine fields (including recurrence, intervals and exclusions). If undefined, only events that match the selected time frame will be shown.
    example: enable_calendar="created"
    example #2: enable_calendar="begin,ending"
    used in: calendar.xml, events.xml (and more)
  • hide_calendar: Hides the calendar pane. If undefined, all entries with begin and end date will be displayed in the calendar pane.
    example: hide_calendar="true"
    used in: ---
  • sql_handler: Defines a class used to delegate all queries to. The prefix of the class name "lib_" is left out. The folder for a library of a module is "modules/lib/". Is mainly used for external data structures defined over mountpoints (see data handlers and "modules/lib/default.php").
    ---
    example: sql_handler="fs" (class name lib_fs)
    example classes: modules/lib/fs.php, modules/lib/csv_contacts.php
    interface definition: modules/lib/default.php
    used in: nodb_fs.xml, nodb_csv_contacts.xml (and more)
  • disable_rights: Disables folder permissions for a module. If undefined, folder permissions can be set for every folder of the module.
    example: disable_rights="true"
    used in: nodb_fs.xml, nodb_imap.xml (and more)
  • disable_folder_operations: Disables folder operations for a module. If undefined, folders can be created, renamed and deleted.
    example: disable_folder_operations="true"
    used in: nodb_pop3.xml, nodb_xml.xml (and more)
  • trigger_new: Calls a PHP method after a new asset was created. Can be more than one method, separated by "|". Method parameters can be added, separated by ":". Default class is "trigger", can be changed with prefix "classname::".
    example: trigger_new="createcontact"
    example #2: trigger_new="somemethod|other_class::anothermethod:100:abc"
    example #3: trigger_new="runxml:modules/coreprojects.xml:projects"
    ---
    signature: static function anothermethod($id, $row, $params, $table)
    [$id = asset id, $row = dataset array, $params = parameters array(100,'abc'), $table = table name, return string empty (success) or error message (trigger failed)]
    ---
    used in: contacts.xml, projects.xml (and more)
  • trigger_edit: Calls a PHP method after an asset was changed. Can be more than one method, separated by "|". Method parameters can be added, separated by ":". Default class is "trigger", can be changed with prefix "classname::".
    example: trigger_edit="editcontact"
    example #2: trigger_edit="somemethod|other_class::anothermethod:100:abc"
    ---
    signature: static function anothermethod($id, $row, $params, $table)
    [$id = asset id, $row = dataset array, $params = parameter array(100,'abc'), $table = table name, return string empty (success) or error message (trigger failed)]
    ---
    used in: contacts.xml, projects.xml (and more)
  • trigger_delete: Calls a PHP method after an asset was deleted. Can be more than one method, separated by "|". Method parameter can be added, separated by ":". Default class is "trigger", can be changed with prefix "classname::".
    example: trigger_delete="deletecontact"
    example #2: trigger_delete="somemethod|other_class::anothermethod:100:abc"
    ---
    signature: static function anothermethod($id, $row, $params, $table)
    [$id = asset id, $row = dataset array, $params = parameter array(100,'abc'), $table = table nae, return string empty (success) or error message (trigger failed)]
    ---
    used in: contacts.xml, projects.xml (and more)
  • disable_trigger_ccp: Disables all triggers on cut-copy-paste. If undefined, the paste command will execute a trigger defined in the "trigger_new" attribute. If undefined, the cut command will execute a trigger defined in the "trigger_delete" attribute.
    example: disable_trigger_ccp="true"
    used in: emails.xml, nodb_imap.xml
    available since: 0.651


Note: Custom classes can be put under "custom/core/classes/" (will be tried first) or "ext/core/classes/" (reserved for extensions). E.g. "class mymethods {}" in "custom/core/classes/mymethods.php".


<view> tag: extended attributes


  • template: Defines the Smarty template, used to render the current view. If undefined, the "template" attribute in the "table" tag will be used or (if not present), the "name" attribute of the current view will be used to determine the Smarty template (e.g. name="display" => templates/asset_display.tpl).
    useful for: refer to a different template without changing the view name
    example: template="free" (for templates/asset_free.tpl)
    used in: gallery.xml, portal.xml (and more)
  • enable_calendar: Enables the calendar box above the tree. Contains relevant fields for time frame selection, can be only field (created), two fields (begin, end) or nine fields (including recurrence, intervals and exclusions). If undefined or not present in the "table" tag, only events that match the selected time frame will be shown in the current view.
    ---
    example: enable_calendar="created"
    example #2: enable_calendar="begin,ending"
    used in: calendar.xml, events.xml (and more)
  • hide_calendar: Hides the calendar pane in the current view. If undefined, the "hide_calendar" attribute in the "table" tab will be used or (if not present), all entries with begin and end date will be displayed in the calendar pane.
    example: hide_calendar="true"
    used in: ---
  • hide_tabs: Hides some tabs in the current view. If undefined, all tabs are visible. Multiple values can be used, separated by "|".
    example: hide_tabs="tabname1|tabname2"
    used in: ---
  • disable_tabs: Hides the tabs bar and shows all (visible) fields in one tab.
    example: disable_tabs="true"
    used in: users.xml
  • default_sql: Defines a default query used to retrieve assets in the current view. If undefined, the "default_sql" attribute in the "table" tag will be used or (if not present), a select query is automatically built by the "fields" and "where" statements assigned to a view. Variables like @folder@ or @table@ automatically get replaced with their current values.
    ---
    special values: no_select (don't run selects)
    example: default_sql="show full columns from @table@" (MySQL)
    used in: sgsml.php
  • nosqllimit: Shows all assets in a folder. If undefined, only a maximum number of assets will be displayed on a page, including links to next and previous pages.
    example: nosqllimit="true"
    used in: ---
  • nosqlorder: Shows assets unsorted. If undefined, assets are displayed sorted by the "orderby" attribute defined in "view" or "table" tags.
    example: nosqlorder="true"
    used in: ---
  • nosqlwhere: Shows all assets in the view. If undefined, filters from "where" attributes in "view" or "table" tags will be applied to all select queries.
    example: nosqlwhere="true"
    used in: ---
  • nosqlfolder: Shows assets of all folders in the view. If undefined, only assets of the current folder will be shown in the current view.
    useful for: views not depending on folders
    example: nosqlfolder="true"
    used in: events.xml, tree.xml (and more)
  • visibility: Defines where the link to the view should be shown. If undefined, the link will be displayed as a button in the view bar at the top. The value "hidden" will not show a link to the view. The value "bottom" will show a link below the tree at the left side. And "active" will only show a button in the view bar, if the view is currently selected.
    valid values: hidden, active, bottom
    example: visibility="bottom"
    used in: emails.xml, users.xml (and more)
  • noviewbuttons: Hides buttons in the current view. If undefined, all buttons defined as "view buttons" are displayed in the upper right in the current view. Can hide all buttons with value "true" or some buttons with names in the value, separated by "|".
    example: noviewbuttons="true"
    example #2: noviewbuttons="paste|delete"
    used in: sgsml.php, calendar.xml
  • nosinglebuttons: Hides buttons for each asset in the current view. If undefined, all buttons defined as "single buttons" are displayed for each asset. Can hide all buttons with value "true" or some buttons with names in the value, separated by "|".
    example: nosinglebuttons="true"
    example #2: nosinglebuttons="take_over|close"
    used in: sgsml.php, calendar.xml (and more)
  • doubleclick: Defines a name of a view that will be opened when a double-click is done on the background of an asset.
    example: doubleclick="details"
    used in: ---
  • accesskey: Defines an accesskey which opens the view. If undefined, views can be accessed by numbers, e.g. first view Alt-1, second view Alt-2, etc.
    example: accesskey="e"
    used in: sgsml.php
  • schema_mode: Defines a mode in which the current view can be used. The value "new" is used for forms that create new assets. The value "edit" is used for forms that change assets. The value "edit_as_new" is used for forms that create new assets from existing assets. The value "static" hides filters and pagers from the view and is used in combination with the "function" attribute. If undefined, creating or editing assets in a view won't be allowed.
    ---
    valid values: edit, create, edit_as_new, static
    example: schema_mode="edit"
    used in: users.xml, emails.xml (and more)
  • schema: Defines a sub-schema (sgsML) that is used for the current view. If undefined, the sgsML schema from the current module will be used for all views. A sub-schema is the first view of a separate module in a separate .xml file. The sub-schema overloads the current view and also attributes from the "table" tag.
    ---
    useful for: map a birthday field in contacts into appointments
    example: schema="sys_nodb_calendar_contacts" (modules/schema_sys/nodb_calendar_contacts.xml)
    used in: contacts.xml, users.xml (and more)
  • right: Defines a permission that is required to access the current view. If undefined, read permissions to the current folder are required.
    valid values: read, write, admin
    example: right="write"
    used in: sgsml.php
  • function: Calls a PHP method to render the current view. Default class is "custom", can be changed with prefix "classname::". It is an important feature to integrate custom PHP applications within Simple Groupware.
    example: function="testing"
    example #2: function="other_class::somemethod"
    ---
    signature: static function somemethod($folder, $view)
    [$folder = current folder id, $view = current view, return HTML output]
    ---
    used in: nodb_phpinclude.xml


Note: Custom classes can be put under "custom/core/classes/" (will be tried first) or "ext/core/classes/" (reserved for extensions). E.g. "class mymethods {}" in "custom/core/classes/mymethods.php".


<rowfilter> tag


Rowfilter is an optional tag in the structure and contains a PHP method to modify the output of an asset in a view. Compared to the <filter> tag, the result can be applied as a style to the whole asset.
Calls a PHP method to modify the output of an asset in a view. There can be multiple <rowfilter> tags inside a <table> tag. Method parameters can be added, separated by "|". Default class is "modify", can be changed with prefix "classname::". The "name" attribute serves as a unique identifier. The "views" attribute contains view names to apply the filter to, separated by "|". The "type" attribute can be set to "_fgstyle" to set a foreground CSS attribute or "_bgstyle" to set a background CSS attribute. The "views" attribute contains the field names to be validated, separated by "|".

Example:

<rowfilter name="filter1" views="all" type="_bgstyle" function="isinpast|ending|background-color:#FFDDDD;"/>

<rowfilter name="filter2" views="all" type="_bgstyle" function="myclass::rowfilter|abc|100"/>

Signature: static function rowfilter($row, $params)

  • $row = dataset array with "data" and "filter" keys
  • $params = parameter array('abc',100)
  • return string style attribute(s)


<rowvalidate> tag


Rowvalidate is an optional tag in the structure and contains a PHP method to validate new assets. Compared to the <validate> tag, it validates the whole row in place of one field.
Calls a PHP method to validate an asset before saving it to the database. There can be multiple <rowvalidate> tags inside a <table> tag. Method parameters can be added, separated by "|". Default class is "validate", can be changed with prefix "classname::". The "name" attribute serves as a unique identifier. The "fields" attribute contains the field names to be validated, separated by "|".

Example:

<rowvalidate name="v1" fields="categoryname|cattype" function="itemsexist|simple_categories|categoryname,cattype"/>

<rowvalidate name="v2" fields="field_a|field_b" function="myclass::rowvalidate|abc|100"/>

Signature: static function rowvalidate($row, $params)

  • $row = dataset array
  • $params = parameter array('abc',100)
  • return string empty (valid asset) or error message (invalid asset)


<field> tag: Extended attributes (optional)


  • simple_default_function: Defines a default input value by using a PHP method when creating a new asset. If undefined, the input value will be empty by default. Default class is "modify", can be changed with prefix "classname::".
    translatable: yes
    example: simple_default_function="getusername"
    example #2: simple_default_function="dateformat|now|{t}m/d/Y{/t}"
    example #3: simple_default_function="fillform|var1" (request parameter "var1")
    example #4: simpleabc_default_function="myclass::default_method|100|abc"
    ---
    signature: static function default_method($params)
    [$params = parameter array(100,'abc'), return string default value]
    ---
    used in: contacts.xml
  • is_unique_with_trash: Requires the field to have a unique value and covers also values that exist in the trash folder. If undefined, the input value of the current field can exist more than once in assets belonging to the same module.
    ---
    useful for: unique system values (e.g. usernames)
    example: is_unique_with_trash="true"
    used in: users.xml
    available since: 0.644
  • no_checks: Avoids checks for insecure HTML. If undefined, all fields will be checked for insecure HTML code (see function modify::htmlfield). This can be useful for filters producing HTML code like forms, that normally get stripped out.
    ---
    useful for: filters producing HTML code like forms (get stripped out by default)
    example: no_checks="true"
    used in: surveys.xml
    available since: 0.643
  • hidden: Fetches the values for the field from the database, but does not show the field in the view. If undefined, all fields defined in a module will be fetched from the database and shown in the view. Can be overridden by "editable" attriute for "new" and "edit" views.
    ---
    useful for: fields to hide in a view but use them in filters
    example: hidden="true"
    used in: calendar.xml, forum.xml (and more)
  • editable: Allows to edit a field that is hidden in all views. Used to set a value in "new" and "edit" views, but do not show the value in other views.
    useful for: notifications, assign colors to assets
    example: hidden="true" editable="true"
    used in: tasks.xml, forum.xml (and more)
  • nodb: Uses a field in a view, but does not create the field in the database table. If undefined, all fields defined in the module will be created in the database.
    example: nodb="true"
    used in: search.xml, stats.xml
  • db_size: Sets the maximum field size for the field in the database table. If undefined, the field size will be determined by the "simple_type" attribute. Text fields get a limit of 255, IDs get 15, dates get 10 and text areas, select boxes are limited to 64k.
    example: db_size="VALUE"
    used in: stats.xml, tree.xml (and more)
  • db_type: Sets a field type for the field in the database table. If undefined, the field type will be determined by the "simple_type" attribute. Text fields get be "varchar", text areas and select boxes get "text", dates, bools and IDs are saved as "int".
    ---
    useful for: fields requiring bigger fields or numeric representations
    example: db_type="int"
    used in: calendar.xml
  • no_search_index: Forbids to put the field values in the search index. If undefined, all field values will be indexed and presented in the search results.
    useful for: password fields
    example: no_search_index="true"
    used in: tree.xml, users.xml (and more)
  • disable_ccp: Does not copy the field value when using copy-paste. If undefined, all field values will be copied to the new dataset.
    useful for: password fields
    example: disable_ccp="true"
    used in: users.xml, surveys.xml (and more)
  • input_height: Sets the height of an input field. If undefined, the height will be set to "300" pixels. Only used for simple types "htmlarea", "codearea" and "spreadsheet".
    example: input_height="300"
    used in: htmldocs.xml
  • notinall: Excludes a field from all views and from the search index. Also avoids fetching the field from the database. Can be overridden for some views with the "onlyin" tag.
    useful for: internal fields like created, lastmodified
    example: notinall="true"
    used in: tasks.xml, projects.xml
  • form: Sets attributes used to display the current field in a form (edit, new, edit as new). Only defined for simple_type "textarea". "no_template_bar" disables the option to add templates to the text box. "no_formatting_button" hides the button "Text formatting rules".
    valid values: no_formatting_button, no_template_bar
    example: form="no_formatting_button|no_template_bar"
    used in: emails.xml, nodb_imap.xml (and more)
    available since: 0.651


<field> tag: extended sub-tags


  • <KEY>: Makes the field a primary key in the database table. Primary keys are unique indexes which speed up lookups in the database.
    example: <KEY/>
    used in: hosts.xml, search.xml
  • <INDEX>: Creates an index over the field in the database table. Indexes speed up lookups in the database.
    example: <INDEX/>
    used in: contacts.xml, tasks.xml (and more)
  • <INDEX_FULLTEXT>: Creates a fulltext index over the field in the database table. Fulltext indexes speed up search operations on texts.
    example: <INDEX_FULLTEXT/>
    used in: search.xml

  • <store>: Calls a PHP method to modify the current field before saving it to the database. There can be multiple <store> tags inside a <field> tag. Method parameters can be added, separated by "|". Default class is "modify", can be changed with prefix "classname::".
    ---
    useful for: convert user input before saving, e.g. convert human readable dates to unix timestamps
    example: <store function="html_tidy"/> (reduce HTML code)
    example #2: <store function="datetime_to_int"/>
    example #3: <store function="myclass::store_method|100|abc"/>
    ---
    signature: static function store_method($value, $row, $params)
    [$value = value to be stored, $row = dataset array, $params = parameter array(100,'abc'), return string storable value]
    ---
    used in: contacts.xml, htmldocs.xml (and more)

  • <restore>: Calls a PHP method to restore the current field before displaying the field in the form of the "edit" and "edit as new" views. There can be multiple <restore> tags inside a <field> tag. Method parameters can be added, separated by "|". Default class is "modify", can be changed with prefix "classname::". The "views" attribute contains view names, separated by "|". Will be applied before "filters" attribute.
    ---
    useful for: make fields empty in "edit as new" view, convert unix timestamps to human readable dates
    example: <restore views="edit_as_new" function="empty_str"/>
    example #2: <restore views="reply|replyall" function="empty_str"/>
    example #3: <restore views="all" function="myclass::restore_method|100|abc"/>
    ---
    signature: static function restore_method($value, $params, $row)
    [$value = value to be restored, $params = parameter array(100,'abc'), $row = dataset array with "data" and "filter" keys, return string restored value]
    ---
    used in: cms.xml, forum.xml (and more)

  • <readonlyin>: Read-only-in removes the field from "new" and "edit" views. If undefined, all fields of a module are visible in a view. The "views" attribute contains view names, separated by "|".
    useful for: non-editable fields like IDs
    example: <readonlyin views="edit"/>
    used in: emails.xml, users.xml (and more)

  • <hiddenin>: Hidden-in fetches the current field from the database, but does not show it in some views. If undefined, all fields of a module are editable in "new" and "edit" views. The "views" attribute contains view names, separated by "|".
    ---
    useful for: fields to hide in a view but use them in filters
    example: <hiddenin views="display"/>
    used in: surveys.xml


Note: Custom classes can be put under "custom/core/classes/" (will be tried first) or "ext/core/classes/" (reserved for extensions). E.g. "class mymethods {}" in "custom/core/classes/mymethods.php".

Note: Custom types can be put under "custom/core/types/" (will be tried first) or "ext/core/types/" (reserved for extensions). E.g. "class type_mytext {}" in "custom/core/types/mytext.php".

Note: Showing a field in a view is evaluated by the following order: notinall (attribute in <field>), notin (tag in <field>), onlyin (tag in <field>), showonly (attribute in <view>)

Note: In Simple Groupware, translatable strings are marked with "{t}", "{/t}". For example "{t}Open{/t}" will be translated to "Offen" in German.


Release changes


  • v0.730: added "disable_notification" and "disable_bgcolor" attributes to the table tag.
  • v0.720: changed form attribute separator from "," to "|".
  • v0.661: added "form" attribute to the "field" tag.
  • v0.651: added "disable_trigger_ccp" attribute to the "table" tag.
  • v0.646: renamed "cust_name" attribute to "custom_name"
    ("cust_name" will continue to work)


sgsML Frequently asked questions / FAQ

<< contents

coming up soon ...


Frequently asked questions / FAQ

<< contents

Here are the most frequently asked questions with some quick answers.

Installation:

Operation and customizing:

General questions:



How do I create a support request?


Open a new support ticket on the sf-net pages or search the archive.

Note: When you change the Simple Groupware code base or add new code without publishing it, there can be no support for your code.

Note: In order to create a ticket on SourceForge.net, you'll need to register and login there first.

Note: If you post your problem on Google Groups without version numbers or information about your server (PHP version, database version, phpinfo output, etc.), your issue cannot be resolved.


The setup stops with: Please give write access to ...


The Simple Groupware installer needs to write into current directory. Therefore, please make sure that the current directory is writable.
When using the Simple Groupware setup instead of the installer, there are several folders that require write permissions. The setup checks automatically all required permissions.
Write permission means that the user running the Apache web server has the permission to write. If you uploaded the Simple Groupware files with a FTP program, the owner of the directory may be different from the user running Apache. In that case it might be necessary to give write permissions to anonymous on a Linux/Unix system.

Directories with "write" permissions: <sgs-dir>/bin, <sgs-dir>/simple_cache, <sgs-dir>/simple_store, also <sgs-dir>/bin/index.php

Directories with "read" permissions: <sgs-dir>/src, <sgs-dir>/lang, <sgs-dir>/import


How do I change the language after the Simple Groupware installation?


Language files are not parsed by Simple Groupware for every page request. Instead they are compiled into the code in order to increase the performance.
If you want to change the language, empty the directory "<sgs-dir>/bin/" and delete the file "<sgs-dir>/simple_store/config.php". Then open your browser with "http://your_server/sgs_dir/src/index.php" to start the setup with the language selection again. If you enter the same parameters for the database connection, all your data will remain.

Note: Making a full backup before changing the system is never wrong.


Can I install Simple Groupware with more than one language?


No. During setup, all translations are directly compiled into the source code. That way, language files don't need to be parsed for every page request and the system has a much better performance.
When all users use the same user interface, there are fewer misunderstandings and less frustration regarding different labels, different sortings, folder names, etc.
Finally training, documentation and support is much easier if every user has the same unique user interface. All users in one organization should be able to read and write one common language in order to communicate with each other. Therefore, Simple Groupware can be installed only with one language.


How can I administrate users and set permissions?


Information about users, groups and permissions can be found here.


Can Simple Groupware be integrated with other software systems?


Yes. There are systems supported by default, see data handlers, authentication. Others can be integrated by using the SOAP server. All kinds of integrations require proper testing and in some cases coding, so it's up to you to hire the right programmers or software companies. Since Simple Groupware is completely open source, there are no limits.


How can I disable (or hide) some components like Personal folders, Personal projects, Bookmarks, Organization, Contacts...?


There are two simple ways:

1. Change the folder access rights so that your users can't see it: Select the folder, select Folder > "Rights: edit" (menu at top of page), remove "anonymous" from "read access" and "write access" panels (select "anonymous" and click X aside), click "Save and go back". Now only the admin user can see the folder.

2. Delete the folder and its subfolders: Select the folder, then select Folder > "Delete incl subfolders" (from the menu at the top of the page). It will be moved to the trash (System / Trash) which is accessible to admin only.

Note: If you hide the "Personal folders", you'll also need to make sure that the users are no longer directed to their personal folders when they log in. Select Organisation > Users in the folder tree at left, select all of the user account records (e.g. tick the box at the bottom left of the list of accounts), click the Edit tab, click the Account tab, enter a new "home folder id" number into each user account record (this is the id number of the folder the users will see when they log in), click "Save and go back". You can find the id number of a folder by moving the cursor over it - it is the last number in the destination URL, e.g. the "Workspace" folder is usually 101.


How can I disable (or hide) some modules for all users?


Modules and mountpoints can be disabled for all users in setup settings. Afterwards, modules can be re-enabled for certain users under "Workspace / Organization / Users -> Tab: Account -> Field: Allow disabled modules". (Feature added in release 0.655)


How can I give write permissions to a folder without allowing users to rename the folder or create subdirectories?


This can be done by giving read permissions to the folders and write permissions to the views "New", "Edit" and "Edit as new". Therefore, log in as super administrator or as another user with "admin" privileges on the desired folder.
Select the folder, select Folder > "Rights: edit" (menu at top of page), set "read access" for the desired user(s), make sure those users are not in the "write access" list and set "view access (users)" to: |new,edit,edit_as_new:write:<user1,user2,etc.>|
Finally click "Save" and you're done.

Note: To allow users only to create assets, you can set the view permissions to: |new,edit_as_new:write:<user1,user2,etc.>|


How can I set individual permissions for every user or group on each contact, bookmark, etc.?


The answer can be found in the Customization FAQs.


After deleting a dataset it appears again in select boxes for the super administrator / How can I restore a deleted dataset?


All deleted datasets are moved to "/Workspace/System/Trash/". From there you can delete them forever or make a restore. Since the super administrator has access to the trash folder, these datasets will be still available as long as they are not deleted forever.


How can I restore a deleted folder?


All deleted folders are moved to "/Workspace/System/Trash/" and all access rights for the folders (and the subfolders) are removed. From the Trash folder, you can delete them forever or make a restore by using Folder->Cut/Paste in the top menu. The restore also requires to set the folder permissions again. Since only the super administrator has access to the trash folder by default, normal users can't restore deleted folders.


When sending mail, I get: trigger::sendmail SMTP not configured


Creating users, groups and mail accounts is described here.


How can I create a shared calendar that is available for a group of persons?


New calendars are created with the "new folder" function.
Login as super administrator and navigate to the folder that should contain the new calendar. Then click "Options" below the tree, enter a name for the new folder and select "Calendar" as module. Then confirm with "Ok". Now the new folder is created and you can you set the rights for it. Select the folder, select Folder > "Rights: edit" (menu at top of page), add the desired users to "read access" and "write access" panels, click "Save". In order to get access to a folder, a user also needs to have at least read access to the parent folders.
Instead of the super administrator, you can also use another user who has the right "admin access" on the folder that should contain the new folder. By default, users are not allowed to specify rights on their personal folders.


How can I integrate Simple Groupware into my LDAP / Active Directory infrastructure?


This is part of the administration documentation, go here.


Is it possible to turn off the creation of a "home" folder?


Yes, you can edit "<sgs-dir>/bin/modules/schema_sys/users.xml", remove:
trigger_new="runxml:modules/core/users.xml:home|createuser" trigger_delete="deleteuser"


The setup stops with: Please modify your php.ini or add an .htaccess file changing the setting "register_globals" to "0"


Older versions of Simple Groupware require to disable "Register globals" in php.ini. Therefore, it is recommended to install the latest version.


I forgot the super administrator password, how can I reset it?


You can delete the file "<sgs-dir>/simple_store/config.php" to start the setup again. More information about passwords and creating users can be found here.


How do I customize Simple Groupware?


The customization tutorial can be found here.


Are there any limitations or charges for the deployment?


No. There are no charges or limitations (e.g. maximum number of seats, servers, users) for the deployment of Simple Groupware. All features are available in the open source package, there is no commercial edition or restriction on professional use. Also support and documentation are available for free. Simple Groupware is Free Software, released under the GNU GPLv2 License.


How many companies use Simple Groupware?


Using Simple Groupware is totally anonymous. There is no activation procedure, no registration, etc. So nobody can say how many users or companies have it running in production or testing.
The download statistics from sourceforge.net are available here.


Is there a date planned when Simple Groupware development stops?


No.


Are there any commercial support services?


No. The support is also for free.


Is there an online demo version of Simple Groupware?


No. Running a demo takes a lot of resources.
You need a dedicated server, install security updates every week, control the logfiles, control the hardware, monitor the services, do an update for every release of Simple Groupware, etc. Also you can't give every user administrative rights. With administrative rights, you can do rather everything with the server and the database.

In order to avoid misuse (spammers, defamation), every user would need to register to the demo and I would need to confirm the registration, create and remove accounts/mail addresses every day. That means people would have to wait some hours until I activate their account. Doing an installation on Windows with XAMPP and Simple Groupware normally takes 10 minutes and you can test all features. Also it would be very difficult to simulate a bigger environment with a LDAP / Active directory servers, IMAP servers, SyncML server, etc.

Therefore, running a public demo wouldn't be a good solution for completely testing and evaluating Simple Groupware.


Is there a virtual machine (VM) of Simple Groupware?


No. Installing Simple Groupware directly on your favorite system is much faster (normally 10 minutes) than downloading a big VM that does not fit into your environment.


What is the best configuration for a MySQL server with 16 GB of RAM?


Percona has created the MySQL Configuration Wizard which gives you examples for your specific hardware. Please note: Simple Groupware currently uses MyISAM as MySQL storage engine with 80-160 tables.


Why is the version number less than 1?


Open source projects normally start with 0.1 and every major package of features gets +0.1. Simple Groupware is currently >158 releases old, so you can also see it as "Simple Groupware 158.0".


Support

<< contents

Photo from o5com / http://www.flickr.com/photos/o5com/4951006091/

In the Simple Groupware Forum, users share questions and information with one another. Any individual with a question or comment about Simple Groupware is welcome to post. Forum and trackers are only available in English. Please do not post a message more than once.


Forum


Forum / mailing list on Google Groups

Note: Messages from new members are moderated, so it may take a few hours until your first message arrives in the discussions list.


Support trackers



Sourceforge Forum Archive



Sourceforge Bugs Archive