Project Open - Configuration Guide.071121

]project-open[ V3.
2
Configuration
Guide
Klaus Hofeditz and Frank Bergmann,
V1.5.1, 2007-11-21

]project-open[ Configuration Guide, V 1.5.1 Page 2

INDEX
1 ABOUT THIS DOCUMENT.............................................................................. 5
1.1 VERSION ...............................................5
1.2 SCOPE .................................................5
1.3 AUDIENCE ..............................................5
1.4 LIMITATION OF LIABILITY ..................................5
1.5 VERSION HISTORY.........................................5
1.6 RELATED DOCUMENTS .......................................6
1.7 TODOS................................................6
2 CONFIGURATION OVERVIEW....................................................................... 7
3 CONFIGURATION DURING INSTALLATION................................................. 8
4 PACKAGE SELECTION AND INSTALLATION.............................................. 9
4.1 VERSION NAMING CONVENTIONS ................................9
4.2 DECIDE WHICH MODULES TO INSTALL...........................10
4.3 DOWNLOAD ADDITIONAL PACKAGES .............................11
4.4 INSTALL ADDITIONAL PACKAGES ..............................12
4.5 INSTALLING FULL-TEXT SEARCH (TSEARCH2) ....................13
5 CONFIGURE USER PERMISSIONS............................................................. 14
5.1 VERTICAL USER PERMISSIONS................................14
5.2 EXTENDING VERTICAL PERMISSIONS............................16
5.3 SUB-ADMINISTRATION AND USER MATRIX ......................16
5.4 HORIZONTAL USER PERMISSIONS ..............................18
6 CONFIGURING THE INTERNAL COMPANY............................................ 19
7 CONFIGURING INVOICE TEMPLATES ....................................................... 20
7.1 AVAILABLE VARIABLES.....................................20
7.2 SAMPLE INVOICE CODE ....................................24
8 PARAMETERS.............................................................................................. 27


8.1 NECESSARY PARAMETERS ....................................27
8.2 OPTIONAL PARAMETERS.....................................27
9 CATEGORIES ............................................................................................... 29
9.1 CATEGORY HIERARCHY .....................................29
9.2 AN EXAMPLE COMPANY TYPES ..............................29
9.3 CATEGORY TYPES.........................................30
10 LOCALIZATION......................................................................................... 33
10.1 SUPPORTED LANGUAGES ...................................33
10.2 CHANGING DEFAULT LANGUAGES .............................33
10.3 ADDING NEW LOCALIZATION MESSAGE .........................33
10.4 DATE, TIME AND CURRENCY FORMATS .........................34
10.5 UNICODE AND DOUBLE-BYTE CHARACTER SETS ...................34
10.6 COUNTRY SPECIFIC ACCOUNTING RULES .......................34
11 ERROR REPORTING ................................................................................ 35
11.1 ONLINE ERROR REPORTING ................................35
11.2 REPORTING ERRORS AT SOURCEFORGE.NET......................35
12 ONLINE SOFTWARE UPDATES .............................................................. 36
12.1 UNIX ONLINE SOFTWARE UPDATES ...........................36
12.2 WINDOWS ONLINE SOFTWARE UPDATES .........................36
13 DATABASE CONFIGURATION ................................................................ 38
13.1 WINDOWS POSTGRESQL DATABASE OPTIONS .....................38
13.2 POSTGRESQL SECURITY CONFIGURATION .......................38
13.3 POSTGRESQL VACUUM CONFIGURATION.......................39
13.4 POSTGRESQL DATABASE BACKUP.............................39
14 MENU CONFIGURATION.......................................................................... 40
15 PLUG-IN COMPONENT CONFIGURATION ............................................. 41
16 GUI CONFIGURATION.............................................................................. 42


17 START PAGE CONFIGURATION ............................................................. 43
17.1 REMOVING THE "WELCOME TO ]PROJECT-OPEN[" TEXT .............43
17.2 REMOVE THE DEFAULT LOGIN OPTION .......................43
17.3 THE ]PROJECT-OPEN[ SYSTEM START PAGE ....................43
17.4 THE ]PROJECT-OPEN[ HOME PAGE .........................46
18 MULTI-CURRENCY CONFIGURATION.................................................... 47
18.1 AVAILABLE CURRENCIES ..................................47
18.2 SUPPORTED CURRENCIES ..................................47
18.3 CURRENCY CONVERSION ...................................48
18.4 CALCULATING MULTI-CURRENCY SUMS .........................49
18.5 EXCHANGE RATES DETAILS ................................49
19 FILE SERVER INTEGRATION .................................................................. 50
19.1 CONFIGURING FILESTORAGE PARAMETERS .......................50
19.2 INTEGRATION WITH AN EXISTING FILE SERVER..................51
20 SYSTEM'S INTEGRATION, APIS AND "USER EXITS" ........................... 54
20.1 APPLICATION API......................................54
20.2 USER EXITS ..........................................54
21 SYSTEM ADMINISTRATION..................................................................... 56
21.1 LDAP AUTHENTICATION ..................................56
21.2 BACKUP AND RECOVERY ...................................56
22 EXAMPLE CONFIGURATION SESSION.................................................. 58
22.1 CLEANING UP AN EXISTING CONFIGURATION ....................58
22.2 BASIC CONFIGURATION ...................................58
22.3 PERMISSION CONFIGURATION ...............................59
22.4 SYSTEM AND DB CONFIGURATION ............................59
22.5 BASIC GUI CONFIGURATION ...............................60


1 About this Document
1.1 Version
Version: 1.5.1, 2007-11-21
Author: Klaus Hofeditz and Frank Bergmann
Status: Preliminary
1.2 Scope
This manual describes the configuration of ]project-open[ V3.0 product family.
1.3 Audience
The manual is written for application administrators of ]project-open[ both at final
customers and at ]po[ partners.
1.4 Limitation of Liability
The procedures described in this manual can affect the behavior of the ]project-
open[ system in ways difficult to predict for users unfamiliar with the ]po[
architecture and source code.
Please be aware that execution configuration procedures by uncertified personnel
may leave your ]po[ system in an inoperative state. Such situations are not
covered by the normal ]po[ maintenance contract.
IN NO EVENT SHALL ]project-open[ BE LIABLE FOR ANY LOSS OF PROFIT
OR ANY OTHER COMMERCIAL DAMAGE, INCLUDING BUT NOT LIMITED TO
SPECIAL, INCIDENTAL, CONSEQUENTIAL OR OTHER INDIRECT DAMAGES
UNDER ANY CAUSE OF ACTION ARISING OUT OF OR RELATING TO THE
CONTENT OF THIS DOCUMENT, INCLUDING, WITHOUT LIMITATION, CLAIMS
ARISING FROM MALFUNCTION OR DEFECTS IN THE PRODUCTS.
1.5 Version History
V1.1: 050702: New Logo
V1.10: 050618: Updated module list
V1.8: 050601: Added chapter about Component configuration
V1.7: 050426: Added chapter about PostgreSQL configuration
V1.5: 050314: Version rename, general revision
V1.4: 050113: Improved software updates chapter


V1.3: 050112: Added several chapters
V1.2: 050109: Important enhancements with perspective of the V3.0 launch.
V1.1: 040531: Extended the document after the installation at Customer #8.

1.6 Related Documents
]project-open[ Unix Installation Guide
]project-open[ Unix Maintenance Guide
OpenACS Administrators Guide:
http://openacs.org/doc/openacs-5-1/acs-admin.html
1.7 ToDos
Explain package interdependencies
Describe different category types in-depth
Convert the email at the end to chapters


2 Configuration Overview
The Configuration of ]project-open[ system consists of taking decisions and
modifying parameters in a number of areas:
Package Selection
User Administration Matrix
System Administrators
System Parameters
Logo and GUI Colors
Home Page
Project States and Project Types
Customer States and Customer Types
Many of the decisions to be taken require in-depth knowledge of the ]project-
open[ architecture, which are not within the scope of this manual. We recommend
leaving the configuration of a productive ]project-open[ system to a certified
]project-open[ consultant.
The installation of ]project-open[ is not within the scope of this manual. Please
refer to related documents in Chapter 1.6.


3 Configuration During Installation
You need to take the first configuration decisions during the installation of ]project-
open[ when the AOLServer application server comes up for the first time. Please
find below a sample screen.
The Email, Username and Password fields are important, because they define
the default system administrator.
However, you dont need to worry too much about the other values because the
system administrator will be able to modify them later in the page Admin /
Parameters.
Email: [email protected]
Username: fraber
First Name: Frank
Last Name: Bergmann
Password: secret
Password (again): secret
System URL: http://www.projop.com:8000/
System Name: ]project-open[ Demo Server
Publisher Name: ]project-open[
System Owner: [email protected]
Admin Owner: [email protected]
Host Administrator: [email protected]
Outgoing Email Sender: [email protected]
New Registration Email: [email protected]


4 Package Selection and Installation
We assume that the OpenACS system and the ]project-open[ Core module
been installed according to the ]project-open[ Installation Guide. This chapter
talks about the installation of additional modules.
4.1 Version Naming Conventions
Please read http://www.project-open.com/whitepapers/Project-Open-
Architecture.ppt for an introduction to the general architecture and the concept of
customizations.
Package versions are described by a four-digit number such as: 2.1.3.1 or
3.0.0.1. The digits have the following meanings:
1. Major Releases. The first version number changes only after major
changes of the system architecture and the data model.
Main releases will come out every 4-8 years. Customizations (changes of
the source code by a customer) will in general not survive an upgrade to a
major release. Also, the data model may not be upgradeable to a new major
release, possibly requiring a manual transfer process.
2. Minor Releases. The second number represents major improvements of
the system such as the addition of new modules or important enhancement
of existing modules.
Minor releases with come out every 6-12 months. There will be always two
minor releases maintained: A stable release that only receives bug fixes
and a feature release where development happens. The feature release
will always contain the latest modules etc. From time to time the feature
release will become the stable release and a new feature release will be
opened.
Minor releases will always provide an upgrade path for the data model of a
previous version. However, customizations may not be preserved between
minor releases, depending on the particular case.
3. Service Releases. The third number represents minor improvements of the
system such as the addition of new fields to a business object etc.
Service releases require an update of the data model via the database
upgrade script. Service releases will preserve customizations in general.
4. Bug Fix Releases. The fourth number represents minor bug fixes. Bug fix
releases dont require an upgrade of the data model and will preserve
customizations in general.
5. Internal Release. A sixth number is used to identify versions for internal
testing purposes. These versions (not releases!) should normally not be
visible publicly. However, they may be used in special circumstances.


4.2 Decide Which Modules to Install
The table below shows you which module is suitable for which ]project-open[
product from 2006-02-01. Please check for an updated table at http://www.project-
open.org/download/, the information below is probably outdated.
Most ]po[ modules are free (GPL or FL). However there are some ]pt[ modules
under the CL that are sold for a license fee.
Explanation:
Module: Name of the module
License: GPL (free), FL (free) or $ (not free)
Active Versions: Which versions are active at the moment?
Maturity:
o Prod = Ready for production use
o Beta = For advanced users only who know what they are doing
o Alpha = Not suitable at all for normal users
o - = Doesn't exist yet
Version: 3-1-2: Currently stable V3.1 production release
pt: Suitable for Project/Translation
pc: Suitable for Project/Consulting
pl: Suitable for Project/Lifecycle
pa: Suitable for Project/Agency
GPLed packages:
Module
Lice
nse
Activ
Vers
ion
Mat
uri
ty
P
t
P
c
P
l
P
a
Comments
Project Management
intranet-core GPL 3-1-X Prod x x x x Projects, Customers, Offices, Users and infrastructure
intranet-dynfield GPL 3-1-X Prod x x x x Dynamic Object Fields for CRM
Customer Management
intranet-spam GPL 3-1-X Beta x x x x Email Marketing Campaigns
intranet-crm-tracking GPL 3-1-X Beta x x x x Web site tracking, online registration
Finance
intranet-payments GPL 3-1-X Prod x x x x Invoice payments
intranet-timesheet GPL 3-1-X Prod x Timesheet mgmt
intranet-timesheet2 GPL 3-1-X Prod x x x Timesheet mgmt with Material
intranet-cost-travel GPL 2-1-1 - x x x x Travel cost mgmt
Human Resources
intranet-hr GPL 3-1-X Prod x x x x Employees, payroll, ...
Knowledge Management
intranet-wiki GPL 3-1-x Prod x x x x Wiki Engine
intranet-search-pg GPL 3-1-x Prod x x x x Search engine for PostgreSQL (>8.0)

Commercial packages (FL = Free License, $=Commercial License)


Module
Lice
nse
Active
Vers
ion
Mat
uri
ty
p
t
p
c
p
l
p
a
Comments
Project Management
intranet-
filestorage
FL 3-1-X
Prod
x x x x File system based filestorage
intranet-forum FL 3-1-X Prod x x x x Discussion forums with tight permissions
intranet-material FL 3-1-X Prod x x x x File system based filestorage
intranet-update-
client
FL 3-1-X
Prod
x x x x Discussion forums with tight permissions
Finance
intranet-cost FL 3-1-X Prod x x x x Base costs
intranet-invoices FL 3-1-X Prod x x x x Base invoices
intranet-freelance-
invoices
$ 3-1-X
Prod
x x x x POs for freelancers
intranet-
timesheet2-tasks
FL 3-1-X
Prod
x x x x Task-based planning for Timesheet
intranet-
timesheet2-
invoices
FL 3-1-X
Prod
x x x x Automatic Invoicing for Timesheet
intranet-
exchange-rate
FL 3-1-X
Beta
x x x x Exchange rate module for multi-currency reporting
Human Resources
intranet-freelance $ 3-1-X Prod x x x x Freelance skill database & Recruiting Pipeline
Translation
intranet-
translation
FL 3-1-X
Prod
x Translation base and workflow
intranet-trans-
invoicing
FL 3-1-X
Prod
x Invoicing for Translation
intranet-trans-
quality
$ 3-1-X
Prod
x Statistical Process Control (SPC) for Translation
Reporting & Data Warehouse
intranet-reporting FL 3-1-X Prod x x x x Reporting Engine
intranet-dw-light FL 3-1-X Prod x x x x Data-Warehouse using MS-Excel Pivot Tables
intranet-dw-mssql $ 3-1-1 Prod x x x x Data-Warehouse using MS-SQL OLAP Services
intranet-dw-
mondrian
$ 0-0-0
-
x x x x Data-Warehouse using Mondrian OLAP Server
Knowledge Management
intranet-simple-
survey
FL 3-1-X
Beta
x x x x
Surveys: Project reports, provider satisfaction,
customer satisfaction,

4.3 Download Additional Packages
In order to install additional packages you first need to download and unpack them
in your local package directory:
/web/<server>/packages
You can do this in two ways: Semi automatically using a web interface or manually
using Unix commands.
Semiautomatic Download:


Go to http://www.project-open.org/download/ and check for new packages
that you want to download. You need to get the entire URL that ends with a
.apm postfix (or a .zip or .tgz postfix for files containing multiple
packages).
Go the package managers page at:
http://<server>/acs-admin/apm/package-load
Enter the URL and press the Load button.
Manual Download:
Go to http://www.project-open.org/download/ and check for new packages
that you want to download. You need to get the entire URL that ends with a
.apm postfix.
Download the packages to a Unix location accessible by the ]project-open[
application
Go the package managers page at:
http://<server>/acs-admin/apm/package-load
Enter the path and press the Load button.
Please note, this was only the download of the packages. The next sections describes the
installation of the packages.
4.4 Install Additional Packages
Start the package installation process with the URL
http://<server>/acs-admin/apm/
Please use this URL and dont use the package installation pages offered in the
Admin menu (in the case you should have noted that there is such a link)
Please follow the link Install Package. You should get a page Package
Installation with a list of available packages. Please choose all packages that you
want to install. Click on those modules that you have decided to install. Package
dependencies (for example: intranet-trans-invoices depends on intranet-invoices)
are handled automatically and conflicts are reported.
You should get a page Select Data Model Scripts with a number of SQL files
selected for installation. They should be all selected. Press Install Packages. You
should get a long screen with messages from the SQL interpreter. At the end there
should be a link Click here to restart the server.
There should be no error messages coming up from an installation. If you do find
messages, please send us an email with the entire output to
mailto:[email protected].


4.5 Installing Full-Text Search (TSearch2)
The installation of the "intranet-search-pg" module may cause some issues
because it uses an full text search extension of the PostgreSQL database. Here
are some tips & tricks:
4.5.1 Installation
- MAKE A COMPLETE BACKUP BEFORE INSTALLING!
Both code and data. The installation of TSearch2 has already lead to
inconsistencies in the database etc.
- The installation of "intranet-search-pg" via /acs-admin/apm/ may go wrong.
In this case please uncheck the execution of the ".sql" file, install the
package and proceed manually below.
- Get the "tsearch2.sql" file that fits to your PostgreSQL database. The file
provided in packages/intranet-search-pg/sql/postgresql/tsearch2.sql is for
PostgreSQL 7.4.6 (the CygWin Windows version). Check
/usr/lib/pgsql/contrib./tsearch2.sql or similar for the version that fits your
PostgreSQL version.
- Source the "tsearch2.sql" file manually. This script should give some
warnings, but at the end you should see some 100 "CREATE FUNCTION"
lines.
- If you get an error like "psql:tsearch2.sql:20: ERROR: access denied for
language C" then you've got a permission issue. Your local database user
needs to have "superuser" rights. Login as user "postgres", start "psql
projop" (we assume that you database is called "projop"), and issue: "alter
user projop createdb;" and "alter user stage createuser;". These commands
provide the user "projop" with the necessary administration rights.
- After "tsearch2.sql" has been executed successfully, you can now manually
source the rest of the code via "psql f intranet-search-pg-create.sql". Don't
worry about the errors in the beginning from "tsearch2.sql". These are due
to multiple sourcing of the file..
- If you get the error like "could not find tsearch config by local" then
you've probably installed your PostgreSQL database with a locale different
from the default locale ("C"). Determine your current locale with "show
lc_messages;". You should get a string such as "es_ES.UTF-8". Now use
this string and update the TSearch2 locale configuration: "update pg_ts_cfg
set locale='es_ES.UTF-8' where ts_name='default';".

Sorry for the hassle, this is due to some issues within the PostgreSQL project. We
are in direct contact with the PG developers to influence future development.


5 Configure User Permissions
For an introduction to user permissions please see:
Overview documentation: http://www.project-open.com/whitepapers/Project-
Open-Permissions-Model.ppt
Developer documentation: http://www.project-open.org/doc/intranet-
core/permission_requirements.html
Developer documentation: http://www.project-open.org/doc/intranet-
core/permissions.html
Or check for general documentation at http://www.project-open.org/doc/
5.1 Vertical User Permissions
You can configure vertical permissions (=profiles, permissions related to departments)
by granting privileges to profiles. Here is an example:
You decide that your employees should be able to see all projects in your
organization, because you trust them. So you grant the view_projects_all
privilege to the employee profile.
You can configure vertical permission at the URL:
http://<server>/intranet/admin/profiles/
The following matrix shows a permissive configuration of vertical permissions.

Permission Name
P
/
O

A
d
m
i
n

S
e
n
M
a
n

S
a
l
e
s

A
c
c
o
u
n
t
i
n
g

P
M

E
m
p
l
o
y
e
e
s

C
u
s
t
o
m
e
r
s

Freelancers

General

Search
intranet
search_intra
net x x x x x x
General permission to search the Intranet. All returned hits are further restricted
according to the users permissions.

Finance

Add finance add_finance x x x x x x x x
Generic permission to enter any financial or cost items (further restricted)
Add costs add_costs x x x x x
Permission to add cost items in general.
Add
payments
add_paymen
ts x x x
Permission to add payment items in general.
Add hours add_hours x x x x x x
Permission (and obligation!) to log hours. You normally allow this only for employees
and people on your company's payroll
Add
absences
add_absenc
es x x x x x x
Permission (no obligation here) to log absences such as vacations, travel time etc.
This may also make sense for freelancers, as to indicate their availability.
Add invoices add_invoices x x x x


View_finance view_finance x x x
Generic permission to enter into the finance module
View costs view_costs x x x

View hours
all
view_hours_
all x x x

View
absences all
view_absenc
es_all x x x

View
invoices
view_invoice
s x x x

View
payments
view_payme
nts x x x

Project
Managemen
t

Add projects add_projects x x x x

View
filestorage
sales
view_filestor
age_sales x x x

View projects
all
view_project
s_all x x x x x x

View projects
history
view_project
s_history x x x x x x

View project
members
view_project
_members x x x x x x

Customer
Managemen
t

Add
companies
add_compan
ies x x x

Add offices add_offices x x x

Edit internal
offices
edit_internal
_offices x x x

View internal
offices
view_internal
_offices x x x x x x x x
View the information of Your Company's offices
View offices view_offices x x x x x x x x
Generic permission to view office (further restricted by other permissions)
View offices
all
view_offices
_all x x

View crm
tracking
view_crm_tr
acking x x x

View
companies
view_compa
nies x x x x x x x x
The general permission to see companies - the user will not see any companies if
this privilege is not set
View
companies
all
view_compa
nies_all x x

View
company
contacts
view_compa
ny_contacts x x x

View
company
details
view_compa
ny_details x x x

User
Managemen
t

Add users add_users x x
Generic permission to add users. The profile of the users to be created are limited
by "User Matrix" permissions
View users view_users x x x x x x x x
Generic permission to see any kinds of users
View user
registrations
view_user_r
egistrations x x x


System
Administrati
on

System
Admin - x
This permission is not found in Admin/Profiles but in /acs-
admin/users/one?user_id=<user_id>
Admin
categories
admin_categ
ories x x
Permission to modify system categories. The user should know what they are
doing...

Translation

View trans
proj detail
view_trans_p
roj_detail x x x x x x

View trans
tasks
view_trans_t
asks x x x x x x

View trans
task matrix
view_trans_t
ask_matrix x x x x x x

View trans
task status
view_trans_t
ask_status x x x x x x

Forums

View topics view_topics x x x x x x x x
Generic permission to view topics (further restricted by topic scope)
Add topic
client
add_topic_cli
ent x x
(
x
)

Add topic
group
add_topic_gr
oup x x
(
x
)

Add topic
noncli
add_topic_n
oncli x x x x
(
x
) x x

Add topic pm
add_topic_p
m x x x x x x x x
Add topic
public
add_topic_p
ublic x x

Add topic
staff
add_topic_st
aff x x x x
(
x
) x

Human
Resources

View Human
Resources view_hr x x
Generic permission to view and edit HR information

5.2 Extending Vertical Permissions
You can also create new user permissions for new roles. To do that, please go the
profile administration page from the last chapter and follow the link Add a new
profile. (Not working in V3.0 alpha!)
5.3 Sub-Administration and User Matrix
The User Matrix administration page can be reached via Admin/User Matrix. The page
specifies the relationship between users of different profiles.
These relationships include:


Administration (A):
The users of one profile can administer users of another profile. This privilege
includes adding users of the specified type (if the add_users privilege is set for the
profile of the creating user), become this users (the administrator can convert itself
into the administered user and it also includes the following Write, Read and View
permissions.
Examples: ]po[ Admins for example should in general be able to administer all
other type of users. Another example are freelancers: In the example below, all
Employees are allowed to administer freelancers.
Write (W):
The permission to modify user data
Read (R):
The permission to read the user data (name, email, contact information, )
View (V):
The permission to view the name of the user, but not the right to see its user data
Users frequently belong to several profiles. In this case the following rules hold:
The Administering user:
A user that belongs to several profiles receives the sum of all privileges of all
profiles he belongs to (union or or-relationship).
Example: Peter Projectmanager is member of both Employees and Project
Managers. He enjoys of the privileges of both profiles.
The Administered user:
An administered user may belong to several profiles. The privileges of the
administering users need to be valid for all of these profiles (intersection or and-
relationship) in order to hold.
The following matrix shows a permissive User Matrix. Bold capital letters indicate the
presence of a privilege; lower case letters indicate the absence.

Accoun
ting
Custo
mers
Emplo
yees
Free
lancers
]po[
Admins
Project
Mana
gers Sales
Senior
Mana
gers
Accounting v R w a V r w a v R w a V r w a V R W A v R w a v R w a V R W A
Customers v R w a v r w a v r w a v r w a V R W A v r w a V R W A V R W A
Employees v R w a V r w a v R w a V r w a V R W A v R w a v R w a V R W A
Freelancers V R W A v r w a V R W A v r w a V R W A V R W A v R w a V R W A
]po[ Admins v R w a V r w a v R w a V r w a V R W A v R w a v R w a V R w a
Project Managers v R w a V r w a v R w a V r w a V R W A v R w a v R w a V R W A
Sales v R w a V r w a v R w a V r w a V R W A v R w a v R w a V R W A


Senior Managers v R w a V r w a v R w a V r w a V R W A v R w a v R w a V R W A

5.4 Horizontal User Permissions
You can modify horizontal permissions or roles by editing the table
im_biz_object_role_map. This table contains a mapping from (acs_object_type,
object_type to roles) using SQL commands:
create table im_biz_object_role_map (
acs_object_type constraint im_bizo_rmap_o_type_fk
references acs_object_types,
object_type_id integer
constraint im_bizo_rmap_object_type_fk
references im_categories,
object_role_id integer
constraint im_bizo_rmap_object_role_fk
references im_categories,
constraint im_bizo_rmap_un
unique (acs_object_type, object_type_id, object_role_id)
);
The following relationships are predefined:
Project
Project Manager (admin)
Full Member
Office
Office Administrator (admin)
Full Member
Customer
Key Account Manager (admin)
Full Member
For example, the Projects roles have been defined using the statement:
-- Setup the list of roles that a user can take with
-- respect to a project:
-- Full Member (1300) and
-- Project Manager (1301)
--
insert into im_biz_object_role_map values ('im_project',85,1300);
commit;

Newly created roles can be used in the filestorage module to restrict permissions. For
example, a software analyst could be a project member with read permissions on all
project folders and write permissions to the analysis folder.


6 Configuring the Internal Company
The internal company represents your company (the company owning the
Project/Translation server). Several ]po[ modules need this company in order to
create transactions, involving your company. You will get an error message if the
company has not been set up, such as:
Internal company missing

To check if the "Internal Company" exists please go to "Companies" and use the
"Company Type" drop-down list and select "Internal". You will most likely see a
single company named "Tigerpond" (in the case of preconfigured demo data).
Please click on this company and edit it to suit your company. Please don't touch
the "Company Nr" field (needs to remain "internal").

If there is no "internal" company (a configuration "from scratch") please go to the
Companies menu and select Add a new Company and create a company with
the following data:
Company Name <Your Company Name>
Company Short Name
internal
Company Status
Active
Company Type
Internal
Address . . .
Please USE THE BOLD VALUES from the example above to setup. Please note
that the Company Short Name should be in lowercase!
Please complete all other fields with the relevant information about your company.


7 Configuring Invoice Templates
]project-open[ allows users to customize the print appearance of quotes, invoices
and purchase orders using HTML templates (invoice templates). There are two
elements that need to work together to provide a new invoice template:
1. You need to design your own .adp template file.
This .adp file is a kind of HTML file with special placeholders to fill-in the
invoice data. You need to place your invoice templates into the filestorage,
typically located at C:\ProjectOpen\filestorage\templates (Windows) or
/web/projop/filestorage/templates (Linux).
2. You need to create a new category entry for your new template.
In /Admin/Categories page please choose Intranet Cost Template. This
should show you some preinstalled templates. Please modify an existing
template or create a new one for your new template. Just specify the name
of your templates in the filestorage folder. Example:
7.1 Available Variables
The following variables are available inside an invoice template. You can include
the content of these variables into your template using a line like:
<H1><%= %page_title %></H1>
Please note that "invoice" is frequently used below to refer to "Financial
Documents" (Invoice, Quotes, Bills, Delivery Notes, etc).
7.1.1 General Variables
page_title The HTML Title of the invoice. Just for the browser header
(usually not printed)
user_id The ID of the current user (currently looking at the page)
internal_contact_email Email of user_id
internal_contact_name Name of user_id
locale The locale of this invoice, determined by the name of the
invoice template. For example "invoice.en_US.adp" will lead to
an "en_US" locale for this financial document.
The "locale" determines the language of static texts and the
formatting of numbers.
user_locale The default locale of the current user. Is in general different
from the "locale". This locale serves as a fallback value in
case that there is no "locale" (see above) defined for the
invoice.
rounding_precision Constant set to "2". Determines the number of digits of
rounding precision for subtotals etc.
default_currency

Defines the Defined by "DefaultCurrency" parameter
subtotal Subtotal (sum of invoice items)
subtotal_pretty Formatted subtotal.
grand_total Grand Total (Subtotal + VAT + TAX)


grand_total_pretty Formatted grand_total

7.1.2 Parameters
The following variables are defined by parameters in the Admin -> Parameters ->
intranet-invoicing section and can be modified by the Administrator.
show_company_project_nr Should we include the customer's project_nr in item_html?
The project_nr can change per item (line) but this rarely
happens, so setting this parameter to 0
("ShowInvoiceCustomerProjectNr" parameter) is an option if
you are using few cummulative invoices.
show_our_project_nr Similar to show_our_project_nr. Determines whether _our_
project_nr should appear in the item_html. Defined by
"ShowInvoiceOurProjectNr" parameter.

7.1.3 Preformatted Pieces of HTML
These pieces of HTML are already formatted to be included in the
InvoiceViewPage and the template.
You can customize these elements via parameters (see section above) or using a
StyleSheet.
invoice_item_html
item_html
item_list_html
note_html Preformatted (<pre>...</pre>) invoice "note" field
payment_list_html List of related payments formatted for the ViewPage (not for
the Preview)
payment_method_html
terms_html The "payment terms" section at the bottom of the page
subtotal_item_html The formatted piece of HTML representing the "subtotal"
section with subtotal, VAT, TAX and grand total.
render_template_id ID of the display template to be used for rendering. Refers to
the category_id field in the im_categories table where you find
the actual name of the template in the "category" field.
payment_terms_html Formatted "payment conditions" section. Usually only
applicable for "hard costs" where invoice_or_bill_p == true
(see below).
7.1.4 Currency and Date Formatting
These formats are used on the SQL level to format variables. The format depend
on the "locale" parameter (see above). For further customization (modifying the
decimal and thousand separators for a particular locale) you can modify the
language definition files in the "catalog" folder of the acs-lang package. Please see
the OpenACS documentation for more details.
cur_format
cur_format


vat_format
tax_format
7.1.5 Related Projects
These variables are useful if you want to refer to the (or the several) project that
are related to the given invoice. Please not that you can have 0, 1 or multiple
projects related to a single invoice (0 for a "stand-alone" invoice without project, 1
for the standard case of one project per invoice and multiple projects if you choose
to do "cumulative invoicing", where you include several (small) projects in a single
invoice).
related_project_nrs The TCL list of the "numbers" of related projects. Please use
"<%= [join $related_project_nrs ", "] %> to use this field in
the template, so that multiple projects are displayed
correctly with a ", " in between.
related_projects The TCL list of the "names" of related projects. See above
for formatting.
num_related_projects The number of related projects. Can be 0, 1 or more.
related_customer_project_nrs The TCL list of the customer's project references to the
related projects. See above for formatting.
7.1.6 Customer and Provider
An Financial Document is usually between the "internal company" (please see
above) and either a Provider or a Customer, depending on the type of financial
document. "Company" in this context refers to this 2nd party, independently of
whether it's a customer or a provider.
company_id ID of the customer or provider
company_name (Long name)
company_path Path (short name)
deleted_p The company may already have been deleted
company_status_id Status of the company. Use "select
im_category_from_id(company_status_id)" to get a human
readable status
company_type_id Type of company. See company_status_id above for
formatting.
crm_status_id Information of CRM acquisition process.
primary_contact_id ID of the company's main contact person. Please use
"select im_name_from_user_id(:primary_contact_id)" to
obtain the name and "select
im_email_from_user_id(:primary_contact_id)" to obtain the
contact's email.
accounting_contact_id ID of the company's accounting contact person.
vat_number The VAT number of company
The following fields contain information about the preferences/default values for
company's payment conditions and templates for different invoice types.
default_payment_days
default_vat
default_payment_method_id


default_invoice_template_id
default_bill_template_id
default_po_template_id
default_delnote_template_id

Information about the company's "Office" selected for this invoice. Please note that
there can be several Offices per company, so this one refers to the particular office
defined in the invoice.
office_id ID
office_name Name of the Office. Can be used to designate a company's
sub organization (department, ) if suitable maintained in
the customer's file
office_path Short name of the office
office_status_id Status (as usual)
office_type_id Type (as usual)
phone
fax
address_line1 First of two address lines
address_line2 Second of two address lines
address_postal_code ZIP
address_state May only be useful for US American addresses.
address_city
address_country_code Two digit code for the country
country_name English name of the country (can be localized using L10n,
pleases see OpenACS documentation for reference).
7.1.7 Financial Item Information:

cost_id ID
invoice_id Same as cost_id
cost_name Long Name (automatically generated)
cost_nr Short Name (automatically generated)
invoice_nr Same as cost_nr
customer_id Customer, either the "internal" company for an bill/po or
customer company for an invoice/quote/delivery_note.
provider_id Provider, either the "internal" company for an invoice/quote
or the provider company for a bill/po.
company_contact_id ID of the Customer's/Provider's contact person to who we
want to send or direct the financial document
company_contact_email Name of company_contact_id
company_contact_name Email of company_contact_id
cost_center_id Cost Center/Department
cost_center_name Long name CC/Dept
cost_note Note (prominent field in InvoiceListPage and Template)
cost_status_id Status (ID)
cost_status Status (human readable)
invoice_status_id Same as cost_status_id


cost_type_id Type (ID)
cost_type Type (human readable)
invoice_type_id Same as cost_type_id
calculated_due_date Due date (effective date + payment days)
calculated_due_date_pretty Due date formatted according to locale
cffective_date Effective date of invoice
invoice_date Same as effective date
invoice_date_pretty Effective date formatted
payment_days Number of days for payment, difference between
effective_date and calculated_due_date.
invoice_office_id Company's office ID
invoice_or_bill_p True ("1") if financial item is a customer invoice or a provider
bill. Both types are "hard costs" and require certain fields
such as payment conditions.
invoice_or_quote_p True ("1") if the document is related to a Customer (as
opposed to Provider). Also true for "Delivery Note".
payment_method_id ID that determines payment details
invoice_payment_method_id Same as payment_method_id
invoice_payment_method Short human readable text for payment method such as
"Bank ABC"
invoice_payment_method_des
c
Long description text for payment method detailing the how
the money should be paid, typically including the bank
name, SWIFT code, IBAN, account number, etc.
invoice_template_id Rendering template for the cost item.
paid_amount Registered payments for this cost item, converted into
paid_currency.
paid_currency Currency of payments, usually identical with
default_currency.
vat VAT (percentage)
vat_amount VAT (percentage x invoice amount)
vat_amount_pretty VAT (percentage x invoice amount) formatted
tax TAX (percentage). This field can accommodate applicable
tact, for example Spanish IRPF, or sales tax.
tax_amount TAX (percentage x invoice amount)
tax_amount_pretty TAX (percentage x invoice amount) formatted
7.2 Sample Invoice Code
Here is a source code of a simple template that is included in the ]project-open[
Windows installer:
<html>
<head>
<title>Invoice Template </title>
<link rel='stylesheet' href='http://www.project-open.com/css/invoice.css' type='text/css'>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
</head>
<body text="#000000">
<table border="0" cellspacing="1" cellpadding="1" width="100%">
<tr>
<td>
<img src="http://www.project-open.com/images/logos/logo.project-open.horiz.tra.gif"
width=230 height=52><br>
<P><b><font size="5">INVOICE</font></b></P>
</td>


<td align="right"> <p><font size="6"><b>]project-open[</b></font><br>
<font size="4"><b>Manage your projects online-<br>
anytime, anywhere</b></font></p>
<b><font size="3">www.project-open.com</font></b> </td>
</tr>
</table>
<hr>
<table border="0" cellspacing="1" cellpadding="1" width="100%">
<tr>
<td valign="top">
<table border="0" cellspacing="1" cellpadding="1">
<tr class=rowtitle><td colspan="2" class=rowtitle>Client Details</td></tr>
<tr>
<td class="roweven">Company</td>
<td class="roweven"><%=$company_name %></td>
</tr>
<%
set address1 ""
if {![string equal "" $address_line1]} {
set address1 "
<tr>
<td class=roweven>Address</td>
<td class=roweven>$address_line1</td>
</tr>"
}
%>
<%=$address1 %>
<%
set address2 ""
if {![string equal "" $address_line2]} {
set address2 "
<tr>
<td class=roweven> </td>
<td class=roweven>$address_line2</td>
</tr>"
}
%>
<%=$address2 %>
<tr><td class="roweven">Zip/City</td>
<td class="roweven"><%=$address_postal_code %><%=$address_city %></td>
</tr>
<tr><td class="rowodd">Country</td><td class="rowodd"><%=$country_name %></td></tr>
<tr><td class="roweven">Phone</td><td class="roweven"><%=$phone %></td></tr>
<tr><td class="rowodd">Fax</td><td class="rowodd"><%=$fax %></td></tr>
<tr><td class="rowodd"> </td><td class="rowodd"> </td></tr>
</table>
</td>
<td align="left" valign="top">
<tr><td colspan="2" class="rowtitle">Provider Details</td></tr>
<tr><td class=roweven>Company</td><td class=roweven>]project-open[</td></tr>
<tr><td class=roweven>Address</td><td class=roweven>Avda. Felix Millet 45</td></tr>
<tr><td class=roweven>Zip/City</td><td class=roweven>08338 Barcelona</td></tr>
<tr><td class=rowodd>Country</td><td class=rowodd>Spain</td></tr>
<tr><td class=roweven>Phone</td><td class=roweven>+34 609 953 751</td></tr>
<tr><td class=rowodd>Fax</td><td class=rowodd>+34 93 741 1235</td></tr>
<tr><td class=roweven>E-Mail</td><td class=roweven>[email protected]</td>
</tr>
</table>
</td>
</tr>
</table><br>
<tr><td><b><font size=2>Date</font></b></td><td><font size=2><%=$invoice_date
%></font></td></tr>
<tr><td><b><font size=2>Invoice No. </font></b></td><td><font size=2><%=$invoice_nr
%></font></td></tr>
</table><br>


<%=$item_html %>
</table>
</body>
</html>


8 Parameters
The parameter administration page can be accessed via Admin / Parameters.
The page shows a summary of all system parameters grouped by module. The
parameters can be edited by clicking on the module link. Each parameter contains
a brief description.
Most parameters are defined by the underlying OpenACS community system and
are not relevant for ]project-open[.
8.1 Necessary Parameters
Please make sure that the following parameters are set to the indicated values.
Using different values can lead to serious security vulnerabilities or other undesired
effects.
acs-subsite Main Site
EmailChangedPasswordP 1
if the admin changes the password, should it be mailed to the user
EmailForgottenPasswordP 1
Email users forgotten passwords
EmailRegistrationConfirmationToUserP 1
Send confirmation email to user after registration
MembersCanInviteMembersP 0
Set this to 1 if you want to allow members to invite other members.
NotifyAdminOfNewRegistrationsP 1
Notify someone of new registrations?
RegistrationProvidesRandomPasswordP 0
have the system generate a random password instead of the user
RegistrationRequiresEmailVerificationP 0
Set this to 1 if the user has to receive and email and come back to the site.
CSV-Import of user data will send out emails (NOT desired normally) to all users if this value is set to 1.
RestrictEntireServerToRegisteredUsersP 1
Do we want to allow only registered users to visit this subsite?
AllowPersistentLoginP 1
Do we allow persistent logins?
RegistrationRequiresApprovalP 1
Set this to 1 if user do not go live immediately
8.2 Optional Parameters
The following parameters are frequently used and can safely be modified. The
table below contains example values from ]project-open[. In particular, you will
have to modify all path parameters (/web///) according to the setup of your
computer.
acs-kernel Kernel


AdminOwner [email protected]
who signs the admin pages, e.g., a programmer who can fix/enhance them
HostAdministrator [email protected]
a person whom people can email with technical problems
OutgoingSender [email protected]
The email address that will sign outgoing alerts.
PublisherName ]project-open[
for legal pages, full corporate entity
SystemName ]project-open[ Server
the name of your system
SystemOwner [email protected]
who signs the average user-visible pages
SystemURL http://www.projop.com/
URL to tell users to go to

intranet-core ]project-open[ Core
ErrorReportURL http://www.projop.com/intranet-forum/new-system-incident
Error Report URL
SystemCSS /intranet/style/style.default.css
Global CSS
SystemLogo /intranet/images/projop-logo.gif
System logo that appears in all screens
SystemLogoLink http://www.project-open.org/
SystemLogoLink
SystemNavbarGifPath /intranet/images/navbar_default
Where are the GIFs located for the navbar?
BackupBasePathUnix /web/projop/filestorage/backup
Path for backup sets


9 Categories
Categories are a general concept being used throughout the ]project-open[
system for several different purposes.
Sometimes categories are used to hold values supposed to be modified by
a knowledgeable user (user).
Sometime categories are supposed to be configurable by system
administrators (admin).
Finally, categories are used as a kind of internal system constant that
should never be touched, not even by a system administrator (constant).
9.1 Category Hierarchy
Categories are can be ordered hierarchically using an "is-a" relationship. This
allows defining category-subcategory relationships.
The "is-a" relationship represents a "transitive closure" of a "parent-child"
relationship. "Transitive closure" means that all parents of a category need to be
entered in an "is-a" field, not just the "direct parent".
This way of defining the category hierarchy has several advantages such as:
- "Multiple inheritance" A category can have more then one parent.
- Fast "is subcategory" query The SQL query to determine whether a
category is a subcategory is very fast, because all cases are stored in the
"is-a" relationship. In particular, this avoids any hierarchical/iterative sub
queries.
However, there are also several disadvantages:
- Complex This scheme is difficult to understand for non-administrators
- Error prone Nothing prevents you from defining a cyclic "is-a" relationship,
possibly leading to infinite loops in the system
Please make sure you understand the concept of a "transitive closure" before
modifying categories yourself.
9.2 An Example Company Types
The table below shows an example of the Company Type category. This category
is supposed to be editable by a sysadmin and shows the general structure of a
category.
Id Category Is-A Description
51 Unknown Use this if the type of the company is not yet clear (to be clarified later).
52 Other Use this for strange cases where you really dont know.


53 Internal Customer
Use this type to denote your own company or companies belonging to
you group or holding.
54
MLV Translation
Agency Company
Customer A Multi-Language Vendor translation agency.
55 Software Company Customer A software company as a customer.
56 Provider Super class of all providers.
57 Customer Super class of all customers.
58 Freelance Provider Provider A provider that consists of a single freelancer.
59
Office Equipment
Provider
Provider A provider for furniture and other office equipment.
You can identify the following fields:
A human readable Category field
An ID that is sometimes used as a constant for internal system purposes
An Is-A field that defines a hierarchical tree (more precisely: directed
acyclic graph) relationship
A Description field to define the precise semantics of a category.
The Company Type category is designed to be extended by knowledgeable
users, so that new types of customers can be added during the lifetime of the
system. However, such a knowledgeable user would need to know that she
couldnt touch the Internal, Provider or Customer fields, because their IDs are
referenced as constants internally in the system.
9.3 Category Types
The following list describes the intended scope of modification of the current
categories:
Module Category Type ModifiableComment
intranet-core
Intranet Annual Revenue user Constants for CRM
Intranet Biz Object Role constant
Role relationships between business objects and their members.
Examples: Project Manager, full member (projects, offices, companies),
Key Account.
Intranet Company Status admin
Used for CRM sales pipeline and partner acquisition pipeline. You
could add values, but there are already too many of them.
Intranet Company Type admin
Used to distinguish different types of companies such as customers,
providers, partners, You can add new company types.
Reserved types::
- Internal: Refers to your own company
- Customer: Companies buying from you. Please use Customer
as a super-type when adding a new type of customer
- Provider: Companies from whom you are buying. Super-type of
all providers
Intranet Office Status admin Constants for office, active or inactive.
Intranet Office Type admin
Main office or sales office. Main Office is uses as a constant, so
please dont change.


Intranet Project Status admin
Project cycle completion state. Many states are used as constants
by the system, with specific meaning. For example, Delivered is used
by the invoicing module etc. Better dont add anything.
Intranet Project Type admin
You can add your project types here.
Reserved types:
- Translation Project: Super-type for all translation projects. This type
triggers certain specific components for translation projects
Project types are currently also being used as types for translation
tasks, which is going to change with the next major release

intranet-timesheet
Intranet Absence Type admin Holiday, Vacation, No problem adding a new type

intranet-crm-tracking
Intranet CRM Interaction constant
Types of interactions with a ]project-open[ site, such as login,
registration, viewing static contents,

intranet-cost
Intranet Invoice Payment Methodadmin
Intranet Invoice Status admin Invoice lifecycle support.
Intranet Invoice Template admin
The category name is used as a filename in /web/projop/filestorage/
templates/ (default) to identify the filename of an invoice template (or
quote, purchase order, )
Intranet Invoice Type constant
The existing types are used as constants. However, you may add new
ones which the corresponding supertype.
Intranet Payment Type admin
Intranet UoM admin
Units of Measure. You can your own UoMs. Translation invoicing refer to
these types in the price list. Other modules may in the future.

intranet-forum
Intranet Topic Status constant Used for incident resolution workflow on tasks and incidents.
Intranet Topic Type constant

intranet-freelance
Intranet Employee Pipeline State admin Freelance and Employee recruitment lifecycle support
Intranet LOC Tool user Skill Category: Localization tools of Freelancers
Intranet Operating System user Skill Category: Operation Systems dominated by Freelancers
Intranet Skill Type user
This category contains the different skill types (such as LOC Tool,
Operating System, ). Please specify the category type of the
corresponding category in the description field (not very clean, but
works).
Intranet TM Tool user Skill Category: Translation Memories dominated by Freelancers
user
You may add new categories here for skills. You need to add these
categories to Intranet Skill Type to activate them

intranet-hr
Intranet Job Title admin Constants for employee lifecycle support
Intranet Experience Level admin
Intranet Hiring Source admin
Intranet Prior Experience admin
Intranet Qualification Process constant


intranet-translation
Intranet Translation Language user
A list of all languages being used by a translation agency. You can add
and delete new languages.
Intranet Translation Subject Area user Subject areas for translation projects. You can add and delete.
Intranet Translation Task Status constant
Translation task workflow support. All states are used as constants
in the program code.
Intranet Quality constant Defines quality levels. Used as constants, you cant change them (yet)

intranet-riskmanagement
Intranet Risk Type admin

intranet-planning
Intranet Task Action Type admin
Intranet Task Board Time Frame admin

ToDo: Describe each of these categories in detail.


10 Localization
You can translate the ]project-open[ user interface in any language (localization,
l10n). This localization process mainly consists of a list of translations for each
language, that can be modified by the user.
10.1 Supported Languages
Currently (V3.0.0), ]project-open[ is available in American English (en_US),
Castilian Spanish ("es_ES"), Brazilian Portuguese ("pt_BR") and German
(de_DE).
Adding a new language is easy. Just enable the language in
http://<your_server>/acs-lang/ and use the localization interface to batch-edit the
texts and/or switch on the translation mode for the user interface.
10.2 Changing Default Languages
Go to http://<your_server>/acs-lang/. This is the page where you can select for
user specific language options.
These options will be included in the standard ]project-open[ user configuration
screens in one of the next versions.
10.3 Adding new Localization Message
If ]project-open[ cant find a specific translation, it will display an error message
such as this one:
MESSAGE KEY MISSING: intranet-core.Hardware_Manufacturer
These errors may also occur if you add new categories (see chapter below) to the
system of if you customize the GUI.
You (the System Administrator) can remove such an error message by using the
built-in localization mode of ]project-open[:
Go to "My Account" and change your user's locale to "en_US". All
localization strings need to be present in English first (as always )
Go to http://<your_server>/acs-lang/admin/.
Click on the on of the first line: Toggle translation mode: On | Off
Return to the initial page with the MESSAGE KEY ERROR. You will see a number
of small green o-handles appear, indicating successful localizations. Red @
symbols indicate missing translations. Clicking on them will lead you to a
localization screen where you can register a translation.
Now you may change your locale to a local language and repeat the steps above.


10.4 Date, Time and Currency formats
]project-open[ uses its own default date format YYYY-MM-DD in all modules.
This format cannot be changed.
Time format is handled inconsistently between different modules. Please refer to
the specific documentation. This situation is going to be improved in one of the
next releases.
Currency format uses ISO three letter abbreviations such as EUR or USD.
]project-open[ is build to handle multiple currencies, so you will need to specify
your currency every time you enter a money amount. The parameters section
provides a system default currency that is used as a default where appropriate.
10.5 Unicode and Double-Byte Character Sets
]project-open[ uses Unicode (UTF-8) as its default character set. All strings
should be enabled for Unicode and Asian double-byte characters. However, this
feature hasnt yet been tested extensively (V3.0.0). Cyrillic and Latin 1 special
characters are know to work.
10.6 Country Specific Accounting Rules
The ]project-open[ Cost Module doesnt use any country specific accounting
rules. VAT and tax are fee-text fields in invoices and other cost items, allowing the
user to add specific values.
]project-open[ will support an export function of costs to country specific
accounting formats in the future, such as KHK-Kaufmann (Germany), ContaPlus
(Spain) and QuickBooks (US).


11 Error Reporting
11.1 Online Error Reporting
]project-open[ includes an option to report errors online to a centralized error-
reporting server.
Example: http://<your_server>/intranet/admin/ttt is a sample file that
contains an explicit error, suitable for testing the error reporting procedure.
Entering this link, you will be shown a typical error message.
In order to configure online error reporting, please copy the following file:

/web/projop/packages/intranet-forum/www/page-error.adp ->
/web/projop/packages/acs-tcl/lib/page-error.adp

There are no limits for the time it might take to resolve an incident in Sourceforge.
Please consider contracting a support contract if you need a deterministic service:
http://www.project-open.com/product/services/support/
Note: The page-error.adp in V3.0.alpha2 contains a formatting error. Please
revert to a newer version of ]project-open[.
11.2 Reporting Errors at Sourceforge.Net
There exists a public ]project-open[ incident management application at
Sourceforge.net:
http://sourceforge.net/tracker/?atid=579555&group_id=86419&func=browse
Also, there is a generic Open Discussion board where you can as questions:
http://sourceforge.net/forum/forum.php?forum_id=295937
You can use these web applications to post errors. You may have to register at
Sourceforge before you can access these pages. Please help us by using a
suitable Subject, by including the error message and by giving us details about the
URL where the error occurred.
There are no limits for the time it might take to resolve an incident in Sourceforge.
Please consider contracting a support contract if you need a deterministic service:
http://www.project-open.com/product/services/support/


12 Online Software Updates
Software Updates always contain the risk that something goes wrong. We strongly
suggest that you backup all system data before a software update, including at
least:
The ]project-open[ source code at /web/projop/packages/*
The content of the PostgreSQL or Oracle database
The content of the /web/projop/* folder in general
Disclaimer: ]project-open[ does not accept any liabilities for errors during online
software updates (see the general disclaimer section above).
You need a valid CVS user in order to perform a successful online software
update. Please consult your ]project-open[ support contract for your specific CVS
user and password. There exists a publicly available CVS user called anonymous
with an empty password. However, anonymous may not have the right to access
all of your installed modules. A suitable CVS account will be created as part of a
support contract.
12.1 Unix Online Software Updates
On Unix systems (Linux, Solaris, Apple OS X, ), please login as the user projop
and use CVS to update your code:
# su projop
# cd /web/projop/packages/
# cvs update
You should see a number of lines, detailing the subdirectories that have been
updated.
In the case of an error please make sure that your CVS parameters are set
correctly:
# su projop
# set | grep CVS
You should see something like this:
CVSREAD=yes
CVSROOT=:pserver:[email protected]:/home/cvsroot
CVS_RSH=ssh

12.2 Windows Online Software Updates
On Windows systems (Win2k, Windows XP, Windows 2003), please use WinCVS
(http://www.wincvs.org/) or a similar client to access the CVS repository. You need


change to the C:\ProjectOpen\projop\packages\ directory and set the following
parameters:
Authentication pserver
Path /home/cvsroot
Host Address projop.dnsalias.com
User Name anonymous (or your CVS user)
Please update the software by following the procedures below.
12.2.1 The First Software Update
When updating the software for the first time, you will need to checkout the
]project-open[ modules from the CVS server:
Please delete all intranet-* folders in C:\ProjectOpen\projop\packages\ or
move them into a temporary folder.
Start WinCVS, log into the CVS server with the parameters above and
issues the command cvs checkout intranet-core in the text window at the
bottom. This will download the intranet-core module from the CVS server
and setup versioning information.
Repeat the cvs checkout command for all intranet-* modules that you
have removed.
12.2.2 Following Software Updates
The subsequent software updates can be executed using a single command:
Start WinCVS and change to the C:\ProjectOpen\projop\packages\ folder
(click on the corresponding folder icon)
Issue the command cvs update. This command should update all folders
below /packages/. You should see log messages detailing the
subdirectories that have been updated.


13 Database Configuration
This chapter describes the configuration of the default ]project-open[ database
PostgreSQL. The configuration of the optional Oracle database is not subject of
this manual.
13.1 Windows PostgreSQL Database Options
There are three different database configuration options to run ]project-open[:
1. PostgreSQL on CygWin - the default option for ]project-open[:
The ]po[ installer by default installs a PostgreSQL database as part of the
CygWin Unix environment. This configuration is convenient because
everything works out of the box. However, PostgreSQL on CygWin does
not perform as well as the other options
2. Native PostgreSQL:
The native version of PostgreSQL (starting with version 8.0) on Windows
performs considerably better then the CygWin version. We highly
recommend this option for any productive use of ]po[. Please see
www.postgre.org for details.
3. PostgreSQL on a separate database server:
You can run the PostgreSQL database on a separate server computer,
possibly even with a different operating system such as Linux or Solaris.
Please contact us for options 2 and 3.
13.2 PostgreSQL Security Configuration
PostgreSQL security is mainly controlled by the file C:\ProjectOpen\ cygwin\ var\
postgresql\ data\ pg_hba.conf. The figure below shows the default ]po[
configuration:
# TYPE DATABASE USER IP-ADDRESS IP-MASK METHOD

local all all trust
In this configuration, the database will allow full access to all data for all local users
of the server computer while blocking the access for anybody not working locally
on the computer.
This setup is very convenient for our ]po[ demo server where we cant predict the
name of the local users. However, you may want to change these settings for a
productive installation.
Please see the PostgreSQL documentation
(http://www.postgresql.org/docs/7.3/static/client-authentication.html) for details or
contact us for installation/ configuration / security consulting services.


13.3 PostgreSQL Vacuum Configuration
Vacuuming is the PostgreSQL name for performing database maintenance.
Periodic maintenance is important for the overall performance of PostgreSQL,
which can degrade considerably otherwise.
The default ]project-open[ Windows installation does not include a periodic
scheduling of the vacuum command.
Please execute the CygWin vacuumdb command periodically:
You can configure a Windows Scheduled Task to execute the included
ProjectOpen-vacuum.bat every day
You can configure the CygWin cron scheduler to execute the command.

Here is an excerpt from a Linux Crontab:

# Full PostgreSQL vacuum every night
20 3 * * 0 su - postgres -c "/usr/bin/vacuumdb -a -f" >> /var/log/pg_vacuumdb.log
2>&1

13.4 PostgreSQL Database Backup
You can backup the PostgreSQL database manually via Admin / Backup / Full
PostgreSQL Database Backup. However, we recommend that you
configure an automatic database backup.
Here is an excerpt from a Linux Crontab:

# Backup PostgreSQL "projop" database every night
20 3 * * 0 su - projop -c "pg_dump -c -O -F p -f
/web/projop/filestorage/backup/pg_dump.`/bin/date +\%Y\%m\%d.\%H\%M`.sql " >
/var/log/pg_backup.log 2>&1


14 Menu Configuration
Menu configuration allows you to add and remove menus and to determine the
visibility of menus to different user profiles.

Figure 1: A sample menu configuration. A capital R stands for readable, while a lower case
r stands for not readable.
Menu permissions only determine whether the menu is visible to a user. It does
not affect the permissions of the page that is references by the menu.
The general idea of ]project-open[ is to keep the menu permissions aligned with
the page permissions. However, certain mismatches can always happen:
There can be pages without menu entries, which a user could see (hidden
pages)
There can be pages with menu entries, which a user is not allowed to see
(forbidden pages)


15 Plug-in Component Configuration
Component configuration allows you to configure the location of a component and
to determine the visibility of components to different user profiles.

Figure 2: A sample component configuration. A capital R stands for readable, while a
lower case r stands for not readable.
You can use component permissions to exclude certain user groups from certain
information. For example, you may want to disable access to the customers forum
and filestorage component for customers.
Please note that a completely empty permission field means that all components
are visible to everybody, in order to maintain backward compatibility to earlier
versions of ]project-open[.


16 GUI Configuration
The following parameters are used to modify the GUI configuration:
intranet-core ]project-open[ Core
SystemCSS /intranet/style/style.default.css
Global CSS
SystemLogo /intranet/images/projop-logo.gif
System logo that appears in all screens
SystemLogoLink http://www.project-open.org/
SystemLogoLink
SystemNavbarGifPath /intranet/images/navbar_default
Where are the GIFs located for the navbar?

SystemCSS:
We recommend that you copy-past-modify the original style.default.css to
create a customized version.
SystemLogo:
To replace the default ]project-open[ logo by your company logo please
add your logo to the /www/projop/packages/intranet-core/www/images/
directory (referred to via the /intranet/images/ URL) and modify this
parameter accordingly.
SystemLogoLink:
The link behind the SystemLogo
SystemNavbarGifPath:
Contains a number of GIFs responsible to render the ]po[ navigation bar
triangles. The colour of these GIFs corresponds to the colour of the system
menus defined in the SystemCSS. You may have to copy-past-modify the
default set of logos to create a new set if you want to modify the default
system colours.


17 Start Page Configuration
17.1 Removing the "Welcome to ]project-open[" Text
The "Home" page of the ]project-open[ demo systems contain a help text
"Welcome to ]project-open[ ". This text is useful for demo systems but should be
removed for a production system.
To remove this content please go to the "Admin" and follow the link "Plugin
Components". In this page please select the "Home Text Help Blurb" and set its
location to "none". Please see chapter "Plug-In Component Configuration" above
for details.
17.2 Remove the Default Login Option
This section is very important if you have installed your ]project-open[ system
used the Windows installers preconfiguration option.
This preconfiguration (Project/Translation, Project/Consulting) installs a TCL
page for the Default Logins that lets everybody log-in without a password.
You need to remove this page if you want to use the system for more then testing
purposes. Please remove the file:
C:\ProjectOpen\projop\www\become.tcl

17.3 The ]project-open[ System Start Page
The ]project-open[ system start page with the URL: http://<your_server/ is
located at /web/projop/www/index.adp. (Unix) or
C:\ProjectOpen\projop\www\index.adp (Windows). This ADP page
contains simple HTML code and is designed to be customized by a system
administrator using any suitable HTML editor.
Also, you can create a TCL file in the same subdirectory. TCL and the ADP file
normally work together to provide the content for a particular page. The TCL
usually includes the business logic, while the ADP page is used to render the
variables from the TCL file in HTML format. As an alternative, you can also use
static HTML files with the extension .htm or .html. Please see the Learning
]project-open[ section at www.project-open.org.
The /web/projop/www/ subdirectory contains the publicly available pages of the
web server or page root. This is the right place to add HTML pages explaining
your company etc.


17.3.1 Immediate Start Option
One option for the system home page is not to have any specific home page at all,
but to redirect to the ]project-open[ core pages. In this case please create a TCL
page at /web/projop/www/index.tcl with the following contents:
ad_page_contract {
Empty system home page (redirects immediately to ]project-open[)

@author [email protected]
@creation-date Nov 2003
} { }

ad_returnredirect "/intranet/"
17.3.2 Home Page with Login Option
The following example shows a typical Intranet main screen from the ]project-
open[ Intranet with some links and a login component.
/web/projop/www/index.tcl:
ad_page_contract {
project-open Intranet index.tcl
Provides the index.adp page with default values for
the different login parameters
} {
{authority_id ""}
{username ""}
{email ""}
{return_url "/intranet/"}
}
/web/projop/www/index.adp:
<! ]project-open[ Intranet index.adp page -->
<html><head><title>]project-open[ Intranet</title>
<meta http-equiv=Content-Type content="text/html; charset=iso-8859-1">
<link media=screen href="/intranet/style/style.default.css" type=text/css
rel=StyleSheet>
<body text=black bgColor=white>
<table cellSpacing=0 cellPadding=0 width="100%" border=0>
<tr>
<td><A href="http://www.project-open.com/">
<img src=/intranet/images/projop-logo.gif border=0 width=230 height=52>
</A></td>
<td vAlign=center align=middle></td>
<td vAlign=center align=right></td>
</tr>
</table>
<tr>
<td align=left>
<table cellSpacing=0 cellPadding=0 border=0>
<tr height=19>
<td><img alt="" src="/intranet/images/navbar_default/left-sel.gif"
width=19 border=0 heigth="19"></td>
<td class=tabsel>
<A class=whitelink href="/intranet/index">Home</A>


</td>
<td>
<td><img alt="" src="/intranet/images/navbar_default/right-sel.gif"
width=19 border=0 heigth="19"></td>
</tr>
</table>
</td>
</tr>
<tr>
<td class=pagedesriptionbar colSpan=2>
<table cellPadding=1 width="100%">
<tr><td class=pagedesriptionbar vAlign=center>
]project-open[ Intranet
</td></tr>
</table>
</td>
</tr>
</table><br>
<tr>
<td vAlign=top>
<tr><td class=tableheader>]project-open[ Links</td></tr>
<tr><td class=tablebody>
<LI><A href="/intranet/">]project-open[ Intranet</a><br>
<LI><A href="http://www.project-open.com/">]project-open[ Web Site
</a>
<LI><A href="http://www.project-open.org/">]project-open[ Developer
Community</a>
<LI><A href="http://www.project-open.org/doc/">Documentation Home</a>
</td></tr>
</table>
</td>
<td>
<tr><td class=tableheader>Intranet Login</td></tr>
<tr><td class=tablebody>

<include src="/packages/acs-subsite/lib/login" return_url="@return_url;noquote@"
no_frame_p="1" authority_id="@authority_id@" username="@username;noquote@"
email="@email;noquote@" &="__adp_properties">
</td>
</tr>
</table>
</td>
</tr>
</table>
<tr><td>
Comments? Contact:
<A href="mailto:[email protected]">[email protected]</A>
</td></tr>
</table>
</body>
</html>


17.4 The ]project-open[ Home Page
The ]project-open[ home page with the URL: http://<your_server/intranet/ is
located at /web/projop/packages/intranet-core/www/index.adp. (Unix)
or C:\ProjectOpen\projop\packages\intranet-core\www\index.adp
(Windows). This page is the default target of the Home menu tab.
The page contains a help text in ]project-open[ Version V3.0.betaX that can
become annoying after a while. You can disable this help text in Admin / Manage
Component Layout / Home Help Blurb by setting the Location to none.
Also, you may want to modify this page to add company messages etc. However,
you may have to make the file writable before doing so, because the file is normally
under CVS control:
On Unix:

# cvs edit /web/projop/intranet-core/www/index.adp
# emacs /web/projop/www/index.adp /web/projop/intranet-core/www/index.adp

Or: simply make the file writable by brute force if you accept to loose your
changes with the next system update:

# chmod ug+w /web/projop/www/index.adp

Windows: Please use WinCVS, change to the local directory and issue the same
cvs edit as above. Or: Simply make the file writable in the Windows Explorer.
Another customization option is to modify the target for the Home menu tab. A
system administrator can change this URL in the Admin / Menus page.


18 Multi-Currency Configuration
]project-open[ in general supports all world currencies and multi-currency
operations. Most of this functionality is covered in the "PO-Finance-User-Guide".
18.1 Available Currencies
]project-open[ already includes a list of 162 currencies:
ADP AED AFA ALL AMD ANG AON ARP ATS AUD AWF AZM BAK BBD BDT BEF BGL BHD BIF
BMD BND BOB BRR BSD BTN BUK BWP BYP BZD CAD CHF CLF CLP CNY COP CRC CSK CUP
CVE CYP DDM DEM DJF DKK DOP DZD ECS EGP ESP ETB EUR FIM FJD FKP FRF GBP GHC GIP
GMD GNF GRD GTQ GWP GYD HKD HNL HRK HTG HUF IDR IEP ILS INR IQD IRR ISK ITL JMD
JOD JPY KES KHR KMF KPW KRW KWD KYD LAK LBP LKR LRD LSL LUF LYD MAD MGF MNT
MOP MRO MTL MUR MVR MWK MXP MYR MZM NGN NIC NLG NOK NPR NZD OMR PAB PEI
PGK PHP PKR PLZ PTE PYG QAR ROL RUR RWF SAR SBD SCR SDP SEK SGD SHP SLL SOS SRG
STD SVC SYP SZL THB TND TOP TPE TRL TTD TWD TZS UAH UGS USD UYP VEB VND VUV
WST YDD YER YUD ZAR ZMK ZRZ ZWD
These currencies are stored in the database in the table "currency_codes".

Table "public.currency_codes"
Column | Type | Modifiers
---------------+------------------------+---------------------
iso | character(3) | not null
currency_name | character varying(200) | not null
supported_p | character(1) | default 'f'::bpchar
symbol | character varying(10) |

18.2 Supported Currencies
However, not all of these currencies are usually needed in a company at the same
time. This would lead to very big drop-down lists in the GUI. Instead, the system
uses a list of "supported currencies". There are by default: AUD, CAD, EUR, JPY
and USD. Supported currencies are marked using the "supported_p" flag. Please
see the figure below for the default configuration.

projop=> select * from currency_codes where supported_p = 't';

iso | currency_name | supported_p | symbol
-----+-------------------+-------------+--------
AUD | US Dollar | t |
CAD | US Dollar | t |
EUR | Euro | t |
JPY | Japanese Yen | t |
USD | US Dollar | t |
(5 rows)


In order to add or remove a "supported" currency you will have to execute an SQL
command manually. The following SQL command add Russian Rubles ("RUR") to
the list of supported currencies:

ptdemo=> update currency_codes set supported_p='t' where iso='RUR';

18.3 Currency Conversion
Please Note: The currency conversion functionality is still in experimental status
and is not supported as part of our normal support packages (Basic, Silver or
Gold support and free SourceForge support). Please contact us for other support
options.
The calculation of "Profit & Loss" of a project and other financial indicators require
normalizing the amount of financial documents to a single currency, so that the
amounts can be summed up.
In order to do so the system needs an up-to-date list of exchange rates of all
"supported currencies" (see the subchapter "Currency Configuration" above for
details). These currency rates and their maintenance are covered by the " intranet-
exchange-rate" ]po[ package. This package defines a list of daily exchange rates
between all "supported currencies" and the USD.
------------------------------------------------------------
-- Exchange rates of currencies with respect to the US dollar
------------------------------------------------------------

create table im_exchange_rates (
day date
constraint im_exchange_rates_nn
not null,
currency char(3)
constraint im_exchange_rates_currency_fk
references currency_codes,
rate numeric(12,6),
manual_p char(1)
constraint im_exchange_rates_manual_ck
check (manual_p in ('t','f')),
constraint im_exchange_rates_pk
primary key (day,currency)
);

The default ]po[ configuration already contains the exchange rates for the default
currencies AUD, CAD, EUR, JPY and USD between 1999-01-01 and 2005-06-30.
Also, the package includes a maintenance screen that allows you to update the
exchange rates for later dates.


18.4 Calculating Multi-Currency Sums
This package can be used to calculate multi-currency sums of financial items. This
functionality will be completely integrated into the version V4.0 of ]po[. Until then
you will have to use this package manually for your reporting SQL queries.
Here is a sample SQL query that takes advantage of currency conversion to
calculate the list of all cost items in EUR and USD:

select
cost_nr,
effective_date,
im_category_from_id(cost_type_id) as cost_type,
customer_id,
amount,
currency,
amount * im_exchange_rate (effective_date::date, currency, 'EUR') as euros,
amount * im_exchange_rate (effective_date::date, currency, 'USD') as dollars
from
im_costs
order by
customer_id,
cost_nr;

18.5 Exchange Rates Details
The "im_exchange_rate" procedure (see example above) calculates the exchange
rate between supported currencies at a given day.

im_exchange_rate(date, char(3), char(3)) -> float

This function uses the "im_exchange_rates" tables to lookup the exchange rates
for both currencies on the given day. The conversion function will take the last
available entries in the table if there is no value for the current day.


19 File Server Integration
This chapter describes how the intranet-filestorage module can be linked to a
Windows or Linux file server. This integration allows users to access the ]project-
open[ files from their Windows desktops using the Windows Explorer.
19.1 Configuring Filestorage Parameters
Members of the ]po[ Administrators profile can modify several parameters of the
Filestorage module.

Figure 3: Filestorage Parameters under Linux or Solaris

These above listed parameters allow mapping Filestorage base directories to
specific locations in the file system of the underlying operating system. The figure
above shows a sample from an Unix-ish operating system. Equivalent values for a
Windows OS are C:/Project-Open/filestorage/companies for example (please
note the forward slashes in Windows filenames).
The following table describes the parameters briefly:
Parameter Description
CompanyBasePathUnix The file system path for Filestorages related to
companies.
HomeBasePathUnix The file system path for the global Home
Filestorage.
MaxNumberOfBytes Allows configuring an upper limit of the size of files
to be uploaded. 0 means that there is no upper
limit.
ProjectBasePathUnix The file system path for Filestorages related to
projects.
ProjectSalesBasePathUnix The file system path for Filestorages related to
project sales activities. Please see the description


below for more information.
UserBasePathUnix The file system path for Filestorages related to
users.

19.2 Integration With an Existing File Server
The ]po[ Filestorage is designed to be integrated with an existing Windows or
Linux fileserver. This means that a file can be accessed not only using ]po[ but as
well directly through file managers of the respective operating systems or other
applications.
]po[ Filestorage always takes its list of files from the existing file server so that
there is no possibility for conflicts or inconsistencies.
This mechanism allows users to access the files in two different ways: Staff
members from within the office are able to access the local Fileserver directly
using their Windows Explorer software. Users working outside the office (sales
representatives, freelancers, customers, home users) can access the same files
via the Internet using ]po[ filestorage.
19.2.1 Integration with a Windows Server
The following instruction guide you step-by-step through the process of setting up
an integration between a Windows file server and Linux machine.
On the Windows Side:
1. Create a new Windows user:
Create a new Windows user (i.e. "projop") with a specific password
("secret").
2. Create a Windows share:
On Windows create a new folder (i.e. "projects") and publish this folder as a
Windows "share" (Properties -> Sharing -> Share this folder). Grant "admin"
permissions to user "projop".
3. Enable Plain Text Passwords on Windows 2k/2k3:
From the Samba HOWTO: Using the registry editor (regedit), create the
registry setting
HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\LanmanW
orkStation\Parameters. Add a new DWORD value: Value Name:
EnablePlainTextPassword Data: 0x01. Once these registry changes have
been made, reboot the Windows machine and try to map a network drive on
the Samba server again. It should work as long as the Samba server is
using plain text passwords.


4. Check whether that works from the Windows side:
Use a second Windows (!) machine to check whether the share "projects" is
accessible with the password etc.
On the Linux Side:
1. Create a /etc/hosts entry for your Windows server. Add a line such as
192.268.0.4 fs
"fs" is just and example and stands for File server. You can choose the
name freely.
2. Install a standard Samba version on the ]po[ Linux server using YaST or
whatever package manager.
3. Check if Samba works:
Check if the Windows share is visible from Linux: Issue:
smbclient -L fs
You should see a list of shares, including "projects"
4. Create a mount directory:
Issue "mkdir /mnt/projects" on Linux. This is the place where the
Windows share will appear on the Linux side
5. Manually mount the Windows share: Issue
mount -t cifs -o username=projop,password=secret
//fs/projects /mnt/projects
Issue mount to check if the new share has been mounted. Issue: ls -l
/mnt/projects to check for files on the Windows server. Unmount
manually with umount /mnt/projects.
6. Add an entry to /etc/fstab:
Add the following line to /etc/fstab:
//fs/projects /mnt/projects cifs
username=projop,password=secret,uid=projop,gid=users
This line assumes that you are running the ]po[ AOLserver with
user="projop" and group="users", as it is the case in the default ]po[
installers.
Please consult the Linux "Samba HOWTO" for more information or post into the
"Open Discussions" forum at www.sourceforge.net/projects/project-open/ for
questions and issues.
Notes:
Please note that the Linix/Windows Samba integration is a quite critical part
of a ]po[ installation. Problems are difficult to diagnose and reproduce,
particularly if they appear to an external user who wants to download or
upload a file.


We have usually prefer CIFS over SMBFS as the mounting protocol,
because CIFS is capable of reconnecting if the Windows server should go
down for a reboot etc. SMBFS does not reconnect, so you would have to
reconnect manually.
However, we had some issues with unreliable connections in the past with
CIFS (in 10/2006), while SMBFS seemed to run more smoothly. So SMBFS
could be an option, in particular if ]po[ is installed on a VMware running on
the file server. This is the configuration that we recommend to small
companies.
19.2.2 Understanding Access Permissions of Unix and Unix-
like operating systems
Access permissions between ]project-open[ and the operating system may be an
issue under Unix-ish operating systems (Linux and Solaris), because of the default
behavior of Unix daemons. These processes create new files and subdirectories
with the user-ID and group-ID of the daemon and only have read permissions for
their user-ID and group-ID (even if you add the daemons user-ID to /etc/group).
This situation may lead to the case that users dont have permissions to read the
]po[ files and the other way around.
The solution of this issue is to run the ]po[ daemon with the same group-ID as the
default group-ID of the users who are accessing the file server directory (i.e.
users).
19.2.3 Understanding Windows File Server Access
Permissions
There should be no issues when integrating ]po[ with a MS-Windows based file
server, because Windows files inherit access permissions from their parent
directory by default.
19.2.4 Separating Sales Documents From Other Documents
Some corporate documents may be too sensitive to keep them in the same
fileserver as the usual project documents. Therefore ]po[ facilitates a second
Filestorage module that is only accessible by typing a particular URL.
The corresponding Filestorage is shown when executing the ProjectViewPage with
the URL variable view_name=sales. You can enable the sales filestorage by
adding a new menu entry in the Menu Administration page, similar to the Files
entry.


20 System's Integration, APIs and "User Exits"
]project-open[ supports the integration with 3rd party systems to allow customers
and partners to create integrated process management solutions. There are
several tools available to facilitate this integration:
20.1 Application API
The ]project-open[ application is different from many other application in terms of
software architecture. ]po[ objects "are located" in the database, but not in the
memory. Or to phrase it differently: ]po[ has an object-oriented database model,
but not an object-oriented GUI (Graphical User Interface). In particular, there is no
application state stored in memory. All transactions are immediately written back to
the database.
This structure leads to a particularly simple API, consisting of:
- A "Read" API, consisting of SQL "select" statements and
- A "Write" API, consisting of PlPgSQL procedures to create new objects in
the database.
Please consult the PO-API-Description for details about the API. This guide will be
available around 7/2006. For a high-level description of the data model please see
the ]project-open[ "Core" Architecture slides in the "White Papers" section of our
web site.
20.2 User Exits
"User Exists" are a technique to inform 3rd party applications about "events" in the
]po[ system. Basically, ]po[ calls certain Unix shell scripts when special actions
happen inside the ]po[ system.
Users:
- user_create(user_id): A new user has been created
- user_update(user_id): An existing user has been updated.
- user_delete(user_id): A user has been removed from the list of active users
Projects:
- project_create(project_id): A new project has been created
- project_update(project_id): An existing project's main data has been
modified
- project_delete(project_id): A project has been marked with the status
"deleted".
Tasks (]project-translation[ and ]project-consulting[ only)


- task_create(task_id): A new task has been created
- task_assign(task_id, user_id): A task has been assigned to a user
- task_update(task_id, new_status_id): A task has been modified
- task_finish(task_id): A task has been finished
- task_delete(task_id): A task has been deleted.


21 System Administration
21.1 LDAP Authentication
]project-open[ supports the integration into infrastructures of larger corporate
environments via LDAP and in general via Unix or Linux PAM (Pluggable
Authentication Modules). For installation details please refer to the OpenACS
Administrators Guide at: http://openacs.org/doc/openacs-5-1/acs-admin.html.
21.2 Backup and Recovery
Please Note:
Application backup is deprecated now and not supported anymore. Instead,
we advise you to use the PostgreSQL database backup because it is more
reliable and guarantees that certain new features of ]po[ are going to be
included in the backup.
For generic backup and recovery please refer to the OpenACS Administrators
Guide at: http://openacs.org/doc/openacs-5-1/acs-admin.html. Also, please refer to
the ]project-open[ Operations-Maintenance-Guide for specific configurations.
21.2.1 Restoring Application Tables
The ]project-open[ application tables can be restored from a previous backup via
the maintenance screens in Admin / Backup and Restore Data. These screens
will show you all previously existing backup file sets (make sure the paths for the
backup/restore locations are correct in the Parameters admin section).
When restoring the files from a previous backup, they are loaded in a specific
following order:
Im_users
Im_offices
Im_companies
Im_projects

This is necessary because of the dependency between the different tables. Missing
entries in one table may cause many errors in the following ones.
There are some cases where you can get database errors during the import. These
errors are clearly shown in the import result screens. In such cases please edit the
CSV file and check the respective lines for special characters, in particular double
quotes and remove them or replace them by single quotes.


However, please not that you can import tables multiple times without getting
duplicate entries, due to the specific table structure of ]project-open[. So you can
fix errors by editing a table and restart the restore process again.
21.2.2 Restoring Tables From V2.1.X
You will need to pre-process the backup when restoring from a V2.1.X version of
]po[:
Verify that im_categories doesnt contain entries that conflict with categories
in the new version and change to category_id from these entries.
Rename filenames from *customers* into *companies*
Edit these files and replace all occurrences of customers by companies
in the file header (the first two line of the file)
Edit the file im_projects.csv and replace as above
The rest of the tables should enter without any change.
21.2.3 Restoring Tables From Earlier Versions
It is not possible to import tables from V1.0 and V1.1, due to incompatibilities of the
data model.


22 Example Configuration Session
Sample Production Installation on Linux: The following is a transcript from a
sample ]po[ configuration session on Linux. The transcript is held informally by
intention.
22.1 Cleaning up an Existing Configuration
Stopping the projop server (if there is one):
servidor:/web/projop/packages # less /etc/inittab
servidor:/web/projop/packages # emacs -nw /etc/inittab
servidor:/web/projop/packages # killall -HUP init
servidor:/web/projop/packages # ps aux | grep projop
Drop the PostgreSQL DB (if there is one)
servidor:/web/projop/packages # su - projop
projop@servidor:~> dropdb projop
Create a new database
projop@servidor:~> createdb projop
Restart the server
- Enable projop in /etc/inittab
servidor:/web/projop/packages # emacs -nw /etc/inittab
servidor:/web/projop/packages # killall -HUP init
servidor:/web/projop/packages # ps aux | grep projop
...
Starting the data model installation (=> Chapter 3)
22.2 Basic Configuration
Login into the fresh server
I go to /acs-admin/apm/ and install the Project/Translation packages:
intranet-core
intranet-cost
intranet-dw-light
intranet-filestorage
intranet-forum
intranet-hr
intranet-invoices
intranet-payments
intranet-timesheet
intranet-trans-invoices
intranet-translation
intranet-update-client
At the end of the page I see:
Unable to get file list from 'C:/ProjectOpen/filestorage/home
find_path=C:/ProjectOpen/filestorage/home
/bin/mkdir: cannot create directory `C:': Permission denied
=> This is still the Windows configuration, I need to change the
parameters to Linux/Unix
I go to /intranet/admin/parameters/ and copy the parameters from
http://ptdemo.dnsalias.com/. Im maintaining the default settings with


web/projop/filestorage/... for the moment. I create te following
filestorage directories:
servidor:/web/projop/filestorage # mkdir project_sales
servidor:/web/projop/filestorage # mkdir users
servidor:/web/projop/filestorage # mkdir templates
servidor:/web/projop/filestorage # chown -R projop:projop *
I check the homepage again and not its OK.
I'm on the homepage and I'd remove the ugly "help blurb" in:
/intranet/admin/components/ and setting the location of "Home Help
blurb" to none.
I check Companies in order to create three sample companies: A
customer, a provider and the "internal company" (=> Chapter 6)
I see that "CustOrIntl" is visible as company type. This is a know bug
from V3.0.0.0.7. So I modify the database to set this category as an
abstract class:
servidor:/web/projop/filestorage # su - postgres
postgres@servidor:~> psql projop projop
projop=# update im_categories set parent_only_p='t' where
category='CustOrIntl';
projop=# \q
I go to /intranet/users/ in order to add the administrator
admin@<Company Name>.com to "]po[ Admins" and "Employees". There is no
user in the Employees view, so I change to All Users.
22.3 Permission Configuration
I do the "Profile" permission configuration with a relatively
permissive setting, allowing PMs to see and add financial documents.
"Employees" are just in-house translators then.
I've done "User Matrix" permission configuration with the standard
setting from PtDemo

Acc-
ounting
Cus-
tomers
Employ-
ees
Free-
lancers
HR
Managers
]po[
Admins
Project
Managers Sales
Senior
Managers
]po[ Admins
vRwa vRwa vRwa vRwa vRwa VRWA vRwa vRwa vRwa
Customers vRwa vrwa vrwa vrwa vrwa VRWA vRwa VRWA VRWA
Employees vRwa vRwa vRwa vRwa VRWA VRWA vRwa vRwa VRWA
Freelancers vRwa vrwa vRwa vrwa VRWA VRWA vRwa vRwa VRWA
Project Managers vRwa vRwa vRwa vRwa VRWA VRWA vRwa vRwa VRWA
Senior Managers vRwa vRwa vRwa vRwa vRwa VRWA vRwa vRwa VRWA
Accounting vRwa vRwa vRwa vRwa VRWA VRWA vRwa vRwa VRWA
Sales vRwa vRwa vRwa vRwa VRWA VRWA vRwa vRwa VRWA
HR Managers vRwa vRwa vRwa vRwa vRwa VRWA vRwa vRwa VRWA

22.4 System and DB Configuration
Checked error reporting
=> Working OK with the default values from V3.0.0.1.1


Checked Online Software Updates with an update to V3.0.0.1.1.
=> Working OK
Checking PostgreSQL "Full DB Backup"
=> Successful. The exported file looks OK.
Security configuration seems already OK.
The pg_hba.conf contains only a local entry, which is OK for a
production server if users can
No "PostgreSQL Vacuum" contrab yet.
=> Root Crontab:
# Full PostgreSQL vacuum every night
20 3 * * 0 su - postgres -c "/usr/bin/vacuumdb -a -f" >>
/var/log/vacuumdb.log 2>&1
Database Backup: No backup configured yet
=> Root Crontab:
# Backup PostgreSQL "projop" database every night
20 3 * * 0 su - projop -c "pg_dump -c -O -F p -f
/web/projop/filestorage/backup/pg_dump.
`/bin/date +\%Y\%m\%d.\%H\%M`.sql " >
/var/log/pg_backup.log 2>&1
However, you will have to include the backup files in your daily
server tape backup.
File Server Integration:
=> You still have to modify the "intranet-filestorage" parameters in
Admin / Parameters for your current "projects" directory.
22.5 Basic GUI Configuration
I copy index.tcl and index.adp from the PtDemo system to
/web/projop/www/ (=> Chapter 17).
These pages still contains the default login (Ben Bigboss), so you
still need to change them.
I add the <Company Name> logo in /web/projop/packages/intranet-
core/images/<company-name>-logo.gif. Ive created this GIF using
PhotoShop using a screenshot from <Company Name>s website and
removing the background using the magic wand.
I've copied the PtDemo invoice tempates to
web/projop/filestorage/packages and checked that a sample invoice
would show OK. However, you would have to adapt the templated you your
corporate CD/CI


Ronda Sant Anton, 51 1 2a
08011 Barcelona, Spain
Tel.: +34 93 325 0914
Fax.: +34 93 289 0729

Project Open - Configuration Guide.071121

Uploaded by

Copyright:

Available Formats

Project Open - Configuration Guide.071121

Uploaded by

Document Information

Original Description:

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Project Open - Configuration Guide.071121

Uploaded by

Copyright:

Available Formats

]project-open[ V3.

You might also like