EXT: Partner Management¶

What does it do?¶

This extension handles everything related to the management of partners (persons, organisations) as well as relationships between partners. So basically, this extension if for everybody who needs to store some kind of people/organisation related data.

Let's say you are the administrator of a club. You might want to have a database which can store all the members of your club, but also what occupations each of your members has (e.g. the president, the cashier, etc.) and in what relationships they are (e.g. there's a group that organizes games, so you would have an organisation 'Game Organizer' and related members to that organisation).

Some functionality of this extension includes:

• Creation of partner records (persons, organisations) with all kinds of related data (lots of address data, unlimited contact information per partner, marital status, birthdate, religion, hobbies, occupations, etc.)
• Maintain relationships between partners with freely definable relationship types (like 'is member of' or 'is mentor for')
• Backend-Module (Web->Partner) with three submodules
  • Search: Search partners and directly edit the partners found
  • Reports: View or download (as CSV or PDF) predefined reports (e.g. Birthday List or Overview of Relationships) or own reports created with the report designer.
  • Tools: Assign existing frontend-user to partner records using various selection criterias or created your own reports using the report designer.
• Possibility to link a partner to a Frontend-User and automatically synchronize the relevant data.
• With the additional extension partner_fe (still in alpha-state) it is possible to display partner records in the Frontend and to maintain its own partner-data (based on the assigned FE-user).

The underlying data model is based on the following open standards by OASIS ( www.oasis-open.org ). This should make it ease to exchange data with other partner management tools.

• xNAL V2.0: extensible Name and Address Language ( www.oasis- open.org/committees/ciq/ciq.html#4 )
• xCIL : extensible Customer Information Language ( www.oasis- open.org/committees/ciq/ciq.html#7 )
• xCRL : extensible Customer Relationships Language ( www.oasis- open.org/committees/ciq/ciq.html#8 )

The extension comes with a full set of test-data so you can easily install the extension, import the test-data and right away start test- driving!

Screenshots¶

Create a new partner¶

• Click on the module Web>Partner
• In the folder list, click on the sys-folder where you want your new partner to be saved
• In the top left corner of the right screen part, click on the link 'create new partner'

• The first thing you have to do is to decide which type of partner you want to create. There are two possibilities: A person or an organisation. The difference should be evident: A person is always a real 'human being' with features like a marital status or a birth date. On organisation is everything else: It can be an organisation, a group of persons, a company... anything you like.
• If you decide to change the type of partner currently selected, you will notice that TYPO3 will reload the screen. Why? Because persons have a different set of fields than organisations.
• N ext, fill in all the fields you need to store. Please note that all the fields are well documented with a icon like this (context-sensitive help). Therefore, I will now just go into details with some specialties.

• The label-field cannot be filled in. It will be created by the partner-extension and displayed once you have saved the partner.
• The tab 'Contact Info/Relationships' gives you an overview of all contact-info (phone, e-mail, etc.) of the partner as well as its relationships with other partners. From here you can also maintain additional contact-info or relationships. More about this later on.
• Dates: All kinds of additional data related to the partner. Please pay attention to the special way you have to enter dates in the Birth- and Death Date fields. You must always enter the dates in the format YYYYMMDD, due to the fact that TYPO3 internally stores date in the UNIX format which cannot handle dates before 1970. Hopefully, there will be a better solution in a future version of the TYPO3-core, but for now just pay attention to entering the dates in this special format.
• Activitites: Check any of the values that apply
• Frontend: Two main things here:
  • You can link the partner to a Frontend-User. The extension will then automatically synchronize the name and the (standard-) email address of the partner with the FE-user record. This is particulary useful in conjunction with the extension partner_fe which allows you to display partner-data in the Frontend. Linking the partner to a FE-user enables you to edit you own partner-data in the Frontend.
  • You can view and/or define field visibility settings for the partner. Fields which are configured for frontend viewing (refer to the configuration section for details on this) can be customized for each partner. For instance, the field 'birth_date' is configured to be a public field. However, one partner wishes that this information is only visible to logged in FE-users. So you would define the field 'birth_date' for this partner to be 'restriced'. Possible values are:
    • Private: Means only the assigned FE-user can see the field
    • Restricted: Means only logged-in FE-users can see the field
    • Public: Menas that all users on the website can see the field

Please note that the actual results of these settings are subject to the implementation of the FE-plugin using these values. The effects mentioned above are the way how the extension partner_fe reacts to these settings.

Create a new relationship¶

• In order to create a new relationship, you will need to open an existing partner for editing.
• In the 'Contact Info/Relationships' tab, you can create a new relationship. You need to know if the current partner is the primary or the secondary partner of the relationship. If you're not sure what a primary or a secondary partner is in a relationship, have a look at the excursion 'Primary or secondary partner' below.
• Chose the relationship type. Again, you might want to read the excursion below if you're not sure what this is for.
• Fill in the rest of the fields (I guess the context-sensitive help should be enough here) and save.
• You now see the updated relationship overview. You might want to check out the partner you have just connected to see what's there!

Create a new contact information record¶

• In order to create a new contact information record, you will need to open an existing partner for editing.
• Go to the 'Contact Info/Relationships' tab and click on the 'Create New Contact Information' link.
• The 'standard' flag can only be set once per contact information-type. So for instance you can only have one standard e-mail address. If the flag has already been set for another contact information record, it will be deleted. Please note that the standard-flag will always feature an asteriks at the beginning of its label and will be shown bold in the contact-info overview.
• The rest should be fairly self-explaining. Use the context-sensitive help if you're not sure about what a field is used for.
• Saving the record will bring you back to the partner. Now you see the contact information you just saved in the contact-info overview.

Web>Partner, Search Partner¶

• Click on the module Web>Partner
• In the folder list, click on the sys-folder where you saved your partner records.
• In the top right corner, select 'Search Partner'
• Now you can enter the search parameters. Your last query will automatically be shown. Activating the 'Exact Search' means that values to the right of the paramter you entered will also be compared. For instance, a partner with the last name 'Miller-Brown' will not be found by entering the value 'Miller' if exact search is activated. If it is not activated howver, this partner will be found.
• You can reduce the number of partners displayed by entering a smaller number in the 'Max. number of results' field. If more partners are found than defined here, you can browse through thre results using the previous/next links.

Web>Partner, Reports>Birthday List¶

• Click on the module Web>Partner
• In the folder list, click on the sys-folder where you saved your partner records.
• In the top right corner, select 'Reports', then 'Birthday List'
• The system will now display a list of all persons from that folder where you entered a birth date. You can chose the number of months to the future you want to display the birthdays for. The system also calculates the age of the partner after his/her birthday and you can directly chose to send an e-mail by clicking on the mail-button to the very right. This will engage your default e-mail client. The e-mail address used is the standard e-mail address for the partner.

Web>Partner, Reports>Overview Relationships¶

• Click on the module Web>Partner
• In the folder list, click on the sys-folder where you saved your partner records.
• In the top right corner, select 'Reports', then 'Overview Relationships'
• You will get a tree-view display of partners and their relationships. Nice if you want to get an overview of a complex hierarchy. You can select a certain relationship type, as it does not make sense to mix the display of different types. The system will then automatically find the top-level partner(s) and start the tree view(s) from there. Please note that the (+)-symbols to collaps parts of the tree do not work yet. This is planned for one of the next versions of the extension.

Web>Partner, Tools>Mass Change Relationships¶

This submodule can be very handy if you need to change many relationships at once. For instance, you might want to enter the team structure of your club. Then you will have to enter many relationships, at least one for every member of a team. With this tool, you select the team you want to assign members to as primary partner. Then you search all team-members by simply filling in the form and with just one more click you can create all relationships at once.

This is how to do it step-by-step:

Click on the module Web>Partner

• In the folder list, click on the sys-folder where you saved your partner records.
• In the top right corner, select 'Tools', then 'Mass Change Relationships'

Now you should get a screen that looks like this:

• Search the primary partner by entering a search string in the field. By clicking the 'Search' Button, the system will look for partners with the entered search strings in their label field.
• If only one partner was found, it is directly selected as the primary partner. If more than one partner was found, select the correct partner from the list.
• Now you are getting to the main screen of the tool. It is divided in three tabs: Existing Relationships, New Relationships and Default Values.
• Obviously, in the Existing Relationships tab , you get all relationships for the selected primary partner. You can edit all fields at once or you can also delete multiple relationships at once. You cannot change the relationship type. If you want to to that, you must delete the relationship and re-enter it with the proper relationship type. Also note a handy feature: By clicking on the garbage-can icon, you can select/deselect all existing relationships (useful if you wan to delete all relationships at once.)

In the New Relationships tab, you get a number of empty fields to search for new secondary partners. Just like when searching for the primary partner, simply enter some search strings in the 'Secondary Partner' field. The system will once again look for these strings in the label field. Chose the partners you want to connect to the selected primary partner by the selected relationship type.

In the Default Values tab, you can define the defaults for new relationships and you can also chose how many search fields you want to get. The chosen defaults will be saved for as long as you are logged in, so they can be re-used. The button 'Set Defaults' will save the defaults for the session and the values will be used for new relationships you search from this point on. If you want to apply the default values to relationships you already selected, chose 'Force Defaults for All'.

Web>Partner, Tools>Report Designer¶

• Click on the module Web>Partner
• In the folder list, click on the sys-folder where you saved your partner records.
• In the top right corner, select 'Tools', then 'Report Desinger'
• To create a new report, click on the 'Create New Report'-link at the top. To change a report, click on the pencil-icon to the left of the report you want to change.
• In the tab 'General' you need to define the scope of data that must be selected. For now, this is done by directly entering the SQL-statement that you need. In one of the next version of the extension, this should be done in a more user-friendly way, similar to the core- function used in Tools>DB Check>Full Search>Advanced Query. For the other fields, refer to the context-sensitive help if in doubt.
• In the tab 'Field Selection' you can define which fileds must be displayed on the screen and which fields must be included when creating a file. For the screen output, you can also define a maximum length.
• In the tab 'Formats', select which formats are allowed for downloading files. Please note: The format 'PDF' is only available if you have the extension FPDF installed on your TYPO3 installation. XML support will come with one of the future version and it will be using the new PHP5-functions. For each selected format, you can define more format- specific options. Should be self-explanatory.
• In the tab 'Preview', you get a CSV-preview of the report after saving. Furthermore, you can download the report in all available formats.

Web>Partner, Tools>Assign Frontend-User¶

This submodule can be used if you want to link existing FE-user records to you partner-records. This makes sense especially when you are also using the partner_fe frontend plugin. There are two modes to map the FE-users to the partners. One (the most precise) method is by comparing e-mail addresses. The other compares names. Both methods end up in a list of suggested mathings which you can edit and then make the mass-update. Once the partners and the FE-users are linked, they are autmatically syncronized, but only in the direction Partner -> FE- user (the partner record is regarded as the master).

• Click on the module Web>Partner
• In the folder list, click on the sys-folder where you saved your partner records.
• In the top right corner, select 'Tools', then 'Assign Frontend-Userr'
• Now you can chose one of the two methods (by e-mail or by last name, as described above).
• If you want to know which FE-users are not yet assigned to a partner, chose 'Check Completeness'.
• The last option displays a list of e-mail addresses of assigned FE- users. This option might be replaced by a more advanced function in a future release.

Basic Setup¶

• First of all, create a sys-folder for all the configuration records you are about to create. The configuration records must be located in the same folder as the actual partner records.
• Go to the Web>List module and click on the sys-folder you have just created.
• Now click on the 'new record' button and start creating all the configuration records you need. What you need and if you chose to use it of course all depends on your requirements of course. This is the maximum you can configure:
• Status. For partner and contact-information records. Examples: 'Active', 'Passive', 'To be archived'
• Contact Permission. For partner records. Examples: 'Unrestricted', 'Do not contact', 'Call X before contacting'
• Titles. For partner records, type 'person'. Examples: 'Mr.', 'Mrs.', 'Herr', 'Frau', 'Monsieur', 'Madame'
• Organisation Types. For partner records, type 'organisation'. Examples: 'Company', 'Club', 'Youth Group'
• Legal Forms. For partners, type 'organisation'. Examples: 'Ltd.', 'AG', 'GmbH'
• Marital Status. For partners, type 'person'. Examples: 'Single', 'Married', 'Divorced'
• Religions. For partners, type 'person'. Examples: 'Christian', 'Muslim', 'Buddhist'
• Occupations. For partners, type 'person'. Examples: 'Youth Trainer', 'Cell Leader', 'Technician'
• Hobbies. For partners, type 'person'. Examples: 'Skiing', 'Snowboarding', 'Reading', 'TYPO3'
• Courses. For partners, type 'person'. Examples: 'Introduction to TYPO3', 'Goalie Training 2005'. Please note that this field might disappear with a future version and be integrated with a real event extension.
• Relationship Types. For relationships. Examples: 'Has Member', 'Has Wife', 'Has Child'

Configuration Records explained¶

For most configuration records, you will only need to supply a short and a regular description. There are some records which offer a bit more, so let's have a look at those.

Additional Recommendations¶

 # Disable the context menu in the folders list
options.pageTree.disableIconLinkToContextmenu = 1

 # Improved overview in the Web>List module
mod.web_list.listOnlyInSingleTableView = 1

Installation¶

This extension depends on the extension static_info_tables. This must be installed before you can install the partner-extension. Please note that this extension needs TYPO3 version 3.8.0 or higher due to the fact that it is using a hook in TCEmain which was not available in an earlier version.

After installation, you can configure the following options:

• noTabDividers : For TYPO3 versions later than 3.7.0, you can disable the “dividers2tabs” feature, which will separate the display of partner-records in the backend into different tabs. Since the tabs are quite an improvement to usability, checking this option is not recommended.
• generateReportsInBackground : Most webservers will time out if a process is taking longer than 30 seconds to complete. Due to this limit, it is impossible to create reports if you have large amounts of data. In this case, it is recommended to turn this feature on. If enabled, reports will be created by a background task which normally do not have a time-out limit. Of course, you will still have to wait... :-) Attention : For this to work, the following conditions must be met:
  • There must be a backend user called “_cli_partner”
  • On Linux, PHP must be installed in /usr/bin/php
  • On Windows, the path to PHP must be set in the Path variable (Control Panel > System > Advanced > Environment Variables > System Variable “Path”). Make sure to restart your system after setting the variable.
• maxNoOfPartner : When viewing custom-made reports in the backend- module of the extension, you will get only a certain number of partner displayed per page. This is to make sure the report can even be displayed if there is a large number of partners. To change the number of partners you get on one page, you can change the value of this option.
• Allow lookups from same page only : If selected, records for value tables like titles, status, occupations, hobbies... must reside on the same page as the main partner records. If deselected, records from all pages are shown in the selection boxes.

If you want to add PDF-support for the report designer, you must also install the extension FPDF.

Upgrade¶

If you are upgrading from version 0.4.0 or lower, you must execute the following steps.

Before installing the new version, please make a backup of all your data from the extension. The easiest way to do that is by using the Extension Manager: Click on the extension 'Partner', then chose Backup/Delete. Click on 'Download all data from:' and save the SQL- file

After you install the new version of the extension, you will get the following screen. Click 'Make updates' to add the new table to your database.

After that is done, chose 'UPDATE!' from the drop-down menu in the Extension Manager (note: you might need to click on the update button once again before you get the UPDATE-entry).

No please pay attention to the warnings and make sure you have really made a backup of your data before proceeding! If your backup is fine, click 'UPDATE' and your database will be change to work with the new version of the extension.

Reference¶

These properties must be defined as Tsconfig in the header of the sys- folder where the partner-records are stored.

tx_partner.fieldVisibility.default {
  tx_partner_main {
    last_name = PUBLIC
    last_name.userChange = 0
    first_name = PUBLIC
    first_name.userChange = 0
    street = PUBLIC
    street.userChange = 1
    postal_code = PUBLIC
    postal_code.userChange = 1
    locality = PUBLIC
    locality.userChange = 1
    country = PUBLIC
    country.userChange = 1
    birth_date = PUBLIC
    birth_date.userChange = 1
  }
  tx_partner_contact_info {
    email = RESTRICTED
    email.userChange = 1
  }
}

Test-driving the Partner-Extension¶

The easiest way to test-drive this extension is to create a new database and then use the demo-data provided as an SQL-dump. Why couldn't I just include a T3X-file using the standard export functionality? Because the relationship between partners and contact- informations is modeled as 1:n, which is not yet supported by the core. This means, the standard import/export functionality doesn't work for this extension.

However, here's a step by step explanation how to easily test-drive the extension by using the SQL-dump mentioned above.

NOTE 1 : This only works with the latest stable version of TYPO3.

NOTE 2 : The script also includes the creation of a system-folder (table 'pages'), a frontend group (table 'fe_groups') and frontend users (table 'fe_users'). If you have extensions installed which add additional fields to these tables, the script will generate errors like Scriptline : 272Columncountdoesn ' tmatchvaluecountatrow1 . In this case, you need to add the additional fields to the script yourself (e.g. by adding empty strings).

Create a new database: With the TYPO3 backend started, click on Tools>Install. Then chose option 1: Basic Configuration. Scroll down until you get the input field for the Database. Fill in the name of the database you want to create in the field 'Create Database' . Scroll down and click the button 'Update localconf.php' and you get a success message 'Database xyz created'. You now have an empty database.

Now chose option 2: Database Analyser. Scroll down and click on the link 'Update required tables COMPARE'. Scroll all the way to the bottom and click 'Write to Database'. You now have an empty database, but with all required tables.

Now click on 'Dump Static Data IMPORT'. Chose 'Import the whole file 'CURRENT_STATIC' directly' and click 'Write to Database'. You have now imported all static data (e.g. Countries).

Now click on 'Create “admin” user'. Enter a username and a password and click on 'Write to Database'. You have now created an admin-user to login to your new database.

Now start your backend (you can use the link at the very bottom of the page). You will be promted to login. Use the login-data of the admin user you just created.

Start Tools>phpMyAdmin (the extension 'phpmyadmin' must be installed first) and click on 'SQL'. Click on the 'Browse' button and chose the file typo3confextpartnerdocpartner_demo_data.sql. Make sure you set the character set to latin1 . Click on the 'Go' button. You have now imported all demo-data for the partner extension.

That's it! Start using the extension by starting the module Web>Partner (Make sure you click on the sys-folder 'Partner', where all the records are located). Enjoy!