View · Search · Index


Showing 1 - 10 of 670 Postings (summary)

E-Mail: Outgoing E-Mail

Created by Malte Sussdorff, last modified by Gustaf Neumann 12 Nov 2020, at 06:31 PM

Current documentation for ACS Mail Lite, the standard API for inbound and outbound email is at .


The current recommendation for sending outgoing mail is via the NaviServer modules nssmtpd, since this handles well large outgoing mails and works as well with >1000 file descriptors open. In OpenACS 5.10, set the package parameter "EmailDeliveryMode" if the acs-mail-lite package to "nssmtpd".

Older Discussion

Outgoing E-Mail at the moment in acs-mail-lite is split in a multitude of procedures, some doubling the efforts of the other. To clean this up I propose the following (in general):

  • Replace acs-mail-lite::send with acs-mail-lite::complex_send, making it a wrapper for complex_send or the other way round (rename complex_send to send and so on).
  • Only support sending of e-mails via SMTP. Use smtp::sendmessage from TCLLIB for it (as does complex_send).
  • Daveb suggested to split up complex_send  to make it easier to test parts of it. Here are some ideas:
    • Sub procedure to generate "to/cc/bcc/_lists" which are used in the respective TO/CC/BCC header. This will also clean up the sending of individual emails.
    • Have only one call to smtp::sendmessage and one hook for the complex_send callback.
    • Sub-procedure to append file tokens. Not sure this is useful as we need to do upvar for the tokens and could not do automated tests on them anyway. So I'd not do it.
  • Have only one sweeper (the complex_sweeper) with support for multiple mail sending servers (so you can have multiple mail senders in the cluster instead of only one).
  • Split of incoming email handing into a separate file
  • Delete acs-mail-lite-procs.tcl :-). Just kidding, but deprecate most of the procedures.

Sadly it is not a straightforward approach, as there is a catch. Using smtp::sendmessage forces us to figure out a new way for setting the bounce-email address header, as the old approach will not work anymore (using the SMTP command "FROM" set to the bounce address). Another options is to use the non-standard "Errors-To" Header  instead.

Installing OpenACS on Windows

Created by Maurizio Martignano, last modified by Maurizio Martignano 05 Nov 2020, at 02:43 PM

Windows-OpenACS (vers. 4.7.6 - November 2020) is a  Windows 64 port of OpenACS 5.9.1 and the latest snapshot of NaviServer and is available at Spazio IT .

This port installs and runs on the following systems:

  • Windows 10,
  • Windows Server 2012 R2,
  • Windows Server 2016 and
  • Windows Server 2019.



Created by Malte Sussdorff, last modified by Poor Yorick 27 Oct 2020, at 01:35 PM

By convention, OpenACS stores all its SQL code in .xql files, which facilitates support for OpenACS on multiple databases.  Though this adds an extra burden to the development, please adhere to this convention.

  • Keep SQL scripts out of .tcl or .adp files, unless they conform to SQL99.  See details below.
  • Assign a name to each db_statement.  see Naming Conventions.
  • Database-specific SQL statements, i.e. statements not conforming to SQL99, belongs in a -database.xql file:
    • select content_item__new() => content-item-postgresql.xql
    • select item_id from content_items => content-item.xql
  • Do not spread pieces of an SQL statement into multiple places, e.g. inline in Tcl, generic .xql, database-specific .xql.
  • If in doubt, be conservative and add SQL scripts into the database-specific file of the database you are working with.
  • Format each SQL script properly.  E.g. break each statement into multiple lines as appropriate to make it more readable.  See code-formatting

To make changes to a .xql file take effect, reload the file.

As an exception to the rule about keeping SQL out of Tcl scripts, pieces of an SQL script that is dynamically generated may be placed in a Tcl script if they conform to the SQL 99 standard.  This is often the case for "where_clause" of listbuilder.


Creation of tables in PostgreSQL:

  • Do not use the "SERIAL" datatype.  SERIAL is an ugly hack meant to make it easier to port Sybase scripts to PostgreSQL.  We have a standard way of defining integer primary keys and giving values to them: Integer with a sequence.
  • When creating a sequence use the CREATE VIEW hack so sequence queries can be shared between PG and Oracle without any extra work.  Otherwise, do the work to make the sequence work both in -oracle.xql as well as -postgresql.xql


Created by Gustaf Neumann, last modified by Gustaf Neumann 06 Sep 2020, at 02:36 PM

XoWiki is a wiki implementation for OpenACS  implemented based on xotcl-core. Instead of trying to implement the full set of wiki markup commands in systems like MediaWiki, XoWiki is based on a rich text editor and focuses more on integration with OpenACS (e.g. categories, general comments, adp-includes, ad-substitution of template variables). XoWiki combines aspects of wikis (ease of page-creation) with aspects of a content management system (revisions, reusable content, multiple languages, page templates).

XoWiki provides functionalities of enterprise wiki systems (such as combining structured with unstructured information, providing security policies, etc.). XoWiki is reused in several other packages such as XoWiki Content flow, S5 or  the Learning Content Tool.



Package Specification Summary for Package: xowiki

Summary: A xotcl-based enterprise wiki system with multiple object types
Description: <pre> XoWiki is a Wiki implementation for OpenACS in XOTcl. Instead of trying to implement the full set of Wiki markup commands of systems like MediaWiki, XoWiki is based on a rich text editor and focuses more on integration with OpenACS (e.g. categories, general comments, ADP-includes). XoWiki combines aspects of wikis (ease of page-creation) with aspects of a content management system (revisions, re-usable items, multiple languages). Furthermore, XoWiki allows one to define different types of links such one could define book-structures (where a navigation structure could be built on the fly) or glossaries with different kind of word relationships (like synonyms, etc.). XoWiki supports pages in multiple languages and is localized. Some features: - cross language links - inclusion of ADP pages - nesting of Wiki-pages - large set of includeable content (includelets) - search - tags - categories - RSS - weblog - podcasts - notifications - web 2.0 gadgets (digg, delicious, my yahoo) - audio embedding - different appearances (template_file) - book-structures - prototype pages - import/export - virtual presence - analysis of collaboration networks - forms - named/unnamed pages - various security policies </pre>
Maturity: Mature
This package depends on: xotcl-core acs-datetime acs-kernel acs-tcl acs-templating acs-subsite acs-lang richtext-ckeditor4 categories file-storage general-comments acs-automated-testing
Packages that depend on xowiki: chat content-portlet eduwiki learning-content learning-content-portlet pages s5 xolirc xowf xowiki-includelet xowiki-portlet
Package parameters:
Size of the xowiki_cache (default 400000, type number, scope global)
Activate experimental menubar stuff (default 0, type number, scope instance)
Activate experimental menubar stuff (default 0, type number, scope instance)
Space delimited names of local URL paths pointing to xowiki instances from where this instance should inherit pages (example: /xowiki /public/wiki) (default , type string, scope instance)
Use either "yui" or "bootstrap" (default bootstrap, type string, scope global)
Preferred richtext editor, such as: xinha, ckeditor, ckeditor4 (default) or wym (default ckeditor4, type string, scope global)
One or more additional css file for this Instance (default , type string, scope instance)
When hstore is activate, don't store entries larger than this size in the hkey. This makes it possible to produce smaller hkey indices and to use e.g. GIN, which has a size limit of 2K. Set to 0 to disable the size limit (default 2000, type number, scope global)
::xowiki::FormPage to search for parameters. The page name has to contain a language prefix and can refer to a different xowiki instance. Example: //xowiki/en:xowiki-standard-parameter (default , type string, scope instance)
Define the valid operations for different kind of users. Currently, two policies are predefined: ::xowiki::policy1 and ::xowiki::policy2. Policy1 requires for all destructive operations (deletes, delete_revision) and programmatical operations (involving tcl code, e.g. editing the ::xotcl::Objects) package admin rights, for reindex site wide admin right). Policy 2 requires also for destructive operations site wide admin rights. (default ::xowiki::policy1, type string, scope instance)
Name of the ADP file to be used for viewing xowiki pages. The default value is 'view-default'. Alternatively, one can use 'view-book' to view pages in book style (needs page_ordering) or e.g. 'oacs-view' for providing a view with the category-tree on the left, or any other tailored view (default view-default, type string, scope instance)
Specify an xowiki includelet (defined in ::xowiki::includelet::*) to be included on top over every pages. In order or add e.g. on each page of this wiki instance a listing of the users currently active in this xowiki instance, set the value of this parameter e.g. to 'presence -interval "10 minutes"'. The valid parameters are defined by the xowiki includlets. (default presence -interval "10 minutes", type string, scope instance)
Use hstore for accessing instance attributes. Create index for existing values via ::xowiki::hstore::update_form_instance_item_index -package_id $package_id (default 0, type number, scope instance)
Description: PackageDescription
Description of the Package. This description will appear for example in the Description of the default RSS feed for this package (default , type text, scope instance)
Description: PackageTitle
Title of the Package; this title will appear for example in the default RSS feed for this package. (default , type string, scope instance)
Form: autoname
Automatically name items of this instance (default 0, type number, scope instance)
Form: display_page_order
Display page_order attribute (Section) in edit forms if possible. (default 1, type number, scope instance)
Options: include_in_google_sitemap_index
Include the package in the google sitemap index (default 1, type number, scope instance)
Options: my_yahoo_publisher
Name of the publisher, when posting URLs to my yahoo (use in connection with with_yahoo_publisher) (default , type string, scope instance)
Options: production_mode
When this parameter is set, new pages are created in a "production" state, where they are not visible to users. These page have to be released via the admin pages. Notification and syndication is decativated, while pages are under "production". (default 0, type number, scope instance)
Options: show_page_references
If enabled it shows on a page view the pages that reference it (default 1, type number, scope instance)
Options: show_per_object_categories
If enabled it shows on a page view the categories assigned to this object (default 1, type number, scope instance)
Options: with_delicious
Add a delicious button to the page (default 0, type number, scope instance)
Options: with_digg
Add a button to submit article to digg (default 0, type number, scope instance)
Options: with_general_comments
use general comments package (default 1, type number, scope instance)
Options: with_notifications
Allow the user to register notifications (default 1, type number, scope instance)
Options: with_tags
allow user to provide tags to pages (default 1, type number, scope instance)
Options: with_user_tracking
track page view usage per user (default 1, type number, scope instance)
Options: with_yahoo_publisher
When specified, a button for adding the content to is added (default 0, type number, scope instance)
Pages: index_page
name of the page to be shown when the package instance is browsed (e.g. en:index) (default , type string, scope instance)
Pages: weblog_page
name of the page to show weblog (when clicking on tags) (default en:weblog, type string, scope instance)
URL: fallback_languages
Specify space delimited two character codes for checking default languages. When this parameter is non-empty, try to get the page in the specified languages as fallback rather than offering a link for creation of a page in the requested locale. Per default this parameter is empty. (default , type number, scope instance)
URL: package_prefix
Part of the URL used before language and page name. This setting is used, when a URL is computed. Per default, the package_prefix is determined by the side not. When for example a default xowiki instance is used as start page of OpenACS, the package_prefix can be set to / (default , type string, scope instance)
URL: subst_blank_in_name
normalize names of pages in a media wiki style. Most dominantly, spaces are turned into blanks. (default 1, type number, scope instance)
URL: use_connection_locale
When this flag is set, per-user specific information is used to determine the default language. Users with different language preferences will see under the same url different content. Per default this flag is turned off, and the package or system wide locale is used. (default 0, type number, scope instance)
xinha: WidgetSpecs
Specify pairs of "pagename,fieldname" followed by a Tcl list which is used as a widget spec for ad_form. "pagename" and "fieldname" can contain wild card characters. The following rather complex widget-specs are from *,text {richtext(richtext),nospell,optional {label Content} {html {style {width: 100%}}} {options {editor xinha plugins {Stylist OacsFs} height 350px javascript { xinha_config.toolbar = [ ['popupeditor', 'bold','italic','createlink','insertimage','separator'], ['killword','removeformat'] ]; xinha_config.stylistLoadStylesheet('/resources/xowiki/examples/xinha-mc-styles.css', {'p.angabe' : 'Aufgabenstellung', 'p.loesungshinweis' : 'Lösungshinweis', 'li.correct_choice' : 'Richtige Antwort', 'li.incorrect_choice' : 'Falsche Antwort'}); }}}} (default , type text, scope instance)

Bug Tracker Summary for Package: xowiki

Open Bugs: 4
All Tracked Issues: 53
Latest Bug Opened: 2020-11-10 Error upgrading to 5.9.1: Unable to dispatch method 'import-prototype-page'
Latest Bug Fixed: 2020-02-11 name-based selection of default values for category based form fields..
Top Bug Submitters: Robert Taylor (10) Michael Aram (9) Ryan Gallimore (9) Carl Robert Blesius (6) Malte Sussdorff (3)
Top Bug Fixers: Gustaf Neumann (47) Stan Kaufman (2) Malte Sussdorff (1)

Code Metrics Summary for Package: xowiki

# Tcl Procs 30
# Tcl Lines 33271
# Tcl Blank Lines 3348
# Tcl Comment Lines 6638
# Automated Tests 8
# Stored Procedures PG: 0 ORA: 0
# SQL Lines PG: 0 (blank 1 comments 0) ORA: 0 (blank 1 comments 0)
# ADP pages 24
# ADP lines 1705
# Include pages (xowiki/lib/) 1
# Documentation pages 0
# Documentation lines 0
Browse Source API-browser

Available Includelets

The following includelets can be used in a page
  • {{activity-graph -max_edges 70 -cutoff 0.1 -max_activities:integer 100 -show_anonymous message}}

    Include an activity graph

  • {{available-formfields -flat:boolean false}}

    List the available form field types of this installation.

  • {{available-includelets}}

    List the available includelets of this installation.

  • {{book -category_id -menu_buttons edit -folder_mode false -locale "" -range "" -allow_reorder "" -with_footer false}}

    Show contents in book mode.

  • {{bookmarklet-button -siteurl "" -label ""}}

    Include bookmarklet button that makes it easy to add the current page as a bookmark in the browser of the client.

  • {{categories -tree_name "" -tree_style:boolean 1 -no_tree_name:boolean 0 -count:boolean 0 -summary:boolean 0 -locale "" -open_page "" -order_items_by title,asc -style mktree -category_ids "" -except_category_ids "" -allow_edit false -ordered_composite}}

    List the specified category tree.

  • {{categories-recent -max_entries:integer 10 -tree_name "" -locale "" -pretty_age off}}

    Display recent entries by categories.

  • {{chat -title "" -chat_id "" -mode "" -path "" -skin -login_messages_p -logout_messages_p -avatar_p -timewindow}}

    Include a chat in the current page

  • {{chat_room -chat_id -mode:optional "" -path:optional ""}}

    Include a chat room

  • {{child-resources -skin:optional yui-skin-sam -show_types ::xowiki::Page,::xowiki::File,::xowiki::Form,::xowiki::FormPage -regexp:optional -language_specific:boolean false -with_subtypes:boolean,optional false -orderby:token,optional last_modified,desc -publish_status:wordchar ready -view_target "" -html-content -parent . -columns objects edit object_type name last_modified mod_user duplicate delete -hide "" -menubar ""}}

    Include the content of the current folder somewhat similar to explorer.

  • {{collab-graph -max_edges 70 -cutoff 0.1 -show_anonymous message -user_id}}

    Include a collaboration graph

  • {{community-link -text "" -url ""}}

    Include a link to the community including the current page. This includelet is designed to work with dotlrn.

  • {{composite-form -edit_links:boolean false -pages "" -ordered_pages}}

    Create a form from the selection

  • {{copy-item-button -page_id -alt copy -book_mode false}}

    Button to copy a page

  • {{countdown-timer -target_time ""}}

    Countdown timer

  • {{create-item-button -page_id -alt new -book_mode false}}

    Button to create a new page based on the current one

  • {{creation-date -source "" -format %m-%d-%Y}}

    Include the creation date of the current or specified page in the provided format.

  • {{current-irc-log -date ""}}

  • {{delete-item-button -page_id -title Delete -alt delete -book_mode false}}

    Button to delete the current or a different page

  • {{delicious -description "" -tags "" -url}}

    Add a button to submit article to delicious.

  • {{digg -description "" -url}}

    Add a button to submit article to digg.

  • {{edit-item-button -page_id -title Edit -alt edit -book_mode false -link "" -target ""}}

    Button to edit the current or a different page

  • {{exam-top-includelet -target_time "" -url_poll "" -url_dismiss "" -poll_interval 5000}}

    This is the top includelet for the in-class exam, containing a countdown timer and the personal notifications includelet

  • {{flowplayer -mp4:required}}

    Include an mp4 image using flowplayer

  • {{folders -show_full_tree false -context_tree_view false}}

    List the folder tree of the current instance

  • {{form-menu -form_item_id:integer -parent_id -form -buttons new answers -button_objs -return_url}}

    Include a form menu for the specified Form

  • {{form-stats -form -parent_id -property _state -orderby count,desc -renderer table}}

    Include form statistics for the specofied Form page.

  • {{form-usages -form_item_id:integer -form -parent_id -package_ids "" -orderby _raw_last_modified,desc -view_field _name -publish_status all -field_names -hidden_field_names _last_modified -extra_form_constraints "" -inherit_from_forms "" -category_id -unless -where -csv true -voting_form -voting_form_form "" -voting_form_anon_instances t -generate -with_form_link true -with_categories -wf -bulk_actions "" -buttons edit delete -renderer "" -return_url -date_format}}

    Show usages of the specified form.

  • {{get -variable -form_variable -source ""}}

    Get an instance variable from the current or from a different page.

  • {{graph}}

  • {{gravatar -email:required -size 80}}

    Include gravatar picture for the specified email

  • {{html-file -title "" -extra_css "" -levels 0 -file:required}}

    Include the specified HTML file

  • {{iframe -title "" -url:required -width 100% -height 500px}}

    Include an iframe contining the specified URL

  • {{item-button}}

  • {{jquery-carousel}}

    Display a sequence of pages via jquery-carousel, based on book includelet.

  • {{jquery-cloud-carousel}}

    Display a sequence of pages via jquery-cloud-carousel, based on book includelet.

  • {{jquery-infinite-carousel}}

    Display a sequence of pages via jquery-infinite-carousel, based on book includelet.

  • {{jquery-spacegallery}}

    Display a sequence of pages via jquery-spacegalleryl, based on book includelet.

  • {{kibana -chart openacs-status-codes -from now-24h -to now -hash "" -width:integer 800 -height:integer 400}}

    Include a Kibana chart identified by the provided hash

  • {{last-visited -max_entries:integer 20}}

    Display last visited pages.

  • {{link-with-local-return-url -text "" -url ""}}

    Insert a link with extra return URL pointing the current object. This is particularly useful in cases, where a return URL must be created for a page that does not yet exist at time of definition (e.g. for link pointing to concrete workflow instances)

  • {{most-frequent-visitors -max_entries:integer 15}}

    List the most frequent visitors.

  • {{most-popular -max_entries:integer 10 -interval}}

    Display most popular pages of this wiki instance.

  • {{my-categories -summary 1}}

    List the categories associated with the current page.

  • {{my-general-comments}}

    List the general comments available for the current page.

  • {{my-references}}

    List the pages which are referring to the current page.

  • {{my-refers}}

    List the pages which are referred to the current page.

  • {{my-tags -summary 1}}

    List the tags associated with the current page.

  • {{my-yahoo-publisher -publisher "" -rssurl}}

    Name of the publisher, when posting URLs to my yahoo (use in connection with with_yahoo_publisher).

  • {{personal-notification-messages -url_poll "" -url_dismiss "" -poll_interval 5000}}

    Personal notification messages This includelet can be used for personal messaging, where a sender can send messages to a single user in a single applications (e.g. in an exam), where the user has to acknowledge every single message to make it disappear (current implementation). The messages are not persisted (current implementation).

  • {{presence -interval 10 minutes -max_users:integer 40 -show_anonymous summary -page}}

    Show users actively in the wiki.

  • {{random-form-page -form:required -publish_status ready -expires 600}}

    Include random form page (instance of the specified form)

  • {{recent -max_entries:integer 10 -allow_edit:boolean false -allow_delete:boolean false -pretty_age off}}

    Display recent modified entries.

  • {{references-graph -folder . -page "" -link_type link -rankdir LR -fontsize 12}}

    Include a graph of the (partial) link structure in a wiki, starting either with a page or a folder. When a page is provided, the local link structure of this page is visualized (including incoming and outgoing links of the page; e.g. -page "." for the current page). Alternatively, the content of a folder can be shown.

  • {{rss-button -span 10d -name_filter -entries_of -title}}

    Include an RSS button referring to pages of the specified time span.

  • {{rss-client -url:required -max_entries:integer 15}}

    Include RSS content

  • {{selection -edit_links:boolean true -pages "" -ordered_pages "" -source -menu_buttons edit -range ""}}

    Provide a selection of pages

  • {{set-parameter}}

    Set a parameter accessible to the current page (for certain tailorings), accessible in the page via e.g. the query parameter interface.

  • {{slidy}}

    Display a sequence of pages via W3C slidy, based on book includelet

  • {{tags -limit:integer 20 -summary:boolean 0 -popular:boolean 0 -page}}

    Display specified tags.

  • {{timeline -user_id -data timeline-data -interval1 DAY -interval2 MONTH}}

    Include a timeline of changes (based on yahoo timeline API)

  • {{toc -style "" -renderer "" -open_page "" -book_mode false -folder_mode false -ajax false -expand_all false -remove_levels 0 -category_id -locale "" -source "" -range "" -allow_reorder "" -include_in_foldertree true}}

    Show table of contents of the current wiki. The "toc" includelet renders the page titles of the current files based on the value of the "page_order" attributes. Only those pages are rendered that have a nonempty "page_order" field.

  • {{unread-items -max_entries:integer 20}}

    List unread items.

  • {{unresolved-references}}

    List the pages with unresolved references in the current xowiki/xowf package. This is intended for use by admins.

  • {{user-timeline -user_id -data timeline-data -interval1 DAY -interval2 MONTH}}

    Include a timeline of changes of the current or specified user (based on yahoo timeline API)

  • {{view-item-button -page_id -title View -alt view -link "" -book_mode false}}

    Button to view the current or a different page

  • {{wf-todo -workflow "" -user_id -ical 0 -max_entries}}

  • {{yui-carousel -title "" -item_size 600x400 -image_size -num_visible 1 -play_interval 0 -auto_size 0 -folder -glob "" -form ""}}

    Include YUI carousel showing the pages of the specified or current folder.

Available Formfield Classes

The following formfield types can be used in xowiki::Forms
FormField (abstract, superclass xo::tdom::Object)
  • -CSSclass
  • -answer
  • -autocomplete
  • -autofocus
  • -correct_when
  • -default
  • -disabled
  • -disabled_as_div
  • -display_field true
  • -error_msg
  • -feedback_answer_correct
  • -feedback_answer_incorrect
  • -form_button_CSSclass
  • -form_button_wrapper_CSSclass
  • -form_help_text_CSSclass
  • -form_item_wrapper_CSSclass
  • -form_widget_CSSclass
  • -formnovalidate
  • -grading
  • -help_text
  • -hide_value false
  • -id
  • -in_position
  • -inline false
  • -label
  • -locale
  • -mode edit
  • -multiple
  • -name
  • -object
  • -pattern
  • -placeholder
  • -readonly
  • -required false
  • -show_raw_value
  • -slot
  • -spec
  • -style
  • -td_CSSclass
  • -test_item_in_position
  • -test_item_minutes
  • -title
  • -type text
  • -validate_via_ajax
  • -validator
  • -value

Available OpenACS Packages

Created by Gustaf Neumann, last modified by Carl Lemp 02 Sep 2020, at 05:18 AM

Wiki pages for the packages available in the OpenACS code repository :

Packages in the oacs-5-9 channel.

How to manage/upgrade CKEditor versions

Created by Gustaf Neumann, last modified by Gustaf Neumann 27 Aug 2020, at 07:46 PM

As of this writing (oacs-5-10), OpenACS supports CKEditor 4, which is kept as a separate package.

Per default, the CKEditor is used via CDN. If you prefer to install CKEditor locally, then go to /acs-admin/, click on the "Richtext CKeditor4" package on the link under site-wide admin. The pages show, how CKEditor is currently used, and offer a link for downloading and installing (gzipped, brotli if available).

Since upgrading to a newer version of CKEditor means often a different user experience.So, many site are reluctant to upgrade automatically to different versions. In these cases, one can configure the version of CKEditor in the NaviServer configuration file.

    ns_section ns/server/${server}/acs/richtext-ckeditor
           ns_param CKEditorVersion   4.14.1
           ns_param CKEditorPackage   standard
           ns_param CKFinderURL       /acs-content-repository/ckfinder
           ns_param StandardPlugins   uploadimage

A version specified in the configuration file override version numbers in the richtext package. When there is no such entry, then the version from the package is used.


SQL: How to log (slow) queries in the system log

Created by Gustaf Neumann, last modified by Gustaf Neumann 27 Aug 2020, at 11:47 AM

SQL logging is usually controlled via the configuration file of NaviServer. However, it can be as well activated at runtime via ds/shell by using the following commands:

  • make sure to turn sql-debugging level on
  • make sure, the logminduration is small enough (NaviServer allows to log only entries a threshold)
ns_logctl severity "Debug(sql)" on
foreach pool [ns_db pools] {ns_db logminduration $pool 0}

If you are interested e.g. in queries taking longer than 0.5 seconds, you can use

foreach pool [ns_db pools] {ns_db logminduration $pool 0.5}

Creating adp box tags for consistent html/css

Created by openacs community, last modified by Gustaf Neumann 26 Aug 2020, at 02:01 PM

Box tag code:

# The box tag is intended to make the markup around a "box"
# standard sitewide so that you can use the same css everywhere to   
# style the site.


template_tag box { chunk params } {
    set class [ns_set iget $params class]
    if {[template::util::is_nil class]} {
        set class box
    set id [ns_set iget $params id]
    if {![template::util::is_nil id]} {
        set id " id=\\\"$id\\\""

    template::adp_append_code "append __adp_output \"<div class=\\\"$class\\\"$id><div class=\\\"boxTop\\\"></div><div class=\\\"boxContent\\\">\""
    template::adp_compile_chunk $chunk
    template::adp_append_code "append __adp_output {</div><div class=\"boxBottom\"></div></div>}"

E-Mail: Incoming E-Mail

Created by Malte Sussdorff, last modified by Gustaf Neumann 24 Aug 2020, at 01:43 PM

Incoming E-Mail in OpenACS works with the latest version of acs-mail-lite in a general fashion using callbacks.

The original version of this documentation is found via at:

We will take a look on what needs to be done to get incoming e-mail working and then continue on to see how packages can benefit.

Project notes:  ACS Mail Lite sends via SMTP which permits the use of an external server to handle email. For scalability, consider expanding the incoming E-mail paradigm to likewise use Tcllib's imap4  or NaviServer&#39;s nsimap  so that most all email can be handled on separate servers. 

Install incoming E-Mail

First, one must have an understanding of postfix basics. See .

These instructions use the following example values:

  • hostname:
  • oacs user: service0
  • OS: Linux
  • email user: service0
  • email's home dir: /home/service0
  • email user's mail dir: /home/service0/mail

Important: The email user service0 does not have a ".forward" file. This user is only used for running the OpenACS website. Follow careful use of email rules by following strict guidelines to avoid email looping back unchecked.

For postfix, the email user and oacs user do not have to be the same. Furthermore, postfix makes distinctions between virtual users and user aliases .  Future versions of this documentation should use examples with different names to help distinguish between standard configuration examples  and the requirements of ACS Mail Lite package.

Postfix configuration parameters:


inet_interfaces=$myhostname, localhost


virtual_alias_domains  =

virtual_maps =regexp:/etc/postfix/virtual


Here is the sequence to follow if installing email service on system for first time. If your system already has email service, adapt these steps accordingly:

  1. Install postfix
  2. Install smtp (for postfix)
  3. Install metamail (for acs-mail-lite)
  4. Edit /etc/postfix/
  5. Edit /etc/postfix/virtual   Add a regular expression to filter relevant incoming emails for processing by OpenACS. service0
  6. Edit /etc/postfix/ - uncomment this line so postfix listens to emails from internet
    smtp inet n - n - - smtpd
  7. Create a mail directory as service0
    mkdir /home/service0/mail
  8. Configure ACS Mail Lite parameters
    BounceMailDir: /home/service0/mail
    EnvelopePrefix: bounce

    The EnvelopePrefix is for bounce e-mails only.

    NOTE: Parameters should be renamed: 
    BounceDomain to IncomingDomain
    BounceMailDir to IncomingMaildir
    EnvelopePrefix to BouncePrefix reflect that acs-mail-lite is capable of dealing with other types of incoming e-mail.

    Furthermore, setting IncomingMaildir parameter clarifies that incoming email handling is setup. This is useful for other packages to determine if they can rely on incoming e-mail working (e.g. to set the reply-to email to an  e-mail address which actually works through a callback if the IncomingMaildir parameter is enabled).
  9. Configure Notifications parameters
    EmailReplyAddressPrefix: notification
    EmailQmailQueueScanP: 0

    We want acs-mail-lite incoming handle the Email Scanning, not each package separately.
    Configure other packages likewise
  10. Invoke postmap in OS shell to recompile virtual db:
    postmap /etc/postfix/virtual
  11. Restart Postfix. 
    /etc/init.d/postfix restart
  12. Restart OpenACS


Processing incoming e-mail


A sweeper procedure like acs_mail_lite::load_mails  should:

  1. scan the e-mails which are in the IncomingMaildir directory on a regular basis.
  2. check if any email came from an auto mailer.
  3. Parse new ones, and
  4. process them by firing off callbacks.

Vinod has made a check for auto mailers by using procmail as follows. Maybe we could get this dragged into Tcl code (using regexp or a Procmail recipe parser) instead, thereby removing the need for setting up procmail in the first place.

Revised procmail filters:

:0 w * ^subject:.*Out of Office AutoReply /dev/null 
:0 w * ^subject:.*Out of Office /dev/null :0 w * ^subject:.*out of the office /dev/null 
:0 w * ^subject:.*NDN /dev/null :0 w * ^subject:.*[QuickML] Error: /dev/null 
:0 w * ^subject:.*autoreply /dev/null :0 w * ^from.*mailer.*daemon /dev/null

To make things granular a separate parsing procedure should deal with loading the e-mail into the Tcl interpreter and setting variables in an array for further processing.

ad_proc parse_email { 
} { 

An email is split into several parts: headers, bodies and files.

The headers consists of a list with header names as keys and their corresponding values. All keys are lower case.

The bodies consists of a list with two elements: content-type and content.

The files consists of a list with three elements: content-type, filename and content.

An array with all the above data is upvarred to the caller environment.

Processing an email should result in an array like this:


  • message_id
  • subject
  • from
  • to
  • date
  • received
  • references
  • in-reply-to
  • return-path
  • .....


  • X-Mozilla-Status
  • X-Virus Scanned
  • .....

We do not know which headers are going to be available in the e-mail. We set all headers found in the array. The callback implementation then checks if a certain header is present or not.

        #get all available headers
        set keys [mime::getheader $mime -names]
        set headers [list]

        # create both the headers array and all headers directly for the email array
        foreach header $keys {
            set value [mime::getheader $mime $header]
            set email([string tolower $header]) $value
            lappend headers [list $header $value]
        set email(headers) $headers


An e-mail usually consists of one or more bodies. With the advent of complex_send, OpenACS supports sending of multi-part e-mails which are needed if you want to send out and e-mail in text/html and text/plain (for old mail readers).

switch [mime::getproperty $part content] {
     "text/plain" {
          lappend bodies [list "text/plain" [mime::getbody $part]]
     "text/html" {
          lappend bodies [list "text/html" [mime::getbody $part]]


OpenACS supports tcllib mime functions. Getting incoming files to work is a matter of looking for a part where there exists a "Content-disposition" part. All these parts are file parts. Together with scanning for email bodies, code looks something like this:

        set bodies [list]
        set files [list]
        #now extract all parts (bodies/files) and fill the email array
        foreach part $all_parts {

            # Attachments have a "Content-disposition" part
            # Therefore we filter out if it is an attachment here
            if {[catch {mime::getheader $part Content-disposition}]} {
                switch [mime::getproperty $part content] {
                    "text/plain" {
                        lappend bodies [list "text/plain" [mime::getbody $part]]
                    "text/html" {
                        lappend bodies [list "text/html" [mime::getbody $part]]
            } else {
                set encoding [mime::getproperty $part encoding]
                set body [mime::getbody $part -decode]
                set content  $body
                set params [mime::getproperty $part params]
                if {[lindex $params 0] == "name"} {
                    set filename [lindex $params 1]
                } else {
                    set filename ""

                # Determine the content_type
                set content_type [mime::getproperty $part content]
                if {$content_type eq "application/octet-stream"} {
                    set content_type [ns_guesstype $filename]

                lappend files [list $content_type $encoding $filename $content]
        set email(bodies) $bodies
        set email(files) $files

Note that the files ie attachments are actually stored in the /tmp directory from where they can be processed further. It is up to the callback to decide if to import the file into OpenACS or not. Once all callbacks have been fired files in /tmp will have to be deleted again though.

Firing off callbacks 

Now that we have the e-mail parsed and have an array with all the information, we can fire off the callbacks. The firing should happen in two stages.

The first stage is where we support a syntax like "".

Second, incoming e-mail could look up the object_type, and then call the callback implementation specific to this object_type. If object_type = 'content_item', use content_type instead. 

ad_proc -public -callback acs_mail_lite::incoming_object_email { -array:required -object_id:required } { }

callback acs_mail_lite::incoming_object_email -impl $object_type -array email -object_id $object_id


ad_proc -public -callback acs_mail_lite::incoming_object_email -impl user {



} {

    Implementation of mail through support for incoming emails

} {

    # get a reference to the email array

    upvar $array email

 # make the bodies an array

        template::util::list_of_lists_to_array $email(bodies) email_body

        if {[exists_and_not_null email_body(text/html)]} {

            set body $email_body(text/html)

        } else {

            set body $email_body(text/plain)


        set reply_to_addr "[party::get_by_email $email(from)]@[ad_url]"

        acs_mail_lite::complex_send \

            -from_addr $from_addr \

            -reply_to $reply_to_addr \

            -to_addr $to_addr \

            -subject $email(subject) \

            -body $body \

            -single_email \



Object id based implementations are useful for automatically generating "reply-to" addresses. With ProjectManager and Contacts object_id is also handy, because Project / TaskID is prominently placed on the website. If you are working on a task and you get an e-mail by your client that is related to the task, just forward the email to "$" and it will be stored along with the task. Highly useful :).

Obviously you could have implementations for:

  • forums_forum_id: Start a new topic

  • forums_message_id: Reply to an existing topic

  • group_id: Send an e-mail to all group members

  • pm_project_id: add a comment to a project

  • pm_task_id: add a comment to a task and store the files in the projects folder (done)


Once the e-mail is dealt with in an object oriented approach we are either done with the message (an object_id was found in the to address) or we need to process it further.

ad_proc -public -callback acs_mail_lite::incoming_email {
} {
array set email {}
parse_email -file $msg -array email
set email(to) [parse_email_address -email $email(to)]
set email(from) [parse_email_address -email $email(from)]

# We execute all callbacks now
callback acs_mail_lite::incoming_email -array email

For this a general callback should exist which can deal with every leftover e-mail and each implementation will check if it wants to deal with this e-mail. How is this check going to happen? As an example, a package could have a prefix, as is the case with bounce e-mails as handled in acs_mail_lite::parse_bounce_address (see below):

ad_proc -public -callback acs_mail_lite::incoming_email -impl acs-mail-lite {
} {
    @param array        An array with all headers, files and bodies. To access the array you need to use upvar.
    @param package_id   The package instance that registered the prefix
    @return             nothing
} {
    upvar $array email

    set to [acs_mail_lite::parse_email_address -email $email(to)]
    ns_log Debug "acs_mail_lite::incoming_email -impl acs-mail-lite called. Recepient $to"

    util_unlist [acs_mail_lite::parse_bounce_address -bounce_address $to] user_id package_id signature
    # If no user_id found or signature invalid, ignore message
    # Here we decide not to deal with the message anymore

    if {[empty_string_p $user_id]} {
        if {[empty_string_p $user_id]} {
            ns_log Debug "acs_mail_lite::incoming_email impl acs-mail-lite: No equivalent user found for $to"
        } else {
            ns_log Debug "acs_mail_lite::incoming_email impl acs-mail-lite: Invalid mail signature $signature"
    } else {
        ns_log Debug "acs_mail_lite::incoming_email impl acs-mail-lite: Bounce checking $to, $user_id"
        if { ![acs_mail_lite::bouncing_user_p -user_id $user_id] } {
            ns_log Debug "acs_mail_lite::incoming_email impl acs-mail-lite: Bouncing email from user $user_id"
            # record the bounce in the database
            db_dml record_bounce {}
            if {![db_resultrows]} {
                db_dml insert_bounce {}

Alternatively we could just check the whole to address for other things, e.g. if the to address belongs to a group (party)

ad_proc -public -callback acs_mail_lite::incoming_email -impl contacts_group_mail {
    {-package_id ""}
} {
    Implementation of group support for incoming emails
    If the to address matches an address stored with a group then send out the email to all group members

     @author Malte Sussdorff (
     @creation-date 2005-12-18

     @param array        An array with all headers, files and bodies. To access the array you need to use upvar.
     @return             nothing
} {

    # get a reference to the email array
    upvar $array email

    # Now run the simplest mailing list of all
    set to_party_id [party::get_by_email -email $email(to)]
    if {[db_string group_p "select 1 from groups where group_id = :to_party_id" -default 0]} {
        # make the bodies an array
        template::util::list_of_lists_to_array $email(bodies) email_body
        if {[exists_and_not_null email_body(text/html)]} {
            set body $email_body(text/html)
        } else {
            set body $email_body(text/plain)
        acs_mail_lite::complex_send \
            -from_addr [lindex $email(from) 0] \
            -to_party_ids [group::get_members -group_id $to_party_id] \
            -subject $email(subject) \
            -body $body \
            -single_email \


Or check if the to address follows a certain format.

ad_proc -public -callback acs_mail_lite::incoming_email -impl contacts_mail_through {
    {-package_id ""}
} {
    Implementation of mail through support for incoming emails
    You can send an e-amil through the system by sending it to
    The email will be send from your system and if mail tracking is installed the e-mail will be tracked.

    This allows you to go in direct communication with a customer using you standard e-mail program instead of having to go to the website.

    @author Malte Sussdorff (
    @creation-date 2005-12-18
    @param array        An array with all headers, files and bodies. To access the array you need to use upvar.
    @return             nothing
} {
    # get a reference to the email array
    upvar $array email

    # Take a look if the email contains an email with a "#"
    set pot_email [lindex [split $email(to) "@"] 0]
    if {[string last "#" $pot_email] > -1} {

 Alternatives to this are:

  • ${component_name} (where component_name could be openacs or dotlrn or contacts or whatever), to store a new bug in bug-tracker
  • (to do mail-through using the user name, which allows you to hide the actual e-mail of the user whom you are contacting).


Once all callbacks have been fired off,  e-mails need to be deleted from the Maildir directory and files which have been extracted need to be deleted as well from the /tmp directory. 

E-Mail: Event Handling

Created by Dave Bauer, last modified by Gustaf Neumann 24 Aug 2020, at 01:43 PM

Sending email on certain events in OpenACS/.LRN is done very haphazardly. This needs to be rewritten so there is a simple way to figure out when an email will be sent, and allow proper handling of user preferences, administrative parameters, and customization.

There are cases where the system (OpenACS or .LRN) needs to send out email, for example, when a new user joins, requests a password reset, or is added to a subsite or .LRN community.

Right now there isn't any system-wide way to mange this email. In some cases, the administrator is notified an email will be sent and is given the option to edit the email before it is sent, but there is no one way this is done.  There are several pages that call  ns_sendmail explicitly, or acs_mail_lite::send explicitly. There are more places this happens in .LRN. Unfortunately there is also a "magic" place where email is sent that is totally unexpected. Inside the dotlrn_community::membership_approve procedure, there is a call to dotlrn_community::send_member_email, which will send an email to the user when the membership is approved, if 1) a parameter is set and 2) an administrator has created and enabled an email message to be sent.

 In addition there is a email sent using the "spam" package in dotlrn/www/admin/users-add-to-community where a dotlrn sitewide administrator can add users to a community, and the users are automatically emailed. In this case the administrator is not notified that an email is sent, or given an opportunity to customize or suppress the email. This causes problems when an administrator attempts to fix a problem by adding a user to a community automatically, and the user is sent a confusing message.

The dotlrn package allows for a custom email to get written by the community admin for each community, but the admin is not allowed to choose if the email is sent when an individual member is added. It is either on or off, always sent, or never sent.

dotlrn-ecommerce extends this by adding several more events for application submission, approval, rejection, etc. And admin can edit these emails on a sitewide or per community basis. In most cases the email is automatically sent, in one o r two cases the admin can edit the email, but not suppress it.

This leads to unwanted email. Often an admin must manually add or remove someone from a subsite or community or otherwise handle a problem. This can lead to welcome emails being sent at the wrong time, confusing the users. 

 A system wide solution would allow packages to create events where email is sent by the system (besides subscribed notifications). This solution would provide an includable interface for creating and editing a default email message for the events. It would also provide an interface to notify an admin that an email will be sent, giving options to suppress the email or edit the content of the email before sending it.

 The beginnings of this feature exist in the dotlrn_member_emails table, dotlrn_community::send_member_email procedure, and the dotlrn-ecommerce package which has a few pages that replicate this interface, but probably needs more generalization to allow working with subsites as well as dotlrn communities. There is also the reusable include for editing the default emails under dotlrn/lib/member-email

This proposal would provide a comprehensive solution for handling system level email events, allowing admins to know when an email is sent, and provide a consistent user interface to manage the emails.



You could achieve this in a general way by using the acs-lang interface at least for the subject and body. For each object_id you would create a new message key, e.g. acs-translations.welcome_email_subject_${object_id} and acs-translations.welcome_email_body_${object_id}. If you have multiple emails per community / subsite, you would rename them to acs-translations.confirmation_email_subject_${object_id} aso. A general interface would then be provided to look for all language key combinations of acs-translations.email_xxx, allowing you to edit the messages for all communities and subsites. If you want to edit them for only one, then you can look for all who have the same object_id. 

A default message would be given with acs-translations.email_subject_welcome, which the mail sending could default to in case no specific language key exists for the community / object_id. Furthermore, acs-translations.welcome_email_help message key is present describing what this email is about. A package like dotlrn would register the three default e-mail keys to start off with this and then the email-handling package can do the rest (e.g. with email-handler::send -to_party_ids -from_addr -email_type "welcome" -object_id).

This approach has the major advantage that you have internationalization by default.

Alternatively you could mimic the message handling done by contacts which allows you to have multiple message types, e.g. email, which you can fill in with default values, which has it's own I18N by having a locale stored in the DB table. But if you ask me, the acs-translations idea sounds better to me :). Though, you can obviously do this with your own tables as well, but you would loose on the nice features acs-lang has to offer.


 Files that currently could trigger email

add_user calls add_user_to_community

add_user_to_community calls membership_approve (if applicable). membership_approve calls send_member_email unconditionaly

so any call to add_user or add_user_to_community could result in a call to send_member_email





Next Page
previous December 2020
Sun Mon Tue Wed Thu Fri Sat
29 30 1 2 3 4 5
6 7 8 9 10 11 12
13 14 15 16 17 18 19
20 21 22 23 24 25 26
27 28 29 30 31 1 2

Popular tags

17 , 5.10.0 , 5.9.0 , 5.9.1 , ad_form , ADP , ajax , aolserver , asynchronous , bgdelivery , bootstrap , bugtracker , CentOS , COMET , compatibility , CSP , CSRF , cvs , debian , emacs , engineering-standards , exec , fedora , FreeBSD , guidelines , host-node-map , hstore , includelets , install , installation
No registered users in community xowiki
in last 30 minutes