Index #

Overview #

eCat's customer file is used to publish customer information to eCat. In addition to a standard set of fields, custom fields can be added to the file to publish as much additional information about customers as needed. The customer file can be uploaded to eCat either by using the file upload tool on the admin web site, or by sending a file named customers.csv via FTP to the ‘/data’ directory on your company’s eCat FTP site.

Customers can be associated with specific users by setting permisisons in your eCat admin console.

The eCat product catalog and other features are fully functional without selecting a customer. However uploading a customer file enables eCat users to quickly select a customer to associate with an order, view the customers sales and product preferences, and more. When a customer is selected, the price level in eCat is automatically set based on the discount code associated with the selected customer and the order details are automatically filled in with the customer information. Depending on user permissions, the default pricing can be overridden at any time. Please refer to the customer file template and notes below for more information.

Download Sample Customer File

Customer File Field Layout #

Fields marked with a 'Y' in the 'Req?' column of the 'customers.csv' specifications must be populated with valid data. Records that are missing entries in required fields will not be imported and will be listed in the file import error report.

Many fields that show a validation description in the file specifications are checked during the import process to verify that they contain valid values. Customer records with fields that do not pass validation may not be imported and warnings or error(s) will be listed in the file import error report.

Both the bill-to and the ship-to address fields must be specified in the first record for each customer, even if the addresses are the same. If a customer has multiple ship-to addresses, these should be listed in the records/rows immediately following the first record for the customer. Bill-to information is optional in the additional ship-to address records.

The fields #

Validating Country Codes #

For companies with many international customers, turning on "Enable country validation?" is an important step to improving the quality of our data import.

When country validation is turned on, the customer import will not validate state and postal code for any country other than the US.

Please note, the BillToCountry and ShipToCountry fields will need to be valid ISO-3166 country codes if this setting is turned on.

Using Territory Codes #

Overview #

Use Territory Codes to relate customers with specific eCat iPad users. (Some companies call these codes 'salesman numbers'.) Assigning territory codes in the customer file and in user account definitions enables eCat admins to control which customers are sent to each user's iPad. User group permissions can be defined for specific types of users in the Admin Console to either send all customers to their iPads or to just send customers that match a territory code assigned to the user.

When an eCat iPad user is associated with a user group set to ‘show only associated' customers’, only customer records with a territory code value matching a territory code associated with the user will be sent to the user's iPad. Customers can be associated with multiple territories/users if desired by listing multiple codes in a territory code field, separated by commas with no spaces. Alternatively, multiple codes can be entered in an eCat user admin console record to associate the user with multiple territories.

'Bill-To' and 'Ship-To' Account Territory codes #

The customer file 'TerritoryCode' field is used to associate users with customers at the bill-to account level. At the ship-to level the 'ShipToTerritoryCodes' field can be used to control which of a specific customer’s ship-to addresses are associated with each eCat user. In both cases this is accomplished by entering a comma separated list of valid territory codes or rep numbers in the appropriate field.

If the ShipToTerritoryCodes field is empty the TerritoryCodes value controls which customers are sent to eCat.

The TerritoryCodes and ShipToTerritoryCodes fields interact as follows.

• If a user's territory code is listed in a customer's (bill-to) 'TerritoryCodes' field, the rep will see the customer record and all ship-to addresses associated with the customer.
• If a user's territory code is listed only in the ShipToTerritoryCodes field of a specific ship to location, the rep will see the customer record and that specific ship-to address.

For example, if a user should see the customer record and all ship to locations, there are two choices

1. Place the user's territory code in the TerritoryCodes field of the first record for the customer, OR
2. Place the user's territory code in each and every ShipToTerritoryCodes field including the first record

However if a user should only be able to view a subset of shipping locations, include the user's territory code in the ShipToTerritoryCodes fields of the desired shipping locations and do not include the user's territory code in the customer record TerritoryCodes field.

Customer Mapping #

Customer mapping is the process of mapping old customer numbers to new ones so that access to old orders, customer lists, and maybe lists doesn’t get lost.

The mapping happens by two mechanisms:

1. A customer mapping file. This is useful when you undergo a big batch customer number migration, which might happen if you roll out a new ERP or merge with another company.
2. Local customer promotion via the customer file MappedBillToCode column. See below for more.

Local Customer Promotion #

Customer records can be created on the iPad, and reps can write orders for them. However, those customer records will eventually become official customers in the your ERP system and then find their way back to us via the customers.csv file.

The process looks like this:

• Rep creates customer on iPad, writes order, submits order.
• Order is exported to you with the StdJsonV2 export format. The local_customer_code field contains the UUID for the local customer. See JSON Order Fields product documentation for more.
• You create customers.csv file, with the MappedBillToCode column populated with the local customer code value.
• eCat syncs and downloads a mapping based on the MappedBillToCode information.

Importing the customer file #

The customer file must be sorted by BillToCode before importing. When there is more than one record for a customer due to multiple ship-to addresses, all customer records with the same BillToCode must adjacent in the file.

The product file upload tool (Tools/Upload Data/Customers) can be used to manually upload your customers.csv file. On the file upload page, click the 'Choose File' button, select the correct file on your computer, then click 'Upload File'. There will be a pause, followed by a confirmation message. After the file is uploaded it may take several minutes for SuperCat's server to check the file and update your eCat database.

The customer file can also be imported by putting it in the '/data' directory of your eCat FTP site. This enables full automation of the file update process.

Error checking #

All data files are checked for errors before they are used to update eCat. After importing a file, check the 'File Import Status' report under Tools/Admin Reports. If errors are discovered in the file, the import date/time stamp will display as a blue link. Click the link to view a list of problems showing the line number and a description of the problem for easy troubleshooting.

There are two types of problem reports, 'errors' and 'warnings'. Errors are problems that could cause eCat to be unreliable or inaccurate. Records with errors are not updated in eCat. Warnings are less serious problems, like fields that are too long. All problems listed in the error report should be corrected.

In order to ensure eCat's reliability, no data will be imported if there is a serious ('fatal') error in the file.

Note: If there are 'errors' during the file import, previously imported records that are no longer included in the new import file will not be removed from your eCat data. Obsolete records are removed only when the file import is error free.