I recently tried to use the notifications package. I found it under documented and kind of confusing. So once I worked it out I wrote the following document. I am still new to OpenACS so id like to get peoples opinion on this. Please correct me if I am doing anything wrong/bad in this tutorial.
OPEN-ACS Tutorial using Notifications package
The notifications package is a very useful but under-documented package. It allows you to send notifications through any defined communications medium (e.g. Email, sms) upon some event occuring within the system.
This tutorial steps through the process of integrating the notifications package with your package.
For this tutorial we will use the example of a jobs package, in which jobs for users are added, updated and removed (by a manager??) and those users need to be NOTIFIED of the existence of a new job or the update or removal of an existing job.
This example assumes that we already have our job system set up (objects defined etc.) and only need to add the notification part.
Create notification types
The first step is to create the notification types. To do this a script similar to the one below needs to be loaded into Postgresql. I create this script in a package/sql/postgresql/package-notifications-init.sql file. I then load this file from my create sql file. The script below creates a job_added notification type. A similar script needs to be written for job_updated and job_deleted if required.
create function inline_0() returns integer as '
declare
impl_id integer;
v_foo integer;
begin
-- the notification type impl
impl_id := acs_sc_impl__new (
''NotificationType'',
''job_added_notif_type'',
''jobs''
);
v_foo := acs_sc_impl_alias__new (
''NotificationType'',
''job_added_notif_type'',
''GetURL'',
''job::notification::get_url'',
''TCL''
);
v_foo := acs_sc_impl_alias__new (
''NotificationType'',
''job_added_notif_type'',
''ProcessReply'',
''job::notification::process_reply'',
''TCL''
);
PERFORM acs_sc_binding__new (
''NotificationType'',
''job_added_notif_type''
);
v_foo:= notification_type__new (
NULL,
impl_id,
''job_added_notif'',
''New Job Notification'',
''Notifications of new jobs added to the jobs system'',
now(),
NULL,
NULL,
NULL
);
-- enable the various intervals and delivery methods
insert into notification_types_intervals
(type_id, interval_id)
select v_foo, interval_id
from notification_intervals where name in (''instant'',''hourly'',''daily'');
insert into notification_types_del_methods
(type_id, delivery_method_id)
select v_foo, delivery_method_id
from notification_delivery_methods where short_name in (''email'');
return (0);
end;
' language 'plpgsql';
select inline_0();
drop function inline_0();
The next step is to setup our notification creation. A new notification must be added to the notification table for each job added. We do this using the notification::new procedure
notification::new \
-type_id [notification::type::get_type_id \
-short_name job_added_notif] \
-object_id $user_id\
-response_id null\
-notif_subject 'new job added' \
-notif_text $job_description
This code would be added into the tcl after we created our new job. The $user_id is the OpenACS object id of the user to which the job has been assigned and the $job_description is some description of the job.
The final step is to setup the notification subscription process. In this example we want to let a user find out when they have a job assigned to them. To do this we put a link on our users personal page that allows them to subscribe to notifications of jobs assigned to them being added. The notifications/requests-new page is very handy in this situation.
Such a link would look something like this:
<a href=/notifications/request-new?object_id=@user_id@&type_id=@type_id@&return_url=@return_page@> Notify me of new jobs assigned to me</a>
in the tcl for this page user_id should be set to the users id. type_id should be set to the id of the notification type, this can be got through the
[notification::type::get_type_id -short_name job_added_notif]
procedure as we used to add the notification above. The return_page should be set to the address we want the user to be redirected to after they have finished the subscription process.
This should be all you need to implement a notification system. For more examples look at the forums package.
