Upgrading to xTuple ERP 3.8.0
UPDATE: Version 3.8.0 is now final. We're highlighting this blog from earlier in the release cycle to help people navigate the upgrade process. If you would like for xTuple to manage your upgrades for you (any Edition of the software, including PostBooks), consider our XTN offering!
Before you upgrade to xTuple EPR 3.8.0, there are a few things you should know:
- This release expands the use of CRM Accounts to include Employees, Sales Reps, and system Users.
- There is a new CRM Account Merge utility.
- There is an extension package to help you clean up data that would otherwise cause problems during upgrades from 3.7.x to 3.8.0.
The rest of this page describes the extension package and how to use it before you upgrade to 3.8.0. Don't worry too much, though, as most people shouldn't have any trouble.
As usual, a few words of caution: We've done our best to make the pre380 extension useful and bug-free. We even used it on our own internal production database. However, you should back up your database before you use this extension and try it in a copy of your database first.
Before upgrading to xTuple ERP 3.8.0, download the pre380 (see below) extension package from SourceForge and install it in your 3.7.x database with the Updater. This package adds a new item to the System > Utilities menu called "Fix 3.8.0 Upgrade Issues..." When you select this menu item, a new window will open with 5 tabs:
Each tab is described below.
This tab briefly describes how to use this window. Here is a little more information to help you use this window effectively:
xTuple ERP 3.8.0 has expanded the use of CRM Accounts to include Employees, Sales Reps, and Users, as well as the previously-supported Customers, Prospects, Tax Authorities, and Vendors. The upgrade script creates new CRM Accounts for every Employee, Sales Rep, and User. As a result, Employee codes, Sales Rep numbers, and Users' usernames that overlap with existing CRM Account numbers will cause problems when upgrading from 3.7.x to 3.8.0, including 3.8.0Beta. The number of databases affected should be small.
Your goal should be to allow the Upgrade to complete. While cleaning the data, you may find CRM Accounts that should be combined together or Sales Reps (or Employees or Users) that really belong to existing CRM Accounts. Use this window to fix the data so you can get to version 3.8, then finish the job with the new CRM Account Merge utility.2
There are three different kinds of problem that may exist with CRM Accounts:
- There may be more than one account with the same CRM Account Number.
- There may be CRM Accounts with an illegal Type.
- The Owner field of an account may not be a defined User.
If there are duplicate CRM Account Numbers, select one of the items from the list and either Edit it or Delete it. The simplest thing you can do to resolve this problem is Edit one of the duplicate accounts and change its CRM Account Number. If you realize that the two CRM Accounts actually represent the same company or person, add an indicator to the CRM Account Number now (for example, add a suffix to the number like "_DUP" or "_MERGEME"). Then use the CRM Account Merge utility after you upgrade. By keeping the names similar, they should be easy to find in the CRM Account Merge list.
If you are sure that only one of the duplicate CRM Accounts is needed, delete the non-essential one. You may need to edit it first to detach contacts or remove the associated Customer, Vendor, etc. If you cannot delete the record or find that the two (or more) CRM Accounts really should be distinct, change the CRM Account number of one of them.
If a CRM Account is shown as having an Invalid CRM Account Type, edit the CRM Account, check that Organization or Individual is checked appropriately, and Save it. You must save the CRM Account to clear this error.
CRM Accounts with Invalid Owners have values in their Owner field that don't represent system Users. Edit the record and either clear the Owner field or change it to a valid User. Alternatively, you can create all of the Users that don't exist.
Old CRM Relationships
This is the most complicated tab in this pre-Upgrade screen. It detects and lets you fix four different kinds of problem:
- Customers, Prospects, Tax Authorities, and Vendors associated with multiple CRM Accounts.
- Customers, Prospects, Tax Authorities, and Vendors with different Numbers than their associated CRM Accounts.
- Customers, Prospects, Tax Authorities, and Vendors that have been orphaned - they have no CRM Accounts.
- Prospects with duplicate Prospect Numbers.
Select a record from the list and click one of the buttons on the right to address the problem.
Here are some examples:
If a Prospect is associated with two CRM Accounts, pick the Prospect from the list on the left. Pick one of the CRM Accounts from the combo box next to the "Detach from" button, then click the "Detach from" button.
If a Customer has a different number than its associated CRM Account, select it from the list on the left. Click the "CRM Account #" radio button if you want the Customer to get the CRM Account's number; click "Record #" if the CRM Account to get the Customer's number. Then click the "Use" button to save the change.
If a Tax Authority has no CRM Account, you can create a new CRM Account for it. Just select the Tax Authority and click the "Create CRM Account" button. The new CRM Account will have the same number and name as the Tax Authority.
Pending CRM Relationships
The list on this tab shows Employee codes, Sales Rep numbers, and Users' usernames that will conflict with existing CRM Accounts during the upgrade. If you have to use this utility at all, this tab is probably where you'll have the most work to do.
We recommend that for Employees and Sales Reps, you click the "Edit" button and change the Employee code or Sales Rep number. If these Employees and Sales Reps should be associated with existing CRM Accounts, add a suffix like "_E" or "_S" or "_MERGEME" for now. After the upgrade, you can use the CRM Account Merge to combine the two.
For example, you might have a Vendor 'GIL' in your database so you can write checks to your Employee 'GIL' (thank you!). The Vendor is associated with a CRM Account, also with the number 'GIL'. Before the upgrade, change the Employee's code to 'GIL_MERGEME'. This will resolve the pre-upgrade conflict. After the upgrade is complete, merge the 'GIL_MERGEME' account (associated with the Employee) into the 'GIL' account, resulting in a single CRM Account that is both an Employee and a Vendor.
This works OK for Employees and Sales Reps but does not work for Users. Why not? Because Users are defined at the database server level. In this case you'll have to change the number of the pre-existing CRM Account (click "Edit CRM Account") and then later merge the pre-existing CRM Account into the new account created by the upgrade for the User.
The final category of problem handled by this window is bad cross-references. 3.8.0 adds a handful of foreign key constraints to the database that were previously handled by the desktop application. Any improper cross-references that may have crept into the data need to be fixed before the upgrade can run.
There should only be a handful of these records and they're easy to handle. The "Record" column in the table shows what kind of record needs to be updated while the "Target" column shows which field in that record needs to be fixed. Select the row in the table and click the Edit button to get the regular editing window. Alternatively, select from a list and click "Set Target" if you don't need the full context to make your decision or click the Clear button to make the target field empty.
1A note to Safari users: Apple's Safari web browser sometimes uncompresses downloaded .gz files. You may need to recompress Downloads/pre380 with the gzip program before you can open it with the Updater.
2 The CRM Account Merge utility in the 3.8.0Beta release is a work-in-progress. It lets you combine the data from two or more CRM Accounts. This is great if somehow you have separate CRM Accounts for the same organization or person, one of which is a Customer and the other a Vendor. The biggest limitation in the 3.8.0Beta release is that it does not yet merge Customers together (perhaps one person placed different web orders with different email addresses, so you now have two Customer records for the same real-world person). The same is true of multiple Vendors - the Beta release doesn't merge them.
Sun, 10/02/2011 - 23:10#1
Anybody can't modify the CRM
Anybody can't modify the CRM module when run this operation, can they?
Mon, 10/03/2011 - 07:49#2
Actually, you can
The risks of using this extension while other people are working are the same as if you were doing the same tasks with the pure PostBooks application. The only real difference is that this extension focuses your effort on those data that will be a problem during the upgrade to 3.8.
There are no locks built in to the extension to prevent other users from doing their work. The worst consequences I can think of are that you might have to redo a couple of fixes that were undone by someone else editing the same CRM Account at the same time and some of your users might be confused if a Vendor, Customer, or CRM Account number changes.
The real problem with this extension is the potential confusion for end-users caused by the temporary duplicate CRM Accounts (see the Pending CRM Relationships section). We expect them to be rare. However, if you do need them, keep the time between creating them, upgrading to 3.8.0, and merging them as short as possible.
Fri, 10/07/2011 - 11:07#3
3.8.0 estimated release-date?
Any thoughts as to when the 3.8.0 full release will be available? Thanks!
Sat, 10/08/2011 - 06:41#4
The final 3.8 release is at least a month out. Look for it in November.
Fri, 10/07/2011 - 17:23#5
Thanks. Any idea when 3.7.4 will be available?
Sat, 10/08/2011 - 06:36#6
Look for 3.7.4 to be released next week.
Thu, 10/20/2011 - 10:35#7
Is it true that xTuple release 3.8.x will require Postgres 9.0.x.?
Tue, 10/25/2011 - 04:03#9
I install binary version for windows 3.7.4. I can use with no problems.
I just compiled and build 3.8 in Visual Studio 2008 OS Win2003 (using command: qmake, nmake).
when logging in with 3.8 and using PostGres of the binary version (update database upto 3.8), I get the error "A connection could not be established with the specified Database as the Proper Database Drivers have not been installed. Contact your systems administrator".
Help me to solve this problem.
Fri, 12/30/2011 - 13:15#10
Beta database upgrades...
Is there a way to reliably upgrade a database from 3.8Beta to 3.8RC2?
Fri, 12/30/2011 - 13:27#11
Re: Beta database upgrades...
You can upgrade a PostBooks 3.8.0Beta database to 3.8.0RC2 by downloading and installing the upgrade packages pb380betato380beta2.gz, then pb380beta2to380rc.gz, then pb380rcto380rc2.gz in that order. They are all available from SourceForge in subfolders of PostBooks-databases.
If you have Standard or Manufacturing edition, you can do the same thing, but with both the Standard Edition upgrade packages and xtmfg upgrade packages from xtuple.org's commercial downloads section.
As always, make a backup of your database just to be safe before upgrading.
Fri, 12/30/2011 - 15:44#12
Mon, 01/09/2012 - 02:44#13
ERP 3.8 installer
When will the 3.8 installer be available?
Mon, 01/09/2012 - 07:56#14
Thu, 02/09/2012 - 14:59#15
Is there any way to get a list of table changes that were made? We seem to have lost the totals on our sales invoices, after the upgrade and I am wondering if it has anything to do with table changes?
Tue, 05/15/2012 - 02:41#16
Did you find a solution?
After upgrading to 3.8.0 "Postbooks" all the tax and totals disappeared of our invoices. They work on the default report but not the custom report. Did you manage to fix this?
Tue, 05/15/2012 - 06:03#17
If you customize the stock
If you customize the stock reports, and you see strange behavior after an upgrade, you'll need to compare the grade 0 stock report and your custom one to identify the problem. That's why we always recommend saving custom reports as a higher grade number (besides just basic version control).
Tue, 05/15/2012 - 16:42#18
Custom Stock reports
The customisation I did to the forms did not add any further fields and I did save as a grade other than 0. I can use the grade 0 one and it works but has an ugly layout. All the fields look to be the same. I could recreate the custom form but was hoping to find out what changed to the Invoice form that would have caused this as customisation is time consuming... especially if you have to do it every time there is an upgrade.
Thu, 02/09/2012 - 16:26#21
Got it from Pierce
"We publish a document which details report definition changes from one version to the next. You can find the most recent example of that here:"
Using this I was able to fix the problem.