SourceTap CRM Documentation

The configuration of the Entity Engine is done through a simple XML file called entityengine.xml. This file is used to define parameters for persistence servers such as JDBC datasource parameters.

For SourceTap CRM, this file is located in the distribution at components/entiy/config/entityengine.xml.

As outlined in the overview, the settings which generally need to be configured are:

• Transaction Factory - see below
• field type - edit the field-type-name attribute of the <datasource> tag.
• datasource location - edit the jndi-name attribute of the <jndi-jdbc> tag relevant to your database.

Transaction Factory

By default the Entity Engine tries to obtain a JTA transaction factory from the application server using JNDI. This table shows the different values for different application servers:

Orion, Resin, Tomcat and Weblogic(see also the Orion, Resin, Tomcat and Weblogic guides)

<transaction-factory class="org.ofbiz.core.entity.transaction.JNDIFactory">
  <user-transaction-jndi jndi-server-name="default"
    jndi-name="java:comp/UserTransaction"/>
  <transaction-manager-jndi jndi-server-name="default"
    jndi-name="java:comp/UserTransaction"/>
</transaction-factory>

JBoss (see also the JBoss 2.4.4 and JBoss 3.0.x guides)

<transaction-factory class="org.ofbiz.core.entity.transaction.JNDIFactory">
  <user-transaction-jndi jndi-server-name="default"
    jndi-name="UserTransaction"/>
  <transaction-manager-jndi jndi-server-name="default"
    jndi-name="java:/TransactionManager"/>
</transaction-factory>

Jetty (see also Jetty guide)

<transaction-factory class="org.ofbiz.core.entity.transaction.JotmFactory" />

The Entity Model describes the table and column layout that SourceTap CRM uses in a database. It can be completely altered without changing any of the internal workings of SourceTap CRM.

The model provided should work with almost any database (care has been taken to ensure the column and table names are SQL compliant).

The entity model is configured through an XML file called entitymodel.xml (located in the distribution at hot-deploy/sfa/entitydef/entitymodel.xml).

The format of the file should be fairly self explanatory - basically SourceTap CRM always refers to the entity-name and field-name attributes within the code. The type attribute of a <field> tag should always match the type attribute of a <field-type-def> tag in your fieldtype-*.xml files.

To change where entities and fields are persisted in your database, simply add (or edit) the attribute table-name (for entities) or col-name (for fields).

We chose the EE over CMP or BMP entity beans because:

• it is more portable between application servers
• table schemas are automatically created and updated
• using the field type definitions, we can add support for new databases very quickly
• it is faster than most CMP implementations and has some nice caching features

This document deals with configuring the entity engine for SourceTap CRM (but should be applicable to most applications). For more details on the entity engine itself and it's inner workings, see:

OFBiz Entity Engine Guide

describes the theory behind the entity engine, its architecture and usage patterns

OFBiz Entity Engine configuration guide

describes all of the entity engine configuration options, whereas this document just describes configuring the entity engine for SourceTap CRM

API Docs

the API docs for the org.ofbiz.entity package

Data can be imported into the SourceTap CRM from comma separated (CSV) flat files. The system supports importing of leads, accounts, contacts, and opportunities. The first line of the CSV file should contain header information with the names of the fields being imported. An example import file is shown below

To import a file choose the Import/Export option from the main menu

From the Import Data option, choose the type of data you want to import. It is recommended that accounts and contacts be imported as leads first and then converted to accounts and/or contacts, rather than directly into accounts and contacts. The reason for this is that the import process will import all data as new records. It does not attempt to match imported data to existing data in the system. On the other hand, the lead conversion process will attempt to match the lead to be converted with existing accounts and contacts, and it will give you the option to update existing information or convert the lead into new records. The lead conversion can be done on a single lead or on a list of leads.

The first step of the import process is to upload the file to the server.

Once the file is uploaded, you will be asked to map the columns in the import file to the fields in the database. The system will attempt to automatically map fields by matching the column names in the first row of the CSV file to field names in the database.

You should verify that the field matching is correct before proceeding. The mapping will match fields based on the first field in the database that contains the text in the column header label, so it may not always map fields correctly. In the file listed above, the two columns in the import file: "Address" and "Address2" should be mapped to "Address1" and "Address2" in the database. However, there is also an "Address" field in the database, so the "Address" column in the file is initially mapped to "Address". In order to fix this, you should change the "Address" field to "NOT MAPPED" and map the "Address1" database field to "Address" from the file.

If the column label in the file doesn't match any database fields, the screen will show the unmatched columns in the "Fields Not Automatically Mapped" area of the mapping screen. You should determine if any of the unmapped columns need to be imported, and if so, you should set up the mapping before proceeding. The mapping screen lists all of the fields in the database, and for each field, there is a drop down containing all of the columns from the import file.

In addition to mapping input columns from the CSV file to the fields in the database, you can also set fields in the database to constant values by filling in the "Fixed Value" field on the screen. This is usefule in cases where you want to set a field in the database such as "Lead Source" to a constant value.

At the bottom of the screen, you are giving the ability to add the imported data to a list. You can either add the data to an existing list by choosing one of the existing lists from the dropdown, or you can create a new list by entering a list name in the text field next to the dropdown. You would typically add imported data to a list if you wanted to perform some activities on the items in the import file as a group. Currently, this is primarily used with the mail merge functionality, which requires a list to perform the merge against. You can also create lists after importing the data by creating a query, but this assumes that you have the ability to define a query that will match the records that have been imported.

You can also use identifiers to tag imported records. Leads, contacts, and accounts can by associated with identifiers, which make them easier to find and group together. At the bottom of the import mapping screen, you are given the option to set assign an existing identifier to the imported record or to create a new identifier and assign it to the imported records.

Once you hit the "import" button, the import process will begin. Once it is complete, you will be given a message telling you the number of records imported and the elapsed time of the import

Queries give you the ability to find the data you are looking for. You can create a query and save the query definition so that the query can be run again with a single click. You can also save the results of a query to a list for further processing, such as for mail merge.

Some screens, such as the Lead and Contact Home screens, have a simplified query interface with a few of the more common fields available to be searched. For example, the main Contact screen shown below allows you to query based on first name, last name, and city.

For more query options, you can click on the "Advanced" link next to the "Run/Save Query" button. This will give you the ability to search on all available fields. There are two different query modes, standard and advanced. The default query mode is controlled by a user preference setting. The standard query screen looks like screen shown below:

This screen allows you to search using query by example. You fill in the values you want to match and then run the query. The query will find any results where the specified fields start with the specified value. For the screen shown above, the query would find all contacts with a last name starting with "Smith", a city that starts with "Dallas", and a type that starts with "Alumni". The query will only return results where all the conditions are met.

The advanced query screen looks like the screen shown below:

This screen allows you to perform more complex queries. You have the option of using the following conditions:

• STARTS WITH - finds records where the field value begins with the specified value
• = - finds records where the field value exactly matches the specified value
• CONTAINS - finds records where the field value contains the specified value anywhere in the string
• ENDS WITH - finds records where the field value ends with the specified value
• < - finds records where the field value is less than the specified value
• > - finds records where the field value is greater than the specified value
• <= - finds records where the field value is less than or equal to the specified value
• >= - finds records where the field value is greater than or equal to the specified value
• NOT EQUALS - finds records where the field value does not match the specified value
• BETWEEN - finds records where the field value is between two specified values. When using BETWEEN, you should enter two values separated by a comma.
• IN - finds records where the field value is in a list of specified values. When using IN, you should enter a list of comma separated values
• NOT IN - works the opposite of the IN condition

In addition to being able to enter different condition operators, you also have the ability to search for values in related tables. For example, the query shown above lets you search for contacts with a first name that starts with "SMITH", who live in "Dallas", who are "ALUMNI", and who have given gifts greater than $500 between January 1, 2000 and December 31,2003.

When you run a query, you can save the query definition so that it can be reused easily. If you enter a name in the "Save Query Definition" field, the query definition will be available in the Query drop down field on the associated list screen. Query definitions are dynamic, meaning that the next time you run the query, you may get different results if records have been added, deleted, or modified.

You can also specify that the results of the query should be saved to a list, which can be used in further processing, such as mail merge. This is done by filling in the "Save Results To List" field before running the query. Saved lists are static, meaning that the results are stored in the list when the query is run. Any inserts, updates, or deletes to the database will not affect the results of a saved list.

The Report Builder allows you to create and run custom reports. Reports can be displayed to the screen or exported to Excel, CSV, or XML. The main screen, shown below, contains a list of pre-defined reports and gives you the ability to create new reports.

The top portion of the screen shows existing reports. When you select an existing report, you will be taken to the report definition, which will give you the ability to modify the report prior to running it. The bottom portion of the screen gives you a list of report types that you can create

The screen below shows the report definition screen.

The report definition screen allows you to choose which fields are show in the report, what criteria will be used to retrieve data for the report, and what the sort order of the data should be.

To add fields to the report, you select fields in the "Available Fields" select box and move them to the "Report Display Fields" select box using left arrow button between the boxes. You can select multiple fields at the same time by using the CTRL and SHIFT keys. If you hold down the CTRL key, each field you click will be hilited. If you hold down the SHIFT key, all fields between the first field clicked and the last field clicked will be hilited. When you use the left arrow button all hilited fields will be moved. Similarly, you can remove fields from the report by hiliting them in the "Report Display Fields" select box and using the right arrow button to move them back to the "Available Fields" select box. You can alter the order of the fields in the report by using the up and down arrow buttons to the right of the "Report Display Fields" select box

Report Criteria are defined in the same way that you handle advanced queries. You can remove a search condition by clicking on the red "X" button in the action column. If you need to add additional conditions, you can click on the green "+" button in the action column.

The order that data is displayed in the report are defined in the "Sort" section of the screen. Adding, removing, and ordering sort columns is done in the same way that you choose the fields to display in the report.

If you want to save the report so that it can be rerun at a later date, you should enter a name in the "Save Report As" field.

The figure below shows the report output screen

The top of the screen shows the number of records returned by the report and allows you to page thru the results. The middle portion of the screen contains the actual report results. You can dynamically alter the sort order by clicking in the column headers. The bottom portion of the screen lets you export data in Excel, XML, or CSV formats.

Data can be exported to Excel, XML, or CSV format using the Report Builder. See the section on Creating Reports for more information.

Lead Conversion is the process of converting a lead into an account, contact, and/or opportunity. Leads are typically generated from marketing events, such as trade shows or mailing campaigns. Once enough information is gathered about a lead to qualify that lead as a potential opportunity, the lead can be automatically converted to an account and/or contact. SourceTap CRM allows you to convert leads on a case by case basis, or to convert a whole list of leads to accounts at the same time.

Individual Leads can be converted from the Lead Detail page. This is done by clicking on the "Convert this Lead to Account/Contact/Opportunity" link as seen in the screen below:

After you click on the "Convert" link, you are taken to a screen that allows you to set the conversion options, as shown below:

The options screen gives you the ability to create a new account for this lead or to map the lead to an existing account. The system will find Accounts with names that are similar to the company name associated with the lead, and give you a list of accounts that the lead might be linked to. You can also control whether the conversion process will also create a contact or opportunity for the lead. If you choose to create an opportunity, you can set the name of the opportunity and the initial stage to be set on the new opportunity.

Once you click on the "convert" button, you may be taken to a screen that lets you map the lead to an existing contact. This step is only done in the case where you choose to map the lead to an existing account and where there is an existing contact in that account with a name that matches the lead being converted. After this, you will be shown a confirmation screen, as shown below, which will give you a final chance to change things prior to initiating the conversion.

Once the lead is converted, you will get a message confirming the conversion and given a set of links that allow you to navigate to the newly created account, contact, or opportunity, as shown below:

The screen below shows a what a typical contact looks like after conversion

In order to import contacts into the system, it is recommended that you first import them as leads and then convert them. This helps eliminate the possibility of duplicate contacts being created, as the conversion process allows you to choose whether to create new accounts/contact information of map the lead to an existing account/contact.

To make this process as easy as possible, the system allows you to convert multiple leads at the same time. This option is available in the "Mass Convert Leads" link from the Lead Home page, as shown below:

The first step is to choose a list of leads to convert, as shown in the screen below:

If you need to create a list, you can do it by creating a query and choosing the save results as list option. The list select screen allows you to view the leads in the list or to delete the list or to start the conversion process. If you delete the list, it will not delete the underlying leads, it will merely remove the list. To begin the conversion process, click on the list name. This will take you to the conversion options page, as shown below:

This screen gives you the ability to control whether contacts and opportunities will be created during the conversion process. It also gives you the ability to attempt to match lead information to existing accounts/contacts. Unless you are sure that none of these leads already exist in the database as accounts or contacts, you should leave the "Find Matching Accounts" option checked. When you click "next", you are taken to the account/contact matching screen, as shown below:

The matching screen gives you a list of leads to be converted and gives you the option to map the lead to existing accounts/contacts in cases where there is a close name match to existing information in the database. You can choose to create new accounts/contacts for each lead, or you can link to one of the suggested matching accounts or contacts. If the matching account is not displayed and you think there might be a matching account in the database, you can click on the "Find Account" link, which will give you the ability to search through accounts to see if there is a better match, as shown below:

Similarly, you can use the "Find Contact" screen, as shown below, to determine if there are any existing contacts that match the lead being converted.

Once you are happy with the account/contact mapping options, you can click next to begin the conversion process. If the list to be converted is large, the matching may be split over multiple screens with a subset of leads listed on each page. The conversion will not begin until you have mapped thru all of the leads. If you back out of or stop the process prior to confirming all of the conversion options, the conversion can be resumed later, and you will only have to confirm the matching of leads that were not previously matched.

You can use this feature to capture leads from your corporate website or any external website. The system will generate an HTML form to capture lead information that you can paste into any web page.

This option is available in the "Generate form to capture leads from your website" link from the Lead Home page, as shown below:

The first step is to choose the fields that you would like to include in the form. This is done from the page shown below:

You can add and remove rows using the "X" and "+" buttons at the right of each row. You can also enter the pages in you website that you would like the system to redirect the user to after submission of the generated form. You can specify different pages based on whether the lead is loaded successfully or not. When you hit the "Generate HTML" button, you will be taken to the generated form page, as shown below:

You should copy the generated HTML from this page and paste it into your external web page. You can modify the look and feel of the form to meet your corporate standards, but you should be careful not to remove any of the generated form elements.

Mail merge is the process of integrating data from SourceTap CRM with document templates. This is typically done for form letters and email campaigns. You can use external tools, such as Microsoft Office, to handle mail merge or use the built in email merge capabilites.

The simplest way to use mail merge is to create a report and export it to CSV format. Then you can use Microsoft Word or any other tool with document merge capabilities to create a merge document. You can also use Microsoft Outlook to handle email merge. See the documentation for your word processing application for more information on merging documents with data.

SourceTap CRM has built-in email merge functionality. To access it, choose the "Email Lists" option from the main menu. This will give you the email list page, as shown below:

The top portion of the screen allows you to create an email template or choose an existing template. For existing templates, you can choose to Edit, Duplicate, or Delete them. Duplicate allows you to create a new template based off of an existing template. The bottom portion of the screen allows you to choose a list of people to send the email to. This list should be either a list of Leads or a list of Contacts. For more information on lists, see Working with Lists. You can also choose to override the "To" address in the template to a static address, which is useful for testing purposes. Before sending any mass mailings out, it is recommended that you test the template on a small list and that you fill in your email address in the "Override" field. Once the template has been sent to you successfully, you can then resend it to the the correct recipients by clearing the "Override" field.

The template editor is shown below:

Email templates can be in plain text or HTML. The "To", "CC", "BCC", "Subject", and "Body" fields can contain static text and field tags that are filled in from the database at run time. The field tags can be filled in from any field in the Lead or Contact information. You should make sure that the fields tags that you enter on the template match the type of list you are sending the email too. For example, if you use information from Leads in the template but send the email to a list of Contacts, you will not get the desired result.

To simplify the creation of templates, the template editor has a list of available fields lists on the right side of the screen. You can switch the template type to Contact or Lead to get the list of fields available for that type. By clicking on an item in the "Available Fields" select list, you will see the correct template tag to be used in the "Field Value" field. You can then copy and past the value from the "Field Value" field to the desired field on the template.

In order to use the email merge feature, you need to set the outgoing mail (SMTP) server to be used for sending emails. This is set in the general.properties file which is located in the components/common/config directory. You should verify the settings of the following parameters in this file:

• mail.smtp.relay.host - the internet address (host name or IP address) of your outgoing (SMTP) mail server
• mail.smtp.auth.user - if your email server requires authentication, this should be the userid required to log into the mail server
• mail.smtp.auth.password - if your email server requires authentication, this should be the password required to log into the mail server

Lists are used to identify a subset of data for further processing. Lists can be created by saving the results of a query or by choosing to add imported data to a list. Currently, you can preform the following actions on lists:

• Mass Lead Conversion - see Lead Conversion for more information.
• Mail Merge - see Mail Merge for more information