Delegation and Permissions

Separation of Logic and Interface

Excellent user and group management

Open source, transparent development

Availability of packages

Full featured API

Full featured documentation

Multi-lingual and internationalized
 

How to get help and find the information you need.

• First of all, try to track down documentation for what you're looking for. The first place to look is in the official OpenACS documentation. Familiarize yourself with this documentation, especially the API browser, which shows you all the commands you can run. Look at the package documentation (and note that sadly, some of the packages don't have documentation). Notice that there is documentation not just for getting installed, but also for developing an OpenACS package.
• Second, try searching on Google. Try your search, but include the word OpenACS in the query. This finds answers a surprisingly high amount of the time.
• Third, look through the forums. Use the search functionality to try and find what you're looking for.
• Fourth, look through the websites listed below. These are websites set up by OpenACS hackers as documentation and how-to guides:
  • Jade Rubick's documentation for OpenACS
  • more soon.
• Fifth, if your question is a quick one, then try asking on the OpenACS IRC channel.
• Sixth, try asking your question on the OpenACS forums. Make sure you clearly describe what your problem is, what version of OpenACS you're using, what you did before and after the problem, and what the error message is. Show relevant portions of your error log. If you want people to be helpful and take their time on your question, make sure you take the time to ask the question in a way that someone can give you a meaningful answer.
• See below for more helpful resources

Introductions to OpenACS

• OpenACS official documentation
• OpenACS: It's complicated, it's not finished--is it worth your time? Absolutely. an introduction to OpenACS. - ignore the installation portion.
• OpenACS package system
• An intro to OpenACS templating describes how to make webpages.
• OpenACS performance and scalability - how does OpenACS compare to other toolkits like Zope?
• Ben Koot's Demo Site is a place where you can check out a lot of the packages available for OpenACS. Keep in mind that many of these packages are deprecated, or may not be the most recent version. Don't necessarily assume this is the latest and greatest. But it is a good place to check out a lot of the functionality of OpenACS packages.

Helping out with OpenACS

• How to get started as a worker bee for OpenACS. This describes how you can contribute if you have time and want to learn more about OpenACS by helping out with simple tasks to improve the toolkit

History of OpenACS

• ACS, as described in the Panda book
• History of OpenACS
• Eve Anderson's info on the old ACS, which OpenACS was based on.
• Archives on ACS era postings

Confronting the learning curve

Participating in an Open Source Community

Your toolkit

Resources and References
 

Steal from my getting started article a little?

This page describes how I am upgrading an ACS 3.4.10 Oracle installation to a OpenACS 4.6.2 Postgres installation.

Here are some other webpages to look at:

http://jongriffin.com/static/openacs/acs-conversion/upgrade
http://openacs.org/faq/one-faq?faq_id=43841
http://openacs.org/doc/openacs-3/html/oracle-to-pg-porting.html
http://grumet.net/random/mikes-migration-guide/
Ola's posting on upgrading OpenACS 3 to 4
Using two databases with OpenACS
Sloan's upgrade scripts -- woohoo! Even better, Sloan's scripts that upgraded their 3.4 installation to OpenACS 4.0! (See this link also: thread announcing file upload. This is how I would do things if I could go back and do it again

 

Note on sequence caching

When you're doing any sort of migration, apparently getting the next sequence values is one of the more expensive operations you'll do. To speed things up considerably, you can cache your sequence values. Both Oracle and Postgres let you do this. (caching sequences in postgres)

Upgrading users

What I'm doing is set up a table that contains the old and new user_ids (so I can map the old values to the new values). It's nothing complicated, just a table with the old value and the new value. I call it upgrade-user-map. Then there is a little utility function which you can use to get the new user_id when you're importing the data. set new_user_id [upgrade_user_id $old_user_id] will do it.

/sql/postgresql/upgrade-user-map-create.sql

--
-- packages/upgrade-user-map-create/sql/postgresql/upgrade-user-map-create.sql
--
-- @author jader@bread.com
-- @creation-date 2003-03-21
-- @cvs-id $Id: upgrade-user-map-create.sql,v 1.1 2003/03/21 22:49:01 oacs Exp $
--

create table upgrade_user_map (
    old_id                 integer
                           constraint upgrade_user_map_old_id_nn
                           not null,
    new_id                 integer
                           constraint upgrade_user_map_new_id_fk
                           references users(user_id)
);

/sql/postgresql/upgrade-user-map-drop.sql

drop table upgrade_user_map;

/tcl/upgrade-user-map-procs.tcl

# /packages/upgrade-user-map/tcl/upgrade-user-map-procs.tcl

ad_library {

    Procs for upgrade of users, and for upgrade for ACS 3.4 intranet

    @author Jade Rubick (jader@bread.com)
    @creation-date 2003-03-31
    @cvs-id $Id$
}

ad_proc -public upgrade_user_id {
    old_user_id
} {
    returns the new user id when given the old
} {
    set user_id [db_string get_new_user_id {
        SELECT
        u.user_id
        FROM 
        users u,
        upgrade_user_map um
        WHERE
        u.user_id = um.new_id and
        um.old_id = :old_user_id
    } -default "0"]

    return $user_id
}

Port common functions

Another thing to do to make the transition easier is to port some common functions over from ACS 3.4. They can be marked as deprecated, so that as you work on your packages in the future, you can gradually move to a more pure OpenACS model. I put these inside the upgrade_user_map package, /tcl/upgrade-user-map-procs.tcl file. Then all packages that I port to OpenACS will have a dependency on the upgrade-user-map package. This will make it easy to keep track of which packages depend on these functions, and I can explicitly go through later and remove than dependency. Note that these functions depend on acs-tcl, which I believe is going to be removed from OpenACS eventually. More work later!

Here are a list of functions I ported into OpenACS:

• im_header
• im_footer
• im_return_template

Ported functions

im_header

ad_proc -public -deprecated im_header {
    {-page_title ""}
    {-page_focus ""}
    {-context_bar ""}
    {-extra_stuff_for_document_head ""}
} {
    Shows page headers for a legacy page ported from an ACS 3.4 installation
} {
return "
[ad_header -focus $page_focus $page_title $extra_stuff_for_document_head]
<font size=4><b>$page_title</b></font>
<br><font size=2>$context_bar</font>
<hr>
<link rel=\"stylesheet\" href=\"/style.css\" type=\"text/css\">
"
}

im_footer

ad_proc -public -deprecated im_footer {
} {
    Shows the footer for the legacy page ported from an ACS 3.4 installation
} {
    return " <hr><font size=-2>
Integrated Bakery Resources ©2003
<a href=/register/logout>log out</a>
</font>"
}

im_return_template

ad_proc -public -deprecated im_return_template {
} {
    Returns a legacy page ported from an ACS 3.4 installation
} {
    uplevel { 
        return "
        [im_header -page_title [value_if_exists page_title] -page_focus [value_if_exists page_focus] -context_bar [value_if_exists context_bar] -extra_stuff_for_document_head [value_if_exists extra_stuff_for_document_head]]
        [value_if_exists page_body]
        [value_if_exists page_content]
        [im_footer]
        "
    }
}

Checklist of things to check for in each ported file

• Use new data model
• Add in permissions

Exporting data from ACS 3.4

The approach I use is easy, but maybe not as elegant as you might like. I export each table to a file, and then import that file into Postgres. Another way you could do this is to define an extra database pool. I'm not sure if this would work with a different database, however.

I am creating an export script for every table I need from the old Intranet, and an import script for every table in the new Intranet. This will be easiest for my own custom packages -- much more difficult for things like the projects and user_groups tables in ACS 3.4.10. I haven't quite solved that problem yet.

The export scripts looks something like this:

# /packages/packagename/www/upgrade/export.tcl

ad_page_contract {
    page which exports the packagename table

    @author jader@bread.com
    @cvs-id $Id$
    @creation-date 3/14/03

} {
}

ns_write "<html><table>"

set file_stream [open /tmp/packagename.export w]

db_foreach get_brand "
...
" {
     puts $file_stream "@%@%@<oneitem>$oneitemvalue</oneitem>..."

     ns_write "<tr><td>$oneitemvalue</td>..."
}

close $file_stream

ns_write "</table></html>"


----------

One caveat: this works as long as the amount of data shown on your page does not overwhelm your browser. This is not a very robust solution. You don't have to display everything out to the browser after you've debugged it. Take out the portion with the ns_write inside the db_foreach statement. Also, make sure you use a browser that doesn't timeout within 60 seconds, like the version of Safari I'm currently using.

Another thing I did with the export scripts is at the bottom of each script, I redirect to the next export script. Add this before the </html>:

<meta HTTP-EQUIV=\"REFRESH\" CONTENT=\"3;URL=http://path/to/next/upgrade/export\">

Importing into OpenACS

The import script (unfinished) looks like this so far:

# /packages/packagename/www/upgrade/import.tcl

ad_page_contract {
    page which imports the packagename table

    @author jader@bread.com
    @cvs-id $Id$
    @creation-date 3/14/03

} {
}


set file_stream [open /tmp/packagename.export r]

set the_whole_file [read -nonewline $file_stream]

close $file_stream

set list_of_lines [split $the_whole_file "@%@%@"]

ns_write "<html><table border=1 cellspacing=0>"

db_dml delete_all "delete from packagename"

# determine highest value for sequence
set highest_seq_value -1

foreach line $list_of_lines {

    if {[exists_and_not_null line]} {
        regexp {<oneitem>(.*)</oneitem>} $line match oneitem

        ns_write "
        <tr>
        <td>$oneitem

        if {$index_value > $highest_seq_value} {
            set highest_seq_value $index_value
        }

        # get the user_id from a user_map table
        set user_id [db_string get_user_id xxxxxxx]

        db_exec_plsql new_packagetablename "
        select packagename__new(...)"
    }
}

Other references

From Mike Bonnet and Andrew Grummet's migration page, I stole this script for Oracle, which shows you the references to any given table. This really helps in deciding which item to port when:

select (select table_name || '.' || column_name from user_cons_columns where constraint_name = uc.constraint_name) 
              || ' references ' ||
             (select table_name || '.' || column_name from user_cons_columns where constraint_name = uc.r_constraint_name) as references
        from user_constraints uc 
       where constraint_type = 'R' 
        and table_name = upper('&table_name')

select (select table_name || '.' || column_name from user_cons_columns where constraint_name = uc.r_constraint_name) 
              || ' is referenced by ' ||
             (select table_name || '.' || column_name from user_cons_columns where constraint_name = uc.constraint_name) as referenced_by
        from user_constraints uc 
       where constraint_type = 'R' 
        and r_constraint_name in (select constraint_name from user_constraints where table_name = upper('&table_name'));

An earlier version of this document is at: http://openacs.org/forums/message-view?message_id=88229.

HOWTO - Virtual Hosting in AOLserver original URL

 

Virtual Hosting in AOLserver

how to host multiple ACS/OpenACS installations with one static IP

---

acs-service-contract is a package that "allows different packages to communicate via defined contracts". Essential, it defines an interface so that different packages can communicate with each other in a structured way.

Understanding how service contracts work

The best guide I've found on service contracts is Benjamin Bytheway's intro to service contracts. It currently uses the pl/pgsql API, instead of the newer Tcl API. However, this will give you an idea of what is going on, so that you can figure out the Tcl API. More information on the Tcl API is found here

Creating your service contract

Benjamin's tutorial describes using the pl/pgsql API. This would be defined in your .sql files, and instantiated when the package was initially installed by the APM. This would be easy enough, but we want to use the Tcl API, for two reasons:

• it is easier to use
• it is database neutral, so it works for both Oracle and PostgreSQL. This eases porting in the future.

Where, then, do you define the workflow when using Tcl?

One of the features in OpenACS that have been added fairly recently has been the ability to have Tcl functions called before and after the install of your package. I believe this is probably the best way to do it.

So, you should look at install-procs.tcl file (and possibly the install-procs.xql and install-procs-postgresql.xql files). This is a little confusing, but I'll spell it out in more detail:

The install-procs.tcl file is looked at when the package is first installed (my guess is that the name is hard-coded in as something for the APM to look at). There are several procedures that if defined are called at specified times. These are package_install, package_uninstall, package_upgrade, package_instantiate, and package_uninstantiate. There may be others as well. I haven't found any documentation for this, but I looked at the bug-tracker and gleaned this from there.

Here is an example of a service contract (stolen from bug-tracker):

...

ad_proc -private bug_tracker::install::package_install {} {
    Package installation callback proc
} {
    db_transaction {
        bug_tracker::install::register_implementations
        bug_tracker::bug::workflow_create
    }
}

ad_proc -private bug_tracker::install::package_uninstall {} {
    Package un-installation callback proc
} {
    db_transaction {
        bug_tracker::bug::workflow_delete
        bug_tracker::install::unregister_implementations
    }
}

ad_proc -private bug_tracker::install::package_instantiate {
    {-package_id:required}
} {
    Package instantiation callback proc
} {
    # Create the project
    bug_tracker::project_new $package_id

    bug_tracker::bug::instance_workflow_create -package_id $package_id
}

ad_proc -private bug_tracker::install::package_uninstantiate {
    {-package_id:required}
} {
    Package un-instantiation callback proc
} {

    bug_tracker::project_delete $package_id
    bug_tracker::bug::instance_workflow_delete -package_id $package_id

}

ad_proc -private bug_tracker::install::register_implementations {} {
    db_transaction {
        bug_tracker::install::register_format_log_title_impl
        ...
    }
}

ad_proc -private bug_tracker::install::register_format_log_title_impl {} {

    set spec {
        name "FormatLogTitle"
        aliases {
            GetObjectType bug_tracker::bug::object_type
            GetPrettyName bug_tracker::bug::format_log_title::pretty_name
            GetTitle      bug_tracker::bug::format_log_title::format_log_title
        }
    }
    
    lappend spec contract_name [workflow::service_contract::activity_log_format_title]
    lappend spec owner [bug_tracker::package_key]
    
    acs_sc::impl::new_from_spec -spec $spec
}

ad_proc -private bug_tracker::install::unregister_implementations {} {
    db_transaction {

        acs_sc::impl::delete \
                -contract_name [workflow::service_contract::activity_log_format_title] \
                -impl_name "FormatLogTitle"

    ...
}

Reference

• You can see the latest code via the CVS browser, at http://cvs.openacs.org/cvs/openacs-4/packages/acs-service-contract/.
• There is also some limited documentation on acs-service-contract.
• post asking about creating a service contract for ecommerce
• this thread contains suggestions on other code using service contracts that can be used as examples.

Adding Workflow to an OpenACS package

I'm trying to add Workflow to the project-manager I'm writing (in collaboration with other OpenACS programmers), so I thought I might as well document what needs to be done, so others can learn from my hard knocks.

Why use workflow, and for that matter, what is workflow?

Lars, the author of the workflow package, defines workflow like this: "[Workflow] provides a service to keep track of a process involving multiple people around some object. Workflow keeps track of the process you wish to follow, of where you currently are in the process (the current state), and who's supposed to do what.

I must confess that I've been awfully tempted not to use workflow. There seems to be quite a learning curve, and it's much easier to duplicate the functionality of workflow doing it your own way. However, several programmers with much more experience than I insist that it is really the way to do things. So if you have a choice, they would recommend using workflow. I'll reserve judgement until I figure out enough to see if it was worth the effort or not.

Documentation

Lars, the uber-programmer who created Workflow, fortunately wrote a lot of documentation for Workflow.

• Documentation on Workflow click on download next to the most recent version of the documentation.
• Developers guide for workflow you will have to click on this link instead of the link in the index.html document. The link doesn't go to the most recent version of the document, which will deprive you of the rest of the document!
• You also really need to look at the source code for both Workflow and bug-tracker.
• A powerpoint presentation on adding workflow

 

project-manager: before workflow

Here is what the application looked like before adding in workflow. I know there are problems with this code, and I don't recommend using it as a basis for your own coding. However, if will give you an idea of what changed. This code is pretty basic. It allows you to add and edit projects, and there is a page for viewing them as well.

project-manager-create.sql

--
-- packages/project-manager/sql/postgresql/project-manager-create.sql
--
-- @author jade@bread.com
-- @creation-date 2003-05-15
-- @cvs-id $Id: project-manager-create.sql,v 1.1 2003/05/15 21:52:31 oacs Exp $
--
--

\i project-manager-table-create.sql
\i project-manager-functions-create.sql

project-manager-table-create.sql

-- TODO:
-- 
-- which items in this data model need to use the content repository?
-- need to add in workflow (for status among other things)
-- need to take into account acs-rels
-- add categories to projects

--
-- packages/project-manager/sql/postgresql/project-manager-table-create.sql
--
-- @author jader@bread.com and everyone else involved in this thread: http://ope
nacs.org/forums/message-view?message_id=90742
-- @creation-date 2003-05-15
--

create table pm_project (
        project_id              integer
                                constraint project_manager_id_fk
                                references acs_objects(object_id) 
                                constraint pm_project_id_pk
                                primary key,
        project_name            varchar(255) 
                                constraint pm_project_name_nn
                                not null,
        -- a user-specified
        project_code            varchar(255),
        -- for subprojects
        parent_project_id       integer
                                constraint pm_project_parent_project_id_fk
                                references pm_project,
        goal                    varchar(4000),
        description             varchar(4000),
        -- is the deadline computed from the end date, or from 
        -- today?
        -- e = end, t = today
        deadline_scheduling     char(1) default 't'
                                constraint pm_project_dline_scheduling_ck
                                check (deadline_scheduling in ('t','e')),
        planned_start_date      timestamptz,
        planned_end_date        timestamptz,
        actual_start_date       timestamptz,
        actual_end_date         timestamptz,
        ongoing_p               char(1) default 'f' 
                                constraint pm_project_ongoing_p_ck
                                check (ongoing_p in ('t','f'))
);


create function inline_0 ()
returns integer as '
begin
    PERFORM acs_object_type__create_type (
        ''pm_project'',                         -- object_type
        ''Project'',                            -- pretty_name
        ''Projects'',                           -- pretty_plural
        ''acs_object'',                         -- supertype
        ''pm_project'',                         -- table_name
        ''project_id'',                         -- id_column
        null,                                   -- package_name
        ''f'',                                  -- abstract_p
        null,                                   -- type_extension_table
        ''pm_project__name''                    -- name_method
        );
    return 0;
end;' language 'plpgsql';
select inline_0 ();
drop function inline_0 ();

project-manager-functions-create.sql

--
-- packages/project-manager/sql/postgresql/project-manager-functions-create.sql
--
-- @author jade@bread.com
-- @creation-date 2003-05-15
-- @cvs-id $Id: project-manager-functions-create.sql,v 1.1 2003/05/15 21:52:31 o
acs Exp $
--
--

select define_function_args('pm_project__new','project_id,project_name,project_c
ode,parent_project_id,goal,description,deadline_scheduling,planned_start_date,pl
anned_end_date,actual_start_date,actual_end_date,ongoing_p,creation_date,creatio
n_user,creation_ip,context_id'); 

create or replace function pm_project__new (integer,varchar,varchar,integer,varc
har,varchar,char(1),timestamptz,timestamptz,timestamptz,timestamptz,char(1),time
stamptz,integer,varchar,integer)
returns integer as '
declare
  p_project_id                                  alias for $1;
  p_project_name                                alias for $2;
  p_project_code                                alias for $3;
  p_parent_project_id                           alias for $4;
  p_goal                                        alias for $5;
  p_description                                 alias for $6;
  p_deadline_scheduling                         alias for $7;
  p_planned_start_date                          alias for $8;
  p_planned_end_date                            alias for $9;
  p_actual_start_date                           alias for $10;
  p_actual_end_date                             alias for $11;
  p_ongoing_p                                   alias for $12;
  p_creation_date                               alias for $13;
  p_creation_user                               alias for $14;
  p_creation_ip                                 alias for $15;
  p_context_id                                  alias for $16;
  v_pm_project_id                               int;
begin
        v_pm_project_id := acs_object__new (
                p_project_id,
                ''pm_project'',
                p_creation_date,
                p_creation_user,
                p_creation_ip,
                p_context_id
        );
        insert into pm_project
          (project_id,project_name,project_code,parent_project_id,goal,descripti
on,deadline_scheduling,planned_start_date,planned_end_date,actual_start_date,act
ual_end_date,ongoing_p) 
        values
          (v_pm_project_id, p_project_name, p_project_code, p_parent_project_id,
 p_goal, p_description, p_deadline_scheduling, p_planned_start_date, p_planned_e
nd_date, p_actual_start_date, p_actual_end_date, p_ongoing_p);
        PERFORM acs_permission__grant_permission(
          v_pm_project_id,
          p_creation_user,
          ''admin''
    );
        return v_pm_project_id;
end;' language 'plpgsql';
/* The __delete function deletes a record and all related overhead. */
  

select define_function_args('pm_project___delete','project_id');
create or replace function pm_project__delete (integer)
returns integer as '
declare
  p_pm_project_id                               alias for $1;
begin
    delete from acs_permissions
                   where object_id = p_pm_project_id;
        delete from pm_project
                   where project_id = p_pm_project_id;
        raise NOTICE ''Deleting pm_project...'';
        PERFORM acs_object__delete(p_pm_project_id);
        return 0;
end;' language 'plpgsql';
/* When we created the acs object type above, we specified a
'name_method'.  This is the name of a function that will return the
name of the object.  This is a convention ensuring that all objects
can be identified.  Now we have to build that function.  In this case,
we'll return a field called title as the name. */

select define_function_args('pm_project___name','project_id');

create or replace function pm_project__name (integer)
returns varchar as '
declare
    p_pm_project_id      alias for $1;
    v_pm_project_name    pm_project.project_name%TYPE;
begin
        select project_name into v_pm_project_name
                from pm_project
                where project_id = p_pm_project_id;
    return v_pm_project_name;
end;
' language 'plpgsql';

project-manager-drop

-- packages/project-manager/sql/project-manager-drop.sql
-- drop script
--
-- @author jade@bread.com
-- @creation-date 2003-05-15
-- @cvs-id $Id: project-manager-drop.sql,v 1.1 2003/05/15 21:52:31 oacs Exp $
--

--drop package, which drops all functions created with define_function_args

select drop_package('pm_project');

--drop permissions
delete from acs_permissions where object_id in (select project_id from pm_projec
t);

--drop objects
create function inline_0 ()
returns integer as '
declare
        object_rec              record;
begin
        for object_rec in select object_id from acs_objects where object_type=''
pm_project''
        loop
                perform acs_object__delete( object_rec.object_id );
        end loop;
        return 0;
end;' language 'plpgsql';

select inline_0();
drop function inline_0();

--drop table
drop table pm_project;

--drop type
select acs_object_type__drop_type(
           'pm_project',
           't'
    );

index.tcl

ad_page_contract {
    Main view page for projects.

    @author jader@bread.com
    @creation-date 2003-05-15
    @cvs-id $Id: index.tcl,v 1.3 2003/05/16 22:23:58 oacs Exp $
    @param orderby indicates when the user clicks on a column to order by that \
column
    @return table_html preformatting html table constructed by querying the sam\
plenotes table

} {
    {orderby:optional {title}}
} -properties {
    table_html
}
# define the columns in the table
set table_def   {
    {edit "" {} {<td><a href="add-edit?project_id=$project_id">Edit</a></td>}}
    {view "" {} {<td><a href="one?project_id=$project_id">View</a></td>}}
    {project_name "Name"}
    {project_code "Project code"}
    {parent_project_id "Parent project"}
    {goal "Goal"}
    {description "Description"}
    {planned_start_date "Start date (planned)"}
    {planned_end_date "End date (planned)"}
    {ongoing_p "Ongoing?"}
}

# construct an html table from the samplenotes database table
set table_html [ad_table -Torderby $orderby project_query {} $table_def]

index.adp

<master>
<property name="title">Projects</property>
@table_html@
<p><a href="add-edit">Add a project</a></p>

index.xql

<?xml version="1.0"?>
<queryset>
  <fullquery name="project_query">
    <querytext>
        SELECT
        project_id,
        project_name,
        project_code,
        parent_project_id,
        goal,
        description,
        deadline_scheduling,
        to_char(planned_start_date,'YYYY MM DD') as planned_start_date,
        to_char(planned_end_date,'YYYY MM DD') as planned_end_date,
        ongoing_p
        FROM
        pm_project
    [ad_order_by_from_sort_spec $orderby $table_def]
    </querytext>
  </fullquery>
</queryset>

add-edit.tcl

ad_page_contract {
    Simple add/edit form for projects
} {
    project_id:integer,optional
    {planned_start_date ""}
    {planned_end_date ""}
} -properties {
    context_bar:onevalue
    title:onevalue
}


set user_id [ad_maybe_redirect_for_registration]

set package_id [ad_conn package_id]

if {[exists_and_not_null project_id]} {
    set title "Edit a project"
    set context_bar [ad_context_bar "Edit Project"]
} else {
    set title "Add a project"
    set context_bar [ad_context_bar "New Project"]
}


ad_form -name add_edit -form {
    project_id:key

    {project_name:text
        {label "Project name"}
    }

    {project_code:text
        {label "Project code"}
    }

    {parent_project_id:text(hidden)
        {value ""}}

    {goal:text(textarea)
        {label "Project goal"}
        {optional}
        {html { rows 5 cols 40 wrap soft}}}

    {description:text(textarea)
        {label "Description"}
        {optional}
        {html { rows 5 cols 40 wrap soft}}}

    {deadline_scheduling:text(select)
        {label "Scheduling"}
        {options {{"From today" "t"} {"From deadline" "e"}} {value $deadline_scheduling}} }

    {planned_start_date:date {value {[util::date acquire clock [clock scan $planned_start_date]]}} optional
        {label "Planned start date"}
        {format "MONTH DD YYYY"}
        {help}
    }

    {planned_end_date:date {value {[util::date acquire clock [clock scan $planned_end_date]]}} optional
        {label "Planned end date"}
        {format "MONTH DD YYYY"}
        {help}
    }

    {ongoing_p:text(select)
        {label "Project is ongoing?"}
        {options {{"Yes" "t"} {"No" "f"}} {value $ongoing_p}} }

} -select_query_name project_query -on_submit {

    set user_id [ad_conn user_id]
    set peeraddr [ad_conn peeraddr]

} -new_data {
    db_exec_plsql do_insert { *SQL* }

    ad_returnredirect "."
    ad_script_abort

} -edit_data {

    db_dml do_update { *SQL* }

} -after_submit {

    ad_returnredirect "index"
    ad_script_abort
}

add-edit.adp

<master>
<property name="context_bar">@context_bar@</property>
<property name="title">@title@</property>

<center>
<formtemplate id="add_edit" style="plain-ibr"></formtemplate>
</center>

add-edit.xql

<?xml version="1.0"?>
<queryset>
  <fullquery name="do_insert">
    <querytext>
        select pm_project__new(
        :project_id, 
        :project_name,
        :project_code,
        :parent_project_id,
        :goal,
        :description,
        :deadline_scheduling,
        to_timestamp(:planned_start_date,'YYYY MM DD HH24 MI SS'),
        to_timestamp(:planned_end_date,'YYYY MM DD HH24 MI SS'),
        null,
        null,
        :ongoing_p,
        now(),
        :user_id,
        :peeraddr,
        :package_id);
    </querytext>
  </fullquery>

  <fullquery name="do_update">
    <querytext>
        UPDATE
        pm_project
        SET 
                project_name            = :project_name,
                project_code            = :project_code,
                parent_project_id       = :parent_project_id,
                goal                    = :goal,
                description             = :description,
                deadline_scheduling     = :deadline_scheduling,
                planned_start_date      = to_timestamp(:planned_start_date,'YYYY MM DD HH24 MI SS'),
                planned_end_date        = to_timestamp(:planned_end_date,'YYYY MM DD HH24 MI SS'),
                ongoing_p               = :ongoing_p
        WHERE
                project_id = :project_id
    </querytext>
  </fullquery>

  <fullquery name="project_query">
    <querytext>
      select
        project_id,
        project_name,
        project_code,
        parent_project_id,
        goal,
        description,
        deadline_scheduling,
        to_char(planned_start_date,'YYYY MM DD') as planned_start_date,
        to_char(planned_end_date,'YYYY MM DD') as planned_end_date,
        ongoing_p
        FROM
        pm_project
       where project_id = :project_id
    </querytext>
  </fullquery>
</queryset>

Adding in workflow

Lars describes a six step process to getting Workflow into your application:

1. Define your default process. The idea typically is to allow your end users to modify the process to suit their needs, but you'll want to provide a process which they can use as a starting point.
2. Identify, declare, and implement the callbacks that your application will need.
3. Write the code to set up the initial process, and to clone that process for each package instance.
4. Integrate workflow support into your application's API.
5. Integrate workflow support into your application's user interface.
6. Integrate workflow into your application's queries

Step 1: Define your default process

What does it mean to define your default process? In my understanding, this is to define three things:

• roles - who are the actors in your application
• states - what are the valid states for this object
• actions - what are valid actions on this object

So let's do that for the project-manager:

Roles for projects

• creater
• participant
• manager
• client_representative

States for projects

• open
• closed

Actions for projects

• create
• close
• reopen
• edit

project-procs.tcl

After this, we're supposed to define our workflow. The definition file goes in /tcl/project-procs.tcl. You'll need to copy a lot of the files from bug-tracker.

namespace eval project_manager::project {}

ad_proc -private project_manager::project::workflow_create {} {
    Create the 'project' workflow for project-manager
} {
    set spec {
        project {
            pretty_name "Project"
            package_key "project-manager"
            object_type "pm_project"
            callbacks { 
                # leave these blank for now
                # bug-tracker.FormatLogTitle 
                # bug-tracker.BugNotificationInfo
            }
            roles {
                participant {
                    pretty_name "Participant"
                    callbacks { 
                        # leave these blank for now
                        # workflow.Role_DefaultAssignees_CreationUser
                    }
                }
                manager {
                    pretty_name "Manager"
                    callbacks { 
                        # leave these blank for now
                        # workflow.Role_DefaultAssignees_CreationUser
                    }
                }
                client_representative {
                    pretty_name "Client representative"
                    callbacks {
                        # bug-tracker.ComponentMaintainer
                        # bug-tracker.ProjectMaintainer
                        # workflow.Role_PickList_CurrentAssignees
                        # workflow.Role_AssigneeSubquery_RegisteredUsers
                    }
                }
            }
            states {
                open {
                    pretty_name "Open"
                    # hide_fields { resolution fixed_in_version }
                }
                closed {
                    pretty_name "Closed"
                }
            }
            actions {
                create {
                    pretty_name "Create"
                    pretty_past_tense "Created"
                    new_state "open"
                    initial_action_p t
                }
                edit {
                    pretty_name "Edit"
                    pretty_past_tense "Edited"
                    privileges { write }
                    always_enabled_p t
                    edit_fields { 
                        # not sure what to do here
                        #component_id 
                        #summary 
                        #found_in_version
                        #role_assignee
                        #fix_for_version
                        #resolution 
                        #fixed_in_version 
                    }
                }
                close {
                    pretty_name "Close"
                    pretty_past_tense "Closed"
                    # what is this doing?
                    assigned_role "submitter"
                    assigned_states { resolved }
                    new_state "closed"
                    privileges { write }
                }
                reopen {
                    pretty_name "Reopen"
                    pretty_past_tense "Reopened"
                    enabled_states { resolved closed }
                    new_state "open"
                    privileges { write }
                }
            }
        }
    }

    set workflow_id [workflow::fsm::new_from_spec -spec $spec]
    
    return $workflow_id
}

Acceptance test

At this point, we probably should check to make sure that what we've done is correct. I have no clue as to how to do that.

Step two: callbacks service contracts

We now need to work to identify, declare, and implement the callbacks that our application will need. Why would we want to do this? These callbacks are functions that can do things like determine default assignees based on certain data in your application, get information about your application's object for use when sending out notifications, or perform "side-effects", such as actually changing the publication state of a content item when you execute the [Publish] action.

So, how do you go about adding in the callbacks? Well, first of all, you better make sure you understand how acs-service-contracts work.

See my page on acs-service-contracts for a background on this. Don't skip this unless you already are comfortable with acs-service-contracts.

We add in an /tcl/install-procs.tcl file. I simply copied it over from bug-tracker, which is probably the best example to use for Workflow code.

The point I'm currently confused on is how to choose what service contracts to implement. Help?

---

If the namespace portion looks confusing, then see my namespace page.

 

Welcome to the OpenACS community

This is my collection of links and resources for people that are getting started with OpenACS. But before we get started, I'd like to share some thoughts on how to best get information and get up to speed with OpenACS.

I think the first thing to realize about OpenACS is that it is not just a technology, it is a vibrant open-source community. The operative word here is community. You are coming into this community as a newbee, or a new person. The OpenACS folks are extremely helpful, more so than any other technical group I've seen. However, you should think about what your resources are for getting information.

The way communities work is very similar to the way a bank account works. You make deposits by doing things that are beneficial to the community, and you make withdrawals by doing things that take the time and energy of the community. The more helpful you are, the more people are going to be willing to help you out. If you have a pattern of being demanding and unhelpful, people aren't going to help you out as much. This isn't malicious, it's just the way people work in general.

What you have to offer?

First of all, let's look at what you have to offer the community. You're new, so you can't offer much in the way of technical knowledge. However, you do have things to offer you can trade for detailed technical help from more knowledgeable individuals:

• If there is no documentation for what you're trying to do, then the single most helpful thing you can do is write documenation as you learn. That's what I've done in my OpenACS articles. I use it both to keep track of what I've learned for my own reference, and as a way of sharing that with others. But it is also something I can trade for the time of more experienced developers. They know that if they help me out, I'll write up documentation for it, and they might not have to answer that question again.
• As you find bugs, you can file them in the OpenACS bug-tracker.
• If you have a particular project in mind, or something you're planning on creating, then building that project and sharing it with the community is good incentive for people to help you. They may be interested in what you're building.
• When a newer newbee asks a question you know the answer to, answer it!
• As a newcomer, you have a unique perspective to OpenACS. You can often see deficiencies and areas to improve that old-timers might not even notice. Feel free to bring them up as suggestions. Remember that the OpenACS community is a community, not a company. It isn't their responsibility to fix things for you, or make them better. But it is often in their self-interest to improve things, and they will. Flames won't get you anywhere, but thoughtful suggestions will.
• Even though you aren't proficient with OpenACS (yet), you may have other skills that are useful. For example, some people have UI design skills, others may have Linux administration skills, or a security background.

I write this not because you're going to have trouble getting help. On the contrary, I've seen people in the OpenACS community help out people that are being very demanding and troublesome. My main hope in writing this is to give newbees a guide to how to most effectively get information.

How to get help and find the information you need.

• First of all, try to track down documentation for what you're looking for. The first place to look is in the official OpenACS documentation. Familiarize yourself with this documentation, especially the API browser, which shows you all the commands you can run. Look at the package documentation (and note that sadly, some of the packages don't have documentation). Notice that there is documentation not just for getting installed, but also for developing an OpenACS package. Try looking in the FAQ
• Second, try searching on Google. Try your search, but include the word OpenACS in the query. This finds answers a surprisingly high amount of the time.
• Third, look through the forums. Use the search functionality to try and find what you're looking for.
• Fourth, if your question is a quick one, then try asking on the OpenACS IRC channel.
• Fifth, try asking your question on the OpenACS forums. Make sure you clearly describe what your problem is, what version of OpenACS you're using, what you did before and after the problem, and what the error message is. Show relevant portions of your error log. If you want people to be helpful and take their time on your question, make sure you take the time to ask the question in a way that someone can give you a meaningful answer.
• See below for more helpful resources

Introductions to OpenACS

• OpenACS official documentation
• OpenACS: It's complicated, it's not finished--is it worth your time? Absolutely. an introduction to OpenACS. - ignore the installation portion.
• OpenACS package system
• An intro to OpenACS templating describes how to make webpages.
• OpenACS performance and scalability - how does OpenACS compare to other toolkits like Zope?
• Ben Koot's Demo Site is a place where you can check out a lot of the packages available for OpenACS. Keep in mind that many of these packages are deprecated, or may not be the most recent version. Don't necessarily assume this is the latest and greatest. But it is a good place to check out a lot of the functionality of OpenACS packages.

Helping out with OpenACS

• How to get started as a worker bee for OpenACS. This describes how you can contribute if you have time and want to learn more about OpenACS by helping out with simple tasks to improve the toolkit

History of OpenACS

• ACS, as described in the Panda book
• History of OpenACS
• Eve Anderson's info on the old ACS, which OpenACS was based on.
• Archives on ACS era postings

After the installation

• Shawn's guide to setting up your homepage, describes what to do after you have installed OpenACS, but before you take on writing your own packages.
• A list of packages and their status for OpenACS.

Writing a package

• Collaboraid's guide to developing packages
• OpenACS official documentation - look for the developers tutorial

Data model

• OpenACS data model diagram, minus tables that aren't related to other tables.

Troubleshooting

If you're using Oracle, this thread describes how to set up Aolserver so that you receive the entire error message from the Oracle database driver. If you get an error message starting with SQL: [too long], then you need to read this. Sometimes, for long error messages, your error messages are truncated, which makes tracking down the errors more difficult.

Other resources

Forum thread on getting started - Several posts on getting started with OpenACS

Nima Mazloumi's list of resources for newbees - lists a bunch of resources to use to get up to speed