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.

Introduction

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 Merge Limits

CRM Accounts

There are three different kinds of problem that may exist with CRM Accounts:

1. There may be more than one account with the same CRM Account Number.
2. There may be CRM Accounts with an illegal Type.
3. 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:

1. Customers, Prospects, Tax Authorities, and Vendors associated with multiple CRM Accounts.
2. Customers, Prospects, Tax Authorities, and Vendors with different Numbers than their associated CRM Accounts.
3. Customers, Prospects, Tax Authorities, and Vendors that have been orphaned - they have no CRM Accounts.
4. 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.

Bad References

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.

1 — A 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.