Documentation

Bounce detection

rambo — Tue, 18 Sep 2007 13:48:36

NOTE: The bounce detector system requires that you have control over the domain under which the bounce detection address resides, it also requires that you know how to configure a SMTP server.

The basic idea is the write outgoing messages so that the SMTP envelope address (and/or Return-Path header) contain a specially formatted email address which receives no other mail than these bounces.

Rest of this document supposes you are running Postfix.

Install PEAR package HTTP_Client
```
# pear install --onlyreqdeps http_client
```
See also the installation document about making sure the file access rights are correct
See main.cf make note of the recipient_delimiter configuration setting (delimited recipients must be enabled and tested to work prior to configuring bounce detection), as default it is + (plus-sign)
Decide on a good account part for the bounce detector, we choose bouncer
Locate bounce_detector.php in the directmarketing support directory, copy it to /usr/local/sbin and make sure the Postfix user can execute it.

In /etc/aliases (or whatever alias file you choose to use) add line:

bouncer: |"/usr/bin/php /usr/local/sbin/bounce_detector.php bouncer+TOKEN@www.example.com http://www.example.com/path/to/directmarketing/logger/bounce/"

note those quotes around the command.

in component configuration (directmarketing/config.html) set backend to 'any bounce detector compatible' (alternatively either 'SMTP' or 'Sendmail')
in component configuration set bounce detector address to bouncer+TOKEN@www.example.com.

Now create a campaign with couple of members where some of them have bogus email addresses and test it, if you check the source of outgoing mails the Return-Path: should show bouncer+<random_string>@www.example.com and those with bogus addresses should be marked with an icon showing that they have bounced. If it doesn't work start by looking trough your mailserver logs (both outgoing and incoming).

OpenPsa 2 setup

openpsa_admin — Tue, 28 Nov 2006 09:09:33

This document outlines how to set up a new OpenPsa 2. You must have installed it first.

Create a new company database

Midgard can host multiple OpenPsa using companies on same server using a concept called sitegroups

Sitegroups are created using the following command

# php /usr/share/php/midcom/lib/midgard/admin/sitegroup/bin/create-sitegroup.php -u admin -p password -s mycompany --admin_password=newpassword

This will create a new sitegroup named mycompany, with administrative user admin that has password newpassword. The command will output something like the following:
```
Sitegroup created with id : 3
```
Write this ID down, it will be required in the next phase

Note: Run php /usr/share/php/midcom/lib/midgard/admin/sitegroup/bin/create-sitegroup.php --help if you want to learn more about the command.

Create a new host

After you have created the sitegroup you have to set up a new Virtual Host for running the OpenPsa installation. You can do this with datagard

Once the VirtualHost has been created into Apache configuration, you can set up the new OpenPsa 2 site using the command

# php /usr/share/php/midcom/lib/midgard/admin/sitegroup/bin/create-host.php -u admin -p password --sitegroup_id 3 --topic_midcom org.openpsa.mypage --extend_style template_OpenPsa2 --hostname localhost --host_prefix /openpsa

Tune the hostname, sitegroup ID and host prefix to fit your setup. The command above would set up OpenPsa 2 to http://localhost/openpsa.

Note: Run php /usr/share/php/midcom/lib/midgard/admin/sitegroup/bin/create-host.php --help if you want to learn more about the command.

Add MidCOM Cron service call for your host

Locate script midcom_services_cron.sh, it not already make a copy of it to /usr/local/bin (or some other directory of your choice).
Edit the script and add your newly created host to the SITES list (in our example case the entry would be localhost/openpsa).
Make sure the script is run from the system cron, if you wish to use the directmarketing module run it every minute, otherwise every 30 minutes is enough.

Setting up modules

After this you should have an OpenPsa 2 installation up and running. Access it via browser, log in, and use the Create Subfolder functionality to enable those modules you wish to use.

Setting up an owner group

You should create your own organization as a company in the OpenPsa Contacts module and configure OpenPsa to recognize it as the owner group of the system. To do this create a snippet named /sitegroup-config/org.openpsa.core/config with contents like the following:

'owner_organization' => 'b6702bd7d60fa57049ab0f75fc42b235',

Funambol SyncML setup

rambo — Fri, 27 Oct 2006 15:07:55

OpenPsa uses the Funambol SyncML server for synchronizing calendar and contact data with mobile devices.

Jump to client configuration

Note about usernames with Funambol

If you wish to use Funambol your usernames must not contain the @-character, and when concatenated with the sitegroup name they must be shorter than 32 characters (so keep usernames and sitegroup names in sensible lenghts).

Installation instructions

Download the stable Funambol server bundle (version 2.3, including Tomcat)
Install the server bundle by running the downloaded installer
Edit the BUNDLE_HOME/server/bin/sync4j-tomcat.sh script to allow both stopping and starting the server
- Change the ./catalina start row to ./catalina $*
Get OpenPsa connector file sync4j-openpsa-connector-1.0.s4j and copy it to server/modules
- In case you don't have a binary handy, use maven s4j to compile it from the CVS source.
Edit the install.properties file within the Sync4J directory (server/install.properties)
- add sync4j-openpsa-connector-1.0 to the modules-to-install list
- configure the sync4j database (the OpenPSA connector supports only MySQL)
- For MySQL 4.1 (available for Debian stable at dotdeb.org)
  - Change the dbms line to mysql
  - Uncomment the mysql lines
  - Edit to fit, pay special attention to the path of the MySQL JDBC connector JAR
  - comment out the hypersonic jdbc lines near end of file, leave user and password which should be filled with the username and password to be used with the MySQL db of your choice
- Create the MySQL database and grant the user full privileges.
- edit the server-name property
Stop the server that was started during installation (run bin/sync4j-tomcat.sh stop in BUNDLE_HOME/server)
In BUNDLE_HOME/server (you must be there) run bin/install.sh tomcat
- Note that this will overwrite any existing configuration, make a backup copy if needed
Start server again (run bin/sync4j-tomcat.sh start, try restarting again if there are problems)
Use the Sync4j Admin tool (you can use it to connect to remote server as well no need to be on local console) to verify the OpenPSA module is loaded.

Setting up the synchronization sources

To avoid any complications, clear the sync4j_sync_source table in the sync4j database
- DELETE FROM sync4j_sync_source
Add rows for the OpenPSA contact and calendar synchronization sources
- INSERT INTO sync4j_sync_source (uri, config, name, sourcetype) VALUES ('card', 'org/openpsa/sync4j/ContactSyncSource.xml', 'contact', 'openpsa-contact')
- INSERT INTO sync4j_sync_source (uri, config, name, sourcetype) VALUES ('cal', 'org/openpsa/sync4j/CalendarSyncSource.xml', 'calendar', 'openpsa-calendar')
Copy the ContactSyncSource.xml and CalendarSyncSource.xml XML configuration files from the connector distribution to BUNDLE_HOME/server/config/org/openpsa/sync4j/
Edit the configuration files to set the correct OpenPSA database configuration parameters
Restart the server

Principal synchronization

The Funambol Sync4J server requires that all user accounts used for synchronization are entered into the sync4j database and linked to a client profile. Thus the OpenPSA user accounts need to be copied to the sync4j database to enable the SyncML feature for the users. The sync4j-openpsa-principals.pl script included in the connector release (folder addons/funambol/src/unix/) can be used to automatically copy the OpenPSA user accounts to the sync4j database. Enter the database connection parameters in the configuration variables located at the beginning of the script and configure cron to run the script periodically to keep the user accounts up to date.

Setting up OpenPSA authentication

The principal synchronization script only copies the user accounts but not the authentication passwords from OpenPSA to the Funambol database. You can either set custom passwords for the users in the Funambol database, or configure the OpenPSAOfficer component to use OpenPSA authentication. Note that the OpenPSAOfficer component only supports native Midgard authentication, not NTLM or PAM.

Place the sync4j-openpsa-connector-1.0.jar file in BUNDLE_HOME/server/lib/
Copy the OpenPSAOfficer.xml XML configuration file from the connector distribution to BUNDLE_HOME/server/config/org/openpsa/sync4j
Edit the configuration file to set the correct OpenPSA database configuration parameters
Change the officer property in BUNDLE_HOME/server/config/Sync4j.xml to org/openpsa/sync4j/OpenPSAOfficer.xml
Restart the server

Client configuration

You can configure a mobile phone or a desktop PIM client to synchronize itself with OpenPSA through the SyncML server.
Many recent phones have built-in SyncMML support, and you can download client plug-ins for clients like Outlook and Mozilla.
The server address is normally http://example.com:8080/sync4j/sync and the server databases are cal for the calendar and card for contacts.
- Note that some clients (Nokia Communicator for example) require the port to be specified separately and it must not be specified as part of the URL (this will lead to error in resolving the name of the server and in some cases these errors are incorrectly reported as invalid user/password). So examine your client manual on the correct way to specify URLs with ports and experiment with various combinations of specifying the port only in url, both url and separate field etc.
The username is username@sitegroup where username is your normal OpenPSA username and sitegroup is the name of the Midgard sitegroup that contains your OpenPSA instance.
The password is your normal OpenPSA password (or a password provided to you by the server administrator)

Digital Business Ecosystem project broker specification

rambo — Thu, 26 Oct 2006 12:27:59

This document describes how the Digital Business Ecosystem project broker looks for potential subcontractors to a task from the DBE network.

Search process

User creates a new task setting following properties
- Start/end (org_openpsa_task.start, org_openpsa_task.end)
- Planned hours (org_openpsa_task.plannedHours)
- Skills required (tags) (set of net_nemein_tags linked to the task via net_nemein_tag_link)
- Minimum length of time slot (in minutes) (parameter: org.openpsa.projects.projectbroker -> minimum_slot)
- Optionally properties related to acceptable contractors:
- Country (parameter: org.openpsa.projects.projectbroker -> country), value is two letter ISO code in letters.
- Maximum time difference (in hours) (parameter: org.openpsa.projects.projectbroker -> max_time_offset)
- TODO: How to reliably determine the timezone of a person.
When the properties are set, a remote_search parameter (domain org.openpsa.projects.projectbroker) is set to REQUEST_SEARCH
- when the service starts search it sets this to SEARCH_IN_PROGRESS
- if no remote search is desired this property is unset or left to NO_SEARCH
Optionally, the Project Broker servent is pinged (using for example XML-RPC) to start the DBE network query for a task with the given guid immediately, otherwise the servent polls the database for new search requests
The Project Broker servent notices this property and queries the knowledge base for potential resources matching the search (based on skills, and potentially country etc)
- skills matching is AND, person must have all of the skill tags in task
- user needs divide tasks up to subtasks if they need subsets
If the potential resources have a calendaring service available, DBE service also checks if the resources have enough free time available during the task timeframe
Once potential resources are found, their company and person records are copied to the local database (see below), and a task resource object marked PROSPECT is created for them
- If they have a calendaring service defined, events for the task's timeframe are also copied
- Remote users and their calendar entries are marked remote as specified in the OpenPSA remote synchronization service
User interface uses AJAX to fetch new prospect entries and populates them to the potential resource list
If the resource has calendaring information available, the UI shows all applicable time slots of working on the task and their previous and next events
- Each slot has a checkbox "use this slot". When clicked, that time is allocated from the planned hours, and a tentative event created for the person
If resource doesn't have calendaring information available they can simply be allocated just as task resources
Once DBE has queried all potential resources, it sets the remote_search property to SEARCH_COMPLETE

Person and company information

Transmit company and person info via vCard if feasible
- Store basics required for actual operations in BML and extend via vCard
Company
- Official name
- VAT code
- Homepage
- Street address
- Zip
- City
- Country
- Tel
- Logo URL
Person
- Firstname
- Lastname
- Email
- Phone
- Jabber ID
- Calendar service (URL or service identifier)
- Photo URL
- Skills
- Timezone
- City
- Country

Endorsements

In endorsement a customer endorses person's ability to deliver project regarding some skills
UI-wise this happens when approving a finished project. User can check a box to endorse the project team and write a comment
Endorsement contains
- Source (person)
- Destination (person)
- Skill (tag)
- Date
- Comment
When seeking potential resources for project, DBE also seeks for endorsements left by user's buddy list members about those resources and the applicable skills
Locally stored as org_openpsa_projects_endorsement

Project Broker test environment

rambo — Wed, 25 Oct 2006 14:29:22

This is a description of the test environment used to develop and test the Project Broker system specified in Digital Business Ecosystem project broker specification.

The test environment consists of two Xen virtual hosts running as independent network nodes. Both hosts contain the following services:

OpenPSA - The OpenPSA instance used both the backend and user interface of the test cases
FADA - The FADA lookup service for locating the Servent
Servent container - The container for the Knowledge Base and the Project Broker servents
Knowledge Base - The DBE Knowledge Base running as a DBE servent
Project Broker - The Project Broker application running as a DBE servent

The FADA nodes are linked together so that the various servents can find each other.

Test data

TODO

Test cases

TODO

Digital Business Ecosystem project broker

openpsa_admin — Fri, 28 Jul 2006 11:00:42

Project Broker is a Digital Business Ecosystem service targeted at automatically finding potential subcontractors from the DBE network. It is a feature currently under work by Yukatan and Nemein.

Digital Business Ecosystem project broker specification

OpenPsa Roadmap

openpsa_admin — Fri, 28 Jul 2006 10:59:43

This is the plan for future releases of OpenPsa. Most features are being developed by Nemein on customer funding. Schedules and features may change based on funding and project time requirements.

If you'd like to participate in OpenPsa 2 development, start by reading the developer section.

OpenPsa 2.1 series: Q3/2006

Calendar
- vCalendar export of calendar data
- vCalendar import of calendar data
Contacts
- vCard export of My Contacts
- FOAF export of My Contacts
- Duplicate finder and matching UI
Direct Marketing
- Configurable CSV campaign importer
- Report on bounced messages, unsubscriptions and clicks
Infrastructure
- Proven Midgard 1.8 compatibility
- Group support for ContactChooser
Invoicing
- Basic invoice tracking system
Projects
- Switching to Getting Things Done style task contexts
- Hour reporting enabled timer
- Task and hour report synchronization via DBE
Support
- Initial OpenPsa 2 port of the Support module

OpenPsa 2.2 series: Q4/2006

Documents
- WebDAV file access
Invoicing
- Basic contract and pricing system
- Invoicing data export in some formats
Projects
- Scheduling of project work into calendar
- Finding potential contractors via DBE
- Rewritten hour reporting tool with support for expenses
- SyncML synchronization of tasks

OpenPsa 2 installation

openpsa_admin — Wed, 26 Jul 2006 11:06:36

These are installation instructions for OpenPsa 2.0. The setup uses the new Midgard PEAR-based packaging system that is not yet integrated into Midgard 1.7 branch. Because of this the installation requires a bit more work than it will with Midgard 1.8.

The paths shown here are the default for most binary installations of Midgard. If you've compiled it from sources to some other location tune the paths accordingly.

Midgard installation

Install latest Midgard 1.7.4 or newer and set up a fresh database with datagard

MidCOM installation

Follow the MidCOM PEAR installation instructions

OpenPsa installation

Install OpenPsa 2 style template

# pear install midcom/template_OpenPsa2

Install OpenPsa core library
```
# pear install midcom/org_openpsa_core
```

Install user and contact management tool

# pear install midcom/org_openpsa_contacts

Install OpenPsa summary page

# pear install midcom/org_openpsa_mypage

Install all the other components you want to use

# pear install midcom/org_openpsa_projects
# pear install midcom/org_openpsa_sales
# pear install midcom/org_openpsa_directmarketing
etc...

Make sure the pear directory is sane

Sometimes PEAR sets too restrictive rights to some of the packages, go to the pear directory (usually /usr/share/php) and run:
```
# chmod -R a+rx *
```

Database setup

You need to upgrade your MySQL database tables with the new structures provided by OpenPsa and MidCOM. Do this by something like following
```
# cd /usr/share/midgard/sql/update
# for updatefile in `ls -a *.sql`; do
     mysql midgard -f -umidgard -pmidgard < $updatefile
  done
```
Then restart Apache to refresh all MgdSchema database defitions

After this you can proceed to OpenPsa 2 setup.

Link detection

rambo — Wed, 17 May 2006 16:12:16

This works by looking for links in outgoing HTML emails and rewriting those according to configured format, in theory one can use any logger with this. This document however concentrates on using the logger builtin to OpenPsa Directmarketing.

Note: This naturally can only catch those clicks that are actually made on the email (or links copy-pasted from the email), after that clicks on the target page and beyond cannot be seen.

In component configuration (path/to/directmarketing/config.html) in 'link detector address put:
```
http://openpsa.example.com/path/to/directmarketing/logger/redirect/TOKEN/?link=URL
```

Now test this with HTML email with some links in it, in your email reader make note of the link, making sure it is of the format above (in place of TOKEN there is a random string and in place of URL there is encoded form of the original link), click on the link and verify you end up where you should.

NOTE: The some browsers disallow redirecting to other domains, thus the link and OpenPsa should optimally be under same domain.

OpenPsa Documentation

rambo — Wed, 17 May 2006 16:00:36

This is a Wiki containing documentation about the OpenPsa management software.

Installation and setup

OpenPsa 2 requirements - System requirements for running OpenPsa
OpenPsa 2 installation - Installing the new generation OpenPsa
OpenPsa 2 setup - Setting up a company into OpenPsa 2

Usage

OpenPsa 2 features - Usage and configuration of various software features

Add-on modules

Funambol SyncML setup - Getting OpenPsa synchronized with mobile devices
Digital Business Ecosystem setup - Enabling P2P synchronization of project data between companies
Bounce detection - Connecting Direct Marketing to an SMTP server to receive bounced address information
Link detection - Making directmarketing log link clicks in emails

Development information

OpenPsa Roadmap - Where the future versions are going

Documentation about the old OpenPsa 1 system is also available.

OpenPsa 2 requirements

openpsa_admin — Wed, 17 May 2006 15:41:08

OpenPsa is a web-based application meaning that end users only need a web browser to access it. The actual software runs on a web server that can be either installed on a company's own network or can be hosted.

End user requirements

Relatively modern web browser: Firefox 1.5+ recommended

Server requirements

Linux or Unix operating system: root access required
Midgard application server: version 1.7.4 or newer
MySQL database server: version 4 or 5
Apache HTTP server: version 1 or 2
PHP4 programming language

OpenPsa 2 features

openpsa_admin — Wed, 17 May 2006 07:36:13

Here is information about several features in OpenPsa 2

Workflow features

Related information - How emails, notes, documents, tasks and events are connected with each other
Task workflow - How the task tracking workflow in OpenPsa works

Integration with third-party services

Email integration - Using OpenPsa to archive important emails into tasks and projects
Jabber integration - How OpenPsa displays the Jabber instant messaging presence information
Skype integration - How OpenPsa communicates with the Skype VoIP network

Jabber integration

openpsa_admin — Wed, 17 May 2006 07:29:05

OpenPsa can display the Jabber presence of contacts in their contact card.

This feature utilizes the Edgar Jabber presence service and requires the users the allow edgar@jabber.netflint.net to see their presence.

Disabling Jabber presence

Jabber presence display can be disabled by editing snippet /sitegroup-config/org.openpsa.contactwidget/config and adding the following:

'jabber_enable_presence' => true,

Running local presence manager bot

Edgar can be installed and run either as the remote service as is default for OpenPsa, or locally. If you're using a local installation you need to point OpenPsa to the correct URL of your Edgar setup:

'jabber_edgar_url'       => 'http://www.example.net/status.php',

Skype integration

openpsa_admin — Mon, 15 May 2006 12:21:53

OpenPsa can display a contact's Skype presence in the contact cards:

The presence indication requires users to enable display of their Skype Web Presence.

Skype presence display can be disabled by editing snippet /sitegroup-config/org.openpsa.contactwidget/config and adding the following:

'skype_enable_presence'  => false,

OpenPsa 1

openpsa_admin — Mon, 15 May 2006 12:12:22

Documentation for the OpenPsa 1.x series.

Installation

Installation - Instructions on installing the OpenPSA package
Troubleshooting - How to resolve errors and problems

Configuration

Setup - Setting up and managing companies in OpenPsa
Support initialization - Setting up the Support helpdesk module
Sales data import - Importing external data into OpenPsa's CRM module
Project reports - Creating custom reports for project data
User management - Managing the organization structure and permissions

Usage

Login - Logging into OpenPsa
My Summary - Reporting hours, mileages and expenses
Projects - Managing projects, processes and tasks
Sales - Managing client contacts and sales projects

Support Message Tags

openpsa_admin — Thu, 22 Dec 2005 15:21:56

The following tags are substituted with the strings on the fly in Support messages where tagging is supported.

[GUID]: GUID of the ticket
[URL]: URL to the ticket
[TYPE]: Type label of the ticket
[OPENED]: Open (Create) time of the ticket
[STATUS]: Status of the ticket
[TARGET]: Name of the assignee
[TARGET]: Target label of the ticket
[DATETIME]: Current date and time
[PRIORITY]: Priority label of the ticket
[SEVERITY]: Severity label of the ticket

Email Tags

As above but only with email fields (SLA recipients for example)

[OPENER]: Email of the opener
[ASSIGNEE]: Email of the current assignee
[LASTPERSON]: Email of the last person to edit the ticket

Support assignation email template article

openpsa_admin — Thu, 22 Dec 2005 15:18:16

The fields used for Support assignation email template article are shown below to be used in Support initialization.

Article->name: AssignMailTemplate
Article->content: text, the template, supports tagging

Support Service Level Agreement articles

openpsa_admin — Thu, 22 Dec 2005 15:17:54

The fields used for Support Service Level Agreement article are shown below to be used in Support initialization.

Article->title: Title of the SLA, shown in the pull-down
Article->extra3: Ticket-type filtering, pipe (|) separated list of GUIDs to type articles, only visible when Ticket->type is among the listed.
Article->content: definitions, code to define the array $SLA_item, currently has the following keys. NOTE: Do not use PHP opening or closing tags.
- check_on_days: array, keys are days of the week, zero is sunday, six is saturday, values are TRUE or FALSE and determine if this SLA definition is active during those days.
- check_hours_start: int, determines the start of the timeframe (each day) during which this SLA definition is active.
- check_hours_end: int, determines the end of the timeframe (each day) during which this SLA definition is active.
- generic_timeout: int, how many seconds of general inactivity to allow before raising a notification.
- message_body: text, OPTIONAL, used to override the body of the default notification message, supports tagging (see below)
- message_subj: text, OPTIONAL, used to override the subject of the default notification message, supports tagging.
- recipients: array, OPTIONAL, keys are ignored, each value is an email address, supports email-tags (see below), default: array('','','')

Example

$SLA_item['check_on_days']=array(  
                            0 => FALSE, //Sunday  
                            1 => TRUE,  //monday  
                            2 => TRUE,  
                            3 => TRUE,  
                            4 => TRUE,  
                            5 => TRUE,  
                            6 => FALSE  //saturday  
                           );  
$SLA_item['check_hours_start']=8;  
$SLA_item['check_hours_end']=16;  
$SLA_item['generic_timeout']=7200; //2 hours  

$SLA_item['message_body']="foo\nbar \nyadayada...";  
$SLA_item['message_subj']="Notify for ";

Support Canned Answer articles

openpsa_admin — Thu, 22 Dec 2005 15:11:16

The fields used for Support Canned Answer article are shown below to be used in Support initialization.

Article->title: Title of the answer, shown in the pull-down.
Article->content: The answer text.
Article->extra1: Default note-type, sets the note-type to this (numeric) value when selected.
Article->extra3: Ticket-type filtering, pipe (|) separated list of GUIDs to type articles, only visible when Ticket->type is among the listed.

Support Access Control Lists

openpsa_admin — Thu, 22 Dec 2005 15:09:55

The parameters used for Support Access Control Lists are shown below to be used in Support initialization.

The ACL system checks person's Department, Group Memberships and Person object parameters to find the best (as in most access) value for each keyword in domain TechSupportACL. The parameters are of format Object->parameter('TechSupportACL', , );

create: Bool, can create new tickets. Will have multiple levels for simplified/full access.
modify_own: int, can edit "own" (user is creator or assignee) tickets. 1 means basic access,3 means full access (including closed tickets), 2 is not used at the moment.
modify_all: int, can edit other than "own" tickets. Same as above
view_details_own: Not used at the moment.
view_details_all: Not used at the moment.
view_list_own: Not used at the moment.
view_list_all: Bool, can view ticket listings.
view_preg: Int, can view this level of publicity.
view_reports: Bool, can view reports.