Customer Importer: Extending the File Importer

This example describes how you can simply extend the FileImporter with custom code, allowing you to import order, product, contact, and payment information into iMIS.

Another option is to completely replace the FileImporter instead of extending it. For more information, see Custom importer – Replacing the File Importer.

The following example is meant to demonstrate that creating a custom import file format is achievable, but the example might not be completely compatible with your iMIS version. The code example used in this tutorial can be found in a GitHub repository. To follow along, download the appropriate file, and open it in Visual Studio.

To work with the File Importer, you will need to create a class to plug in to the existing code:

Decide on a file format that you want to support (for example, comma-delimited or XML).

Write a class that implements the appropriate interface for what you are importing (for example, IImportedDataContractBuilder or ICommerceDataContractBuilder), and write code to work with that format (the example project implements ICommerceDataContractBuilder since it is for importing commerce transactions).

Register your class as a SOA data contract builder (make an entry in the web.config file, similar to how you would register your own custom contract assemblies and persistence for SOA).

Use the File Importer.

After you have done all of this, you can use your class with the File Importer.

Example: Extending the File Importer

This example supports importing new items (products) along with orders using a comma-delimited syntax. The first word on each line tells us what we are importing. For products, we can then supply the code, name, description, type, prices, accounting treatment, and tax category. For example:

Product, P1, P1 Name, Description of P1, SALES_PUB, 42.00, 37.00, Accrual, Non-Taxable

Orders will have two types of rows:

Order row
One or more OrderLine rows

For the order row, our file can provide an optional iMIS ID for an existing contact, or some information about the contact if it is a new one. For example:

Order, , Murphy, Brian, [email protected], 5125551212, , 10 Main St, , Austin, TX, 78704

For the OrderLine rows, we can supply the product, quantity, and price. For example:

OrderLine, P1, 1, 42.00

ICommerceDataContractBuilder (which derives from IImportedDataContractBuilder) defines a single method (CreateImportCollection) that you need to implement, as well as some properties.

Your code will be called when the user uploads a file, and your code uses that file to create a collection of data contracts to return. You can do this however you like. You also need to support a handful of properties related to displaying errors in the FileImporter, and providing a friendly name for your class to display in a drop-down list.

Our class, called SampleOrderImporter, implements ICommerceDataContractBuilder and adds only a single property, an instance of CommerceSettings. That property is set for you before your code is called, and you can use it to get information like price sheet IDs and default currency.

The code in the ProcessOrderImportRow method for creating an order does each of the following:

Creates a new PersonData contract using the iMIS ID in the row or, if an iMIS ID is not supplied, from the contact details supplied in the row.

If you are creating a new contact, you will want to assign an identifier to the CustomerPartyData.OriginatorCustomerId field. This example displays a random GUID, but you might use some other unique value that means a little more in your context. If you do not assign something to this field, you might see duplicate contacts created when the SOA server processes the BillToCustomerParty, SoldToCustomerParty, and delivery options.

Creates a DeliveryData containing the shipping method and address for the SoldToCustomerParty.

In the example project, we do not provide for having the order delivered to a different contact, but you could certainly support that using additional details in your import file format.

Creates the OrderData.

The code in the CreateNewParty method for creating a new contact when an iMIS ID is not supplied does each of the following:

Creates a PersonData using the contact details supplied.
Creates an AddressData using the contact details supplied.

Adding an item isn’t too complex, although you must be aware that the standard and discount prices are created separately. So the code in the ProcessProductImportRow method will add three data contracts to the collection in order to add one item: the item itself, a standard price, and a discount price. This method does the following:

Creates a new ProductItemData object.
Creates two new ItemPriceData objects:
- One for the standard price (notice that this object uses the CommerceSettings to obtain the DefaultPriceSheetId)
- One for the discount price (notice that this object uses the CommerceSettings to obtain the DefaultDiscountPriceSheetId)

The FinishComboOrder method performs the final step in this example by creating a RemittanceData object containing payment information. This method does the following:

Calculates the total of all OrderLines to determine the amount of the payment
Creates a RemittanceDataCollection and adds one RemittanceData object using the default currency, the payment method of Cash, and the BillToCustomerParty as the Payer
Adds the ComboOrder to the collection of contracts that will be returned

The CreateImportCollection method returns the collection of contracts to the caller. The File Import content item takes care of the rest.

Remember, registering your class involves updating the web.config file. The section already exists because it is used for other importers. You just need to add your type in that section. The ReadMe.txt file in the example project includes an example of the line to be added.
Once completed, if you look at the File Importer content item, you should see that the custom Order import format has been added to the drop-down of available formats.
A user can select a file, upload it, and if successful, process the import batch to add items, parties, and orders to the database.