Admin Admin User Profiles
The User Profiles page shows all the current profiles active on the system and what actions they are capable of/prohibited from performing. Check the corresponding box with respect to the profile and action, and then press "Save Changes" to update the permission settings. The permissions are sorted alphabetically and can be filtered by their "Pretty name".
All creation/deletion/modification of User Profiles is done from this screen.
To set profile permissions with respect to other users and not actions see the User Matrix page.
For more description about the specific range, control and context of each individual permission setting, see User Profile Permissions.
References
- Admin Home
- User Matrix - vertical profile permissions
- User Profile Permissions - a description of each permission
Admin Admin Categories
Categories are a very important and essential element to ]project-open[. They are used to control the "type" and "status" of objects, and are the primary control mechanism for drop-down menu selection all over ]project-open[. Editing and extending the categories should be done with care and caution, because some category types and stati are system constants used throughout the system, so editing them could possibly have dire side effects system wide. See a list of the most important Categories in the ]project-open[.
Category Type vs. Category
(Screenshot displaying all categories belonging to the category type "Intranet Absence Type".
A Category Type is representational of a grouping of categories, the category being one of a possible set of values that could satisfy the current state of the category type. In the example above, we have several categories as options to fill in as the possible value of "Intranet Absence Type". The list of categories that belong to each Category Type are unique, so the "Active" category of "Intranet Foo Bar" is unique and does not share the same underlying system value as the "Active" of "Intranet Sna Fu." Categories as implemented in ]project-open[ control options input values on drop down menus, for instance, whenever users are prompted to specify what type of project a project is this box has "Intranet Project Type" selected as its source, and will consequently displaying each of its categories as options for selection.
Add Category Type
To add a new category type, click on the link "Add a new Category Type" located under "Admin Links". This option is only present when "All" Category Types are selected from the Filter.
- New Category Type - the name by which this new category type is known
- Category Nr. - the internal numerical representation of this category type, only edit this if you very sure what you are doing, the automatically generated number will work fine.
- Category Name - Category Types exist to have categories, so provide the first new category name for this category type
- Category Translations - the translations of this category for when the system locale is set to this language only active system locales will be presented as options, please make sure that the "en_US" translation is identical to the new Category Name
- Int 1, String 1 - Integer and String values that can be associated with the category name, not the new Category Type. This is useful in instances where you would always like to a number or string come up or be closely related to a category value for example Category "Spanish VAT Tax" in "Intranet Category VAT" having the value 15%.
Add Category
To add a category to a pre-existing Category Type, use the filter to find the desired category type and use either the Admin Link "Add category" or use the link found at the bottom of the list of categories. The resulting screen is exactly the same as above, except that the Category has already been filled in for you.
To modify a pre-existing category, click on the category name as it appears on the list and alter the details in the resulting screen. Be very careful about this, as many categories are used as system constants and their alteration will lead to undesired/non-functioning results in the system. Consult the context help for each category type at Categories.
Please also note that in order to model category hierarchies you currently have to add not only the direct ancestor hierarchy but ALL parent categories to the "Parent Section"
References
- Admin Home
- Categories - the object type description and it's role in the data - model
- Category List - a listing of the major ]project-open[ categories, with entries for each category
Admin Admin Cost Center Permissions
The "Cost Center Permission Help" is an administration to control and determine the access rights for financial documents within a company cost center. This is designed for use in larger corporate environments where a department head should be able to see what's happening in his group. However, he or she should not necessarily know what's going on in other departments and in the company as a whole.
The following table shows the Cost Center hierarchy and lists the access permissions for each Cost Center and each user profile.
Please note that this table inherits from the permissions set in the 'Admin - Profiles' section. You can't remove permissions here that you have set there.
Abbreviations
In the following, the first line refers to to Read permissions, while the second line revers to Write permissions:- R - Read All - User can read all types of financial documents for this Cost Center
- W - Read All - User can create/modify all types of financial documents for this Cost Center
- I - Customer Invoices
- Q - Customer Quotes
- D - Delivery Notes
- B - Provider Bills
- P - Purchase Orders
- T - Timesheet Information
- E - Expense Reports
(User has Read privileges on all documents, but no Write privileges.)
Upper case letters signify that the user has the privilege. Lower case letters signify that they do not. Individual privileges can be activated and dis-activated on a single case by case basis clicking on the letter, which will then toggle to the opposite of what it previously was.
References
Admin Admin SQL Profiling
The SQL Profiling page provides information about interactions between the database and commands and queries being issued from within the ]project-open[ interface. This is useful in tracking down lags and seeing the actions leading up to crashes. From the main page a list of every command run on the database within the parameter range of time can be seen.
The time and duration of the query are recorded along with the IP address and the file pathname containing the SQL. If you would like to see the SQL along with the statistics associated with each SQL commands, first turn on,
- "Database statistics is currently off (turn it on)"
and make sure that the statistics have been enabled. Once they have been enabled, click on any of the commands that are listed and get a more detailed breakdown of what exactly was contained in each request.
To set the parameters on the time window and other viewing options click,
- "Set Package Parameters"
for an options menu.
References
- Admin Home Page
- [Interactive Shell] - executes commands and displays their results by direct interaction with the AOLserver
Admin Admin Restart Server
Pressing this link will force a restart of the AOLserver. Depending on your machine specifications it may take from 15 seconds up to 5 minutes for the AOLServer to be available again.
References
Admin Admin Parameters
]project-open[ parameters control the appearance and behaviors of options that are configurable within the application and specifically linked to each individual package. The parameters list screen is grouped by package, with each parameter belonging to the package listed above it. The parameters are editable in batch mode per package, that is, no single parameter is editable from the main screen, one must click on the package name corresponding to the desired parameter, and be linked to a page showing all the available parameters in this package in editable form and then find and alter the desired parameter.
The main page lists each package, followed by their parameters, in alphabetical order. Clicking on a package name allows you to edit the parameters.
References
Admin Admin Menu Permissions
Setting view rights on pages per user profile. Permission setting from this page is not just limited to menus, but also tabs, links, and reports. Upper case letters signify that the user profile has the permission. Add a new menu using the link located at the bottom of the list.
R - read web page, menu, tab, etc.
To see the corresponding menu to this entry and other details, click on the hyper-linked name.
The URL path name given is where this menu can be found. Append this name to your server URL to view it. Click on "Detailed Permissions" if you are interested in more than just viewing or read rights on the page.
References
Admin Admin Materials
Since ]project-open[ is a Project Management based tool for use by service companies the primary "material" in question is the time and skills of employees. This is not to exclude the listing and management of tangible goods and materials from this screen, but this is the primary use we envision for our traditional customers with ]project-open[ in production.
Click a material to edit it's details and use the link "Create New Material" located at the top of the page to add another material to the list.
References
Admin Admin Localization Home
]project-open[ is designed for use in multi-linguistic environments. For instructions on how to localize/translate ]po[ consult Localization. If you are interested in enabling an already supported language, this page covering covering admin actions within the localization sub system should be of help.
The localization system in ]project-open[ is an adapted version of OpenACS's localization sub-system with only slight change.
Toggle Translator Mode - Switch translation mode off/on. Translation Mode lets you go through ]po[ screen by screen, clicking on Strings as they are graphically presented and translating them.
Change System Locale/Timezone - set the default language for users. Users can edit their own details with "My Account". These settings take effect for new users, login screens, or when a translation string can not be found in the desired language.
Import/Export All Messages - using the catalog files found at "acs-lang/catalog" import/export all the translation strings in XML format. If you only desire to import/export the message strings of a particular language, click on the hyper-linked "Label" of the language to be presented that option.
This is the list of all actively supported languages. Just because a language is listed does not signify that it has been fully translated throughout ]project-open[. To edit the details of a language as presented on the list, click on the pencil and paper located to left of the "Locale" entry. If you would like a language to be presented as an option on drop-down menus throughout ]project-open[, first enable it by checking the appropriate "Enabled" box. To add a language not currently presented on the list, use the link "Create New Locale" at the bottom of the page.
Click on the desired language to be lead to a package by package listing of localization strings. Or search all available strings within the language. Click on a specific package to see all the strings and translate them.
A list of all message keys within the package, its English translation, and the corresponding translation into the target language if available. Use batch translation to speed up work. Click on a single message key if you only wish to translate that one specific string.
References
Admin Admin LDAP Authentication
]project-open[ can link to a directory server using LDAP to provide authentication services for users. ]po[ is not limited to a single directory server and can hold links to multiple servers at one time, offering users a selection upon log-in to chose their appropriate directory server instance.
References
Admin Admin Interactive Shell
This is an interactive server that allows admins to execute commands in the context of the AOLserver and see their results, which is part of of the underlying OpenACS application. This would include all commands found within the API Doc and any generic TCL commands.
(Screenshot showing the results of a generic database query on projects)
References
Admin Admin Exchange Rates
This page displays a history list of the currency rate fluctuations on the system for the Active Currencies on the system. An active currency is one that has been designated as one of the active currencies and shows up as an available option on drop down menus throughout the system. This is NOT the place to either add a new currency that is not already present in the ]project-open[ currency database or to set a particular currency as the system locale. To introduce a new currency (not already present), it can only be added by modifying the currency list within the source code and then updating the system. To set a currency (already present) to the system default is done at the Parameters page with the parameter DefaultCurrency located under the heading "intranet-cost".
The 'US Dollar' currency is required and can't be modified. The value of the US Dollar should always be '1.0', because it is the reference currency, and therefore internally every currency is expressed in it's relative strength versus the US Dollar.
- Add Active Currency - select a new currency from the pre-existing list of available currencies to add to the list of active currencies on the system
- Update Exchange Rates - update the system's exchange rate information to reflect the current ones
Add Active Currency
From the Exchange Rate Home Page, look to the left hand side Navigation Bar and under "Admin Links" click on "Manage Active Currencies". You will be shown a list of all the current active currencies on the system i.e. currencies that will appear as options when users are asked to input fiscal data. From this menu you can remove currencies from the active list, or using the drop down menu to the right you can choose to add another currency to list.
Update Exchange Rates
To make sure the exchange rates stored on ]project-open[ reflect the current global exchange market it is necessary to update them. This action is simple, and only requires a click on "Get Exchange Rates" button. While that is the only technical issue involved, due to the sensitivity and volatility of this financial information, the first question to arise otherwise is Who to trust for the most reliable and up to date information? Currently, ]project-open[ connects to X-Rates a free and public web-site for currency trading information. For any business not wishing to rely on this service, we can either be contacted for other solutions, or you can delve into the source code and manually update the internal exchange rates by hand.
The history of the exchange rate fluctuation as recorded on ]project-open[ is listed on the Exchange Rate homepage so that any discrepancies can be tracked.
References
Admin Admin DynViews
Dynamic Views or "DynViews" control the display settings on the primary list pages. These pages would be the main pages a user lands on after clicking on tabs like "Projects", "Users", "Companies". These views can be accessed in the code of content pages to produce the resulting layout.
Each "view" has an id and a name. Add new views from this page. Click on the "View Name" entry to link to more detailed information about the specific details on the view.
From here, new columns can be added to the view, or existing ones can be modified by clicking on them, affecting the visual outcome.
References
Admin Admin User Matrix
A matrix chart showing the user permissions in relation to other system profiles. See User Profiles to set permissions on a per action basis per user profile. This is a "who can see who" display of permissions, showing the degree of interaction possible between user profiles. Along the X-axis is each user profile, with an entry representing that user's profile permissions compared to the corresponding profiles along the the Y-axis.
- 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 user” (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 types of users. "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 the user's data.
|
|
Accoun
|
Custo
|
Emplo
|
Free
|
]po[ Admins |
Project Mana
|
Sales |
Senior Mana
|
|
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 |
(Upper Case letters signify that the user has the permission, lower case that they do not.)
For users that belong to more than one profile group their total permissions are the union of their various profiles. For example, a user who is both a "Senior Manager" and an "HR Manager" will have the aggregate permissions of these two profiles when interacting with other users, so belonging to multiple user profiles is not mutually exclusive.
For users wishing to interact with other users belonging to multiple profiles, their rights over the user are the intersection of their permissions over the multiple profiles. For example an "Employee" wishing to view a user who is both a "Senior Manager" and an "HR Manager" must have view rights over both these profiles, not just one in order to view the other user.
USER 1 belongs to Profile A and B
USER 2 belongs to Profile C
USER 3 belongs to Profile C and D
USER 1 Permissions on USER 2 = { Profile A Permissions (w/respect to C) ∪ Profile B Permissions (w/respect to C) }
USER 1 Permissions on USER 3 = { Profile A Permissions (w/respect to C) ∪ Profile B Permissions (w/respect to C) } ∩ { Profile A Permissions (w/ respect to D) ∪ Profile B Permissions (w/ respect to D) }
References
Admin Admin User Exits
"User Exits" are a technique to inform 3rd party applications about "events" in the ]po[ system. Basically, ]po[ calls certain Unix shell scripts when special actions occur 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.
References
Admin Admin SysConfig Wizard
System Configuration (SysConfig) is meant to be used as a wizard for a fresh ]project-open[ install, to guide configuration for the first steps of ]project-open[.
- Basic Configuration Wizard - everything one would imagine from the title.
- Disable everything except SysConfig Wizard - force users to complete the wizard before using ]project-open[.
- Delete Security Tokens - clicking on this will delete all security tokens
Security tokens are the authorization data that users carry around with them like badges during their session. This can be a security concern, since all ]project-open[ downloads begin with the same security token seed number, theoretically should you never have changed the security tokens your system will be vulnerable since anyone could login with the same security token that is distributed all ]project-open[ downloads. Once you perform this action once however, the system is planted with a new seed, and safe as ever. This action is performed automatically on completion of the SysConfig Wizard.
- Move Projects & Forum Topics - used for demo servers to keep data fresh and current
References
Admin Admin Site Map
A listing of all "mounted" packages and their directory contents. For each mounted package you can:
- Set global access permissions for all pages of the package.
- Set parameters for the package.
- Delete or unmount the package.
To mount package contents so that they are available to the underlying sever, simply click on the "mount" option. Other options of interest include "permissions" and "parameters" two options associated with each package that display all permissions/parameters directly linked to this package. Installed yet unmounted packages are distinguishable because they lack an entry for the column heading "Instance".
References
Admin Admin Portlet Components
This screen controls the display options for all "Components" found throughout ]project-open[. Components are add-on displays that track information, usually time sensitive materials or continually updating and changing information. Three component examples below,
One of the easiest ways to identify a component is finding the light gray bar that extends from the component title and activates its visibility by passing the mouse pointer close to the bar to display a few location GUI options, such as shifting the component to the left or right, or to close it completely.
The "Portlet Components" Admin Page displays a list of all possible system portlet components, but not if whether the portlet is currently active/enabled. The components are grouped by package, each component and it's functionality being contained within this package. Thusly, a component will not be available if its package has not yet been installed.
This screen also displays the current permission settings on each component and are set here as well. If you would like to enable a particular component, click on it's name to edit and view the options available for this component. The only way to create new components is by adding and modifying them through the source code.
Enable the portlet component and it will appear on the page of the URL listed.
References
Admin Admin @Home Page
The ]project-open[ Admin Home Page shows a menu list of all the available admin pages and links to each of the respective pages. This Admin menu is specific to ]project-open[ and should not be confused with the OpenACS Admin Home Page. Although the two pages are similar, the vast majority of administration actions in ]project-open[ occur from its admin homepage and not that of OpenACS.
- API Doc - indexed and searchable archive of all programming procedures
- Backup and Restore
- Cache Flush - purge the cache of all its current contents, clicking on this will not link to another page, but simply carry out the action
- Cache Status - monitor the cache contents line by line
- Categories - drop-down menu configuration
- Cost Centers - financial sub-divisions between a company and offices
- Cost Center Permissions - setting view/change rights for users on financial documents according to Cost Centers
- Developer Home - page unifying several useful resources for developers
- DynFields - tool to help extend the database automatically and graphically
- DynViews - control the display settings of list pages
- Exchange Rates - manage active system currencies and update exchange rates
- Interactive Shell - execute commands in the AOLserver and see the result
- LDAP - authentication server/configuration
- Localization Home - translate/language management
- Materials - inventory types
- Menus
- Package Manager - install/uninstall/update
- Parameters
- Portlet Components
- Restart Server - does not link to another page, restarts the server after users clicks, wait 2-5 minutes for service to return to normal.
- SQL Profiling - view and investigate all queries being run on the database
- Simple Surveys
- Site Map - mount packages
- [Software Updates]
- SysConfig - general system configuration using the SysConfig Wizard
- User Exits - subroutines invoked to link with third party applications
- User Matrix - "who can see who" user permission matrix
- User Profiles - define permissible actions per user profile or add/delete a user profile
- Workflow - manage workflow processes
Available Admin Operations from the Admin Home Page:
- Upgrade Information - check for available system updates and execute them
- Delete Demo Data - nuke all system data to start fresh
- Convert Parameters (Windows to Linux) - re-formats OS specific data so that data can be ported back and forth between OS's
- Convert Parameters (Linux to Windows) - the inverse action of the above
- Anonymize the Server - make user actions and activity on the server anonymous (useful for demo purposes)
- Import Data From LTC Organiser - import data from the outside LTC-Organiser Application
Admin Admin Cost Centers
Cost Centers are fully self contained financial divisions within the company, that each contribute to the overall financial state of the company. They help to clarify who is generating revenue, where funds are being spent, and by whom. Project costs and reveues that are generated can be designated as belonging to a specific Cost Center. Within each Cost Center, the hierarchy can be further classified into sub-cost centers within each larger cost center. Employees and Managers can be assigned to Cost Centers, which controls their access rights on viewing/modification privileges for financial documents.
(Screenshot of "Cost Center" homepage, displaying what employees are part of the cost center, and the Cost Center's hierarchical location.)
New Cost Center
Located at the bottom of the Cost Centers home page is a link to create New Cost Centers.
References
Admin Admin Cache Status
The Cache is a memory optimization that ]project-open[ uses to speed up actions that are resource costly and occur frequently. The main page displays the currently active caches and their operational statistics.
Each individual cache can be flushed by clicking on "flush". If you would like to see individual line-entries within the cache, search for the item's name. The most commonly cached items are SQL and database related values.
References
Admin Admin Cache Flush
Upon clicking the link "Cache Flush" all the currently held contents of the cache will be flushed. For a more detailed control of cache contents see Cache Status.
References
Admin Admin Backup and Restore
The ]project-open[ database regularly dumps all it's contents into a back-up directory. The frequency and schedule of these database dumps is not currently configurable from within ]project-open[, rather it is controlled by OS. In Linux systems this would be the cron daemon, and in Windows, scheduled processes.
The back-up path is configurable, and the directory path can be set in the Parameters Admin Screen under "intranet-core" as BackupBasePathUnix. The back-up admin page has two important functions:
- New Backup - force a database dump right now. This creates a new backup file instance.
- Restore - restore the database using the contents of the selected back-up file.
References
Admin Admin API Doc
The API Doc allows searches on all the active running code on the system, and general browsing of active running code, listed by package. The two primary coding languages present in the API are TCL and PostgreSQL. Basically this a graphical interface that presents and hyperlinks, and indexes the contents of the "sql/, tcl/, and www/" directories found in each package. The API Home Page consists of two important components:
- A Listing of all currently enabled and installed packages.
- A search bar for all the code that is currently enabled and installed.
The entry for each package consists of:
- Library Files - all ".tcl" files contained within this package
- Procedures - a listing of all procedures found within the ".tcl" files
- SQL Files - a listing of all ".sql" files found within this package
- Content Pages - a listing of all the code files (.adp, .tcl) that dynamically generate HTML pages basically everything located in the www/ directory of this package
Library Files
A listing of all ".tcl" files contained within this package. These files contain all the procedures used in code execution, therefore the majority of the file names are terminated in "procs.tcl". This is an alphabetically sorted list view of the files contained within the "tcl" directory of the files found in each package.
Clicking on an individual file name links to a page displaying a listing of all the procedures within the file and their names. If you are interested in the source code of a particular procedure, click on the specific procedure name. Procedures used internally by this procedure are hyper-linked to their own source. The source of accompanying Generic/PostgreSQL/Oracle XQL files is also shown, if available.
Procedures
This is a listing of all the procedures contained in the .tcl files of this package, presented alphabetically. Each procedure name links to a screen showing what specific .tcl file this procedure can be in and belongs to. Also , the source of the each procedure can be seen, as well as the source of related XQL files, if available. Note that procedures called within the body of this procedure are hyper-linked, so that you can quickly jump and see their source as well.
SQL Files
A listing of all ".sql" files contained within this package. These files contain all the create/delete/update routines run on the database. This is an alphabetically sorted list view of the files contained within the "sql" directory of files found in each package. Clicking on a particular file name will link to the source of the file.
Content Pages
A listing of all files responsible for generating HTML webpages that are the interactive screens that end users view and use to interact with ]project-open[. The majority of files responsible for dynamically generating content are ".tcl" or ".adp" for AOL dynamic pages. This is an alphabetically sorted list view of the files contained within the "www" directory of files found in each package. Clicking on a particular file name will link to the source of the file.
References
Admin Attribute Type Map
For DynField attributes that have been created within the system the specification on when and how they should been shown can vary depending on the sub-type of object they are. This is not a permissions setting page, but rather a customization that allows you to define the DynField based on background information available. For example, the field should a generic "A-B-C" classification for all "Company" type objects, but should be limited to a more specific "X-Y-Z" classification options when the object type is a "Software Company".
References
Admin Attribute Permissions
What User profiles should have the ability to view/edit newly created DynFields.
r - read
w - write
Upper case denotes that users have the privilege, lower case they do not.
References
Admin DynFields - Object Types
This page lists all object types that are extensible by DynFields. Only these types have been prepared to automatically display DynField values. The list of available extensible object types will grow in time with the program.
From the list view, clicking on either the "Pretty Name" or the "Object Type" name of an entry links to the following page.
A list of all current active attributes, that is attributes being used by widgets or displays within the system, is shown along with accompanying details such as to what database table and to what widget, this attribute belongs. Click on an individual attribute to learn more about it.
- Add A Completely New Attribute - create a new attribute that will become part of this object type
- Add An Attribute That Already Exists in the DB - add a pre-existing database attribute from another table to this one, to unlock the desired attributes you must add the corresponding extension table first. See below.
- Add A New Extension Table - unlock the attributes of another database tables making them candidates for extension to this database table
References
Admin DynField Permissions
This page allows Admins to set permissions on DynFields according to user roles. This determines whether a particular user should be able to see/edit the specific attribute on a widget, new creation form, etc. Find the corresponding object type and attribute the desired Dynfield pertains to and set the permission.
R - read
W - write
Upper case letters signfy that the user has the right. Lower case letters signify that they do not.
References
Admin ]project-open[ System Administration
This guide to ]project-open[ System Administration is written for and intended for use and consultation by both current SysAdmins needing to maintain ]project-open[ and developers who would like to improve/contribute/extend the ]project-open[ repository code. To efficiently locate material of interest:
- Perform a search with the search bar located on the upper right of this page.
NOTE: If you would like to perform additional searches from the page displaying the results of your previous search, please use the search bar located at the bottom of the page. The upper-right hand side search bar will also include information from the demo server, as well as the wiki.
- URL Look-Up
Use the Url of an admin page up to look up the corresponding wiki page entry for more details. Ex. The ]project-open[ Administration Home Page
/myserver/intranet/admin -> www.project-open.org/documentation/intranet_admin
Replace "/" with "_" and then append that name to "www.project-open.org/documentation/"
- [SysAdmin Tutorial] - start simple
Admin Admin DynFields
Dynamic Fields or "DynFields" is a system that enables Administrators or Developers to extend both the database and the consequent in program display of these attributes, automatically. That is, there should be no reason to examine or modify the underlying source code while making changes. Within the context of ]project-open[, DynFields are meant to be used as a developer resource as an alternative to time consuming customization changes on the source code. The principle demonstration of the strength of DynFields are when businesses request additional specialized fields that only affect them. Given a list of their requierements, a developer can scale the speed of their work by several factors, implementing this customization using DynFields.
DynField Extensible Architecture - this disscusses the general implementation of DynFields in ]project-open[
The process of adding/extending a GUI widget in ]project-open[ using DynFields is generally
- Creating/Identfying if already exists the widget that will correspond to the changes made.
- Extend the desired Object Type.
- Set the permissions on the widget.
- Object Types - The main DynField configuration page. Allows you to define DynFields per object type.
- Permissions - Defines who can read or write a DynField.
- [Widgets] - DynField-Widgets are pieces of HTML code to display the value of a dynfield, together with the definition of a value range.
- Widget Examples - shows a preview of all available widgets, a useful resource when testing modifications.
- Documentation - a locally stored copy of the text found here DynField Extensible Architecture
References
Admin Admin Developer Home
This page is as straight forward as it's name. A grouping of useful links to information about developing both OpenACS and ]project-open[.
References
Admin Admin Workflow
This is the management menu for workflow processes on the system. Each workflow that has been implemented on the system is listed here, with the number of active instances of each workflow currently on the system as well if there are remaining tasks that are unassigned. Click on the business proces name to examine and edit the details of each workflow.
- New Simple Process - a wizard help guides you through creating a new simple workflow to become implemented into the system
- New Advanced Process
References
Admin Admin Simple Surveys Permissions
Alter permissions about who is able to create and alter simple surveys on the system.
Set permissions on individual surveys by user profile. Use the link "Modify global survey permissions" to control permissions by user profiles on simple surveys in general, not just in relation to specific surveys.
References
Category Intranet Absence Type
This category defines various types of user absences, together with their specific workflow.
The absence type 5000-5005 are used as constants and may be associated with specific functionality. However it is OK to disable these types and/or to add new absence types.
Constant Range
The following absence types correspond to the default ]po[ configuration.
category_id | category | aux_string1
-------------+--------------+----------------------
5000 | Vacation | vacation_approval_wf
5001 | Personal | personal_approval_wf
5002 | Sick | sick_approval_wf
5003 | Travel | travel_approval_wf
5004 | Training |
5005 | Bank Holiday |
Absence Workflows
The aux_string1 value defines a workflow to be started when a new user absence is created. The workflow key needs to correspond to one of the workflows defined in Admin -> Workflow. Otherwise it is ignored.
Color codes absences
Color code for absences can be customized by providing a value for String 2 representing the color code.
References
Related Object Types
Related Categories
Category Intranet Absence Status
Defines the states or a user absence during its lifecylce.
The categories listed below are used as constants in TCL code and in PL/SQL procedures of absence workflows. However it is OK to disable these states and to define new states yourself.
Constant Ranges
category_id | category
-------------+-----------
16000 | Active
16002 | Deleted
16004 | Requested
16006 | Rejected
Constant Meaning
- Active: This is the default status if the absence is not controlled by a workflow.
With workflow control, this status indicates an approved absence. - Deleted: Technical deletion status. Absences in this status are not shown in the GUI.
- Requested: Initial state if the absence is controlled by a workflow.
- Rejected: Final state after the absence has been rejected by a workflow.
References
Related Object Types
Related Categories
Category Intranet Invoice Template (Deprecated)
This category is not used anymore.
Instead, please use Cost Template for specifying how to render ]po[ financial documents such as invoices, quotes and purchase orders.
Category Intranet Biz Object Role
System constant - please do not modify.
The category representss the types of relationships between business objects and their members.
Examples: Project Manager, full member (projects, offices, companies), Key Account.
Category Intranet Job Title
Constant Ranges
category_id | category
-------------+----------------------
151 | Linguistic Staff Jr.
152 | Linguistic Staff Sr.
153 | Project Manager Jr.
154 | Project Manager Sr.
155 | Freelance
156 | Managing Director
References
Category Intranet Office Status
Used to enable/disable offices. Possible additional categories include "Opening Soon", "On Vacation", "Closed until Further Notice", if you should feel a need for it.
Constant Ranges
Please don't modify the following categories that are used as constants:
category_id | category
-------------+----------
160 | Active
161 | Inactive
References
Related Object Types
Related Categories
Category Intranet Operating Systems
Operating Systems that are users are proficient and experienced in using.
Constant Range
category_id | category
-------------+---------------
2350 | Windows 98
2351 | Windows NT
2352 | Windows 2000
2353 | Windows XP
2354 | Linux
2355 | Windows Vista
2356 | Windows 7
References
Category Intranet Payment Type
Not used by ]project-open[ anymore. This category type has been replaced by Invoice Payment Method. However, we preserve these value for backward compatibility of older ]po[ installations.
Constant Ranges
category_id | category
-------------+---------------
1000 | Bank Transfer
1002 | Cheque
10116 | Wire Transfer
10117 | Check
References
Category Intranet Topic Type
Topic Types distinguish between the way how forum topics are used by the user.
- News: One persons creates a news for many others
- im_forum_topic: One person defines an incident that need to be resoved until a certain deadline and that can be assigned to another person.
- Task: Like an incident, but less urgent...
- Discussion: Many to many open discussion.
- Note: One person asserts something about the subject.
- Help Request: Not used anymore
- Reply: A reply to one of the previous topics.
Constant Values
The following constants should not be modified.
category_id | category
-------------+--------------
1100 | News
1102 | Incident
1104 | Task
1106 | Discussion
1108 | Note
1110 | Help Request
1190 | Reply
References
Related Object Types
Related Categories
Category Task Board Time Frame
Not used anymore.
Category Intranet Topic Status
Topic Status indicates the state of a forum item in the [forum package]. The stati are used to implement a status engine tracking the completion of forum tasks and incidents.
Constant Values
The following constants should not be modified or deleted. Also, it doesn't make much sense to add new stati.
category_id | category
-------------+---------------
1200 | Open
1202 | Assigned
1204 | Accepted
1206 | Rejected
1208 | Needs Clarify
1210 | Closed
References
Related Object Types
Related Categories
Category Risk Type
Modifiable by ? : AdminCategory Task Action Type
Modifiable by ? : AdminCategory CRM Interaction
Modifiable by ? : No - System Constant
Types of interactions with a ]project-open[ site, such as login, registration, viewing static contents, …
It's use has been deprecated, and no longer plays an important role in ]project-open[.
References
Category Intranet Customer Status
Modifiable by ? : Admin
Used for CRM sales pipeline and partner acquisition pipeline. You
could add values, but there are already too many of them.
Category Intranet Translation Subject Area
Modifiable by ? : User
Subject areas for translation projects. You can add and delete.
Category Intranet Translation Memory Tool
Translation Memory Tools that users are proficient in.
Constant Range
category_id | category
-------------+---------------------------
2100 | Trados 3.x
2102 | Trados 5.x
2104 | Trados 5.5
2106 | Trados 6.x
2108 | IBM Translation Workbench
2110 | Trados 7.x
References
Category Intranet Translation Memory Tools
Modifiable by ? : User
Skill Category: Translation Memories dominated by Freelancers
Category Intranet Translation Task Status
Translation task workflow support. All states are used as constants in the program code.
Constant Range
category_id | category
-------------+-----------
340 | Created
342 | for Trans
344 | Trans-ing
346 | for Edit
348 | Editing
350 | for Proof
352 | Proofing
354 | for QCing
356 | QCing
358 | for Deliv
360 | Delivered
365 | Invoiced
370 | Payed
372 | Deleted
References
Category Intranet Cost Center Type
This category has a diminished role currently, but should see more growth as ]project-open[ continues to develop financial controlling functions.
Constant Ranges
category_id | category
-------------+-------------------
3001 | Cost Center
3002 | Profit Center
3003 | Investment Center
3004 | Subdepartment
References
Related Object Types
Related Categories
Category Intranet Project Status
The project status category models the life cycle of a project from the preliminary acquisition and quoting phase onto the development and execution phase, and then finally invoicing the customer and receiving payment.
It is possible to extend the stati in this category. However, you should not modify the three main stati "Potential", "Open" and "Closed".
Project Stati:
- Potential
- Open
- Closed
- Pre-Sales
- Pre-Sales Negative Reply
- Project Execution
- Invoicing and Payment
- Constant Range
Potential
Potential stati refer to the sales and pre-sales phases of a project life cycle. During these phases, the sales team may have already logged hours and incurred other types of cost that need to be assigned to a project: but it is not yet clear if the customer will pay for these efforts.
The "Potential" status is used in many places in the system as a hard-coded constant, so please do not modify this status. If necessary, you can disable this status.
- Potential
The project has not yet been initiated but is speculatively being developed. - Inquiring
The first phase of contact with the customer to capture a lead. - Qualifying
The customer checks the qualification and capacity of the provider. - Quoting
The process of writing up a quote. - Quote Out
Waiting for the customer to sign the project.
Open
This status represents the execution of a project. "Open" is used as a constant in many parts of the system as a hard coded constant, so you should not modify this status.
- Open
Project has been initiated
Closed
This status documents why or how a project was terminated. "Closed" is used as a constant in many parts of the system as a hard coded constant, so you should not modify this status. A project may be closed in several different ways:
- Declined
The customer didn't sign the contract. We lost the project before it went into the "Open" status. - Delivered
We have successfully delivered the project. This status is the signal to the accounting department that invoicing can start. - Invoiced
The invoice has left the company. - Deleted
Creating the project was a test or an error, or the project had to be deleted for other technical reasons. - Canceled
Either the provider or the customer has canceled the project, even though it already reached the status "Open" at some moment.
Pre-Sales
- Potential
First idea of a project has been created. - Inquiring
The customer is inquiring for more data. - Qualifying
The customer is interested but needs to clarify the capabilities. - Quoting
Preparing a quote for the customer. - Quote Out
The quote has been send to the customer, but no reply has been received yet.
Negative Replies from Pre-Sales:
- Declined
The customer has declined on a quote, but there is still a chance to win the project with a new quote. - Deleted
There is no chance anymore to get forward with the project.
Project Execution
- Open
The project is being executed. - Delivered
The project has been delivered to the customer. - Canceled
The project has been canceled during the execution.
Invoicing and Payment
- Invoiced
An invoice has been sent to the customer. - Partially Paid
We have received some money, but not the whole amount. - Closed
The project has been successfully closed
Constant Range
category_id | category
-------------+------------
71 | Potential
72 | Inquiring
73 | Qualifying
74 | Quoting
75 | Quote Out
76 | Open
77 | Declined
78 | Delivered
79 | Invoiced
81 | Closed
82 | Deleted
83 | Canceled
References
Related Object Types
Related Categories
Related Tutorials
Category Intranet Translation Quality Type
To evaluate user proficiency.
Constant Range
category_id | category
-------------+-----------------
110 | Premium Quality
111 | High Quality
112 | Average Quality
113 | Draft Quality
References
Category Intranet Annual Revenue
This annual revenue figure refers to the estimated company turnover of a customer company, data that is primarily used for the CRM module to categorize clients. The current values are all in euros, simply add more categories if revenues are generated in other currencies.
Constant Ranges
category_id | category
-------------+-------------
222 | EUR 10-100k
223 | EUR 0-1k
224 | EUR 1-10k
225 | > EUR 100k
226 | Pre-revenue
References
Category Intranet Company Status
Used for CRM sales pipeline and partner acquisition pipeline. Some Company States are used as constants, but it is safe to add new sub-states to these constants.
Constants
The following values are used as constants and should not be modified:
- Active or Potential - A super-status for both Active or Potential. Used for the Project's customer select box.
- Potential - The super-status for all pre-sales stati such as Inquiries, Qualifying, Quoting and Quote Out.
- Active - An active company. Only active companies are listed in most drop-down boxes of companies.
- Inactive - The super-status for all non-active states such as Declined or Deleted.
- Deleted - Companies of this status are by default excluded from most drop-down boxes.
category_id | category
-------------+---------------------
40 | Active or Potential
41 | Potential
42 | Inquiries
43 | Qualifying
44 | Quoting
45 | Quote out
46 | Active
47 | Declined
48 | Inactive
49 | Deleted
References
Related Object Types
Related Categories
Category Intranet Cost Center Status
Not a prominent category in ]project-open[, mainly used for signaling the condition of the cost center, if it is in use.
Constant Ranges
category_id | category
-------------+----------
3101 | Active
3102 | Inactive
References
Related Object Types
Related Categories
Category Intranet Cost Status
Cost Status allows for tracking the lifecycle of financial documents.
Only two categories are used as constants, so please don't modify them. You can use and extend the other stati at your convenience.
Constants
- Created - This is the default status of all financial items after creation.
- Paid - Used as a constant in the payments package.
Constant Ranges
category_id | category
-------------+----------------
3802 | Created
3804 | Outstanding
3806 | Past Due
3808 | Partially Paid
3810 | Paid
3812 | Deleted
3814 | Filed
3816 | Requested
3818 | Rejected
References
Related Object Types
Related Categories
Category Intranet Cost Type
Determines the type of a financial document.
This category is entirely made up by constants, modifying them will break the system. Also, please don't add any add values here.
Constants
Customer Financial Documents:
- Customer Invoice - Invoices are legally binding.
- Quote - A quotation to a customer.
- Delivery Note - Indicates that a certain service has been delivered to the customer.
Provider Financial Documents:
- Provider Bill - Represents an invoice received from a provider.
- Purchase Order - Ordering services from a provider.
Internal Financial Items:
- Expense Item - Represents a single travel expense from the expenses package.
- Expense Bundle - Represents a group of Expense Items.
- Employee Salary - Represents the cost to the company caused by payroll
Technical categories:
- Customer Documents - Super-category for all customer related financial documents.
- Provider Documents - Super-category for all provider related financial documents.
- Repeating Costs - Super-category for all repeating cost items.
- Timesheet Budget - reserved
- Expense Planned Cost - reserved
Constant Range
category_id | category
-------------+----------------------
3700 | Customer Invoice
3702 | Quote
3704 | Provider Bill
3706 | Purchase Order
3708 | Customer Documents
3710 | Provider Documents
3714 | Employee Salary
3716 | Repeating Cost
3718 | Timesheet Cost
3720 | Expense Item
3722 | Expense Bundle
3724 | Delivery Note
3726 | Timesheet Budget
3728 | Expense Planned Cost
References
Related Object Types
Related Categories
Category Intranet Employee Pipeline State
Used for tracking the recruitment of employees and freelancers.
Constant Range
category_id | category
-------------+---------------------------
450 | Potential
451 | Received Test
452 | Failed Test
453 | Approved Test
454 | Active
455 | Past
10097 | Received Translation Test
10098 | Failed Translation Test
10099 | Aproved Translation Test
10100 | Deleted
References
Category Intranet Experience Level
A category to rate the skills and level of previous knowledge with a given skill.
Constant Range
category_id | category
-------------+-------------
2200 | Unconfirmed
2201 | Low
2202 | Medium
2203 | High
References
Category Intranet Freelance Skill Type
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).
Constant Range
category_id | category | category_description
-------------+------------------+-----------------------------------
2000 | Source Language | Intranet Translation Language
2002 | Target Language | Intranet Translation Language
2004 | Sworn Language | Intranet Translation Language
2006 | TM Tools | Intranet TM Tool
2008 | LOC Tools | Intranet LOC Tool
2010 | Operating System | Intranet Operating System
2014 | Subjects | Intranet Translation Subject Area
2016 | Expected Quality | Intranet Quality
References
Category Intranet Invoice Payment Method
How do you want your customer to pay your invoices?
This category is used in a drop-down box in the [invoice view page]. In the invoice template the "category_description" is used to write out a customer readable instruction on how funds are to be transferred.
Constant Range
There are no constants. The values below are just examples. We have created two fictitious bank accounts, modeling how you yourself can set a bank account link between two companies as an option for payment method selection.
category_id | category | category_description
-------------+------------------+-----------------------------------
800 | Undefined | Not defined yet
802 | Cash | Cash or cash equivalent
804 | Cheque EUR | Check in EUR payable to company
806 | Cheque USD | Check in US$ payable to company
808 | ABC-Bank EUR | ABC Bank,
: ABC Street 123,
: 12345 Banksville
: IBAN: 0123-1234-56-7890123456
810 | Caja Ahorros EUR | Caja de Ahorros ABC,
: ABC Street 123,
: 12345 Banksville,
: IBAN: 0123-1234-56-7890123456
References
Category Intranet LOC Tool
Software aids for localization and translation.
Constant Range
category_id | category
-------------+----------
2300 | Pasolo
2302 | Catalyst
References
Category Intranet Office Type
Determines the type of offices. This category is not frequently used in ]project-open[ but used to differentiate company offices by function.
It's no problem to add additional offices types if you should see the need for it.
Constant Range
Please don't modify the following categories that are used as constants:
category_id | category
-------------+--------------
170 | Main Office
171 | Sales Office
References
Related Object Types
Related Categories
Category Intranet Prior Experience
Used to classify a user's previous work knowledge.
Not used anymore in ]project-open[, but preserved for compatibility with older ]po[ installations.
You could use this category type to add a DynField to an employee's in the HR module.
Constant Ranges
Please do no modify the following categories:
category_id | category
-------------+---------------------
400 | Small Project Work
401 | Medium Project Work
402 | Large Project Work
References
Category Intranet Project Type
This category serves two purposes:
- Control whether certain portlet components will appear or not appear in the project view page and
- To extract reports on revenues per type of activity.
Special Project Types
The following project types trigger special behavior of ]project-open[. For this reason, please do not modify the names of these categories in the category list page.
- "Consulting Project":
Refers to "normal" projects with that include timesheet tasks with information on estimated and billable time per task.
- "Translation Project":
Enable special functionality for translation agencies such as a translation workflow etc.
- "Software Release":
A special project type for ITSM release management in IT organizations.
- "Milestone":
Projects of type Milestone will appear in the milestone list page of the milestone package.
Constant Range
category_id | category
-------------+-------------------------
85 | Unknown
86 | Other
87 | Trans + Edit
88 | Edit Only
89 | Trans + Edit + Proof
90 | Linguistic Validation
91 | Localization
92 | Technology
93 | Trans Only
94 | Trans + Int. Spotcheck
95 | Proof Only
96 | Glossary Compilation
97 | Strategic Consulting
98 | Software Maintenance
99 | Software Development
100 | Task
101 | Ticket
2500 | Translation Project
2501 | Consulting Project
2502 | Service Level Agreement
2503 | Trans Only (Dynamic WF)
2504 | Milestone
4300 | Bug Tracker Container
4305 | Bug Tracker Task
4597 | Software Release Item
4599 | Software Release
References
Related Object Types
Related Categories
Related Tutorials
Category Intranet Qualification Process
Not use in ]po[ at the moment (V3.4).This category type was used as part of the HR module to classify candiates during the HR recruiting process.
The data are still preserved for compatibility with older ]po[ installations.
Constant Ranges
category_id | category
-------------+--------------------
191 | University Studies
192 | Domain Expert
193 | None
Configuration Database Configuration
]project-open[ has been developed primarily using PostgreSQL as the database back end for information storage and retrieval. We are looking for companies who are looking to sponsor an effort to support Oracle, contact us for more information.
There are three different options available for the coupling relationship that links ]project-open[ to PostgreSQL.
- Run PostgreSQL on a Windows Machine using CygWin . The ]project-open[ 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, the performance of PostgreSQL on CygWin is not as optimal as the other options.
- 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 ]project-open[.
- Run PostgreSQL on a separate database server computer, possibly even with a different operating system such as Linux or Solaris and then link ]project-open[ to this server.
PostgreSQL Security Configuration
PostgreSQL security configurations are controlled by a config file found at:
- Linux - "var/postgresql/data/pg_hba.conf"
- Windows - "C:\ProjectOpen\ cygwin\var\postgresql\data\pg_hba.conf"
The default configuration ]project-open[ uses is:
# 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 ]project-open[ demo server where we cannot predict the name of the local users. However since you will more than likely be able to know every user involved and using ]project-open[ (your list of employees and customers) you may want to change these settings for a productive installation.
Please see the PostgreSQL documentation for more details.
PostgreSQL "Vacuum" Maintenance
“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. You can either:
- Manually execute the CygWin “vacuumdb” command periodically:
- You can configure a Windows “Scheduled Task” to execute “ProjectOpen-vacuum.bat” every day
- You can configure the CygWin “cron” scheduler to execute the command.
On Linux systems configure the "Crontabs" daemon to execute the periodic maintenance.
# Full PostgreSQL vacuum every night 20 3 * * 0 su - postgres -c "/usr/bin/vacuumdb -a -f" >> /var/log/pg_vacuumdb.log 2>&1
PostgreSQL Database Backup
Within ]project-open[ you can manually perform a backup using the Backup and Restore admin page. However we recommend setting an automatic database backup process. In Windows
- Manually execute the CygWin “pg_dump” command periodically:
- You can configure a Windows “Scheduled Task” to execute “ProjectOpen-pg_dump.bat” every day
- You can configure the CygWin “cron” scheduler to execute the command.
In Linux configure the "Crontabs" daemon to execute the periodic backup.
# 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
Reference
Configuration Filestorage Integration
Internally, ]project-open[ uses its own filestorage system to manage file contents using the package "intranet-filestorage". However there are number of third party applications that can more powerfully manage files, including the underlying OS filestorage managers, so ]project-open[ can easily link with and integrate into a number of file servers.
Overview
("po34demo" is the server name instance in this example)
These above listed parameters (found at Parameters Admin Menu) allow the mapping of filestorage base directories to specific locations in the file system of the underlying operating system. The figure above shows a sample from a Unix-like 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 ]project-open[ filestorage is designed to be integrated with an existing Windows or Linux fileserver. This means that a file can be accessed not only using ]project-open[ but also directly through file managers of the respective operating systems or other applications.
]project-open[ filestorage always takes its list of files from the existing file server so that there are no possibility of 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 ]project-open[ filestorage.
To implement this interoperability between machines, ]project-open[ utilizes the free software Samba which is a networking tool. The Samba How To guide may be of interest during the course of installation.
Integration with Windows
The following instructions guide you step-by-step through the process of setting up integration with a Windows file server and a Linux machine.
On the Windows Side:
-
Create a new Windows user:
Create a new Windows user (i.e. "projop") with a specific password ("secret"). -
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". -
Enable Plain Text Passwords on Windows 2k/2k3/2k7:
From the Samba HOWTO :
Using the registry editor (regedit), create the registry setting HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\LanmanWorkStation\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.
-
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.
Integration with Linux
The following instructions guide you step-by-step through the process of setting up integration with a Linux machine and a Windows fileserver.
On the Linux Side:
- Create a /etc/hosts entry for your Windows server. Add a line such as
- Install a standard Samba version on the ]po[ Linux server using YaST or whatever package manager. Check if Samba works:
- Create a mount directory: Issue
- Manually mount the Windows share: Issue
- Add an entry to /etc/fstab: Add the following line to /etc/fstab:
192.268.0.4 fs
"fs" is just and example and stands for File server. You can choose the name freely.
Check if the Windows share is visible from Linux: Issue:
smbclient -L fs
You should see a list of shares, including "projects"
mkdir /mnt/projects
on Linux. This is the place where the Windows share will appear on the Linux side
mount -t cifs -o username=projop,password=secret //fs/projects /mnt/projectsIssue 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
unmount /mnt/projects.
//fs/projects /mnt/projects cifs username=projop,password=secret,uid=projop,gid=usersThis 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.
Integration Notes
- Please note that the Linux/Windows Samba integration is quite a 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 typically 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 VMware running on the file server. This is the configuration that we recommend to small companies.
- Access permissions between ]project-open[ and the operating system may be an issue under Unix-like 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 have read-only 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 do not have permissions to read the ]po[ files and the other way around.
The solution to 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”).
- 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.
-
Some corporate documents may be too sensitive to keep them in the same fileserver as the usual project documents. Therefore ]project-open[ 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.
References
Configuration GUI Configuration
The outward appearance and look of ]project-open[ is controlled by several parameters. These have nothing to do with the functionality, and are meant to be used by a business in order to put their "personal" stamp onto ]project-open[.
Portlets
Portlets do appear on Portlet Pages such as the landing page for particular projects, users or companies.
Each Portlet Page consists of one or more portlets.
Portlets for all user / user groups are managed using the following admin page: http://[YOUR_SERVER]/intranet/admin/components/
A fully installed ]po[ might contain up 100 different portlets. Use the filters on the left side to limit the elements shown.
The very right columns containing either a lowercase or uppercase letter 'r' define if a is visible ('R') to a user group or not ('r').
Portlets can be enabled/disabled for all user groups.
CSS
Cascading Style Sheets are used in order format HTML output for the dynamically produced pages of ]project-open[. The default style sheet used throughout the system is controlled by the parameter SystemCSS below the "intranet-core" grouping of parameters. The parameter consists of a file pathname to the style sheet. Default set-up for the parameter is "/intranet/style/style.default.css" on Linux.
We recommend to anyone wishing to modify the CSS that they do so by copying and pasting the original, and then modify according to suit their needs. Add the newly modified CSS to "intranet/style/" and then alter the paramter accordingly to point to the new CSS.
Logo
(Default System Logo found in the upper left hand corner of the page)
To insert your company's graphic into ]project-open[, the parameter SystemLogo below the "intranet-core" grouping of parameters must be changed. This parameter consists of a file pathname to the system logo. Default is "intranet/images/projop-logo.gif".
To reflect your company logo, add the new image file to "intranet/images/" and then change the parameter to point to the new file. The parameter SystemLogoLink is also useful, and it controls the URL that is associated with logo. Default is "www.project-open.com". Simply change the URL the parameter points to and then every mouse click with direct users there.
Nav Bar
(Default Nav Bar found on the left hand side of page)
References
Configuration Software as a Service (SaaS) FAQ
- What kind of support for configuration do you offer when start using Saas?
- We currently using EXCEL/(other tool) to manage our projects. Is there a way to import this existing data to po?
- How can templates for Financial Documents be adjusted to our Corporate Design ?
- How to Update Your Company Logo?
-
- For additional FAQ's please see: http://www.project-open.com/en/services/project-open-hosting-saas.html#faq
What kind of support for configuration do you offer when start using Saas?
In case your chosen package does not include any monthly support or in case you do need additional support ]po[ offers a range of services, such as training sessions, configuration support and legacy data import. For additional information please inquire using our contact form. As a SaaS client you'll receive a 10% rebate on our regular prices.
In case you have already used ]po[ in a local environment, additional support might not be necessary. For beginners we recommend contracting at least some 4-6 support hours to streamline the initial phase. Support can be provided by email, chat or by telephone.
We currently using EXCEL/(other tool) to manage our projects. Is there a way to import this existing data to po?
Importing legacy data into a new ]po[ SaaS instance of ]po[ is possible. Please inquire for a detailed quote and tell us about quantity structure, data to be imported (customers, users, projects) and their attributes (Name, email, ...Project Name, Project Nr., ...., etc.).
How can templates for Financial Documents be adjusted to our Corporate Design
Find additional information in regards to template generation here.
How to Update Your Company Logo?
In order to have your company logo shown on the top left corner of your application and in your templates, please proceed as follows:
- Make sure that your logo is either in format jpg/png/gif and is named logo.gif/logo.png/logo.gif
- Login to your ]project-open[ server and navigate to your internal company page.
http://[YOUR_SERVER]/intranet/companies/view?company_id=8720
- Go to your Company File Storage, navigate to the sub-directory 'template_logo' and upload your logo. You will overwrite the default ]project-open[ logo files located in this folder with your own logo.
- Adjust parameter 'SystemLogo' on page http://[YOUR_SERVER]/intranet/admin/parameters/ accordingly so that it fits your logo file type.
Example: In case you uploaded 'logo.jpg' the value of 'SystemLogo' would need to be changed to '/logo.jpg' (without single quotes)
Configuration Financial Document Configuration
]project-open[ comes with generic pre-configured financial document templates. Financial documents refer to invoices, provider bills, delivery notes, quotes, etc.
There are two options to use templates within ]po[:
- Open Office Templates (.odt)
- ADP Templates
Open-Office Template
Find more information on how to use ODT templates at http://www.project-open.org/documentation/page_intranet_admin_templates_index
ADP Templates
Adapting the template to reflect your company's business procedures requires some basic knowledge of HTML and CSS and an HTML editor program (Dreamweaver, FrontPage, etc.). After completing these steps, all financial document template forms in the system will reflect the changes you have made in this customization.
- You will need to design a template .adp form that will become the default template for invoices system-wide. Or you could modify the default templates that come with ]project-open[ to reflect your company needs.
- Place the newly created/adapted invoice in the template folder/directory typically located at:
- Linux - /web/projop/filestorage/templates
- Windows - C:\ProjectOpen\filestorage\templates
- Create a new Category entry to represent the new template so that the newly created template becomes available as an option in menus. This involves adding a new category entry for the category type "Intranet Cost Template". Modifying categories is done through the Category Admin Menu. The new category entry must have the same name as the template file in order for it to work successfully. I.e. if the new template file name is "foobar.adp" the new category entry must be "foobar.adp"
There are a number of placeholder variables that are available when designing your template, that provide access from the template to useful finance information throughout the system.
(Category admin screen with "Intranet Cost Template" selected)
Parameters
There are a number of parameters that are of interest relating to invoices. They can be found at the Parameters Admin Menu under the section "intranet-invoices".
References
Configuration Permissions Configuration
]project-open[ is a networking tool that centers around one individual company and it's interactions with both customers and providers, While the software promotes free access and movement of information between these three actors so that they can work together, in many cases dealing with sensitive information and actions, it is more desirable to strictly control what users can see and do. The complicated intricacies of implementing this will most likely be one of the most time consuming configuration elements of ]project-open[, however it will allow companies a fine grain of control over users to ensure security and competitive advantage.
- Permissions Model/Access Rights - the theory behind the permissions architecture in a business climate
Managing Permissions within ]project-open[
- Defining each User Profile - Horizontal Permissions
- [Managing the Hierarchy - Vertical Permissions]
- [More Financial Control - Cost Center Permissions]
- [Menus, Dynfields, Portlet Componenets, and DynViews]
References
Configuration @Configuration Overview
This page summarizes a number of configuration steps that repeat with every ]po[ implementation. Please excuse us that not all configuration pages have been written yet, we will complete the missing pages in the following weeks and months.
Meanwhile you can consult our Open Discussions forum at www.SourceForge.net for free support (please search for your question before you start a new discussion topic). Please contact us for professional support to accelerate your configuration process.
Configuration Topics
For a full configuration please proceed with the following topics more or less in the specified order:
- The Configuration Wizard - creating a suitable base configuration to start with.
- [User Group Configuration] - identify user groups with different permissions.
- Menus Configuration - simplify your system by hiding menu tabs.
- [Portlet Configuration] - simplify your system by hiding portlet plugin components.
- User Profiles - define user groups and their permissions.
- [The User Matrix] - determine the relationship between user groups.
- [Category Project Status] - define the life cycle of a project in your company.
- [Category Project Type] - define the types of projects used in your company.
- [Category Company Status] - define the life cycle of customers and providers.
- [Category Company Type] - define the types of customers and providers.
- [Category Other Stati and Types] - define the stati and types of other ]po[ objects.
- [Materials & Service Types] - define the types of services provided by your company to customers.
- [Currency & Exchange Rates] - what currencies do you use and how to convert between currencies.
- [Department & Cost Centers] - define the departments and the cost center hierarchy of your company.
- Language, Date, and Currency (old) - What do we speak? What day is it? What do we get paid in?
- The Internal Company (old) - define your own company.
- Start Page and Home Page (old) - landing pages for the server domain name and first access page.
- [Necessary Parameters (old)] - critical system parameters.
- [Optional Parameters (old)] - important parameters that help to configure ]project-open[ uniquely for your company.
- GUI Configuration (old) - The look of ]project-open[, change CSS appearance and system logo.
- Financial Documents (old) - customize the look of invoices, provider bills, quotes, etc.
- Filestorage Integration - define where to store documents related to projects and other objects.
- Database Configuration - integrate ]project-open[ with a database.
- Permissions (old) - configure the internal security of ]project-open[ by restricting read/write privileges.
- [configuration_workflow] - configure dynamic workflows to control the life cycle of business objects.
- [configuration_user_exits] - define operation system scripts to be executed when creating and modifying business objects.
References
-
Admin Home Page - online help for the ]po[ administration screens
Configuration Financial Document Configuration - Placeholder Variables
The following list of variables are useful when adapting the finance document template during [configuration]. These variables can be included into the template and represent varying values of financial data. This is not the complete list, but generally speaking these are the most frequent and useful. Most variables found throughout ]project-open[ can be input into the templates as well. Variables can be inserted into templates using a line like:
<H1><%= %variable_name% ></H1>
Please note that in the lists below that invoice is meant to refer to all financial documents. Variables are presented alphabetically by variable name.
- General Variables
- Related Projects
- Customer and Provider
- Financial Items
- Currency and Date Formatting
- Pre-formatted HTML
General Variables
- default_currency - defines the "DefaultCurrency" parameter
- internal_contact_email - email of user_id
- internal_contact_name - name of user_id
- grand_total - grand total (Subtotal + VAT + TAX)
- grand_total_pretty - formatted grand_total
- 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.
- page_title - The HTML title of the invoice. Just for the browser header (usually not printed)
- rounding_precision - Constant set to "2". Determines the number of digits of rounding precision for subtotals etc.
- subtotal_pretty - formatted subtotal
- subtotal - subtotal (sum of invoice items)
- user_id - the ID of the current user (currently looking at the page)
- user_locale - The default locale of the current user is, in general, different from locale. This locale serves as a fallback value in case that there is no locale defined for the invoice.
Related Projects
These variables are useful if you want to refer one or more projects that are related to the given invoice. Please note 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).
- 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.
- related_projects - The TCL list of the "names" of related projects.
- 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.
Customer and Provider
A 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.
- accounting_contact_id - ID of the company's accounting contact person.
- company_id - ID of the customer or provider
- company_name - (Long name)
- company_path - Path (short name)
- 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 about the CRM acquisition process.
- deleted_p - The company may already have been deleted…
- 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.
- vat_number - The VAT number of company
The following fields contain information about the preferences/default values for the company's payment conditions and templates for different invoice types.
- default_bill_template_id
- default_delnote_template_id
- default_invoice_template_id
- default_payment_days
- default_payment_method_id
- default_po_template_id
- default_vat
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.
- address_city
- address_country_code - Two digit code for the country
- 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.
- country_name - English name of the country (can be localized)
- fax
- office_id - ID
- office_name - Name of the Office. Can be used to designate a company's sub organization (department, …) if suitably 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)
Financial Items
- calculated_due_date - due date (effective date + payment days)company_contact_email - Email of company_contact_id
- calculated_due_date_pretty - due date formatted according to locale
- cffective_date - effective date of invoice
- 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_name - Name 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 - Status (human readable)
- cost_status_id - Status (ID)
- cost_type - human readable ID
- cost_type_id - Type (ID)
- customer_id - Customer, either the "internal" company for a 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.
- invoice_date - same as effective date
- invoice_date_pretty - effective date formatted
- 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".
- invoice_payment_method - short human readable text for payment method such as "Bank ABC"
- invoice_payment_method_id - same as payment_method_id
- invoice_payment_method_desc - 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_status_id - same as cost_status_id
- 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
- payment_days - number of days for payment, difference between effective_date and calculated_due_date
- payment_method_id - ID that determines payment details
- 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
- vat - VAT (percentage)
- vat_amount - VAT (percentage x invoice amount)
- vat_amount_pretty - VAT (percentage x invoice amount) formatted
Currency and Date Formatting
These formats are used on the SQL level to format variables. The format depends 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
- tax_format
- vat_format
Pre-formatted Pieces of HTML
These are pieces of HTML are already formatted to be included in the InvoiceViewPage and the template. You can customize these elements by using a StyleSheet.
- item_html
- item_list_html
- invoice_item_html
- payment_list_html - List of related payments formatted for the ViewPage (not for the Preview)
- payment_method_html
- payment_terms_html - Formatted "payment conditions" section. Usually only applicable for "hard costs" where invoice_or_bill_p == true (see below).
- note_html
Preformatted (<pre>...</pre>) invoice "note" field - 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. - subtotal_item_html
The formatted piece of HTML representing the "subtotal" section with subtotal, VAT, TAX and grand total.
References
Configuration Language, Date, and Currency Configuration
Set Language
The default language setting can be found in the Parameters Admin Menu as the parameter SiteWideLocale in the package "acs-lang".
The default setting that comes with ]project-open[ is "en_US". If a language translation string cannot be find, the system will revert to displaying the default language if available. For information regarding supported languages see Languages and Localization. You can also set the system wide language as a SysAdmin using the Localization Admin Menu. Each user however can configure their profile to display ]project-open[ in their desired language. Using the SiteWideLocale parameter you have only set the default system language applicable to all users if they have not have changed their profiles otherwise.
(User Profile Locale Settings apply first and foremost, then default system language)
Set Currency
]project-open[ supports multiple currencies in use at the same time. In order to activate currencies so that they become present as options in drop down menus and exchange rate updates see Exchange Rate Admin Menu. To set a default system currency find the parameter DefaultCurrency on the Parameters Admin Menu page and set the parameter to the according three digit ISO currency code. See supported currencies for a list of ISO codes.
Set Date
Dates follow the default format "YYYY-MM-DD". ]project-open[ uses OS utilities to set the system time.
References
Configuration Start Page and Home Page Configuration
- Removing the Home Page Help Component
- System Start Page
- Immediate Start Option
- Start Page with Login Option
Removing The Home Page Help Component
On the "home" page of ]project-open[ "localhost://intranet/" you will find a help component designed for demo use. This is of course not relevant for use in production systems and should be removed.
(Home Page Help Component)
To remove this component go to the Portlet Components Admin Screen. And edit the details of the "Home Page Help Blurb" Component. To disable the component from being seen you can either 1) set the page URL to "none" or 2) disable the component by selecting "not enabled". Only one of these actions need to be performed.
System Start Page
The ]project-open[ system start-page with the URL http://localhostname is located at
- Linux - /web/projop/www/index.adp
- Windows - C:\ProjectOpen\projop\www\index.adp
This .adp page contains simple HTML code and is intended to be customized by a system administrator using any common HTML editor.
Additionally you can create .tcl files in the same subdirectory (www) .tcl and .adp files normally work together symbiotically to produce content pages in ]project-open[. The .tcl will work the business logic and the .adp page is used to render the variables in the .tcl file into HTML format. Alternatively, you can just use static HTML files as with any typical web server application.
The /web/projop/www subdirectory contains the publicly available web pages of the web server or "root pages". This would be the correct place for pages dealing with marketing, general info or public disclosures.
Immediate Start Option
One option is to not have any start page, and instead redirect to the system home page or other ]project-open[ core pages. In this case please create/alter the existing "index.tcl" file at /web/projop/www/ (all together /web/projop/www/index.tcl) to mirror the below code.
ad_page_contract {
Empty system home page (redirects immediately to ]project-open[)
@author frank.bergmann@project-open.com
@creation-date Nov 2003
} { }
ad_returnredirect "/intranet/"
Replace "/intranet/" with any other system url to send users to places other than the home page.
Start Page with Login Option
To force users to authenticate themselves before continuing on into ]project-open[ you will to set the index.adp and index.tcl files similarly to the code found below. The code will produce a content page with a login prompt and several links.
/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>
<table cellSpacing=0 cellPadding=0 width="100%" border=0>
<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>
<table cellSpacing=0 cellPadding=0 width="100%" border=0>
<tr>
<td vAlign=top>
<table cellSpacing=0 cellPadding=5 border=0>
<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="/">]project-open[ Developer Community</a>
<LI><A href="/doc/">Documentation Home</a>
</td></tr>
</table>
</td>
<td>
<table cellSpacing=0 cellPadding=5 border=0>
<tr><td class=tableheader>Intranet Login</td></tr>
<tr><td class=tablebody>
<!-- Include the login widget -->
<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>
<table cellSpacing=0 cellPadding=5 width="100%" border=0>
<tr><td>
Comments? Contact:
<A href="mailto:support@project-open.com">support@project-open.com</A>
</td></tr>
</table>
</body>
</html>
References
Possible values are
- absolute_links: '0'
- abstract_p: 'f'
- auto_save: 'false'
- creation_date: '2009-11-17 09:29:56.963056+01'
- creation_user: '448'
- creator: 'Richard Thiemann'
- current_user: '0'
- description: ''
- do_substitutions: '1'
- folder_id: '-100'
- form: '::xowiki::WikiForm'
- id_column: 'page_id'
- last_modified: '2009-11-17 09:29:56.963056+01'
- mime_type: 'text/html'
- name: 'en:configuration_start_page_home_page'
- nls_language: 'en_US'
- object_id: '333840'
- object_type: '::xowiki::Page'
- package_id: '252723'
- page_id: '333840'
- page_order: 'Configuration'
- parent_id: '252746'
- pretty_name: 'XoWiki Page'
- pretty_plural: 'XoWiki Pages'
- publish_date: '2009-11-17 09:29:56.963056+01'
- publish_status: 'ready'
- recursion_count: '0'
- references: ''
- render_adp: '1'
- revision_id: '333840'
- security_inherit_p: 't'
- sql_package_name: '::xowiki::Page'
- storage_type: 'text'
- supertype: 'content_revision'
- table_name: 'xowiki_page'
- title: 'Start Page and Home Page Configuration '
- unresolved_references: '0'
- with_table: 'true'
Developer Localization
Michael Menzel from Eurotransmit coordinates the localization efforts for ]po[. Please contact Michael if you want to contribute or subscribe yourself to our localization mailing list.
This page is dedicated to translators who are preparing localized versions of ]project-open[. If you have developed a localization of ]project-open[ independently, please contact us and provide us with the catalog files so that we can include them in the product and give you credit.
- Localization Basics
- No Trados, Please!
- How to Localize project-open
- Add a New Localization Message
- Date, Time and Currency Formats
- Unicode and Double-Byte Character Sets
- Known Localization Issues
- Country Specific Accounting Rules
- Coordination and Communication
- Terminology
- Translation Server
Localization Basics
]project-open[ includes it own integrated localization system. Please see the configuration guide for details. You need to be a "P/O Admin" of the server in order to access the "Localization Admin" page at the URL http://l10n.project-open.net/acs-lang/admin/
No Trados, Please!
If you would like to use Trados in order to translate ]project-open[ this option is available at the OpenACS Localization page in ]project-open[ at the /acs-lang/admin/ section. There you can export and import translation strings as XML.
However, it is not a good idea to use Trados for software localization.
- There are not that many strings to translate, really (~4,000)
- The same English source string may need to be translated into different target strings, depending on the context. This is the reason why there are quite a few "duplicate" strings. For example, the same "Edit" English string may refer in one page to an action and in another page to a Workflow stage.
How to Localize ]project-open[
We strongly suggest the following sequence; this process works the same on our localization server as it would on your own ]project-open[ installation:
- Please go through the terminology and translate these strings to your target language. Please research the terminology of similar applications in the Web and make sure you hit the right formality/informality decisions. Please document your decisions in the respective language page here on the Wiki.
- In order to receive an account and privileges on our localization server you need to first contact us requesting the right to edit and providing us a short explanation of why you are translating ]project-open[. We can put you into contact with other companies or freelancers who are working on similar projects, or who have already done so in your native language. Please check our list of languages to see if ]project-open[ has already been translated to your language.
- Once logged into the localization server make sure that your account matches your target language. This can be done by clicking on the "My Account" link and editing the "Localization" information. If your target language is not offered as an option continue to step 4 and you will have to return back to this step later.
- Either navigate using the "Admin" and then "Localization Home" links or go directly using the URL "myserver_name/acs-lang/admin" to access the localization preference page. Note: you must have System Administrator privileges to do this and all following steps.
- Make sure your target language is enabled. If your target language is not listed as available go the bottom of the menu page and click on "Create New Locale". Once your target language has been enabled, it will then be offered as a profile option on your personal account options. If you had to skip Step 3, go back and edit your localization details after enabling your target language.
- Now "Toggle Translator Mode" to "On" from the main localization administration page you were directed to at Step 4.
- Now time to translate. After enabling Translator mode, Green Circles, Yellow Asterics, and Red @'s should have appeared next to most text segments in the system. If you are unhappy with the translation click on the symbol next to the entry and translate it, offering a brief explanation for why you changed it. Go through all tabs and pages in the system translating the respective strings. Important tip to save time: In Firefox you can ctrl-click links, so that the links are opened in separate tabs. Then you can translate these strings and submit them. Pressing Ctrl-W (close tab) in Firefox will save you the time the browser needs to reload the following page.
- Then after you have translated all important strings in their context, you should use the "batch translation" option in /acs-lang/admin/ in order to catch the less exposed strings. With these strings you won't see a context, so it may be quite difficult to find the right translation. In cases of doubt please omit the translation instead of adding a bad translation.
Add a New Localization Message (MESSAGE KEY MISSING ‘intranet-core.Hardware_Manufacturer’ Error)
If ]project-open[ cannot 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] to the system of if you customize the GUI. You (the System Administrator) can remove such error messages by using the built-in localization mode of ]project-open[ as is described above. After choosing the target language return to the initial page with the MESSAGE KEY ERROR, which now should be replaced by another symbol most likely a red '@' or a green circle and translate.
Date, Time and Currency Formats
]project-open[ uses the default date format “YYYY-MM-DD". This format cannot be changed. Time format is handled inconsistently and diiferently throughout the system. Please refer to the specific documentation of each package. This situation is undesirable and will be improved in one of the following releases.
Currency is formatted using ISO three letter abbreviations such as “EUR” or “USD”. ]project-open[ is built to handle multiple currencies, so you will need to specify your currency every time you enter a monetary amount. The parameters section provides a system default currency that is used as a default where appropriate.
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 has not yet been tested extensively (V3.0.0). Cyrillic and Latin 1 special characters are known to work.
Known Localization Issues
There are several known issues with localization in ]po[ V3.4:
- Time, Date, Number & Currency Formats:
As mentioned above, ]po[ uses its own data & time format YYY-MM-DD HH24:MM throughout the system. Numbers and currencies are formatted in American style. Exceptions: The [InvoiceViewPage] honours the locale of the invoice template to create country specific invoice printouts and most reports allow you to specify the number format in order to deal with country specific handling of numbers in MS-Excel. - Sending Emails:
It seems that UTF-8 characters are broken somewhere between AOLserver and the Linux Sendmail/Postfix mail agents. We haven't been able to identify the exact location yet and would be greatful if an experience Linux admin from a double-byte writing country could give us a hand... - Filestorage Issues:
The filestorage experiences broken characters on some Linux systems (but not on others). We haven't been able to identify these issues yet.
The following L10n issues have been fixed in V3.4:
- Japanese Lastname-Firstnames name format:
]po[ now consistently uses the PL/SQL function "im_name_from_user_id(user_id)" to determine the name of a specific user. By customizing this function you can change the system wide name format. This mechanism is also useful in German companies with a formal name convention "Lastname, Firstnames".
Country Specific Accounting Rules
The ]project-open[ Finance Module does not use any country specific accounting rules due to their wide variation from country to country. VAT and Tax are fee-text fields in invoices and other cost items, allowing the user to add specific values.
]project-open[ supports an export function of costs to country specific accounting formats,
- KHK-Kaufmann (Germany)
- ContaPlus (Spain)
- QuickBooks (US)
Coordination and Communication
Please subscribe to our new "localization" mailing list . This should be the preferred communication medium for localizers.
For general questions not related to localization please use the Open Discussion forum at SourceForge. The Open Discussions forum is the communication platform for the general ]project-open[ community.
Please request write permissions to this Wiki if you would like to participate in the localization of ]project-open[.
Terminology
Please see the terminology of key ]project-open[ terms before starting to translate. It is probably a good idea to start translating these terms first, in order to guarantee a consistent terminology and to save yourself time later.
Please copy the list of terms from the terminology to your "language_xx" page, in order to be able to translate the terminology.
Please note, this (www.project-open.org) server takes about a minute to "save" the Wiki page after you have pressed "OK". Please don't interrupt the browser during that time, it will come back eventually.
Translation Server
The ]project-open[ translation server http://l10n.project-open.net/ is the centralized repository of translations. Once you are part of your language team, we can provide you with access to this server. Also, we can import any translations made on your local server to our localization server in order to spread your work. We will include translations from the localization server in all main releases from now on.
Developer Data Model
- General Conventions
- Main Classes
- Complete and Detailed Object-Type Map
- Category Listing and Administration Menu
General Conventions
- Table names are always in plural form, written in lower case, and delimited by the underscore character "_"
Company -> im_companies Office -> im_offices Project -> im_projects
- Table names pre-fixed with "im" are ]project-open[ specific, non-prefixed/"acs" pre-fixed table names are inherited from OpenACS
Timesheet Tasks (]project-open[) -> im_timesheet_tasks Party (OpenACS) -> parties Object (OpenACS) -> acs_objects
- Tables (generally) conform to the 2nd normal form
- Denormalized table columns are named with a "_cache" postfix.
- All main tables have an integer primary key <table_name>_id. This primary key references the table "acs_objects" which contains the type of the object. This id is not plural and need not be prefixed.
im_projects -> project_id groups -> group_id
- Most object-object mappings are handled by the "acs_rels" table and its subclasses. Any additional auxiliary mapping tables are called "something_something_map".
- Boolean fields have a "_p" postfix and contain 't' or 'f' char values
Example Attribute from im_costs variable_cost_p bpchar
- All main objects include "object_type_id" and "object_status_id" fields. "Type" is used to create minor subclasses of the objects, for example the distinction between "customer" and "provider" for im_companies objects. "Status" is used to deal with the object's lifecycle, such as "potential", "active", "closed" and "deleted".
Example Attributes from im_tickets ticket_status_id int4 ticket_type_id int4
Main Classes
- Object
- Business Object
- Office
- Company
- Project
- Configuration Item
- Categories
- Attributes
- Privileges
- Permissions
Object - acs_objects
The root table for the acs object hierarchy. It all starts here folks.
Business Object - im_biz_objects
Most data and the most important objects in the ]project-open[ data model are derived from and structured as "Business Objects". A business object is just a database table which adheres to the following conventions.
- A integer primary key called <object>_id representing a unique object ID
- The primary key references the "acs_objects" table, where meta-data about object type, creation date, etc. is stored
- Two integer keys <object>_type_id and <object>_status_id
- These two keys reference the "im_categories" whose function is explained in more detail below.
Business Object Sub Classes:
Office - im_offices
Represents physical office locations and their data attributes.
Company - im_companies
Represents commercial organizations, what their relation is to your company, contact info, their industry, etc.
Project - im_projects
The "project" concept and running a business using project-management principles is a fundamental to ]project-open[ and it's construction and operation. The majority of actions and activities in ]project-open[ center around project objects, which store data about projects, like creation date, final customer destination, manager, etc.
Configuration Item - im_conf_items
Categories - im_categories
Category Listing - see all the available ]project-open[ category types and their descriptions
Conventional/traditional database design normally includes many foreign key tables defining the type and status of an object. For example, to capture all the different stati and types of "im_projects" we should create two new tables "im_projects_status" and "im_projects_type". As a result, for every new table x we would like to introduce there is at a minimum 2x more tables to create to track their type and status, possibly more for a complex object.
]project-open[ has taken a different route in our database design model. In order to save space and maintenance efforts, all object type and status id's are stored in one single table, "im_categories" the look-up table for all individual object's to consult. We believe this design offers the following advantages over the classical model:
- The total number of database tables is reduced by a ~third
- A single maintenance screen is responsible for a managing categories
- Built-in localization, hierarchical categories, and common GUI widgets
- Referential Integrity is enforced
We do acknowledge that it is possible to assign the wrong category to a field, however this mistake has not happened before by any programmer and it is a relatively easy error to detect.
Within the context of ]project-open[ "Categories" are a general concept being used throughout the system for several different purposes.
- Sometimes categories are used to hold values which should be modified by a knowledgeable user (“user”).
- Sometimes 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”).
Category Hierarchy
Categories can be ordered hierarchically using an "is-a" relationship. This lets you define 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 as 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.
Category Example - Company Type - company_type_id
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 and function 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 don’t know. | |
| 53 | Internal | Customer | Use this type to denote your own company or companies belonging to your 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.
|
Categories consist of 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 he or she couldn’t touch the “Internal”, “Provider” or “Customer” fields, because their IDs are referenced as constants internally in the system.
For instructions on how to access the administration menu to view/modify/add categories in ]project-open[ consult below.
Attributes - acs_attributes
Privileges - acs_privileges
Permissions - acs_permissions
Complete and Detailed Object-Type Map
OpenACS provides an administration tool that compiles an automatic map of all the object-types and their hierarchical relation. However, it is not perfect and some database objects are hidden. Most notably you will see that "im_categories" does not appear. Unfortunately we cannot provide a link to see this in real time on the demo server, because you need "SysAdmin" priveleges to see this. Here are the instructions on how to access the Object-Type Map from your own ]project-open[ installation. You must have Admin privileges.
1. The OpenACS Admin Menu is slightly hidden, there is no direct access from internal ]project-open[ screen, you must type the address "myserver/admin" to see the following screen.
2. Click on the "Object-Type" Link and you will be directed to listing of object-types. Clicking on each individual object will display all of it's variable attributes and inheritance.
Category Listing and Administration Menu
From the ]project-open[ admin home page you will find a link to the category manager. You must have admin privileges to view and manipulate the categories. Please do not attempt to change/add categories unless you fully understand first and have read the PO-Configuration Guide, specifically the section on Categories, or have read the relevant wiki entries about categories on this page, or the Category page. Some category types are mandatory and should not be edited.
1. From the ]project-open[ Admin Menu click on "Categories" or proceed directly to the menu screen with the URL "myserver/intratnet/admin/categories"
2. Use the filters to search for category types and view their corresponding categories. The "category" vs. "category type" distinction is:
- Add a new Category - within a pre-existing category type, add a new a category
- Add a new Category for a new Category Type - create a new category type, and add a new category to the newly created category type.
3. Please note: Categories are frequently cached for performance reasons. You may have to restart the server after adding or modifying a category in order for the changes to take effect. Or you could flush the memory cache.
Developer About Customer Types
]project-open[ is capable of serving diverse customers in many different business sectors. In order to provide this capability, ]project-open[ includes a number of mechanisms to "configure" (adapt without changing the source code) the application for the specific customer. This page lists some of the most pronounced variation of ]project-open[ that have been the most frequent in our customer base.
Please keep in mind: ]project-open[ must be able to work with all of these customers without modifying the source code!
- Small vs. Big
- Horizontal Project Management vs. ITSM vs. Translation
- Employee Trust and Security Authorization
- Coherence vs. Incoherence
- Department vs. Company vs. Group
- Country Specific Differences
Small vs. Big
]project-open[ can serve organizations from 3 to 3.000 "Employees". Employees is a broad term, since we have to include all freelancers, contributing customers, and infrequent or one time users. Clearly, larger organizations need to formalize processes a lot more then their smaller counterparts - functionality that is essential for large customers tends to be perceived as unnecessary overhead by smaller ones. Individual customer needs should determine the final look of ]project-open[, there is no set out-of-the-box pre-made installation for any industry sector or company size.
Horizontal Project Management vs. ITSM vs. Translation
]project-open[ can serve customers in different business sectors:
- Horizontal PM and Professional Service Automation (PSA):
Consulting companies, advertising agencies, marketing departments, R&D departments, engineering companies, law companies and many other business sectors basically require generic "horizontal" project management to run their companies. In addition, these companies need relatively generic financial and human resources management. This is the "base" configuration of ]project-open[.
- IT Services Management:
Organizations running IT systems require special add-on packages to automate the interaction with hardware and software.
- Translation Organizations:
Translation agencies and internal translation departments (ITDs) require a number of add-on packages to deal with many small provider companies and to integrate with available CAT tools (computer aided translation).
To deal with these different business sectors, ]project-open[ includes a number of add-on packages to the "base" that can deal with the specifics of each business sector.
These specific add-on packages can extend the ]project-open[ "core" using "Plugin Portlet Components", DynFields, DynViews and Menus. This way, they don't add additional complexity to the "core".
Employee Trust and Security Authorization
Should a normal Employee be able to see the full customer list of a company? In some companies (in particular ones with high fluctuation and a low barrier of entry) employees should only be able to see their projects and their customer contacts, while by default companies should be as permissive as possible to reduce overhead costs for authorization services and to improve knowledge flow within the company. Basically there is no correct answer, there is only what is best for the customer, and security and trust decisions should be made on a case by case basis, after fully understanding the company and their intended use of ]project-open[.
Coherence vs. Incoherence
A member of the [ERP-SELECT] mailing list once put it like this: "An ERP system is merely a place where some people can store data and other people trust that this data are correct". However, companies vary a great deal with respect to employees trusting each other to enter "clean" information into an ERP system.
Roll-outs in "coherent" companies are usually very difficult, because every employee wants to make sure during the evaluation period that the system will be able to capture his information well. While the first couple weeks and the roll-out experience in general might plant early doubts and frustrations, this is only temporary and operations usually go very smooth afterward. This is because the Users had specific expectations on what they would be using ]project-open[ to do, it just took a transitional period in order to learn how using a new system. The contrary is the case in less coherent companies, when customers realize that either their requirements were not complete, or that they only now fully understand their automation processes, but only after a quick and painless roll-out of a product that has done little to add value to their company. Not to say that an easy or hard roll-out experience will be indicative of future success with ]project-open[, but be aware of these concerns and recognize them when they happen.
]project-open[ is designed to deal with these differences by means of its default "flexibility" i.e., ]project-open[ in its default configuration provides users with relatively little restrictions on how to enter data and how to structure data. This default configuration is useful for smaller companies and for a quick roll-out at larger organizations. However, large "coherent" companies will typically ask for additional rules (data checks, workflows) after the initial roll-out and "incoherent" companies will need special reports in order to deal with partially inconsistent data.
Department vs. Company vs. Group
This describes the larger context in which ]project-open[ customer organizations work:
- Department:
The organization is part of a larger company. For example, the IT department of the R&D department of a large company might choose ]project-open[ to deal with project and service management, while the rest of the company uses a SAP R/3 systems for managing production, supply chain etc.
In such a context, all CRM, HR, provider management and finance actions are located at the central (SAP) systems and ]project-open[ would then have to import this data and follow the rules defined in the central systems.
- Independent Company:
A (more or less) independent service company will use ]project-open[ to manage most operational processes, except for accounting which is usually handled by a separate accounting package. In this configuration, ]project-open[ will probably serve as the "master" of all operational data, including project billing and finance in general. This data is then exported to the accounting package, so that the accountants can elaborate on the company's balance and income statements every quarter.
- Group:
As a member of a group, the ]project-open[ customer will run more or less like an independent company (see above). However, special access rules may apply for members of neighboring group companies, particularly of neighbor companies that also run ]proje ct-open[.
In order to deal with this type of variability, the most important tool is the capability to disable portlets and menus in ]project-open[, plus there are several add-on packages (auditibility extension, cost-center permissions, SAP-import, ...) in order to reamain conscincious of a business's "autonomy".
Country Specific Differences
Most obviously, language is one the most important difference between countries. Please see the localization section for details. Other differences include:
- Different requirements and habits of financial management
- Varying levels of trust vs. distrust and coherence vs. incoherence specific to each country
- Different ways to present invoices, quotes and purchase orders to business partners.
- Legal requirements governing corporate disclosures, finance, and accounting
]proejct-open[ deals with languages using its localization subsystem and is developed using American English as the base language. Trust and coherence are handled as detailed above, and the presentation of invoices and quotes can be configured using "templates" in the financial system.
Developer About
How do I start out developing modules/extensions for ]po[ ?
Check developers FAQDeveloper Documentation
Until we haven't finished restructuring the developer section, Google and the Full Text Search of http://www.project-open.org are your best friends.
Commit Log
A Commit Log is available at http://www.project-open.org/commitlog.txt
]po[ Developer Mailing List
Stay informed and receive important updates related to ]project-open[ by subscribing to our mailing lists. We manage our mailing lists through SourceForge.
Activity is quite low at this point, the SF forum is still the number one communication platform for community and ]po[ Core Team.
Other Developer Forums:
- Developing interactive Project Dashboards using AJAX/DHTML
http://code.google.com/p/project-open-dashboard/
Developer Reporting a bug
When fixing a bug, more then 50% of the time spent on correcting the error is spent attempting to "reproduce" the bug. "Reproducing" a bug means being able to see the exact issue on one of our development servers in order to understand the bug completely. The original bug reporter is indispensable and can help us save considerable time by including detailed instructions on where and how the bug was encountered allowing us to quickly "reproduce" the bug ourselves. Please follow these guidelines when posting a bug report .
-
- Provide a descriptive name for the bug. "Expense menu tab links to wrong page" is preferred over "Menu tab is broken".
- Provide the URL of the page where the error occurs. "http://www.myposerver/intranet-core/expenses?view=all"
- What are the steps to reproduce the bug? Does the bug only appear under specific circumstances? How did you originally encounter the bug?
- Please try to reproduce the bug on our demo server. This helps us to determine if the bug is specific to your installation or global, or possibly already solved by an upgrade.
- If the bug can be reproduced on the demo server, please open a ticket at sourceforge.net . If possible, please provide screen shots and -if applicable- sample files. It is a great idea to create the screen shots using MS-PowerPoint or OpenOffice "Impress", because you can add comments.
- Please tell us the version of ]project-open[ you are currently running on. Usually we are interested in the version number of the "intranet-core" package in the Package Manager (http://[YOUR_SERVER]/acs-admin/apm/). If the issue is related to an installer, please tell us the version number of your operating system and the installer you used.
- If you want us to fix this issue for you we would need SSH access to your server if the bug is related to your specific installation. This information includes your IP address, username (root) and the password.
We usually make sure that all critical bugs are fixed before we release a new version. Depending on the seriousness of your bug, it may take awhile to receive attention if it is minor and not critical.
Users with a ]project-open[ service contact please log on www.project-open.org and go to http://www.project-open.org/intranet-helpdesk/ to create a new "Bug Request" ticket.
Developer CVS Updates & Versions
This page describes how to access the ]project-open[ source code repository and how to update your ]project-open[ installations manually.
Installing CVS on Linux and Windows
CVS (http://www.nongnu.org/cvs/) is the version control system used to keep the ]project-open[ product code. You need to install a CVS client on your computer in order to access the ]project-open[ cvs server:
- Linux:
CVS is available with all major Linux distributions. Please enter "cvs" in a Linux terminal to check whether CVS is already installed.
To install CVS you can enter "yum install cvs" (CentOS and Red Hat Linux) or "apt-get install cvs" (Debian and Ubuntu).
- Windows:
We recommend the Tortoise CVS (http://www.tortoisecvs.org/) as CVS client. It is proven and free.
Source Code and CVS Control
The ]project-open[ source code is located in the /packages/ folder at /web/projop/packages (Linux) or C:\project-open\servers\projop\packages (Windows). Below /packages/ you should find some 125-135 subdirectories, which correspond to ]project-open[ list of packages.
In order to work with CVS, your source code needs to include "CVS" folders in every package. Depending on your installer, these "CVS" folder may be available or not.
To check for CVS folders, please go to any package (for example: /packages/acs-admin/) folder and list the available sub-directories. You should see something like this:
- acs-admin.info
- catalog
- CVS
- lib
- tcl
- www
Please check if the "CVS" folder is present in your installation.
Downloading ]project-open[ Code with CVS Folders
If your code does not include these "CVS" folders then please download a version of the ]project-open[ source code that includes these folders.
To do so please go to http://sourceforge.net/projects/project-open/files/ and download "project-open-Update-3.4.0.8.0b.tgz" (or any later version of "project-open-Update-x.y.z.v.w.tgz").
Please move your /packages/ somewhere and unpack the project-open-Update-3.4.0.8.0b.tgz file:
- Linux:
# cd /web/projop/
# tar xzf project-open-Update-3.4.0.8.0b.tgz
- Windows:
You can use 7-Zip (http://www.7-zip.org/) to unpack the ".tgz" file.
(There will be a warning during the extraction process, which you can ignore.)
Please check that the "CVS" folders are available now.
Updating to the Latest Version ("HEAD")
Once the CVS folders are available in your code, you can update to the latest ]po[ version ("HEAD") or any other version.
For further instructions please go to http://www.project-open.org/documentation/tutorial_updates
]project-open[ Versions Overview
Please see [version overview and history] for details.
The "HEAD" version of ]project-open[ is in general relatively stable, and several users have reported to upgrade their system regularly to HEAD.
However, generally users should stay with stable versions released on SourceForge either as installers or as "Upgrades".
CVS Packages on the ]po[ CVS Server
The "official" name of the ]project-open[ CVS server is cvs.project-open.net. At the moment there are a number of alias names for the same server including berlin.project-open.net, www.project-open.org, projop.dnsalias.com etc., but all names except for cvs.project-open.net will be dropped at some time in the future.
The ]project-open[ product consists of some 160 packages, which includes both free and commercial packages (please see the www.project-open.com -> Shop page for details). Also, some of the packages are obsolete or not yet prepared for a general audience, so they are not included in the normal product releases. Please treat these packages carefully and never try them on a production server. Please use a development server instead.
- acs-admin
- acs-api-browser
- acs-authentication
- acs-automated-testing
- acs-bootstrap-installer
- acs-content-repository
- acs-core-docs
- acs-datetime
- acs-developer-support
- acs-events
- acs-kernel
- acs-lang
- acs-lang-server
- acs-mail
- acs-mail-lite
- acs-messaging
- acs-reference
- acs-service-contract
- acs-subsite
- acs-tcl
- acs-templating
- acs-translations
- acs-workflow
- ajaxhelper
- ams
- auth-ldap
- auth-ldap-adfind
- auth-ldap-adldapsearch
- bug-tracker
- bulk-mail
- calendar
- categories
- chat
- cms
- contacta
- diagram
- ecommerce
- events
- faq
- general-comments
- intranet
- intranet-amberjack
- intranet-asus-server
- intranet-audit
- intranet-big-brother
- intranet-bug-tracker
- intranet-calendar
- intranet-calendar-holidays
- intranet-confdb
- intranet-contacts
- intranet-core
- intranet-cost
- intranet-cost-center
- intranet-crm-tracking
- intranet-cvs-integration
- intranet-dw-light
- intranet-dynfield
- intranet-exchange-rate
- intranet-expenses
- intranet-expenses-workflow
- intranet-filestorage
- intranet-forum
- intranet-freelance
- intranet-freelance-invoices
- intranet-freelance-rfqs
- intranet-freelance-translation
- intranet-ganttproject
- intranet-gtd-dashboard
- intranet-helpdesk
- intranet-hr
- intranet-html2pdf
- intranet-invoices
- intranet-invoices-templates
- intranet-ldap
- intranet-mail-import
- intranet-material
- intranet-milestone
- intranet-nagios
- intranet-notes
- intranet-notes-tutorial
- intranet-ophelia
- intranet-otp
- intranet-payments
- intranet-pdf-htmldoc
- intranet-procedures
- intranet-release-mgmt
- intranet-reporting
- intranet-reporting-cubes
- intranet-reporting-dashboard
- intranet-reporting-finance
- intranet-reporting-indicators
- intranet-reporting-translation
- intranet-reporting-tutorial
- intranet-resource-management
- intranet-rest
- intranet-rss-reader
- intranet-search
- intranet-search-pg
- intranet-search-pg-files
- intranet-security-update-client
- intranet-security-update-server
- intranet-simple-survey
- intranet-soap-lite-server
- intranet-spam
- intranet-sysconfig
- intranet-timesheet
- intranet-timesheet2
- intranet-timesheet2-invoices
- intranet-timesheet2-task-popup
- intranet-timesheet2-tasks
- intranet-timesheet2-workflow
- intranet-tinytm
- intranet-trans-invoices
- intranet-translation
- intranet-trans-project-wizard
- intranet-trans-quality
- intranet-ubl
- intranet-update-client
- intranet-update-server
- intranet-wiki
- intranet-workflow
- intranet-xmlrpc
- lars-blogger
- mail-tracking
- notifications
- organizations
- oryx-ts-extensions
- postal-address
- psets
- ref-countries
- ref-itu
- ref-language
- ref-timezones
- ref-us-counties
- ref-us-states
- ref-us-zipcodes
- rss-support
- search
- simple-survey
- tclwebtest
- telecom-number
- trackback
- wiki
- workflow
- xml-rpc
- xowiki
Access and Permissions
Most of the packages above are accessible for the CVS user "anonymous" with an empty password.
However, access to some packages (the ones listed as closed-source in www.project-open.com -> Shop) is restricted to specific users. These packages include:
- intranet-audit
- intranet-cost-audit
- intranet-freelance
- intranet-freelance-invoices
- intranet-freelance-rfqs
- intranet-otp
- intranet-reporting-cubes
- intranet-reporting-dashboard
- intranet-reporting-finance
- intranet-reporting-translation
- intranet-trans-quality
- intranet-ubl
Developer Contributing Patches
Let's assume that you have found a bug in your ]project-open[ installation that you have fixed yourself. Or maybe you have added a new feature to ]project-open[ that your would like to share for future releases of ]project-open[. Now you would like to contribute this patch, so that it will be included in future releases.
The Mechanics
Please create the patch using the following commands:
cd /packages/your_package/www/ cvs -z3 diff -u source_file.tcl > patch.diff
Then please go to our Source Forge Bug Tracker page and create a new Bug Report with all the necessary context of the problem ("bug") that your patch solves. Please add a description of the intended new behavior after the patch has been applied. Then please include your patch in the bug description, either in plain text (short patches) or via upload (longer patches).
Intellectual Property Rights
By contributing the patch you agree that your code will become part of the ]project-open[ source code and will be issued under the same license as the original source code file.
The Decision Process
Due to the long release cycle of ]project-open[ it may take several weeks or months before the ]project-open[ core team will decide on whether or not to include the patch in the next release. At that moment, the team will mark the patch as "closed" (if it has been included) or as "rejected" (if it hasn't been included in the product).
Please Follow the Original Formatting
Please follow the formatting and code style of the original source code file for your patch. We (]project-open[ core team) use the Emacs "TCL-mode" formatting, plus tabs for SQL and HTML statements.
Generic vs. Specific Patches
The ]project-open[ source code has been designed to be very "configurable" in order to serve diverse companies involved in many distinct industries. Our primary targets and most successful implementations so far have been consulting companies, translation agencies, advertising companies and internal IT departments. For this reason, the ]project-open[ code needs to honor and allow the specific configurations of each possibly diverse system. For example, there can be no English plain text in the code, instead you must conform the internal localization system so that ]project-open[ can be localized easily to all global languages. When deciding whether or not to accept a particular patch the ]project-open[ core team has several areas of concern, such as if the patch is suitable for different business sectors or solely targeted towards the interests of one industry and if all of these sectors will benefit from the inclusion of this patch into ]project-open[.
So please don't be disappointed if the ]project-open[ replies negatively because they have decided that your patch is too specific.
Dynfield DynField Extensible Architecture
Original Text by Frank Bergman and Juanjo Ruiz
What is DynField?
DynField is an extension of the original OpenACS SQL Metadata system. DynField allows developers to extend objects with new fields. These new fields will appear automatically on all suitable OpenACS pages that deal with this object such as the object's view, edit and list pages.
DynField is an _extension_ mechanism which allows adding dynamic attributes to existing OpenACS objects. However, DynField is not a generic object management system. The creation and deleting of objects are outside of the scope of DynField, because is functionality is frequently handled using PL/SQL or PG/SQL in an object specific way.
DynField is based on code of the great Attribute Management System (AMS) from Matthew Geddard and Richard Hamilton. Also, this document is based on their documentation.
Do I need DynField?
The main purpose of DynField is to allow developers to customize the system for specific web sites or customers without modifying the underlying TCL and ADP source code in the CVS version control system.
- You probably won't need DynField if you only develop a single web community or if you are in the business of adapting OpenACS to customer requirements.
- However, you probably need DynField if you develop a new module that may be useful to many customers with slight variations for each customer.
Design Decisions and Requirements
Please see the The Need for a Different Approach to DB Extendibility for an overview over design decisions and requirements. Basicly, we tried to keep the system as simple as possible (it only defines two new tables) and to stick as much as possible to the original OpenACS Metadata system. Also check the Slides on Dynfield Extensible Architecture.
Architecture
The architecture consists of an extension table to acs_attributes and one new table containing pre-configured "widgets":
acs_attributes already contains the link to OpenACS objects via the object_type field, so dynfield_attributes is basically an extension table that links to dynfield_widgets.
Defining New Attributes
DynField comes with several maintenance screens that allow to define new attributes for a given object type. There are two options:
- Create a new entry for an attribute that already exists.
Use this option in order to enter the existing object fields into DynField. This allows you to use DynField to create object maintenance screens - Create a new entry and create a new table column.
Use this option if you really want to extend the object type.
Extension Tables
The figure to the right shows a typical setting for the object type "User". "User" information is generally stored in the "users" table. However, part of the information is stored in the superclasses of "User" such as "Person", "Party" and "Object".
As a consequence we will have to gather information from all of these "extension tables" when displaying a "User" and we will have to save information to all of these tables when modifying a user. The management of these extension tables can be very difficult in practice, because there can be any number of database constraints related to these extension tables, and some of the extension tables may require a creation using a PL/SQL or PG/SQL database procedure.
This is the reason why we decided NOT to support a generic object creation functionality in DynField. Instead, DynField restricts itself to modifying existing objects, which can be mapped into SQL "update" statements for the extension tables. Even with these restrictions it is possible that a DynField "update" will violate database constraints. However, the probability is much lower in general.
Attribute Widgets
The most important information of an attribute is defined via its "Widget". This widget includes the definition of:
- How the attribute is displayed in an HTML form (using a text box, a drop-down box etc.)
- How it is stored in the database
- Whether or not a validator can be applied to the attribute (when editing the attribute value)
In short, the widget defines the semantics of an attribute. Widgets are explained further below.
DynField and ad_form
You have two options when dealing with DynField and ad_form. Shorthand and detailed.
Shorthand
Shorthands is a completely simple way of creating forms without many options. The supplied object_id must already exist in the acs_object table. The shorthand procs is dynfield_form, which is simply a wrapper for ad_form. For example, to create and ad_form named "contact_person_ae" create a page contacts/www/contact-person-ae.tcl with the following content:
ad_page_contract {
} {
{ct_contact_id:integer,notnull}
}
set title "Contact Person Add/Edit"
set context [list $title]
dynfield_form -package_key "contacts" \
-object_type "ct_contact" \
-page_name "edit_page" \
-form_name "contact_person_ae" \
-object_id $ct_contact_id \
-return_url ""
ad_return_template
The positioning of the form elements on the screen is defined with the attributes themselves. Please see the DynField "layout manager" for details.
The contacts/www/contact-person-ae.adp would contain:
<master> <property name="title">@title@</property"> <property name="context">@context@</property"> <formtemplate id="contact_person_ae"> </formtemplate">
That's it. If this isn't flexible enough you can also go with the detailed method.
Detailed
For many application the DynField and ad_form shorthand will be too simplistic. For those situations, you can use DynField to interface with ad_form. You need to define ad_from -form elements like this:
ad_form ... -form [dynfield::ad_form::elements \ -package_key "contacts" \ -object_type "ct_contact" \ -list_name "contact_person"] ...
Note that this procedure returns an ad form appropriate element list. If you intending to define other elements you will need to ad_from -extend -name form_name -form ...
In the ad_form -edit_request block put
ad_form ... -edit_request {
dynfield::object::attribute::values -vars -object_id $object_id
} ...
This returns the variables upvared into your page, i.e. the first_names attribute could be returned with a value of "Jane" and the last_name attribute with a value of "Doe"... etc. ad_from looks for all form elements and appropriately pre-fills the form with the given values.
In the -on_submit block you enter the following:
ad_from ... -on_submit {
dynfield::ad_form::save \
-package_key "contacts" \
-object_type "ct_contact" \
-list_name "contact_person" \
-form_name "contact_person_ae" \
-object_id $ct_contact_id
}
This is how you interface with DynField and ad_form. You may also specify other code in the -form -on_submit and -on_submit blocks.
DynField and Your Package's UI
To display attributes you can call dynfield::object::attribute::values to get the results back as upvared variables, as an array or as a list however you want. So, if on the contact-view page you do, for example to get an array with all attribute_values that are not null represented in.
dynfield::object::attribute::values -array "contact_info" -object_id $ct_contact_id
To add dynfield_attribute_values to a multirow you call dynfield::multirow::extend to efficiently extend your multirow with dynfield_attribute_values. For example:
db_multirow contacts get_contacts { select ct_contact_id from ct_contacts }
dynfield::multirow::extend \
-package_key "contacts" \
-object_type "ct_contact" \
-list_name "contact_person" \
-multirow "contacts" \
-key "ct_contact_id"
ToDo ...
"Pages" and Attribute Layout
DynField defines the notion of a "page", allowing attributes to be layouted differently in different TCL/ADP pages. Each page defines the position for each attribute. There are three different types of layout defined in DynField, for each type there are specific actions to be taken, but in all of them you can specify which attributes you want to show and which not. This combined with the Cascade Style Sheets and the style option in the <formtemplate> ACS templating tag gives a wide variety of formating options.
Hint: The layout management makes heavy use of the acs-templating and template::form systems, if you do not feel comfortable with it, please revise the corresponding documentation.
- "Absolute positioning"
- "Relative positioning"
- "ADP template"
- <formlabel>: Returns the label of the element
- <formhelptext>: Returns the help text and the 'chunk' between the (<>) and (</>) tag
The "Absolute positioning" uses DIV classes for each label/widget pair. Once the classes are defined is up to the CSS to move each field to the desired place. The use of DIV tags complies with European Accessability regulations.
The "Relative positioning" uses the same principle as the <grid> tag of the ACS template system in order to emulate a table-like structure.
First we define the height and the width of the desired table and after that we sort all the included attributes. The table-builder will use this sort order and the width (x) of the table, so the first (x) elements will be placed in the first rown, the second ones in the second rown, and so on as you can see in the next table example:
| 1st | 2nd | 3rd |
| 4th | 5th | 6th |
| 7th | 8th | ... |
"ADP template" has all the posible freedom because you are editing line by line how you want your form to look like. For the people who has already embebed some dynamic form in a template it should be pretty straight forward as they are used to use the different <form[...]> tags. The dynfield package just adds two new tags to the existent ones which we think are very usefull:
Layout process
The dynfield package is just an extension of what we already have in our page. So you can add fields to pages without form, pages defining the form in the adp file or pages using template::form/ad_form. The drawback of this implementation is that one can get confuse about what is really being executed at one moment and which what values. The standard process shall be the following:
- Call to the load&show dynfield procedure in the tcl file which:
- Get the old attributes values from the database
- Set the page layout/style. First look at the -style paramenter, if nil use the -page_url parameter, if nil get the default page_url for the specified object_type, if nil not to use layout manager (i.e. use standard ACS layout)
- If page_url is used get the layout variables of the corresponding layout_type
- Create form and form elements
- Call to the <formtemplate> tag in the adp file
- Call to the store dynfield procedure in the 'is_valid' section of your template::form/ad_form or in the *-2.tcl page if you do not use it.
Layout tables
The layout pages are defined in the table dynfield_layout_pages:
- object_type: each page can use attributes from more than one object_type
- page_url: we use the global page url as the page identifier
- layout_type: one of the previusly described types 'absolute' 'relative' 'adp'
- table_width: number of rows for the table, only for 'relative' layouts
- table_height: number of cols for the table, only for 'relative' layouts
- adp_file: name of the adp template to use, only for 'adp' layouts
- default_p: use this page as the default one for this object_type
The dynfield_layout table define the attributes showed in each page
- attribute_id: dynfield attribute identifier
- object_type
- page_url: reference to dynfield_layout_pages
- class: the name of the CSS class, only for 'absolute' layouts
- sort_key: an integer defining the place of the attribute, only for 'relative' layouts
... For further reference please look the documentation in the dynfield procedures.
DynField Widgets
DynField defines several kinds of widgets:- Standard OpenACS Widgets:
These widgets use the existing OpenACS widgets to display a wide range of data types.
DynField sets up a number of these widgets during the installation process, so they are ready to use - Category Select Widgets:
These widgets define drop-down boxes with options defined using the OpenACS categories module.
Please read below how to create a new Category Widget. - SQL Select Widgets:
These widgets define drop-down boxes using an SQL statement to determine the range of valid options.
The following section explains the different choices for a widget in detail:
Storage Type
The storage type determines how the value of the widget is stored in the database. There are several options:
- "Table Column":
The standard storage type: A new column is created in the object's table or in an extension table to store the attribute value. - "Multi-Select Mapping Table": (not implemented yet!)
A special storage type to store multiple values, for example from a multiple select box. The values are stored using an internal mapping table. ToDo: Implement and describe mapping table.
OpenACS Datatype
The OpenACS datatype is a high-level description of the datatype. It is used to create both the SQL datatype for Oracle/Postgres and the datatype for the ad_form.
| OpenACS Datatype | SQL Datatype |
|---|---|
| string | varchar(1000) |
|
boolean |
char(1) |
| number | "number" |
| money | number (12,2) |
| date | date |
| text | varchar(4000) |
| integer | integer |
|
enumeration |
varchar(100) |
| keyword | varchar(1000) |
Datatype
Widget
Creating a New Category Widget
Creating a new Category Widget requires an integration between the OpenACS "Categories" package and DynField:
- You have to create a new Category tree for the widget (if it doesn't exist already). Go to the category admin pages at /categories/cadmin/ and select "Create a new tree". Let's call it "Customer Classification" and press OK.
- Select the new tree and choose "Add node at top level" to give it its root node. Let's call the root node "No Classification" and press OK
- Now you can successifly add sub-categories to "No Classification" by clicking on the "Add child" link. For example we might add the sub classifications "A" (= great customer), "B" (= ok customer) and "C" (= customer to get rid of)
- Finally on the category part, we have to find out the "tree_id" of the current tree. To do this, please check the current URL for a "tree_id" piece, which is followed by a number. Perhaps "tree_id" is written as "tree%5fid=630", with the "%5f" representing the underscore "_". However, we need the number behind the "=", so the 630 in this example.
- Now let's go to /dynfield/widgets/ and select "Create a new widget" link at the bottom.
- Let's enter the following data:
- Widget Name = "customer_classification"
- Pretty Name = "Customer Classification"
- Pretty Plural = "Customer Classifications"
- Storage Type = "Normal Value"
- ACS Datatype = "Integer"
- Widget = "Category"
- Datatype = "Integer" and
- Paremeters = "{custom {category_tree_id 630}}" (please replace the 630 by your tree_id)
- That's it. Now you have a new "customer_classification" widget that is available when you define new attributes of an object.
DynField Permissions
ToDo
Possible values are
- absolute_links: '0'
- abstract_p: 'f'
- auto_save: 'false'
- creation_date: '2011-11-25 18:04:19.139283+01'
- creation_user: '853'
- creator: 'Richard Thiemann'
- current_user: '0'
- description: 'An explanation of the DynField Design Architecture'
- do_substitutions: '1'
- folder_id: '-100'
- form: '::xowiki::WikiForm'
- id_column: 'page_id'
- last_modified: '2011-11-25 18:04:19.139283+01'
- mime_type: 'text/html'
- name: 'en:dynfield_design'
- nls_language: 'en_US'
- object_id: '768742'
- object_type: '::xowiki::Page'
- package_id: '252723'
- page_id: '768742'
- page_order: 'Dynfield'
- parent_id: '252746'
- pretty_name: 'XoWiki Page'
- pretty_plural: 'XoWiki Pages'
- publish_date: '2011-11-25 18:04:19.139283+01'
- publish_status: 'ready'
- recursion_count: '0'
- references: ''
- render_adp: '1'
- revision_id: '768742'
- security_inherit_p: 't'
- sql_package_name: '::xowiki::Page'
- storage_type: 'text'
- supertype: 'content_revision'
- table_name: 'xowiki_page'
- title: 'DynField Extensible Architecture'
- unresolved_references: '0'
- with_table: 'true'
Dynfield Slides on Dynfield Extensible Architecture
Slides on Extensible ArchitectureDynfield The Need for A Different Approach to DB extendibility
Original Text by Frank Bergmann
- The following posting is a kind of high-level requirements document explaining the business that finally lead to the creation of FlexBase.
Hi,
We're currently facing an old question again: How to build a large scale OpenACS application (composed by several modules) that can be customized so that it suits more then one customer? Sounds easy, but it isn't if you want to avoid a copy-paste-modify approach.
Let's take a simple example to explain the requirements: Let's consider user management. OpenACS provides several standard user management screens with the fields "first_names" and "second name". However, people in Spain have two first names and two second names, such as "Juan José Ruiz Martínez". And this time we are working for a demanding customer who requires us to do it "their way" and to use their design standards. So we actually have to include the four pieces of the name in one line so that the users screen needs to look like:
Name: [First1] [First2] [Second1] [Second2] Username: [Username] Email: [Email] Password: [Password] URL: [Url]
However, another customer from the US may requires us to add a field for a middle name such as in "Frank W. Bergmann" and a third customer requires us to add a second email address for the private email (just to put an example).
Option 1: The Current Copy-Past-Modify Approach
The standard approach in the OpenACS community (and also in many other Web-based content & community tools) for such a situation is to take the OpenACS code as a base and to extend it, adding the necessary fields "manually".
This works pretty well for the first and maybe for the second customer, but after that you're getting a holy mess of different versions that are difficult to maintain. Imagine that you need to upgrade to the next version of OpenACS or that you have developed an improvement for one of the customers that might be useful for the others as well.
Extensible Architecture Requirements
But if you start thinking about how to unify the user management code for all customers, you immediately get to the question of how to extend the unified code to accommodate the different requirement and you get to a list of quite ugly requirements:
- Adding new fields to a business object:
We want to be able to add any number of new fields to a user or another object without touching the "core" code. These new fields should support validation and referential integrity such as all other fields. - Integrating new packages:
We want to be able to add new packages to the system, so that they are integrated with the rest of the system. Let's consider adding a "bookmark list". We may want to be able to show a list of bookmarks on the users main page, even though the users page didn't "know" about bookmarks before. And please remember, we don't want to touch the TCL or ADP code, because they are common to all of our customers.
Also, we want to add a link "add a bookmark" in another part of the page and we want to add a new item in the global site menu such as "Bookmark Management". - Customized layout and design:
Customers are picky, so we want to be able to adapt to all of their design preferences, particular in terms of form layout. Colors and stuff are covered by CSS stylesheets anyway.
Taking into account the overall TCL/ADP structure of OpenACS pages, we can translate these requirements into technical issues that we have to tackle:
- Customizing ADPs:
How can we add dynamicallynew pieces of code to an ADP page to display new contents or links?
How do we dynamically add new fields to a form or new columns to a list view? - Customizing TCLs:
How can we dynamically add business logic to TCLs? - Customizing SQLs:
How can we patch SQL statements to include new fields from new "extension tables" or dynamic attributes? How do we sort the results according to an extension field that didn't exist at the time when we wrote the SQL? - Menus and Navigation:
How can we dynamically adapt the navigation to reflect the presence of new packages? - Links and References:
How do we link from "core" pages to pages in new add-on packages that didn't exist at the time of writing the "core" pages?
Option 2: Extensibility Using User Exits
So let's come back to our user registration example in order to explore how "User Exits" could help us to build a single page that would serve all of our fictitious customers.
The ADP Page
Here we could add several "user exits" to the ADP page that would look like this:
<%=[ad_call_proc_if_exists TCL_library_routine] %>
We could then write a TCL_library_routine implementation for a specific customer that would add the right HTML code in order to create the new fields. Also, we could call ADP includes on an similar "if exists" base to include pieces of content.
The TCL Page
The TCL page has to provide the ADP page with additional business logic for the new fields. So we could use same "user exits" trick and call a TCL library routine at the end of the TCL if it exists.
The SQL
This is more complicated. Let's imagine that the new user name fields are implemented via a "user_extension_table". How do we "join" the contents of this table into our exiting SQL?
One option is to use SQL "views". The TCL page would do a "select * from my_users" where "my_users" is an SQL view that by default only performs a "select * from cc_users". However, our extension module could now overwrite this view with a new version that joins cc_users with the user_extension_table. This approach may cause problems when there is more then one package adding fields to a user, but it's simple and straight-forward.
Menus, Navigation, Links and References
We could again use the "user exits" to implement flexible menus and references.
Pros & Cons
The advantage of this "architecture" is that it's quite simple, transparent and easy to understand. It is actually already being used in the request processor using the ad_call_proc_if_exists routine. Also, it provides a simple "migration path" to migrate an existing hard-coded system towards a more flexible one without rewriting the whole code. However, there may be "extension conflicts" between different modules that extend the same business object, and the code may become very ugly ("spaghetti") with the time.
Option 3: Store Everything in the Database
The current ]project-open[ architecture stores all variable elements in the database, such as menus, links, "components" (ADP includes), table columns and form fields. Table columns include the TCL code to render a table cell content and they include the "order by" clause if a user wants to sort a list by a specific column. Here is the comlete documentation: http://www.project-open.org/doc/intranet-core/
Pros & Cons
This is a very straight-forward approach that allows for great flexibility and performance. An extension module can just add a new column to a table and define some extra_select, extra_from and extra_where pieces for the SQL clause. However, the approach requires a considerable initial effort and storing TCL code in the database isn't really an elegant solution. So this is why we are considering alternatives in a project that is not related to ]project-open[.
Option 4: Extending ad_form and Templating
The last option that we explored is based on the OpenACS templating system and ad_forms. These modules use a list of fields in order to control the rendering of forms and tables. Normally, these lists of fields are defined statically as part of the TCL page as in the following example:
ad_form -form {
menu_id:key
{name:text(text) {label Name} {html {size 40}}}
{label:text(text) {label Label} {html {size 30}}}
{url:text(text) {label URL} {html {size 100}}}
{sort_order:text(text) {label "Sort Order"} {html {size 10}}}
} [...]
However, the definition of these fields could be moved out of the ad_form procedure call into a variable. And once it is within a variable, we could overwrite this variable in the case that an exension module has added more fields in a database table:
set field_list {
menu_id:key
{name:text(text) {label Name} {html {size 40}}}
{label:text(text) {label Label} {html {size 30}}}
{url:text(text) {label URL} {html {size 100}}}
{sort_order:text(text) {label "Sort Order"} {html {size 10}}}
}
if {[check_the_database]} {
set field_list [get_field_list_from_the_database]
}
ad_form -form $field_list [...]
This "architecture" would allow for a simple and convenient default configuration defined in the TCL page, while allowing for full extensibility by extension modules.
Another shortcoming of ad_form is its current HTML layout inflexibility. ad_form renders the form fields as a vertical list by default. There is no easy way to say that first_name and second_name should go together into the first line of the form. However, ad_form allows for custom rendering "form templates", so that we could tackle this issue by introducing new field parameters for field positioning (absolute horizontal/vertical or relative line/column) and by creating a customized version of a form template to implement something similar to a "layout manager" in Java.
Also, there are facilities in ad_form to handle dynamic fields via acs_attributes and the OpenACS SQL metadata system. However, the implementation of the acs_attributes feature is not very "transparent" (you don't understand easily what it happening) and doesn't seem to be commonly used. The only place that I have seen is group_type maintenance, and this is an incomplete implementation error with an error when trying to use default values.
Pros & Cons
ad_form and templating could allow for a flexible architecture without storing TCL code in the database. It would provide a very elegant solution if the integration with acs_attributes would work in real-world applications.
However, I personally don't like the "hide as much as possible" philosophy of ad_form, and I have lost many hours debugging relatively simple issues due to the lack of transparency and documentation.
How to Proceed?
How should we go forward? I currently believe that the third option (extending ad_forms with or without acs_attributes) is the most promising one, but I see a lot of risks related to it. Is there an interest from the community and the package maintainers to support our efforts? How should we organize the development so that our modifications could be incorporated into OpenACS?
We are exposed to a certain pressure in order to come up with a viable plan within a few days...
Dynfield DynField - Extensible Architecture
Original Text by Frank Bergman and Juanjo Ruiz
What is DynField?
DynField is an extension of the original OpenACS SQL Metadata system. DynField allows developers to extend objects with new fields. These new fields will appear automatically on all suitable OpenACS pages that deal with this object such as the object's view-, edit and list pages.
DynField is an _extension_ mechanism which allows adding dynamic attributes to existing OpenACS objects. However, DynField is not a generic object management system. The creation and deleting of objects are outside of the scope of DynField, because is functionality is frequently handled using PL/SQL or PG/SQL in an object specific way.
DynField is based on code of the great Attribute Management System (AMS) from Matthew Geddard and Richard Hamilton. Also, this document is based on their documentation.
Do I need DynField?
The main purpose of DynField is to allow developers to customize the system for specific web sites or customers without modifying the underlying TCL and ADP source code in the CVS version control system.
- You probably won't need DynField if you only develop a single web community or if you are in the business of adapting OpenACS to customer requirements.
- However, you probably need DynField if you develop a new module that may be useful to many customers with slight variations for each customer.
Design Decisions and Requirements
Please see the initial posting at OpenACS for an overview over design decisions and requirements. Basicly, we tried to keep the system as simple as possible (it only defines two new tables) and to stick as much as possible to the original OpenACS Metadata system. Also check the enclosed PowerPoint slides.
Architecture
The architecture consists of an extension table to acs_attributes and one new table containing preconfigured "widgets":
acs_attributes already contains the link to OpenACS objects via the object_type field, so dynfield_attributes is basicly an extension table that links to dynfield_widgets.
Defining New Attributes
DynField comes with several maintenance screens that allow to define new attributes for a given object type. There are two options:
- Create a new entry for an attribute that already exists.
Use this option in order to enter the existing object fields into DynField. This allows you to use DynField to create object maintenance screens - Create a new entry and create a new table column.
Use this option if you really want to extend the object type.
Extension Tables
The figure to the right shows a typical setting for the object type "User". "User" information is generally stored in the "users" table. However, part of the information is stored in the superclasses of "User" such as "Person", "Party" and "Object".
As a consequence we will have to gather information from all of these "extension tables" when displaying a "User" and we will have to save information to all of these tables when modifying a user. The management of these extension tables can be very difficult in practice, because there can be any number of database constraints related to these extension tables, and some of the extension tables may require a creation using a PL/SQL or PG/SQL database procedure.
This is the reason why we decided NOT to support a generic object creation functionality in DynField. Instead, DynField restricts itself to modifying existing objects, which can be mapped into SQL "update" statements for the extension tables. Even with these restrictions it is possible that a DynField "update" will violate database constraints. However, the probability is much lower in general.
Attribute Widgets
The most important information of an attribute is defined via its "Widget". This widget includes the definition of:
- How the attribute is displayed in an HTML form (using a text box, a drop-down box etc.)
- How it is stored in the database
- Whether or not a validator can be applied to the attribute (when editing the attribute value)
In short, the widget defines the semantics of an attribute. Widgets are explained further below.
DynField and ad_form
You have two options when dealing with DynField and ad_form. Shorthand and detailed.
Shorthand
Shorthands is a completely simple way of creating forms without many options. The supplied object_id must already exist in the acs_object table. The shorthand procs is dynfield_form, which is simply a wrapper for ad_form. For example, to create and ad_form named "contact_person_ae" create a page contacts/www/contact-person-ae.tcl with the following content:
ad_page_contract {
} {
{ct_contact_id:integer,notnull}
}
set title "Contact Person Add/Edit"
set context [list $title]
dynfield_form -package_key "contacts" \
-object_type "ct_contact" \
-page_name "edit_page" \
-form_name "contact_person_ae" \
-object_id $ct_contact_id \
-return_url ""
ad_return_template
The positioning of the form elements on the screen is defined with the attributes themselves. Please see the DynField "layout manager" for details.
The contacts/www/contact-person-ae.adp would contain:
<master> <property name="title">@title@</property"> <property name="context">@context@</property"> <formtemplate id="contact_person_ae"> </formtemplate">
That's it. If this isn't flexible enough you can also go with the detailed method.
Detailed
For many application the DynField and ad_form shorthand will be too simplistic. For those situations, you can use DynField to interface with ad_form. You need to define ad_from -form elements like this:
ad_form ... -form [dynfield::ad_form::elements \ -package_key "contacts" \ -object_type "ct_contact" \ -list_name "contact_person"] ...
Note that this procedure returns an ad form appropriate element list. If you intending to define other elements you will need to ad_from -extend -name form_name -form ...
In the ad_form -edit_request block put
ad_form ... -edit_request {
dynfield::object::attribute::values -vars -object_id $object_id
} ...
This returns the variables upvared into your page, i.e. the first_names attribute could be returned with a value of "Jane" and the last_name attribute with a value of "Doe"... etc. ad_from looks for all form elements and appropriately pre-fills the form with the given values.
In the -on_submit block you enter the following:
ad_from ... -on_submit {
dynfield::ad_form::save \
-package_key "contacts" \
-object_type "ct_contact" \
-list_name "contact_person" \
-form_name "contact_person_ae" \
-object_id $ct_contact_id
}
This is how you interface with DynField and ad_form. You may also specify other code in the -form -on_submit and -on_submit blocks.
DynField and Your Package's UI
To display attributes you can call dynfield::object::attribute::values to get the results back as upvared variables, as an array or as a list however you want. So, if on the contact-view page you do, for example to get an array with all attribute_values that are not null represented in.
dynfield::object::attribute::values -array "contact_info" -object_id $ct_contact_id
To add dynfield_attribute_values to a multirow you call dynfield::multirow::extend to efficiently extend your multirow with dynfield_attribute_values. For example:
db_multirow contacts get_contacts { select ct_contact_id from ct_contacts }
dynfield::multirow::extend \
-package_key "contacts" \
-object_type "ct_contact" \
-list_name "contact_person" \
-multirow "contacts" \
-key "ct_contact_id"
ToDo ...
"Pages" and Attribute Layout
DynField defines the notion of a "page", allowing attributes to be layouted differently in different TCL/ADP pages. Each page defines the position for each attribute. There are three different types of layout defined in DynField, for each type there are specific actions to be taken, but in all of them you can specify which attributes you want to show and which not. This combined with the Cascade Style Sheets and the style option in the <formtemplate> ACS templating tag gives a wide variety of formating options.
Hint: The layout management makes heavy use of the acs-templating and template::form systems, if you do not feel comfortable with it, please revise the corresponding documentation.
- "Absolute positioning"
- "Relative positioning"
- "ADP template"
- <formlabel>: Returns the label of the element
- <formhelptext>: Returns the help text and the 'chunk' between the (<>) and (</>) tag
The "Absolute positioning" uses DIV classes for each label/widget pair. Once the classes are defined is up to the CSS to move each field to the desired place. The use of DIV tags complies with European Accessability regulations.
The "Relative positioning" uses the same principle as the <grid> tag of the ACS template system in order to emulate a table-like structure.
First we define the height and the width of the desired table and after that we sort all the included attributes. The table-builder will use this sort order and the width (x) of the table, so the first (x) elements will be placed in the first rown, the second ones in the second rown, and so on as you can see in the next table example:
| 1st | 2nd | 3rd |
| 4th | 5th | 6th |
| 7th | 8th | ... |
"ADP template" has all the posible freedom because you are editing line by line how you want your form to look like. For the people who has already embebed some dynamic form in a template it should be pretty straight forward as they are used to use the different <form[...]> tags. The dynfield package just adds two new tags to the existent ones which we think are very usefull:
Layout process
The dynfield package is just an extension of what we already have in our page. So you can add fields to pages without form, pages defining the form in the adp file or pages using template::form/ad_form. The drawback of this implementation is that one can get confuse about what is really being executed at one moment and which what values. The standard process shall be the following:
- Call to the load&show dynfield procedure in the tcl file which:
- Get the old attributes values from the database
- Set the page layout/style. First look at the -style paramenter, if nil use the -page_url parameter, if nil get the default page_url for the specified object_type, if nil not to use layout manager (i.e. use standard ACS layout)
- If page_url is used get the layout variables of the corresponding layout_type
- Create form and form elements
- Call to the <formtemplate> tag in the adp file
- Call to the store dynfield procedure in the 'is_valid' section of your template::form/ad_form or in the *-2.tcl page if you do not use it.
Layout tables
The layout pages are defined in the table dynfield_layout_pages:
- object_type: each page can use attributes from more than one object_type
- page_url: we use the global page url as the page identifier
- layout_type: one of the previusly described types 'absolute' 'relative' 'adp'
- table_width: number of rows for the table, only for 'relative' layouts
- table_height: number of cols for the table, only for 'relative' layouts
- adp_file: name of the adp template to use, only for 'adp' layouts
- default_p: use this page as the default one for this object_type
The dynfield_layout table define the attributes showed in each page
- attribute_id: dynfield attribute identifier
- object_type
- page_url: reference to dynfield_layout_pages
- class: the name of the CSS class, only for 'absolute' layouts
- sort_key: an integer defining the place of the attribute, only for 'relative' layouts
... For further reference please look the documentation in the dynfield procedures.
DynField Widgets
DynField defines several kinds of widgets:- Standard OpenACS Widgets:
These widgets use the existing OpenACS widgets to display a wide range of data types.
DynField sets up a number of these widgets during the installation process, so they are ready to use - Category Select Widgets:
These widgets define drop-down boxes with options defined using the OpenACS categories module.
Please read below how to create a new Category Widget. - SQL Select Widgets:
These widgets define drop-down boxes using an SQL statement to determine the range of valid options.
The following section explains the different choices for a widget in detail:
Storage Type
The storage type determines how the value of the widget is stored in the database. There are several options:
- "Table Column":
The standard storage type: A new column is created in the object's table or in an extension table to store the attribute value. - "Multi-Select Mapping Table": (not implemented yet!)
A special storage type to store multiple values, for example from a multiple select box. The values are stored using an internal mapping table. ToDo: Implement and describe mapping table.
OpenACS Datatype
The OpenACS datatype is a high-level description of the datatype. It is used to create both the SQL datatype for Oracle/Postgres and the datatype for the ad_form.
| OpenACS Datatype | SQL Datatype |
|---|---|
| string | varchar(1000) |
|
boolean |
char(1) |
| number | "number" |
| money | number (12,2) |
| date | date |
| text | varchar(4000) |
| integer | integer |
|
enumeration |
varchar(100) |
| keyword | varchar(1000) |
Datatype
Widget
Creating a New Category Widget
Creating a new Category Widget requires an integration between the OpenACS "Categories" package and DynField:
- You have to create a new Category tree for the widget (if it doesn't exist already). Go to the category admin pages at /categories/cadmin/ and select "Create a new tree". Let's call it "Customer Classification" and press OK.
- Select the new tree and choose "Add node at top level" to give it its root node. Let's call the root node "No Classification" and press OK
- Now you can successifly add sub-categories to "No Classification" by clicking on the "Add child" link. For example we might add the sub classifications "A" (= great customer), "B" (= ok customer) and "C" (= customer to get rid of)
- Finally on the category part, we have to find out the "tree_id" of the current tree. To do this, please check the current URL for a "tree_id" piece, which is followed by a number. Perhaps "tree_id" is written as "tree%5fid=630", with the "%5f" representing the underscore "_". However, we need the number behind the "=", so the 630 in this example.
- Now let's go to /dynfield/widgets/ and select "Create a new widget" link at the bottom.
- Let's enter the following data:
- Widget Name = "customer_classification"
- Pretty Name = "Customer Classification"
- Pretty Plural = "Customer Classifications"
- Storage Type = "Normal Value"
- ACS Datatype = "Integer"
- Widget = "Category"
- Datatype = "Integer" and
- Paremeters = "{custom {category_tree_id 630}}" (please replace the 630 by your tree_id)
- That's it. Now you have a new "customer_classification" widget that is available when you define new attributes of an object.
DynField Permissions
ToDo
Possible values are
- absolute_links: '0'
- abstract_p: 'f'
- auto_save: 'false'
- creation_date: '2009-04-08 17:12:22.36931+02'
- creation_user: '272160'
- creator: 'Richard Thiemann'
- current_user: '0'
- description: 'An explanation of the DynField Design Architecture'
- do_substitutions: '1'
- folder_id: '-100'
- form: '::xowiki::WikiForm'
- id_column: 'page_id'
- last_modified: '2009-04-08 17:12:22.36931+02'
- mime_type: 'text/html'
- name: 'en:dynfield_design_architecture'
- nls_language: 'en_US'
- object_id: '274760'
- object_type: '::xowiki::Page'
- package_id: '252723'
- page_id: '274760'
- page_order: 'Dynfield'
- parent_id: '252746'
- pretty_name: 'XoWiki Page'
- pretty_plural: 'XoWiki Pages'
- publish_date: '2009-04-08 17:12:22.36931+02'
- publish_status: 'ready'
- recursion_count: '0'
- references: ''
- render_adp: '1'
- revision_id: '274760'
- security_inherit_p: 't'
- sql_package_name: '::xowiki::Page'
- storage_type: 'text'
- supertype: 'content_revision'
- table_name: 'xowiki_page'
- title: 'DynField - Extensible Architecture'
- unresolved_references: '0'
- with_table: 'true'
Dynfield DynField - Extensible Architecture
Original Text by Frank Bergman and Juanjo Ruiz
What is DynField?
DynField is an extension of the original OpenACS SQL Metadata system. DynField allows developers to extend objects with new fields. These new fields will appear automatically on all suitable OpenACS pages that deal with this object such as the object's view-, edit and list pages.
DynField is an _extension_ mechanism which allows adding dynamic attributes to existing OpenACS objects. However, DynField is not a generic object management system. The creation and deleting of objects are outside of the scope of DynField, because is functionality is frequently handled using PL/SQL or PG/SQL in an object specific way.
DynField is based on code of the great Attribute Management System (AMS) from Matthew Geddard and Richard Hamilton. Also, this document is based on their documentation.
Do I need DynField?
The main purpose of DynField is to allow developers to customize the system for specific web sites or customers without modifying the underlying TCL and ADP source code in the CVS version control system.
- You probably won't need DynField if you only develop a single web community or if you are in the business of adapting OpenACS to customer requirements.
- However, you probably need DynField if you develop a new module that may be useful to many customers with slight variations for each customer.
Design Decisions and Requirements
Please see the initial posting at OpenACS for an overview over design decisions and requirements. Basicly, we tried to keep the system as simple as possible (it only defines two new tables) and to stick as much as possible to the original OpenACS Metadata system. Also check the enclosed PowerPoint slides.
Architecture
The architecture consists of an extension table to acs_attributes and one new table containing preconfigured "widgets":
acs_attributes already contains the link to OpenACS objects via the object_type field, so dynfield_attributes is basicly an extension table that links to dynfield_widgets.
Defining New Attributes
DynField comes with several maintenance screens that allow to define new attributes for a given object type. There are two options:
- Create a new entry for an attribute that already exists.
Use this option in order to enter the existing object fields into DynField. This allows you to use DynField to create object maintenance screens - Create a new entry and create a new table column.
Use this option if you really want to extend the object type.
Extension Tables
The figure to the right shows a typical setting for the object type "User". "User" information is generally stored in the "users" table. However, part of the information is stored in the superclasses of "User" such as "Person", "Party" and "Object".
As a consequence we will have to gather information from all of these "extension tables" when displaying a "User" and we will have to save information to all of these tables when modifying a user. The management of these extension tables can be very difficult in practice, because there can be any number of database constraints related to these extension tables, and some of the extension tables may require a creation using a PL/SQL or PG/SQL database procedure.
This is the reason why we decided NOT to support a generic object creation functionality in DynField. Instead, DynField restricts itself to modifying existing objects, which can be mapped into SQL "update" statements for the extension tables. Even with these restrictions it is possible that a DynField "update" will violate database constraints. However, the probability is much lower in general.
Attribute Widgets
The most important information of an attribute is defined via its "Widget". This widget includes the definition of:
- How the attribute is displayed in an HTML form (using a text box, a drop-down box etc.)
- How it is stored in the database
- Whether or not a validator can be applied to the attribute (when editing the attribute value)
In short, the widget defines the semantics of an attribute. Widgets are explained further below.
DynField and ad_form
You have two options when dealing with DynField and ad_form. Shorthand and detailed.
Shorthand
Shorthands is a completely simple way of creating forms without many options. The supplied object_id must already exist in the acs_object table. The shorthand procs is dynfield_form, which is simply a wrapper for ad_form. For example, to create and ad_form named "contact_person_ae" create a page contacts/www/contact-person-ae.tcl with the following content:
ad_page_contract {
} {
{ct_contact_id:integer,notnull}
}
set title "Contact Person Add/Edit"
set context [list $title]
dynfield_form -package_key "contacts" \
-object_type "ct_contact" \
-page_name "edit_page" \
-form_name "contact_person_ae" \
-object_id $ct_contact_id \
-return_url ""
ad_return_template
The positioning of the form elements on the screen is defined with the attributes themselves. Please see the DynField "layout manager" for details.
The contacts/www/contact-person-ae.adp would contain:
<master> <property name="title">@title@</property"> <property name="context">@context@</property"> <formtemplate id="contact_person_ae"> </formtemplate">
That's it. If this isn't flexible enough you can also go with the detailed method.
Detailed
For many application the DynField and ad_form shorthand will be too simplistic. For those situations, you can use DynField to interface with ad_form. You need to define ad_from -form elements like this:
ad_form ... -form [dynfield::ad_form::elements \ -package_key "contacts" \ -object_type "ct_contact" \ -list_name "contact_person"] ...
Note that this procedure returns an ad form appropriate element list. If you intending to define other elements you will need to ad_from -extend -name form_name -form ...
In the ad_form -edit_request block put
ad_form ... -edit_request {
dynfield::object::attribute::values -vars -object_id $object_id
} ...
This returns the variables upvared into your page, i.e. the first_names attribute could be returned with a value of "Jane" and the last_name attribute with a value of "Doe"... etc. ad_from looks for all form elements and appropriately pre-fills the form with the given values.
In the -on_submit block you enter the following:
ad_from ... -on_submit {
dynfield::ad_form::save \
-package_key "contacts" \
-object_type "ct_contact" \
-list_name "contact_person" \
-form_name "contact_person_ae" \
-object_id $ct_contact_id
}
This is how you interface with DynField and ad_form. You may also specify other code in the -form -on_submit and -on_submit blocks.
DynField and Your Package's UI
To display attributes you can call dynfield::object::attribute::values to get the results back as upvared variables, as an array or as a list however you want. So, if on the contact-view page you do, for example to get an array with all attribute_values that are not null represented in.
dynfield::object::attribute::values -array "contact_info" -object_id $ct_contact_id
To add dynfield_attribute_values to a multirow you call dynfield::multirow::extend to efficiently extend your multirow with dynfield_attribute_values. For example:
db_multirow contacts get_contacts { select ct_contact_id from ct_contacts }
dynfield::multirow::extend \
-package_key "contacts" \
-object_type "ct_contact" \
-list_name "contact_person" \
-multirow "contacts" \
-key "ct_contact_id"
ToDo ...
"Pages" and Attribute Layout
DynField defines the notion of a "page", allowing attributes to be layouted differently in different TCL/ADP pages. Each page defines the position for each attribute. There are three different types of layout defined in DynField, for each type there are specific actions to be taken, but in all of them you can specify which attributes you want to show and which not. This combined with the Cascade Style Sheets and the style option in the <formtemplate> ACS templating tag gives a wide variety of formating options.
Hint: The layout management makes heavy use of the acs-templating and template::form systems, if you do not feel comfortable with it, please revise the corresponding documentation.
- "Absolute positioning"
- "Relative positioning"
- "ADP template"
- <formlabel>: Returns the label of the element
- <formhelptext>: Returns the help text and the 'chunk' between the (<>) and (</>) tag
The "Absolute positioning" uses DIV classes for each label/widget pair. Once the classes are defined is up to the CSS to move each field to the desired place. The use of DIV tags complies with European Accessability regulations.
The "Relative positioning" uses the same principle as the <grid> tag of the ACS template system in order to emulate a table-like structure.
First we define the height and the width of the desired table and after that we sort all the included attributes. The table-builder will use this sort order and the width (x) of the table, so the first (x) elements will be placed in the first rown, the second ones in the second rown, and so on as you can see in the next table example:
| 1st | 2nd | 3rd |
| 4th | 5th | 6th |
| 7th | 8th | ... |
"ADP template" has all the posible freedom because you are editing line by line how you want your form to look like. For the people who has already embebed some dynamic form in a template it should be pretty straight forward as they are used to use the different <form[...]> tags. The dynfield package just adds two new tags to the existent ones which we think are very usefull:
Layout process
The dynfield package is just an extension of what we already have in our page. So you can add fields to pages without form, pages defining the form in the adp file or pages using template::form/ad_form. The drawback of this implementation is that one can get confuse about what is really being executed at one moment and which what values. The standard process shall be the following:
- Call to the load&show dynfield procedure in the tcl file which:
- Get the old attributes values from the database
- Set the page layout/style. First look at the -style paramenter, if nil use the -page_url parameter, if nil get the default page_url for the specified object_type, if nil not to use layout manager (i.e. use standard ACS layout)
- If page_url is used get the layout variables of the corresponding layout_type
- Create form and form elements
- Call to the <formtemplate> tag in the adp file
- Call to the store dynfield procedure in the 'is_valid' section of your template::form/ad_form or in the *-2.tcl page if you do not use it.
Layout tables
The layout pages are defined in the table dynfield_layout_pages:
- object_type: each page can use attributes from more than one object_type
- page_url: we use the global page url as the page identifier
- layout_type: one of the previusly described types 'absolute' 'relative' 'adp'
- table_width: number of rows for the table, only for 'relative' layouts
- table_height: number of cols for the table, only for 'relative' layouts
- adp_file: name of the adp template to use, only for 'adp' layouts
- default_p: use this page as the default one for this object_type
The dynfield_layout table define the attributes showed in each page
- attribute_id: dynfield attribute identifier
- object_type
- page_url: reference to dynfield_layout_pages
- class: the name of the CSS class, only for 'absolute' layouts
- sort_key: an integer defining the place of the attribute, only for 'relative' layouts
... For further reference please look the documentation in the dynfield procedures.
DynField Widgets
DynField defines several kinds of widgets:- Standard OpenACS Widgets:
These widgets use the existing OpenACS widgets to display a wide range of data types.
DynField sets up a number of these widgets during the installation process, so they are ready to use - Category Select Widgets:
These widgets define drop-down boxes with options defined using the OpenACS categories module.
Please read below how to create a new Category Widget. - SQL Select Widgets:
These widgets define drop-down boxes using an SQL statement to determine the range of valid options.
The following section explains the different choices for a widget in detail:
Storage Type
The storage type determines how the value of the widget is stored in the database. There are several options:
- "Table Column":
The standard storage type: A new column is created in the object's table or in an extension table to store the attribute value. - "Multi-Select Mapping Table": (not implemented yet!)
A special storage type to store multiple values, for example from a multiple select box. The values are stored using an internal mapping table. ToDo: Implement and describe mapping table.
OpenACS Datatype
The OpenACS datatype is a high-level description of the datatype. It is used to create both the SQL datatype for Oracle/Postgres and the datatype for the ad_form.
| OpenACS Datatype | SQL Datatype |
|---|---|
| string | varchar(1000) |
|
boolean |
char(1) |
| number | "number" |
| money | number (12,2) |
| date | date |
| text | varchar(4000) |
| integer | integer |
|
enumeration |
varchar(100) |
| keyword | varchar(1000) |
Datatype
Widget
Creating a New Category Widget
Creating a new Category Widget requires an integration between the OpenACS "Categories" package and DynField:
- You have to create a new Category tree for the widget (if it doesn't exist already). Go to the category admin pages at /categories/cadmin/ and select "Create a new tree". Let's call it "Customer Classification" and press OK.
- Select the new tree and choose "Add node at top level" to give it its root node. Let's call the root node "No Classification" and press OK
- Now you can successifly add sub-categories to "No Classification" by clicking on the "Add child" link. For example we might add the sub classifications "A" (= great customer), "B" (= ok customer) and "C" (= customer to get rid of)
- Finally on the category part, we have to find out the "tree_id" of the current tree. To do this, please check the current URL for a "tree_id" piece, which is followed by a number. Perhaps "tree_id" is written as "tree%5fid=630", with the "%5f" representing the underscore "_". However, we need the number behind the "=", so the 630 in this example.
- Now let's go to /dynfield/widgets/ and select "Create a new widget" link at the bottom.
- Let's enter the following data:
- Widget Name = "customer_classification"
- Pretty Name = "Customer Classification"
- Pretty Plural = "Customer Classifications"
- Storage Type = "Normal Value"
- ACS Datatype = "Integer"
- Widget = "Category"
- Datatype = "Integer" and
- Paremeters = "{custom {category_tree_id 630}}" (please replace the 630 by your tree_id)
- That's it. Now you have a new "customer_classification" widget that is available when you define new attributes of an object.
DynField Permissions
ToDo
Possible values are
- absolute_links: '0'
- abstract_p: 'f'
- auto_save: 'false'
- creation_date: '2009-04-08 17:10:32.27804+02'
- creation_user: '272160'
- creator: 'Richard Thiemann'
- current_user: '0'
- description: 'An explanation of the DynField Design Architecture'
- do_substitutions: '1'
- folder_id: '-100'
- form: '::xowiki::WikiForm'
- id_column: 'page_id'
- last_modified: '2009-04-08 17:10:32.27804+02'
- mime_type: 'text/html'
- name: 'en:dynfield_extensible_architecture'
- nls_language: 'en_US'
- object_id: '274757'
- object_type: '::xowiki::Page'
- package_id: '252723'
- page_id: '274757'
- page_order: 'Dynfield'
- parent_id: '252746'
- pretty_name: 'XoWiki Page'
- pretty_plural: 'XoWiki Pages'
- publish_date: '2009-04-08 17:10:32.27804+02'
- publish_status: 'ready'
- recursion_count: '0'
- references: ''
- render_adp: '1'
- revision_id: '274757'
- security_inherit_p: 't'
- sql_package_name: '::xowiki::Page'
- storage_type: 'text'
- supertype: 'content_revision'
- table_name: 'xowiki_page'
- title: 'DynField - Extensible Architecture'
- unresolved_references: '0'
- with_table: 'true'
FAQ Configuration FAQ
- How can I set up my system to allow access from the internet?
- Why does po not send any mails?
- How can I customize DynField Permissions?
- Whats the meaning of 'Database will allow full access to all data...'
How can I set up my system to allow access from the internet?
Please see: Configuration steps to allow external internet access to a po VM
Why does ]po[ not send any mails?
Check ]po[ mail queue
OpenACS manages its own mail queue. From table acs_mail_queue_outgoing mails will be forwarded to a local MTA. Check its content to see if mail will be sent out.
Check system mail queue
Run
mailq -v
If there are still mail messages pending, this command should show you why. For example, you might see something like "Deferred: Connection refused by <some SMTP server>"
[Terrance Crow]
Check if you local MTA is running and accepting mail
]po[ uses by default the postfix MTA. To check if postfix is running use:
ps waux | grep postfix
Check log file
Have a look at the log file (default location: var/log/mail)
Check local DNS server for MX Record
In case mail is only send out to "external" recipients, but not to local recipients, check the MX record of your local DNS server.
Check your resolv.conf
Check your DNS server entries in /etc/resolv.conf. Please check that the DNS servers are working. Be aware that mydns is not able to resolve external domains, so you will have to enter a DNS server that is capable of resolving external domains too.
[ref]
Check if your ISP requires valid bounce addresses
Some ISP (and everyday more) do exhaustive validation checks before accepting email. In some case providers check for a valid bounce address.
In OpenACS package acs-mail-lite builds random system email addresses to manage bounces instead of real addresses. Validation checks performed by ISP's would fail.
If your email doesn't get delivered, please adjust function 'bounce_address' of /packages/acs-mail-lite/tcl/bounce-procs.tcl accordingly.
The easiest way would be to simply return a valid email address.
(Thanks to Frank Diekhoff, Pentamino GmbH for evaluating this)
How can I customize DynField Permissions?
When I try add additional fields to the Helpdesk Tickets, the system won't let me edit them.
You have to configure several layers of permissions when adding a new DynField:
- ]project-open[ V3.4.0.7.5:
Please make sure you have updated at least to this version of ]po[. There are known issues with earlier versions.
- Read/Write Permission per Profile:
Please go to Admin -> DynFields -> Object Type -> Ticket -> Attribute Types.
Here you can set permissions per user group.
Please make sure that "Employees" have "RW" (capital and bold letters) permissions for all [DynFields].
- Read/Write Permissions per Object Subtype:
Please go to Admin -> DynFields -> Object Type -> Ticket -> Attribute-Type-Map.
Here you can set permissions per Ticket Type (or: Project Type, Absence Type, ...).
Please make sure that all radio boxes are in the rightmost E=Edit position.
- Appear/Disappear per Layout Page:
Please got to Admin -> DynFields -> Object Type -> Ticket -> DynField Layout -> default
This feature isn't used much in ]po[ V3.4. In future versions this feature will become a kind of "formular editor".
Please click on "Add attribute" and create new attributes while the Attribute drop-down box contains values. Please use Y-Pos=10 and Label-Style=plain.
What is the actual meaning of: "In this configuration, the database will allow full access ..."
What is the actual meaning of :
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 can’t predict the name of the local users. However, you may want to change these settings for a productive installation.
Please see http://www.postgresql.org/docs/7.3/static/client-authentication.html and the PO-Configuration-Guide for details.
The basic configuration allows all users of your local computer access to all of your data. Is that right for you? In general yes.
However, there are configurations where normal users have the right to log onto your server computer. That is the case for example if you use Windows Terminal Server. In this case you will have to modify your PostgreSQL security configuration.
FAQ Installation FAQ
Please also consult the Installation Overview page for additional information about installing ]project-open[
General
- What is the best way to run project-open? Should I use VMware, a "native" install, hosted, or "software as a service"?
- How can I install OpenACS packages so that they work on project-open?
- How can I install project-open on my hosted webserver?
- What are the minimum requirements to run project-open on a dedicated server?
- I successfully installed project-open, what's next?
- How do I get rid of the demo accounts on my LOGIN screen?
- Is there a way to get there quicker then going to "Projects" and then selecting the corresponding Filters?
- Is it possible to run po in a high availability/failover cluster?
- How can I migrate from Linux to WIN / from WIN to LINUX?
- I get the following error: ERROR: column/function "xxx" does not exist
- I get the following error: ERROR: invalid command name "xyz" while executing ...
- I get the following error: OpenACS could not allocate a handle from database pool "pool1". ...
- I get the following error: Please contact your SysAdmin and tell him to change the parameter 'intranet-subsite.DefaultMaster' to '/packages/intranet-core/www/master'.
OS Specific
For step-by-step installation guides directed towards specific platforms, choose your OS (or the most similar if yours is not listed)
- To run ]po[ on a Mac please make use of VMware Fusion
General
What is the best way to run ]project-open[? Should I use VMware, a "native" install, hosted, or using "software as a service"?
Choosing the right option depends heavily on the specific needs and technical capabilities of the implementing company, there is no one "best way".
VMware
Running ]project-open[ on a virtual machine hosted on your server is one good option. Most companies generally already have a fileserver up and functional that is integrated into a backup system. Also the CPU's of these fileservers are most likely idle during the day due to lack of high performance demands on fileserver processers, leaving ]project-open[ plently of resources to function. Many small companies have already effectively implemented this approach with sucess. These companies usually forward port 80 of their aDSL routers to access the ]po[ VMware, either on port 80 (configured to run Pound by default) or directly to the AOLserver (by default on port 8000). If the company does have a dedicated IP address, they get an account on DynDNS (free) to allow constant external access associated with a fixed DNS name. This configuration may be the nightmare of an Internet security consultant, but AOLserver provides great protection against "script kiddy" attacks, leaving your own employees as your largest remaining security threat. The other option is a "dedicated server" at a hosting site. For 10 concurrently active users at peak time (an organization with ~50 members) you'll need 1GB RAM, a 2GHz CPU and 20GB disk space, a recent SuSE, Fedora or CentOS system and root access in order to install the software. We have had negative reports from virtually hosted servers, so you might be forced to use a dedicated server.
Advantages of VMware
- Cheap overhead for small companies with small amounts of users (supports up to 10 concurrent active users at a time)
- Easiest do-it-yourself install, extensive technical knowledge is not required
- No-hassle install: Just run the VMware on top of your existing fileserver.
- Access to your local fileserver - just mount the fileserver share in your Linux "fstab"
- Unlimited storage...
- Local backup: Backup is a real issue with hosted solutions.
- Fast access to your files when you're in your office.
Disadvantages of VMware
- Slow performance for networks with more than 10 active users.
- Limited bandwith (typically 512kBit/s or 256kBit/s upload of your aDSL line) for external users
- Slight Overhead for system management and maintenance
- Security
SaaS (Software as a Service)
We commercially offer the service detailed above for companies that wish to use ]project-open[ and not concern themselves with the technical details. Unlimited 24-hour access (with full admin privileges) to your personalized ]project-open[ system, hosted hassle free from our dedicated servers is available on a monthly fee basis. For more details see our commercial website .
Advantages of SaaS:
- No hassle with installation
- System maintained and updated by us
However, we have just released RPM installers for Fedora, CentOS, OpenSuSE. Using these installers you should be able to install ]po[ on your web server if you really wanted to.
It's quite easy to to move a ]po[ installation from one server to another (just perform a backup - restore), so it may be a good option to start with a "hosted" or "SaaS" installation and then move it "home" server if you really see the need for it.
How do I install OpenACS packages so that they work on ]project-open[?
Here is how the relationship between OpenACS and ]project-open[ works:
* Both ]project-open[ and OpenACS (application) modules work side by side on the same OpenACS "kernel". So in general it's no problem to install new OpenACS modules in a ]po[ system. ]po[ is currently (2007-02-16) based on OpenACS 5.1.3, so please use the OpenACS modules from this version.
* The ]po[ GUI system is different from OpenACS, and we've developed our own "master template". So in order to access a newly installed OpenACS modules you'll need to add an entry in the Admin -> Menus section to make the newly installed OpenACS module accessible from ]po[.
* Integration with ]po[: New OpenACS modules are usually completely separate from the "]po[ world". So you have to think about ways to move information back and forth. That's usually done using database triggers or via explicit "coding".
* ]po[ is based on a single "OpenACS Subsite". Or in other words: You can install ]po[ modules only once per server, while you can usually install multiple instances of OpenACS modules per server.
Let's take the "Calendar" as a practical example: We've just added the standard OpenACS 5.1.3 "calendar" module to our default ]po[ distribution. The module worked fine as a standalone personal calendar, but we wanted to map ]po[ events such project deadlines and tasks into the calendar. So we've created an "intranet-calendar" module that defines a menu item for "Calendar", a pluggable "calendar overview component" for the homepage, and a few database triggers so that ]po[ objects are "duplicated" as calendar-items. So the "intranet-calendar" module doesn't really add new functionality, but it provides the "glue code" to link the new module with the system and to provide end users with a pleaseant and integrated user experience.
A brief look into the source code of "intranet-calendar" will reveal to you all necessary steps for such an integration. It's just some ~500 lines of (mostly SQL) code.
How can I install ]project-open[ on my hosted webserver?
If you plan to run ]po[ on a shared server with your prefered ISP please consider the following:
- The machine should run a OS that is supported by us, such as SuSE, Debian, RedHat, Ubuntu, etc.
- Your server should have at least 512 KB guaranteed RAM (consider 1GB guaranteed RAM on Virtual Servers to be on the save side) and at least 10GB of HDD
- Depending on configuration options offered you might need to install additional software such as AOL webserver and Postgres Database.
Going with a package that provides root access is less troublesome and highly recommended
Please note that ]project-open[ requires AOL Server and Postgres. It therefore requires at least a Virtual Dedicated Server. ]po[ can't be installed on Web Hosting Plans providing exclusively Apache Webserver & MySQL.
In case you do not have IT expertise to install and configure all components necessary, you might want to make use of our professional services. We can help you finding the right hosting provider / package for you and install your system on a server of you choice.
What are the minimum requirements for running ]project-open[ on a dedicated server?
The minimum requirement for a dedicated servers are:
- 1GByte RAM (for 3-5 users accessing the system). My development server is running on 512MB, but that's probably too low for production use.
- A more or less recent Pentium is OK (3 years old, single core)
- 20GByte disk space should be OK as a minimum, assuming that you won't use the filestorage a lot. The VMware is limited to 20GByt, and many customers use that system for production
- Bandwidth shouldn't be a problem because ]po[ pages are quite small in general. For example, it's no problem to access a ]po[ system behind a normal aDSL-Line (50kByte/s upstream speed).
- Backup: We always perform backups at night via a cron script. Then we download these backups to a local server via RSYNC. Make sure you install a similar mechanism.
I successfully installed ]po[. What's next?
Installing ]po[ successfully in a company has to do a lot with change management. Please contact us for more material and our change management methodology (PowerPoint slides with best practices).
I frequently need to look at the list of "Delivered Projects" in order to create invoices. Is there a way to get there quicker then going to "Projects" and then selecting the corresponding Filters?
You can bookmark most pages in ]po[, so you may just create a shortcut in your Web Browser. This works particularly well for ListPages and reports. However, it doesn't work for pages designed to create new objects.
How do I get rid of the demo accounts on my LOGIN screen?
As for now please edit /web/projop/www/index.adp and delete the lines responsible for listing the Demo accounts.
OS Specific
Linux
Is ]project-open[ available for Linux?
Yes, all major Linux distributions are supported. Please checkout the Download pages.
Also, there are users running ]project-open[ on Mac OS-X, *BSD, Sun Solaris, AIX. We have even heard about a port to OpenVMS...
VMware
Is ]project-open[ available for VMware?
Yes it is. This is the quickest way to install ]project-open[ onto a system, and most often, the easiest way. We recommend using either "VMware 2.X" or "VM Player", both available for download (free of charge) at the VMware website .
We have had several reports of successful installs using "VMware ESX 3.5" although it may be necessary to use the VMware converter to transform the provided image into a workable format.
VMware does not boot / can not configure source image
Check your vmware settings and under the adapter settings, make sure that the "lsi logic adapter" is selected. After making this change the system should boot fine.
Windows
Is ]project-open[ available for Windows?
Yes, all recent Window versions (XP, 2000, 2003) are supported. ]project-open[ doesn't run on Win-95 and Win 98 though. Checkout the Windows download pages.
Can I use native PostgreSQL with Windows?
Yes you can. Our Windows installer includes a particular version of PostgreSQL for "CygWin" (7.5.X). This version has prooved to work very well in our tests and this is the version that we are using for our internal test & development servers.
Since the version 8.0 in March 2005 there is a "native" version of PostgreSQL for Windows. This version is know to be some 30% faster then CygWin Postgres, and is supposed to be more stable in future. However, there are some issues when moving a backup dump from 7.5.x to 8.0.x, so that we won't deliver this option as part of our free Windows Installer yet. However, you can try it yourself or you can contract us to upgrade your system.
We recommend an upgrade to 8.0 on Windows for companies with more then 10 "concurrent users" (=> users that access the system _at_the_same_moment_). Apart from that we would recommend you to stay with the CygWin version that comes with the installer.
How can I migrate from Linux to WIN / from WIN to LINUX?
If possible ensure that on both machines the same version of AOL Server and Postgres is installed. For detailled installation instructions pls. see http://project-open.org/documentation/list_installers
Steps involved:
- Make a db backup from your current ]po[ server
- Copy the packages folder from you productive server to the new server
- Stop AOLserver and dump exiting database 'projop'
- Create new db on new server and restore the backup made earlier
- Start AOLserver
column_does_not_exist
I get the following error: ERROR: column/function "xxx" does not exist
Some update scripts had not been executed during an update. Search for the script that creates the column or function:
find /web/projop/packages -type f -name 'upgr*.sql' -exec grep -il 'COLUMN_NAME/FUNCTION_NAME' {} \;
and execute it.
I get the following error: ERROR: invalid command name "xyz" while executing ...
Check the error.log (/web/projop/log/error.log) if all tcl libs have been compiled during startup. The error indicates that a tcl function is not accessible/available.
Go to http://www.project-open.org/api-doc/ and search for the function using "OpenACS Tcl API Search". Verify the tcl lib that contains this function for completeness / correct version.
Check also if the file has the right permission. It needs to be executable for the user that starts AOLServer (usually 'projop')
I get the following error: OpenACS could not allocate a handle from database pool "pool1".
OpenACS Installation: Error
Thank you for installing the Open Architecture Community System (OpenACS), a suite of fully-integrated enterprise-class solutions for collaborative commerce.
This is the OpenACS Installer which performs all the steps necessary to get the OpenACS Community System running on your server.
Please read the Release Notes before proceeding to better understand what is contained in this release.
The following database pools generated errors:
* OpenACS could not allocate a handle from database pool "pool1".
Possible causes might include:
* The database is not running.
* The database driver has not been correctly installed.
* The datasource or database user/password are incorrect.
* You didn't define any database pools.
The first step involved in setting up your OpenACS installation is to configure your RDBMS, correctly install a database driver,
and configure AOLserver to use it. You can download and install the latest version of the AOLserver Oracle and PostgreSQL drivers
from the OpenACS.org Software Page.
Once you're sure everything is installed and configured correctly, restart AOLserver.
gatekeepers@openacs.org
This error indicates that the DB was not available when the OpenACS framework started. Make sure that the PostgreSQL DB is running and listening on port 5432.
Using WINDOWS:
Check if Postgres is running:
Please use CTR-ALT-DEL to start the WIN Task Manager and check under the tab "Processes" if there's at least one process "postgres.exe" listed. If so, restart ]po[ (START -> project-open -> Stop project-open / START -> project-open -> Start project-open). If you continue getting this error message check next if firewall settings prevent ]po[ from getting access to the database. By default ]po[ is connecting to the DB through port 5432.
Open a console (START -> RUN -> cmd) and execute
netstat -an
The output should contain one line reading:
TCP 127.0.0.1:5432 127.0.0.1:5432 LISTENING
If there's no such connection please check your WIN error logs.
Using Linux:
ps -waux | grep postmastershould show the postmaster process. If not please see log files what PostgreSQL might have prevented from starting up.
I get the following error: Please contact your SysAdmin and tell him to change the parameter 'intranet-subsite.DefaultMaster' to '/packages/intranet-core/www/master'.
http://[SERVER]/acs-admin/apm/packages-install and update package "intranet-core"
http://[SERVER]/acs-admin/server-restart
FAQ Localization FAQ
- Is project-open available in my language?
- How do I localize project-open?
- I translated and localized project-open. How can I contribute my work to the project-open product?
Is project-open available in my language?
Find a list of language ]project-open[ is translated into here
How do I localize ]project-open[?
Find a list of language ]project-open[ is translated into here
Please note that we provide a dedicated localization server that is used by our Partners in charge for localization. If you want to become Translation Partner for a language that is not yet covered please get in touch with us.I translated and localized ]project-open[. How can I contribute my work to the ]project-open[ product?
First of all we very much appreciate your contribution to the project. If you are not an official ]po[ Language Partner but you have localized ]po[ on a local machine please proceed as follows:
- Export all translation strings to XML files. See this page for more details.
- Extract the XML files from your system and send them per email to one of the members of the project-open core team.
Here an example how you can extract the files on a *nix machine using cpio:find . -name '*.xml' |cpio -pdvm /tmp/cat/
FAQ Developer FAQ
- Why should I participate in project-open?
- What can I learn from developing and using project-open?
- How can I contribute to project-open?
- How can I actively participate in project-open?
- Where is a good place to start learning project-open?
- How do I set-up a developemnt enviroment for project-open?
- How does project-open handle software releases?
- How do I get my own current copy of the project-open source code?
- How do I get the latest version of project-open?
- How do project-open upgrades work?
- How do project-open developers communicate?
- How do I become an expert project-open developer?
- How do I write a bug report?
- How do I contribute a software patch?
- How do I contribute a translation of project-open?
- How do I contribute to the Wiki?
- What is the project-open product?
- What are the guidlines for my code to become accepted into the product?
- How do I publish new functionality reports?
- How do I fix "column xxx does not exist" errors?
Why should I participate in ]project-open[?
Good question!
You are probably an employee or a manager of a ]project-open[ customer or a ]project-open[ partner if you reading these lines. Only a few "independent" open-source developers are willing to spend their free time fiddling with ERP software...something that we are attempting to change.
As a professional ]project-open[ user you are probably looking here in order to learn how to run ]project-open[ and how to adapt the system to your needs or the needs of your customers. Participating can provide you with several advantages:
- Demonstrate and publicize your knowledge as a partner:
As a ]project-open[ partner, one of the best ways to demonstrate your knowledge is to participate actively in the "Open Discussions" (see "communication" below). - Learn about other companies with similar needs:
As a ]project.open[ customer, posting in the "Open Discussions" forum will make you visible to other customers. There are about 3,000 companies in the world running their business using ]project-open[, so more then 3,000 employees are looking at these discussion forums, more or less regularly, to learn about best practices. But peers will only contact you if you are visible. - As an "independent" open-source developer:
]project-open[ is one of the largest open-source web-applications available and a successful open-source project which continues to grow. Participating in this community will make you familiar with the details of professional software development and provide you with a references for your first job. - Improve your personal or "corporate" CV:
Being an active member in an open-source community will increase your sophistication and your market value. The effect is well know for individual contributors. But even companies can (sometimes) demonstrate their skills when collaborating in creating sophisticated commercial software.
What can I learn from developing and using ]project-open[?
The answer depends on your personal interests. ]project-open[ is the world's largest open-source application and a successful software product. Here are a few areas that could be interesting:
- The mechanics of an open-source software community.
- Efficient software development in a "Network Organization":
The ]project-open[ team only consists of hand full of persons maintaining a huge application and a large customer base. There´s ample room for more contributors. - Structuring large software applications:
]project-open[ is huge - more then a million lines of code. By working with ]project-open[ you will understand the underlying concepts of managing complexity such as modular design, configurability, data-modeling, object-oriented design and much more. - Business software - the interface between business and technology:
Learn the relationship between technology/automation and commerce and how to supply businesses with useful software products. - Product Management:
How to create a single application that suits very different customer organizations ("customer variability")? This question is related to the hyped concept of "Software Product Lines" and similar software engineering concepts. - Entrepreneurial skills:
How to establish a new software application in a specific market? How does marketing and PR work in open-source projects? - Technical skills:
System administration, database administration, SQL, procedural SQL and SQL optimization.
Please post in "Open Discussions" (see below) if you are interested. We can recommend you a lot of books and/or activities within the ]project-open[ community to learn about these areas.
How can I contribute to ]project-open[?
There are many ways to contribute to ]project-open[. However, if you want to contribute successfully it is important to find a balance between your learning needs and the attention you will require from others in order become a contributing member, and the value of your contributions on the other side. On one hand, we would like for everyone to contribute, and on the other we only have so much time to dedicate to newcomers. You can't expect that senior community members will spend much time with you, unless you have saved them time by learning the basics yourself...
Here are a number of areas ordered by increasing "seniority":
- Bug reports:
Did you find a bug in ]project-open[? Please post the bug in our bug-tracker. Please see the "How to contribute a bug report" guidelines on how to post a useful bug report. - Bug fixes:
You found a bug and then you found a way to fix it? Please see the "How to contribute a bug fix" below for guidelines on how to post your fix. - Help with documentation:
Are you able to write reasonable English and would you be willing to contribute to the Project-Open Wiki ? Then you could contribute to the documentation or get in charge of a particular wiki area. If you are not able to write in English or perfer not to, we also welcome anyone wishing to begin contributing articles in their own language. - Write about your experience with ]project-open[, write articles about ]project-open[:
This option could be particularly interesting for ]project-open[ partners. By writing about your own experiences in implementing or developing ]project-open[ you gain visibility for your company while at the same time contributing to the community. - Sharing new knowledge and insights about ]project-open[:
You learned an important trick or a new concept that hasn't been documented anywhere? Encountered strange and erratic system behavior? Please post your story in "Open Discussions". - Reports and Performance Indicators:
Did you create a new and useful report or a set of indicators to monitor a process? Please post your experience here on this Wiki. It doesn't matter whether your report has been written using the ]po[ reporting engine of using an external reporting engine (MS-Access, Crytal Reports, Jasper Reports, PHP, ...) - Did you write a new package? Please see below for guidelines on how to contribute code.
How can I actively participate in ]project-open[?
- FAQ Manager - someone willing to go through ]project-open[ forums to look for new material, and to improve and build upon the pre-existing FAQs
- Localization - please see the languages section. Do you want to participate in the translation into your language?
- Reports and Indicators - did you develop an interesting report or performance indicator that you would like to share with the community?
- Bug Reports and Patches - If you find a bug please take the time to report it, and if you think you can fix it, go ahead or try and solve another pre-existing bug.
There are several areas where we are actively looking for help:
Where is a good place to start learning ]project-open[?
Please see our "notes tutorial" for a step-by step introduction to ]project-open[. The tutorial isn't finished yet, but the available content may already give you a good idea. For a full comprehension of ]project-open[ there are several areas to explore:- SQL and data modeling - ACID transactions, object-oriented data models, procedural SQL, hierarchical queries, ...
- TCL programming language - you need to understand TCL in order to modify the GUI (no need to understand TCL for reporting, though)
- Security and access permissions - groups, privileges, permissions, authentication, ...
- Packages & Configuration - package manager, parameters, DynFields, DynViews, ...
- Workflows - Petri-nets, business process modeling, ...
- OpenACS libraries - templates, form builder, list builder, ...
- Project Management - How to organize people to execute project efficiently?
- Finance - How to account for projects and services
- Human Resources - managing the people behind the projects and services
An important hint that will help your understanding of ]project-open[:
Read the source code. Don't be afraid of looking inside ]project-open[ packages. In particular the "intranet-notes" package is easy to understand (and designed as a learning experience). As a second lesson, the "intranet-expenses" is an interesting introduction to ]project-open[ on an entire system wide level.
How to setup a ]project-open[ development environment?
To begin experimenting and investigating ]project-open[ you will of course need a working application and several additional tools. A ]project-open[ development environment consists of:
- A running ]project-open[ server with sample data.
- An Emacs/VI/VIM etc. editor to edit the source code.
- A tool to watch the "error.log" file. This file contains error and debugging information
- At the /ds/ URL of any ]project-open[ server you will find a number of developer tools such as:
- /ds/ - SQL profiling and statistics on server requests
- /ds/shell - an interactive shell that lets you execute statements in the context of the AOLserver
- /api-doc/ - interactive developer documentation
- Optionally, you can install pgAdminIII to increase the comfort of working with the database.
- In a Windows environment you may additionally want to install Tortoise or WinCVS in order to access the ]project-open[ CVS version control system.
Note that most of these requirements are merely suggestions, if you would like to hack your own way through ]project-open[ you only will need a text editor and a working ]project-open[ installation, the rest are simply auxillary tools to aid development.
How does ]project-open[ handle software releases?
The ]project-open[ team releases new versions every 12-18 months. These main releases (for example: 3.0, 3.1, 3.2, 3.3, 3.4, 4.0, ...) include important new features. A jump in the "major number" (i.e. 3.4 - 4.0) indicates an incompatible upgrade, while changes in the "minor number" (i.e. 3.3 - 3.4) indicates that an automatic upgrade is possible. From time to time there are "update releases" (3.3.1, 3.3.2, 3.3.3, ...) in order to deal with bugs or to release minor improvements.
The relatively long release cycle of ]project-open[ is due to the fact that businesses that run on our software need stability and can't be asked to continually expend the effort to upgrade with every new release, and there is a relatively high and time consuming effort in creating installers for every desired platform.
Between releases we continuously add features and publish "update installers" for those customers interested in new features.
How do I get a current copy of the ]project-open[ source code?
All ]project-open[ code is controlled by a CVS version control system. In the CVS, each package is stored as a separate project.
In order to checkout all ~130 ]project-open[ packages please perform the following instructions
- cd /web/projop/packages (change the current directory to the packages home of the local ]po[ server)
- cvs -d :pserver:anonymous@cvs.project-open.net:/home/cvsroot/ login (empty password)
- cvs -d :pserver:anonymous@cvs.project-open.net:/home/cvsroot/ checkout intranet-core (get the "core" package)
- cp intranet-core/all-checkout.sh . (copy the "all-checkout.sh" file contained in the core package)
- bash all.checkout.sh (performs a checkout of all other ]project-open[ packages)
Apart from that: The source code is part of every ]project-open[ server. Please go to the /web/projop/packages/ folder and you can explore the ~130 packages that make up ]project-open[.
How can I get the most up to date version of ]project-open[?
- For the lastest versions of ]project-open[ and related components, such as VMware images, RHP installers, or Documentation, browse our Source Forge Download Zone which is where our releases are made publicly available.
How do upgrades work?
A ]project-open[ version really consists of two parts:
- The TCL code in the /packages/ directory and
- The contents of the PostgreSQL database
In order to keep the two parts together, each package contains a sql/postgresql/upgrade/ folder with upgrade scripts. These SQL scripts add new columns to database tables etc. in order to upgrade the data model to support the latest version.
Upgrades within a "minor release" (i.e. 3.3) are automatic and backwards compatible in most cases (you can downgrade your TCL code to 3.3.2.1, even though you have already executed the upgrades from 3.3.2.1 to 3.3.2.2).
The upgrade process is integrated into the "Home" page (if you are logged in as System Administrator). As an alternative, the SysAdmin can use the /acs-admin/apm/ Package Manager to execute upgrade scripts individually. Finally, you can even execute upgrade scripts manually using "psql -f upgrade-x.x.x.x-y.y.y.y.sql".
How do ]project-open[ developers communicate and network?
Open Discussions Forum at SourceForge
The main communication channel for both developers and users is the "Open Discussions" forum at [SourceForge] This is the right place for all technical questions, announcements, etc. We recommend that active users/developers subscribe to forum updates ("Monitor this Forum"). This way, the forum can act as a mailing list.
Bug-Tracker at SourceForge
Please use the Bug-Tracker in order to submit bug reports or patches.
The ]project-open[ core team looks at the open bugs list before all important releases to make sure that no critical bugs are open. Please consult our guidelines for bug submission Reporting Bugs to contribute one.
OpenACS Forums
The OpenACS community meets at http://www.openacs.org/forums/. These forums are useful for ]project-open[ developers when dealing with non-]project-open[ specific issues sich as learning TCL, data-model and libraries etc.
Technically ]project-open[ is based on OpenACS. ]project-open[ consists of an array of packages that can be installed on top of any existing OpenACS installation extending and transforming the functionality of OpenACS, so the original OpenACS platform is inseperably linked to ]project-open[.
Mailings
]project-open[ sends out mass mailings to all registered users at [//www.project-open.org/] a few times a year with updates about the product and important security anouncements. However, this is basically a one-way communication.
OpenACS Developer Conferences
OpenACS (the uderlying platform that ]project-open[ runs on) usually organizes developer conferences in Europe twice a year. We recommend all active ]project-open[ developers attend these conferences if at all possible. Please ask around in the "Open Discussions" forum if other ]project-open[ community members are participating as well.
]project-open[ Developer Conferences
The ]project-open[ team organizes a Developer Conference once a year in Barcelona, Spain. For details please see [//www.project-open.com/en/services/project-open-devcon.html">http://www.project-open.com/en/services/project-open-devcon.html]. The conference is split into a tutorial part (two days) and a practial session (two days) where participants can develop software with help from an experienced tutor.
How can I become an expert ]project-open[ developer?
There is a short PowerPoint presentation on the difference between good developers and [excellent developers].
The single most important factor is probably the capability to learn from code that other people have written. So start today, print out the source code of "/packages/acs-kernel/sql/postgresql/*.sql and consult the documentation at http://www.openacs.org/doc/ for reference.
How do I submit a bug report?
Please consult our guidelines on bug submission Reporting Bugs.
How do I contribute a patch?
Please consult our guidelines on patch submissions Contributing Patches.
How do I contribute a translation?
Please consult our localization page for information on becoming a ]project-open[ partner and a step by step tutorial on best practices for localization.
How can I contribute to this Wiki?
Please consult the Wiki Contributions & Standards page.
What are the guidelines for code to be accepted into the "product"?
- Your patch should solve a problem that many users have.
- Your patch should be in line with the general ]po[ configuration system.
How to contribute new functionality, reports etc?
... even if we don't accept your code into the "product" you can get your own Wiki page to present your extensions and link to your download page.
How do I fix "column xxx does not exist" errors?
In many cases one or more update scripts has not been executed correctly. Please search for the script and execute it again.
Example:
Database operation "select" failed
(exception ERROR, "ERROR: column p.menu_name does not exist
LINE 5: p.menu_name AS menu_name
^
")
Search in packages folder:
find . -type f -name 'upgr*.sql' -exec grep -il 'menu_name' {} \;
returns:
./intranet-core/sql/postgresql/upgrade/upgrade-3.3.0.0.0-3.4.0.0.0.sql
upgrade-3.3.0.0.0-3.4.0.0.0.sql:
...
create or replace function inline_0 ()
returns integer as '
DECLARE
v_count integer;
BEGIN
select count(*) into v_count
from user_tab_columns
where lower(table_name) = ''im_component_plugins''
and lower(column_name) = ''menu_name'';
IF v_count = 0 THEN
ALTER TABLE im_component_plugins ADD menu_name varchar(50) default null;
END IF;
select count(*) into v_count
from user_tab_columns
where lower(table_name) = ''im_component_plugins''
and lower(column_name) = ''menu_sort_order'';
IF v_count = 0 THEN
ALTER TABLE im_component_plugins ADD menu_sort_order integer not null default 0;
END IF;
return 0;
end;' language 'plpgsql';
select inline_0();
drop function inline_0();
...
So sourcing this sql usually fixes the error:
su - projop psql -f /web/projop/packages/intranet-core/sql/postgresql/upgrade/upgrade-3.3.0.0.0-3.4.0.0.0.sql
FAQ Bug Tracker FAQ
- How can I associate bugs with projects/software?
- How can I allow freelancers to create and add bugs
References
How can I associate bugs with projects/software?
- Obviously, you could name your versions including your product name, working around the issue.
- You could install more then one instance of the bug-tracker package, one for each of your products.
Please try this first on a demo server...
- Use the ]po[ Helpdesk:
In the future (]po[ V3.4) we are going to replace the Bug-Tracker with the ]po[ Helpdesk package for ITSM compliant services management. The package is already installed on the http://po34demo.project-open.net/ demo server.
With the Helpdesk package you could define different types of Bugs for each of your products and assign different lists of versions for each bug type using DynFields and Categories. However, the Helpdesk package is still beta, so please try on a demo server first.
How can I allow freelancers to create and add bugs?
The Bug-Tracker is a package originally developed for OpenACS, and not for ]po[. So it does not adhere to the ]po[ configuration mechanisms, but to the OpenACS configuration.
You can set read/write/create permissions for the Bug-Tracker using the Admin -> Site Map. Please select "permissions" of the "bug-tracker" package, and modify the permissions for the various user group.
FAQ One Time Passwords FAQ
One Time Passwords (OTPs) are meant for use in only specific situations, and should not be used on a regular basis to gain access to the system. The use of OTPs is enabled automatically for each user depending on the privileges of the user and the type of connection channel (trusted Intranet or untrusted Internet). OTPs are frequently of use in public situations like Airports or Internet Cafes. If the system finds the connection to be insecure, the user will be prompted to enter an OTP
FAQ
I'm locked out of my account but my OTP list is current, what should I do?
- After x# of incorrect login attempts (default is 3) the user will automatically be barred from further attempts, and in order to regain access to the system must either generate a new list of OTPs (only possible using a trusted and secure connection) or contact the System Administrator to provide a new list remotely.
How will I know when I should generate a new list of OTPs?
- The system will print out a warning if there are less then x# of OTPs (defualt is 10) left on a user's list. This way, the user will be notified to renew their OTP list.
Help Process: GEN User Management
Users in ]project-open[ represent physical persons who interact in some way with the system.
Topics
- List of ]po[ users
- User Permissions and Access Rights
- User Self Service
- Creating A New User
- Adding a Member to a Project
- Adding a Member to a Customer
- Adding a Member to an Office or Department
- Filestorage Permission Management
- Creating a new User
- Delete a User
- Re-activate a User
- Changing a Users Password
- Set Users default locale
- Searching for Users
- Troubleshooting a User
- Managing a Users Payroll Information
- Navigation through large lists of objects
- Time sheet Management
List of all ]po[ users
To see a list of all current ]po[ users go to http://[YOUR_SERVER]/intranet/users/
User Permissions and Access Rights
The management of permissions and access rights is the most complicated element of ]project-open[ because it really is a management of trust relationships. There is a dilemma between:
- Access: Users should have access to all information and documents necessary to do their job.
- Restriction: Users should not have access to more information then necessary to do their job.
To solve this dilemma ]project-open[ introduces three types of access permissions:
- "User Profiles" which correspond to department membership in a company
- "Project Roles" which correspond to the function of the user in a specific project and
- "User Hierarchy" which corresponds to the hierarchy in the company.
Each of these concepts are explained below.
User Profiles
User profiles correspond to department membership in the company or business partners respectively.
- Senior Management: The management of the company with access to all corporate information
- Project Managers: Employees with special skills to manage projects
- Employees: Employees from several departments such as sales, operations, ...
- Finance: Employees with access to invoices and other financial information
- Freelancers: External users who can take part in specific projects. Freelancers have basicly no access rights outside the specific projects they take part of.
- Clients: External users with permissions similar to Freelancers.
Please note that the groups Employees, Freelancers and Clients are mutally exclusive.
Project Roles
Project roles define access permissions to project on a case-by-case base. Project roles are particularly useful for "Freelancers" and "Clients" with normally very restricted access to the system.
Project Roles can be extended and customized for a specific company. However, a number of predefined project roles exist:
- Administrator:
The administrator of a project can assign new users to the project and change its main characteristics. Also, the enjoys full read and write access to all associated components such as discussion forums and filestorage. - Member:
A member has access to all information of a business object but is not allowed to administer the object.
]project-translation[ for example adds several translation specific roles such as:
- Translator
- Editor
- Proof Reader
User Hierarchy
The user hierarchy determines which user has the right to "administer" (change the password and email, ...) other users. The hierarchy consists of:
- System Administrator
- Senior Management
- Employees
- Freelancers and Customers
Being able to administer a user is particularly useful in cases where the user has forgotten his password or has otherwise problems to work with the system.
User Self Service
Examples for this philosophy are:
- The management of users contact information and email
- Prices and rates of freelancers
- The management of users skills. However, a confirmation from a supervisor is necessary to validate users skills.
Create A New User
1. Click on the "Users" tab on the main menu| ... | Forum | Users | Admin | ... |
" symbol in the projects submenu. Hold the mouse over the symbol (don't click!), and a comment will appear ("Add a new user").
| ... | Org Chart | |
| Profile |
Effects of Creating a New User
Step 4 initiates several actions:
- It creates a new user that appears in
Users - It creates a new folder for the users files
- It send an email notification to the new user.
Contact Information
Contact information allow to specify a large number of address related information about a user. Special fields include:
-
ICQ Number:
The AOL ICQ messenger number -
MSN Email ("MSN"):
The users Microsoft MSN Messenger Email - this email allows ]project-open[ to display the online status of the user.
User Portraits
Users portrait are used typically in the intranets of distributed organizations to present employees to the staff of other offices. Knowing about employees of other offices allows for easier communication and improves the coherence in a distributed organization.
User Filestorage
This field shows the content of a filestorage space associated with each user. The space is meant to store CVs, contracts and other user specific information. The filestorage contents is visible only for:
- Administrators
- Senior Management
- Human Resources Staff (future)
Related Links:
- Project Filestorage
- Customer Filestorage
Freelance Information
This box only appears for freelancers and contains freelance specific information:
- Trans Rate
- Editing Rate
- Hourly Rate
- Bank Account
- Bank ID
- Payment Method
- Note
- Private Note
Freelance Skills
Freelance skills are list of "Skill Type" - "Qualification" pairs that describe the skills of a freelancer.
| Skills | ||||||||||||||||||||||||||||||||||
| Source Language | Target Language | Sworn Language | TM Tools | LOC Tools | Operating System | Subjects | ||||||||||||||||||||||||||||
|
|
|
|
|
|
|
||||||||||||||||||||||||||||
Set User's default locale
The user's default locale is defined in a users account (http://[YOUR_SERVER]//intranet/users/view?user_id=[USER_ID])
Delete a user
Users can be de-activated by changing their status in the Administration portlet of their user account (http://[YOUR_SERVER]/intranet/users/view?user_id=[USER_ID]):
Re-activate a deleted user
Use ]po[ Full-Text search and find user based on name or email address. Please note that you would need to check "Include deleted".
Open user account and change status in ADMIN portlet (see above).
Help Expense User Help
Expense items are the basic unit component in order to keep track of project-related costs incurred by project members while traveling, using public transit on company time, or hosting clients for business related purposes.
Topics
Create New Expense Item
1. While in the ]project-open[ workspace enviroment click on the "Expenses" tab. This will give you access to a menu of the pre-existing expense items.
2. Below "Expense List" click on the tab for "Add one new Expense item". This will take you to the next page where you will be requested to complete the following data fields.
3. After clicking "OK" you will be redirected back to the original Expense page, where the just completed Expense item shoudl be now displayed in the list
Reference
- intranet-expenses package
- expense item object type
- expense bundle object type
Help package_manager_screenshot4.gif
| Name | Content Type | Last Modified | By User | Size |
|---|---|---|---|---|
| package_manager_screenshot4.gif | image/gif | 2009-04-07 14:17:09+02 | Richard Thiemann | 38543 |
Screenshot of Package Manager
Help package_manager_screenshot3.gif
| Name | Content Type | Last Modified | By User | Size |
|---|---|---|---|---|
| package_manager_screenshot3.gif | image/gif | 2009-04-07 14:16:31+02 | Richard Thiemann | 35115 |
Screenshot of Package Manager
Help package_manager_screenshot1.gif
| Name | Content Type | Last Modified | By User | Size |
|---|---|---|---|---|
| package_manager_screenshot1.gif | image/gif | 2009-04-07 14:15:59+02 | Richard Thiemann | 14736 |
Screenshot of Package Manager
Help General Project Help
Help Topics
- Create a New Project
- Add a new Member to a Project
- Grant access permission to Members
Create a New Project
Creating a new Translation project includes several steps, each described below.
| 1. Click on the "Projects" tab on the main menu |
|
||||||||
2. Click on the " " symbol in the projects submenu. Hold the mouse over the symbol (don not click!), and a comment will appear ("Add a new project"). |
|
||||||||
| 3. The "Add New Project" page should appear. Here you can fill out the project base data, consisting of project purpose, customer etc. | |||||||||
| 4. Choose an appropriate project name, describing the project purpose in 3-10 words. You don not need to mention the customer, because the customer is handled separately. |
|
||||||||
| 5. Fill in a unique Project Number. A default Project Number is generated by the system, consisting of the current year plus the project count for this year.
The format of the project number can be customized to suit the conventions of your company.. |
|
||||||||
|
6. Chose a client from the list of active clients. Please note:
|
|
||||||||
|
7. Chose a project manager list of project managers. |
|
||||||||
|
8. Chose a Project Type. Note:
|
|
||||||||
|
9. Chose a Project Status or leave the default status "Open" if you want to start with the project. Note:
|
|
||||||||
|
10. (]project-translation[ only): Choose Source and Target languages. The language codes follow ISO conventions, consisting of a two-letter language ID in lower case, followed by a two-letter country ID in upper case. Notes:
|
|
||||||||
| 11. (]project-translation[ only): Choose a Subject Area that best suits your translation project. |
|
||||||||
| 12. Fill in Start and End Dates and press the "Create Project" button. |
Effects of Creating a New Project
Step 12 initiates several actions:
- It creates a new project that appears in
Projects - Create a number of folders in the file system depending on the Project Type.
- Add the current user as an administrator (owner) of the new project
- Add the project manager as an administrator of the new project
- Send an email notification to the project manager, informing him about the new project.
Folder Structure
A folder structure is created as a function of the project type and other parameters. The figures below show prototypical structures being created
Example of a structure for an "IT-Consulting" project:
| Name |  |
Size | Modified | |||
|
 |
|
|
|||
|
|
|
|
|
||
|
|
|
|
|
||
|
|
|
|
|
||
|
|
|
|
|
||
|
|
|
|
|
||
|
|
|
|
|
Example of a file structure created for a "Trans+Edit+Proof" translation project from English ("en") to German ("de"): There is one source folder ("source_en") and one trans/edit/proof/deliv folder for each target language.
| Name | |
Size | Modified | |||
|
|
|
|
|||
|
|
|
|
|
||
|
|
|
|
|
||
|
|
|
|
|
||
|
|
|
|
|
||
|
|
|
|
Help Rollout Guidance
A company's introduction and adoption of ]project-open[ should be done both in a cautious and premeditated manner in order to ensure that the system is being effectively utilized and to avoid confusion and problems. The ideal Rollout plan for a company wishing to implement ]project-open[ is dependent on a number of factors, such as company size, internal structure, and if there is a pre-existing project management mentality and orientation or not. However, these are not the only limiting factors, and a thorough examination of all variables should be undertaken before attempting the product Rollout.Help Simplified Installation for Unix
Help Operations and Maintenance
Help Installation for Windows
Installing ]project-open[ on Windows OS is self-explanatory and requires no special considerations, simply follow the instructions and steps presented by the installation wizard.Indicator Active Customers Last Month
Counts the number of customers with projects in the last 30 days.
Indicators @Indicators
Indicators are reports that track one single business aspect to provide decision makers with relevant and concise data that barometrically represents the current corporate climate. ]project-open[ extracts information and converts into an easy to follow graphic display to forecast future trends and understand past ones. These indicators are pre-defined and most are available with the standard ]project-open[ download.
- Customer Management
- Financial Management
- Human Resources Management
- Timesheet Management
- System Usage
Customer Management
- Active Customers Last Month
- [New Customers Per Month]
- [New Projects Per Month]
Financial Management
- [Net Margin for Last Two Months]
- [External Costs]
- [Revenues]
- [Gross Margin for Last Two Months]
Human Resources Management
- [Headcount]
- [Sick Days per Month]
- [Average Employee Time in Company]
Project Management
- [Productive Hours]
- [Late Projects]
- [Open Projects]
- [Projects per Project Manager]
Timesheet Management
- [Average Timesheet Hours Per Project]
- [Average Timesheet Hours Per Employee]
System Usage
- [Forum Use]
- [Financial Documents per Project]
- [Live Operation Duration]
Indicators Project Histogram
This indicator displays the current status of all projects on the system, in a histogram format.
Preview this LIVE on our public demo-server
References
Related Object Types
- [Report]
Related Packages
Related Modules
Installation Debian
The ]po[ team provides primary support for RedHat/CentOS. Installers for other Linux distros are maintained by ]po[ partners or the community.
The following instructions are outdated and require several adjustments. If you want to contribute please get in touch with us.
This page introduces two options installing ]po[ on debian:
- Manual installation
- Installation using ]po[ deb packages (Alpha)
Manual Install
(originally provided by Iván Belmonte, http://ivanhq.net/)
Instructions for installing ]project-open[ on Vanilla Debian ETCH 4.0
NOTE:
- As seen in a comment below, don't use PostgreSQL version 8.3 because it's still not working well with ]po[. You should use 8.1 for now.
- This installation instruction will first install an older version (V3.2) of ]project-open[ and then upgrade to the latest version.
1. Packages
Install system dependencies for ]po[
apt-get install libreadline5-dev zlib1g-dev tcl8.4 tcl8.4-dev tk8.4-dev bison flex cdbs libpam0g-dev libperl-dev python2.4-dev python-dev x-dev
2. Aolserver
Install Aolserver4, needed modules and tdom
apt-get install aolserver4 aolserver4-dev aolserver4-doc aolserver4-nscache aolserver4-nsopenssl aolserver4-nspostgres aolserver4-nssha1 aolserver4-nsxml tdom
3. PostgreSQL
Install PostgreSQL and the contrib package (contains tsearch2, needed for fulltextsearch feature)
apt-get install postgresql-8.1 postgresql-contrib-8.1
You must change some behavior on PostgreSQL config. Edit /etc/postgresql/8.1/main/postgresql.conf. Look for VERSION/PLATFORM COMPATIBILITY section, and enable these variables as follows
add_missing_from = on regex_flavor = extended default_with_oids = on
Edit /etc/postgresql/8.1/main/pg_hba.conf. Look for the local IPv4 local connections section, and change md5 auth with ident as follows
# IPv4 local connections: #host all all 127.0.0.1/32 md5 host all all 127.0.0.1/32 ident sameuser
Restart postgresql
/etc/init.d/postgresql-8.1 restart
3. ]project-open[
Download and install ]po[ V3.2. We will upgrade to V3.4 in a step further down.
wget -c http://ivanhq.net/po/deb/project-open_3.2-1_i386.deb dpkg -i project-open_3.2-1_i386.deb
Create a user and a group for running ]po[
groupadd projop useradd -g projop -d /web/projop -s /bin/bash projop
Create a log dir and change permissions on the website for the new user
mkdir /web/projop/log chown -R projop:projop /web/projop
Create a new database for ]po[ (default postgres charset is latin9, set it to utf8)
su - postgres createuser -a -d projop createdb --owner=projop projop -E UTF8 createlang plpgsql projop exit
Load demo data into the new database
su - projop cd /web/projop/packages/intranet-core/preconf gzip -d project-open-3.2.sql.gz psql projop -f project-open-3.2.sql
Check the data has been correctly imported
psql projop projop=# select count(*) from users; count ------- 196 (1 row) projop=# \\q
Edit config file (/web/projop/etc/config.tcl) and change main path settings
#set homedir /usr/local/aolserver #set bindir [file dirname [ns_info nsd]] set homedir /usr/lib/aolserver4 set bindir /usr/lib/aolserver4/bin
Launch the server to see if it works okay
/usr/sbin/aolserver4-nsd -f -t /web/projop/etc/config.tcl -u projop -g projop # Ctrl+C to stop
Exit user projop
exit
4. Init system
Edit default Aolserver4 init script /etc/init.d/aolserver4 and change next parameters
#USER=www-data #GROUP=www-data #ADDRESS=127.0.0.1 #CONF=/etc/aolserver4/aolserver4.tcl USER=projop GROUP=projop ADDRESS=0.0.0.0 CONF=/web/projop/etc/config.tcl
Change next line (about line 42, remove -s main)
#-u $USER -g $GROUP -b $ADDRESS:$PORT -s main -t $CONF >/dev/null 2>&1 -u $USER -g $GROUP -b $ADDRESS:$PORT -t $CONF >/dev/null 2>&1
Test everything works
reboot
BE PATIENT, ]po[ can take up to 1 min to start after rebooting.
5. Config
Look into config file (/web/projop/etc/config.tcl) for tuning your server sitename, listening port, etc
6. Upgrade to ]project-open[ V3.4
Please go to http://www.sourceforge.net/projects/project-open/files/ -> V3.4 and download the latest ]po[ update (project-open-Update-3.4.x.y.z.tgz).
- Rename the old /web/projop/packages folder into packages.3.2 or similar.
- Extract the contents of the update installer into /web/projop/packages
- Restart ]project-open[
- Go to http://host:port/acs-admin/apm/ and select "Install packages" at the bottom of the page
- Select all packages with status "update" and choose "Next ->"
- After another restart please check the "Admin" page for additional upgrade instructions.
6. Enjoy!
Installation using ]po[ deb packages (Alpha)
This document describes how to install ]project-open[ 3.4.0.8 on a freshly installed Debian system
NOTE:
* As seen in a comment below, do not use PostgreSQL 8.3 or 8.4 because it's still not working well with ]po[. And seeing as how 8.2 is not available in Debian you should use 8.1 for now.
1. Packages
Install system dependencies for ]po[:apt-get install libreadline5-dev zlib1g-dev tcl8.4 tcl8.4-dev tk8.4-dev bison \ flex cdbs libpam0g-dev libperl-dev python2.4-dev python-dev x-dev
2. AOLserver
2.1 AOLserver on Debian
The original Debian packages for aolserver4 in Etch and Lenny are broken. Squeeze is the only version with a working aolserver4. If you are using Squeeze skip to step 4. Otherwise start at step 1. The new aolserver4 packages (4.5.1) should make thier way into the main Debian repositories pretty soon.
step 1: add the following to your /etc/apt/sources.list
deb http://mobigroup.ru/debian/ lenny main deb-src http://mobigroup.ru/debian/ lenny main
step 2: update all packages
apt-get update
step 3:
apt-get install debian-mobigroup-keyring
step 4: Install Aolserver4, needed modules and tdom
apt-get install aolserver4 aolserver4-dev aolserver4-doc aolserver4-nscache \ aolserver4-nsopenssl aolserver4-nspostgres aolserver4-nssha1 aolserver4-nsxml tdom
2.2 AOLserver on Ubuntu
Karmic and Lucid both have a 4.5.1 version of aolserver4-core available. Just modify the above to fit your situation.
3. PostgreSQL
3.1 PostgreSQL on Debian
Until they get around to updating the DB for ]po[ it is necessary to use PostgreSQL 8.1 which means you will need to download the packages from the Debian Etch branch.
step 1: add the following to your /etc/apt/sources.list and comment out the Lenny/Squeeze source lines
deb http://ftp.de.debian.org/debian/ etch main contrib non-free deb-src ftp://ftp.de.debian.org/debian/ etch main contrib non-free
step 2: apt-get update
step 3: apt-get install postgresql-8.1 postgresql-contrib-8.1
step 4: add the following to /etc/apt/preferences
Package: postgresql-common
Pin: version 71
Pin-Priority: 1001
Package: postgresql-client-common
Pin: version 71
Pin-Priority: 1001
Package: postgresql-8.1
Pin: version 8.1.17-0etch1
Pin-Priority: 1001
step 5: remove or comment out the Etch source lines in /etc/apt/sources.list and restore the Lenny/Squeeze lines.
3.2 PostgreSQL on Ubuntu
Hardy has an 8.2 version of PostgreSQL available so just do the above steps with the hardy branch.
4. ]project-open[
Install ]po[ V3.4.0.8.
- add IT Admins repository to your /etc/apt/sources.list
deb http://www.itadmins.net/packages/debian/ lenny/etch/squeeze main contrib non-free
-
add the IT Admins Group key to apt.
wget http://www.itadmins.net/packages/debian/itadmins_archive_keyring.gpg && cat itadmins_archive_keyring.gpg | apt-key add -
- Install
apt-get update apt-get install project-open
IMPORTANT!!! you will be asked about replacing certain configuration files during the installation of ]po[. YES!!! you want to replace the config files installed on your system with the ones that come with ]po[.
5. Init Page
Visit http://site.domain.tld:8000/ or https://site.domain.tld:8443/ and login with sysadmin@tigerpond.org (password: system)
6. Init System
There is an init script for ]po[ provided with the package. To control ]po[ simply:
/etc/init.d/projop start/restart/stop
7. Config
Look in config file (/web/projop/etc/config.tcl) for tuning your server sitename, listening port, etc
References
Installation About ]po[ Installers
There are several ways to install and use ]project-open[, each with specific advantages and disadvantages. Below is a list of possible options, in order of increasing technical difficulty. Each entry on this page is only a brief discussion of the option, with a link to forward you to a page with a more in-depth examination of the installation.
- Demo Server:
Demo Server - If you are just curious about ]project-open[ or would like to quickly evaluate/test our software with little investment of time or hassle, try on our online demo-server for a quick walk through.
- SaaS:
Software as a Service (SaaS) - The most hassle free way to get your company up and running with ]project-open[. You need only an internet connection, a few hours of preparation and you're ready to go.
- Native Installers:
Please choose your operating system and install ]project-open[. Please see the system requirements below.
-
]po[ Virtual Machine
Our VMware appliance includes a complete ]project-open[ installation on CentOS Linux configured for production use. VMware players are available for Windows and Linux platforms.
- CVS
To load additional modules or update your local installations, a CVS server is at your disposal at anonymous@cvs.project-open.net:/home/cvsroot (no PW)
Services Offered
Please contact us if you are going to use ]project-open[ in production. Most customers will need at least a few hours of configuration and training services before a go-live, in order to take full advantage of the application's options. Also, we can provide organizations with help on project definition, scoping and change management.
Demo Server
To evaluate the functionality of ]project-open[ you can use our demo server:
- http://demo.project-open.net (Version 3.4)
The disadvantage of the demo servers is that you can not log-in as an Administrator for security reasons. The Demo Server is pre-configured with several fictitious users and sample companies mimicking real life scenarios th