Basic Tutorial

Introduction

UPDATE: please see https://docs.openpetra.org/ or https://handbuch.openpetra.de/ for a more uptodate manual!

The aim of this tutorial is to describe the functionality of OpenPetra at its current state. You will learn what you can do with OpenPetra, and how to do it.

There is a demo database available that will provide the examples for this tutorial.

Installation

Currently, only the Standalone version is available for quick installation on Windows. You just download it from Sourceforge via the link from the OpenPetra website.

You will need Administrator permissions to be able to install OpenPetra on your workstation.

The installer will tell you to install the .Net Framework if this is not installed on your windows system already.

The Standalone version of OpenPetra uses the light-weight database SQLite, which does not need to be installed separately. Please note that for bigger databases SQLite will become quite slow, and at that stage you might want to work with a proper database system. You can either install your own OpenPetra server running on Windows or Linux using a free database system, eg. MySQL or PostgreSQL. Alternatively, there will soon be a hosted service provided by some developers of OpenPetra, and for a small monthly fee you can benefit from a centrally hosted version of OpenPetra. More on this will follow soon...

Start your OpenPetra for the first time

You will find an OpenPetra icon in your start menu or even on the Desktop, if you did not disable that choice during the installation. When you double-click that icon, you will get to the Login screen:

Login Screen

Please login to OpenPetra with the 'demo user'. Its username is demo and its password is demo as well.

You will see the Main Menu of OpenPetra:

Walk-through: Main Menu

• On the left hand side is the Navigation Pane, which allows switching of the context you are currently working in.
  • The main selection you take is the Module of OpenPetra you want to work in.
    • This is done by clicking one of the bars that have icons in the bottom of the Navigation Pane, eg. 'Partner' or 'Ledger'.
    • Select a Module of your choice.
  • Once you have selected a Module, the items above the Modules change to reflect the sub-divisions of the Module, called Sub-Modules.
  • Under each Sub-Module there are entries which represent an Area in the Sub-Module.
    • Select an item of your choice in an Area of a Sub-Module.
• On the right hand side is the Task List.
  • The items in the Task List are Tasks, which are logically grouped under different headings.
  • The Task List changes according to your selection on in the Navigation Pane.
    • Select different Modules and entries under Areas in the Sub-Modules to see how the Tasks presented are changing accordingly.
  • By clicking on a Task in the Task List, an action is performed by OpenPetra.
    • This will result in the opening of a Form or a Dialog Box.

Example Task: Changing a User's Password

The first action you should do is to change the password of the 'demo' user. To do this, go to the Settings module, and select the Task "Set Password".

The sysadmin user

You may have noticed that one of the modules was grayed out when you logged on using the demo user: the system manager module. OpenPetra is often used with many different users. There is one user, the sysadmin user, who is dedicated to the administrative tasks, including

• creating new user accounts
• helping users by resetting their forgotten passwords
• creating backups of the database etc.

Give it a try: Restart OpenPetra, and on the login screen enter as user sysadmin with the password CHANGEME (in capital letters).

Now the Petra Screen will look something like the following, and the System Manager module is no longer grayed out.

Tasks you may want to try:

• Change the password for the sysadmin user
• You can retire the DEMO user, and create your own user
• You can give permissions as you need for the user, by selecting the Modules that the user should have access to.

Base Data or Demo Data

After you have installed the Standalone version of OpenPetra, you will have already a very limited set of data in the database. This database already has a ledger (number 43) for running the finances of a legal entity, and the sitekey is 43000000 as well. The sitekey is used for generating the partner keys for your partners.

If you want to start your very own database, please download the empty base Database, which contains just a demo user and some other necessary data to allow OpenPetra to start at all. The link for the file is: http://openpetraorg.sourceforge.net/sampledata/empty.yml.gz

TODO: unfortunately this caused a failure for me with OpenPetra Standalone 0.2.6 and the mentioned .yml.gz file.

If you want to use a database with already quite a number of addresses, some months of financial data, etc, please download one of our other demo databases. TODO

To install such a data file, please take a backup first of your database, because the new data file will completely replace your current data. Please go to module System Manager, then to database and there Import/Export. Select "Export all Data" to store your own data to a local text file, or "Reset Database" to import a yml.gz file which could be your own backup or one of the sample databases or the empty base database.

Please note that you can unzip the yml.gz files with 7zip on Windows or gunzip on Linux, and it is a text file which you can open in any text editor. This opens up a lot of possibilities, just be careful not to change data and to import it again without knowing what effects that could have.

Configuration

Finance module

You need to create your own ledger, if you don't want to use the default ledger with number 43 that comes with the demo database. Creating your own ledger also allows you to define your own ledger number, your base currency, your financial year, the number of financial periods per year and the number of periods that are allowed to be open at the same time.

After adding the new ledger, you should allow some of your users to work with that ledger, by adding the new Ledger to their account in System Manager, Users, Maintain Users.

You will need to restart your OpenPetra client in order to see the new menu item for the new ledger.

Partner module

To be able to create new partners, which all get a partner key in the form <unique 4 digit ID for your office><6 digit ID for partner>, you need such a 4 digit ID that identifies your office or site, that is why we call it the sitekey.

In the current version of OpenPetra 0.1, you cannot set the site key independently, but you need to create a ledger as described in the paragraph above, and the sitekey will be created automatically based on your ledger key. So if you have created ledger 23 for example, your partner keys will all start with 0023.

Managing 'Partners' and Addresses

Introduction and Definitions

In OpenPetra, the word 'Partner' is used to describe anyone who is helping the organisation in working towards its goals. Partners include individuals who support the Organisation through gifts, churches, organisations who supply goods and services, members of staff, and internal units (sub-divisions of the Organisation).

Partners and Partner Classes

Let’s look at an office. Nothing happens without relations with other people and groups, and in OpenPetra, everyone that the office deals with is called a Partner. Partners may be people or organisations. In fact OpenPetra uses several different classes of partner, since slightly different data needs to be stored for each. People are the most common, and we look at them below. Two of the classes, churches and organisations are fairly obvious (organisations include companies that we buy items from). Another common class of partner is a unit, a term used to refer to the internal sub-divisions or offices of the Organisation. Your office is a unit, and it will exchange information with other units.

Families and Persons

Finally we have people - the largest group of partners. The reason we left them until last is that people are more complicated than you might think! With many people, for example a married couple who support the Organisation, we only need basic information, like name, address and a record of donations. We treat the couple as one, and we call them a partner of class Family. OpenPetra uses this term, Family, even if the supporter is a single person.

However, in some situations, we need to record individual information, such as date of birth, gender, etc, which cannot apply to a couple. OpenPetra does this by using a fifth class of partner record, known as class Person. However, a Person record is only used for additional information; it is not the main record of the partner’s address etc.

Addresses

We must record a partner’s address, so that we know how to contact them. However, they may have more than one address - for example a private address and an office address. OpenPetra stores addresses separately from partners, and calls them locations. One partner can have several address locations. However, we need to know which address to send any mail to, and so we make one address the Mailing Address.

Where to find Partner and Address Functionalities

Partners and addresses are both maintained in the Partner Module of OpenPetra. You select the Partner Module by clicking "Partner" in the Navigation Pane of the Main Window of OpenPetra and then selecting "Partners" in the "Main" section.

Partners form the key data in OpenPetra on which other data is based (eg. Gifts/Donations in the Finance Module, Personnel Data in the Personnel Module).

Walk-through: Creating Partners

New FAMILY

To create a new Partner of Partner Class 'FAMILY', choose Add New Family in the New Partner Task Group in the Task Pane of the OpenPetra Main Window (found in the Partner Module).

The New Partner Dialog is brought up. It allows you to set several things before the Partner Edit Screen for a new Partner is shown.

• The 'Sites Available' list shows the available 'Sites'. An OpenPetra installation can use several Sites to split up the information that is entered. A sub-office will usually be a different Site and have a different 'Site Key' than the main office. Through that Partners with different Partner Keys will be created. In the demo data there is only one Site available, which is pre-selected for you.
• The Partner Key is set to a unique, non-used number. Although this can be changed, this is rarely necessary, so leave the value that is shown.
• The Partner Class can be changed to any other Partner Class, but this is already preset to FAMILY, so we can just accept that selection.
• The Acquisition Code can be set to reflect the way how we acquired this Partner's data. Have a look at the various values and select any one.
• Choose 'OK' once you are happy with your selection, or 'Cancel' to cancel the creation of a new Partner.

The Partner Edit Screen is shown.

• Fill in the Title, First Name(s), and Surname of the Partner you want to create.
  • Please note that hints on what information should be entered in the respective data field are shown in the Status Bar of the Partner Edit window.
• Check No Solicitations if the Family prefers not to be contacted by your organisation, except for important information (such as Gift Receipts).
• Select a value in the Addressee Type Field. This affects certain mailing operations in OpenPetra, eg. how to a Family is addressed in an email or letter. 'FAMILY' is already pre-selected, which will be correct for nearly all circumstances.
• Select a value in the Partner Status Field. Usually Partners are ACTIVE when entered; not being ACTIVE means the Partner will automatically be excluded from many operations and Reports in OpenPetra.
• Save the information you have entered by pressing the Save Button in the ToolBar. Congratulations, you have created you first Partner! :-)
• Further details can be added by clicking on the Partner Details Tab. The data fields on this Tab allow recording of different information for each Partner Class - this is achieved by having different data fields for PERSONs, FAMILYs, ORGANISATIONS, etc. For instance, you could set the Marital Status to 'M' for married and record the wedding date in the Marital Status Since field.
  • Notice that the date you enter is formatted in a specific way once you leave the data field. The same date format will be used in OpenPetra in all of your offices all around the world to disambiguate dates (as the order of month, day, year can vary greatly from country to country).
• An address (or several) can be recorded on the Address Tab. You can also record telephone numbers, e-mail-Address, etc there.
  • In case several Addresses are entered, one Address should be set as the Mailing Address so it is clear to which of the Addresses OpenPetra should send mail.
• Save the information you have entered by selecting Save in the File Menu.

New PERSON

Creating Partners of any Partner Class except PERSON is similar to the creation of a FAMILY. For PERSONs, a slightly different approach is taken, which is all automatic once you select which FAMILY a PERSON should belong to.

To create a new Partner of Partner Class 'PERSON', choose Add New Person in the New Partner Task Group in the Task Pane of the OpenPetra Main Window (found in the Partner Module).

The New Partner Dialog is brought up.

• Since a PERSON must belong to a FAMILY, the dialog has an additional Button, "Family...". Choose this Button to bring up the Partner Find Screen. Search for an existing FAMILY and accept it by double-clicking on the relevant line in the list of found Partners (please refer to the section on finding Partners below on how to use this screen). This brings you back to the 'New Partner Dialog', where the name of the selected FAMILY is displayed next to its Partner Key.
• The Partner Class can be changed to any other Partner Class, but this is already preset to PERSON, so we can just accept that selection.
• Choose 'OK' once you are happy with your selection, or 'Cancel' to cancel the creation of a new Partner.

The Partner Edit Screen is shown.

• Fill in the Title, First Name(s), and Middle Name (Initial) of the Partner you want to create. Note that the 'Surname' is taken over automatically from the FAMILY.
• Select the Gender of the Person.
  • Note that the Addressee Type is changed automatically to match the selected Gender.
• In the 'Addresses Tab' you can see that the 'Best Address' of the FAMILY you selected in the 'New Partner Dialog' is taken over automatically from the FAMILY.
• A 'Relationship' is automatically created that points from the FAMILY to the PERSON and from the PERSON to the FAMILY.
  • 'Relationships' can be used in OpenPetra for creating a selection of Partners and for reporting purposes. (Please note that Relationships are recorded, but cannot be shown in the user interface of OpenPetra at this stage.)
• Further details (eg. Academic Title or Occupation) can be added by switching to the Partner Details Tab.
  • Note that the data fields on the Partner Details Tab allow recording of more information than those available with a FAMILY.
• Save the information you have entered by selecting Save in the File Menu.

(Note: as of June 2010, the Partner Edit Screen in OpenPetra provides only basic functionality. However, over time it will get the rich set of functions that the Partner Edit Screen in Petra 2.3 has already got. See the 'Partner User Guide' at Petra User Guides for details on what can be done with the screen in Petra 2.2. The screen has even more features in Petra 2.3.).

Finding Partners

To find Partners which you or others have created (eg. Partners which are part of the demo database), choose Find Partners in the 'Maintain Partner' Task Group in the Task Pane of the OpenPetra Main Window (found in the Partner Module).

The Partner Find Screen is brought up.

Like the Partner Edit Screen, the Partner Find Screen is a central screen in OpenPetra. Since Partners form the key data in OpenPetra on which other data is based (eg. Gifts/Donations in the Finance Module, Personnel Data in the Personnel Module), it is important to be able to find Partners easily.

The Partner Find screen facilitates not only the finding, but also the working with found Partners.

(Note: as of June 2010, the Partner Find Screen in OpenPetra provides only basic functionality. However, over time it will get the rich set of functions that the Partner Find Screen in Petra 2.3 has already got. See the 'Partner User Guide' at Petra User Guides for details on what can be done with the screen in Petra 2.2. The screen has even more features in Petra 2.3.).

Entering Find Criteria

• The top section of the Screen contains several Criteria Fields.
  • Criteria Fields in which text can be entered are treated as 'Criteria starting with xxx'.
    • Example: Enter 'Hof' in the 'Partner Name' Criteria Field to find Partners whose names start with 'Hof', eg. Hoffman, Hofmann, Hoflinger, etc.
    • The small button on the right side of the text fields will provide the ability to change the way OpenPetra applies the 'joker' or wildcard search: at the end of the text (as currently implemented), at the beginning of the text, at both the end and the beginning of the text, and will also offer an exact match option, where no joker is applied at all. This ability is not implemented yet (as of June 2010).
  • The 'Country' Criteria Field can be cleared to search for Partners who have Addresses in any Countries.
  • If a Partner Key is entered in the 'Partner Key' Criteria Field, all other Find Criterias are ignored.
• Press the Clear Button to start over again. It resets the Criteria Fields to defaults.
• Press the Search Button to search the OpenPetra database for Partners who match the combination of the Search Criteria entered.
  • Example: Supposing you enter 'Meyer' in the 'Partner Name' Criteria Field and select 'FAMILY' in the Partner Class Criteria field and enter 'Washington' in the 'City/Town' field and you press the Search Button, Petra will try to find all Partners whose name starts with 'Meyer' who live in a city whose name starts with 'Washington' and which are of Partner Class 'FAMILY'.

Working With Found Partners

Partners that match the combination of the Find Criteria you entered are found are shown in a list in the bottom part of the screen.

• You might want to change the Find Criteria you entered if the Partner you are searching for is not found, or if too many Partners are found.

Note: If several Addresses are entered for a Partner, the Partner is listed several times - once for each Address. To see a shorter list that contains only the Mailing Addresses, check "Mailing Addresses Only" in the Find Criteria Section and repeat the search operation. (Partners usually have only one Mailing Address.)

Selecting a Partner

• Use the cursor UP or DOWN keys on the computer keyboard or the mouse to select a Partner of your choice.

Viewing and Editing of a Partner

• Use the ENTER key on the computer keyboard or double click on the selected Partner.
• The Partner Edit screen opens and allows viewing and editing of the data.

Partner reports

TODO

Manage donations

TODO

• import from bank transaction statement
• Post batches
• print gift receipts
• print other letters for treasurer or new donors

Pay your bills

TODO

GL Batches

TODO

• manual batches
• Reports