Yahoo Store Integration

 

Getting Started with Yahoo! Store

This page provides an overview of the steps required to integrate xTuple ERP with a Yahoo! Store using xTuple ERP's XML import facility. You can download the xTuple Yahoo Store integration files from the xChange.

The summary gives a short, undetailed description of what you need to do to successfully import a sample order that xTuple has generated. The summary is followed by a more detailed explanation of the steps involved and how to avoid some of the potential pitfalls. Note that importing Yahoo! Store orders requires an XSLT processor, which is not part of xTuple ERP.

The supplied Yahoo store XSLT file and these implementation instructions demonstrate the basic features of xTuple XML integration. These provide an example for a typical Yahoo! Store and xTuple configuration.  Your eCommerce configuration and local environment will vary, so you may need help from your system or network administrator, xTuple VAR, or xTuple's consulting services to get this running.

 

What is XSLT And Why Do I Care?

XSLT is "a language for transforming XML documents into other XML documents." [ http://www.w3.org/TR/xslt ]

Yahoo! Stores can create XML files that represent orders placed through a web site. xTuple ERP can import XML files that conform to the xTuple import API.  xTuple has written an XSLT stylesheet that transforms a Yahoo! Store XML file into an xTuple ERP import API XML file.

To use this XSLT stylesheet you need an XSLT processor, which is a program that reads an XML file and an XSLT stylesheet and produces another XML file as output.

 

Installation Summary:

  1. Install xTuple ERP and an xTuple database.
  2. Download and unzip the yahoo.zip file from the PostBooks download page on SourceForge.
  3. Make sure you have a XSLT processor installed on your machine. You can download binaries of the Xalan XSLT processor from the PostBooks download page on SourceForge.
  4. Log in to your xTuple database with the xTuple ERP application.
  5. Go to System > Configure Modules > Sales and change Sales Order# Generation to either "Automatic, Allow Override" or "Manual".
  6. Go to System > Master Information > Configure Data Import and Export
  7. On the XSLT Mapping tab from the field for your operating system, browse to the directory where you unzipped the yahoo.zip file, click (once!) on the "yahoo" directory, then click the Choose button.
  8. On the XSLT Processor tab, enter the command to run an XSLT processor to transform the Yahoo! XML file into one that xTuple ERP can read directly.  Enter the command here as you would on a command line but put %f where your XSLT processor expects the name of the Yahoo! XML file and %x where your XSLT processor expects the name of the XSLT stylesheet. If you don't have a tax authority named "Yahoo" then you need to look at your data, find a reasonable default tax authority, and pass this value to the stylesheet parameter customer_default_tax_authority.
  9. Set the value of Default Import File Directories for your operating system to the "inbox" folder that was created by unzipping yahoo.zip.  As in step 7, click (once!) on the "inbox" directory, then click the Choose button.
  10. Choose what you want xTuple ERP to do with successfully imported XML files.
  11. Click Save
  12. Go to System > System Utilities > Import XML
  13. You should see the sample order file listed. Click "Process All"

Congratulations!  You have imported your first Yahoo order.

Look in your Customer and Sales Order windows.  You should see a new customer with the number 'MDA' and a corresponding Sales Order for him.
 

Installation Details:

  1. Install xTuple ERP and an xTuple database.

    If you are trying xTuple ERP for the first time then install the demo database.  You can download both from the PostBooks project page on SourceForge.

    If you already have xTuple ERP installed and running, make a backup copy of your database and test with that. The XML import and Yahoo! Store integration were introduced in xTuple ERP version 2.3.0, so you might have to upgrade your test database and get a new version of the xTuple ERP application.
     
  2. Download and unzip the yahoo.zip file from the PostBooks download page on SourceForge.

    If you want to allow multiple people to import files then you must choose whether to install the files on each person's computer or put them in a shared network directory. In either case, the files must be installed so the path to the files is exactly the same on all computers using the same operating system.

    For example, if you have a network of Macintosh computers, you could unzip the yahoo.zip file on a networked filesystem that is mounted as /Volumes/xTuple on all of the Macs that have permission to mount that filesystem.

    On Windows you will have to be careful about drive letters - make sure that the network share is always mounted with the same drive letter by all Windows client workstations.

    Avoid spaces embedded in the path to these files. If there are any spaces, xTuple ERP will not find the files.
     
  3. Make sure you have an XSLT processor installed on your machine. You can download binaries of the Xalan XSLT processor from the PostBooks download page on SourceForge.

    The Yahoo! Store stylesheet has been tested with the Xalan, Saxon, and xsltproc XSLT processors. If you already have one of these installed then you should not install another. Many Macs have xsltproc installed with the operating system.

    If you do need an XSLT processor, you can install any of those mentioned above. xTuple has put .zip files of Xalan on the PostBooks download page on SourceForge for Linux, Mac OSX, and Windows. See http://xml.apache.org/xalan-c/ for more information about Xalan.

    As in step 2, you have a choice whether to install the XSLT processor on each individual workstation that needs it or on a shared network filesystem.  Also as in step 2, the path to the XSLT processor file(s) must be exactly the same on all computers using the same operating system. Also as in step 2, make sure there are no spaces embedded in the path to the XSLT processor.

    If you are running Linux or Mac OSX and you choose to download and unzip the Xalan binaries from SourceForge, be aware that there are special system adminstration considerations if you choose to install Xalan in /lib or /usr/lib. You may have to modify permissions or system files to allow the use of these shared libraries. On Mac OSX, you might also have to modify the paths to the shared libraries inside the binary files themselves with install_name_tool.

    For Macintosh users, place the Xalan files in the /usr/lib folder. On the Mac, the lower-level folders are hidden by default; you won't see these in the Finder unless you make a modification. This site will help you with the Finder issue: http://www.macworld.com/article/51830/2006/07/showallfinder.html
     
  4. Log in to your xTuple database with the xTuple ERP application.
     
  5. Go to System > Configure Modules > Sales and change Sales Order# Generation to either "Automatic, Allow Override" or "Manual".

    The Yahoo! Store assigns sales order numbers to each sales order and places these in the XML files that it creates.  To ensure that xTuple ERP can import these orders, make sure that xTuple ERP is set to allow users to enter order numbers manually or override the system-generated value.

    If you choose "Automatic, Allow Override", find out from Yahoo! what the next order number generated by your Yahoo! Store will be and set the Next # for Sales Orders in xTuple ERP to something very different to avoid overlap. If the sales order numbers generated by Yahoo! conflict with sales orders already entered in xTuple ERP then the import will fail.
     
  6. Go to System > Master Information > Configure Data Import and Export
     
  7. On the XSLT Mapping tab from the field for your operating system, browse to the directory where you unzipped the yahoo.zip file, click (once!) on the "yahoo" directory, then click the Choose button.

    The Default XSLT File Directories are the places in which the Yahoo! Store import process will look for the yahoo_to_xtupleapi.xsl stylesheet on different operating systems. This stylesheet holds the instructions for converting a Yahoo! order file to one acceptable to xTuple ERP. This must be the directory containing the stylesheet and not the stylesheet itself. The mechanism that imports Yahoo! Store orders is also used to import XML files generated by other software to populate other tables in the xTuple ERP database and this parameter tells xTuple ERP where to look for all of these stylesheets, not just the one for Yahoo! Stores.

    As in steps 2 and 3, the path to this directory must be exactly the same on all computers using the same operating system, even if it is on a network filesystem, and there cannot be any spaces embedded in the path to this directory.
     
  8. On the XSLT Processor tab, enter the command to run an XSLT processor to transform the Yahoo! XML file into one that xTuple ERP can read directly.  Enter the command here as you would on a command line but put %f where your XSLT processor expects the name of the Yahoo! XML file and %x where your XSLT processor expects the name of the XSLT stylesheet. If you don't have a tax authority named "Yahoo" then you need to look at your data, find a reasonable default tax authority, and pass this value to the stylesheet parameter customer_default_tax_authority.

    If the directory containing the XSLT processor is listed in your PATH environment variable (and this PATH has been exported on Macs and Linux machines), you can simply type the name of the XSLT processor as the first word of the command. If that directory is not in your PATH, you'll have to enter the full path to the XSLT processor binary.

    Different XSLT processors expect the file to transform and the stylesheet that describes how to do the transformation in different orders. The process by which you get the files to import might create files with different names. That's why the command line for the XSLT Processor lets you use %f - so you don't have to change the command every time you want to import a file with a different name.  The %x is there because XML files generated by different programs need different stylesheets to transform them (see 7 above).

    xTuple ERP requires three pieces of information not provided by Yahoo!  Store orders which cannot be derived from other data in either the Yahoo! file or the xTuple ERP database:
    • the default tax authority for new customers,
    • whether you want to store the Yahoo! ship-to address or billing address in the correspondence contact information of new xTuple customer records, and
    • how far off in the future you want to set the scheduled date for shipping sales order line items


    The stylesheet has coded within it the following defaults which you can override using stylesheet parameters:

    • setting "YAHOO" as the default tax authority for new customers,
    • using the billing address as the correspondence contact for the customer, making the assumption that if the billing address and ship-to address are different then this is a gift order, and
    • scheduling shipping the day after the import is run, assuming that orders are to be filled the day after they have been entered into xTuple ERP.


    Warning about importing Yahoo! Store orders into the demo database:
    The demo database does not have a tax authority named "YAHOO" but the stylesheet xTuple provides assumes that one exists. Either create a tax authority named "YAHOO" or override this default by passing a value for the "customer_default_tax_authority" stylesheet parameter on the command line. Each XSLT processor has its own rules for setting stylesheet parameter values, so consult the documentation for your XSLT processor.

    Another warning:
    xTuple ERP does not currently recognize spaces embedded in stylesheet parameter values. You cannot assign a value to "customer_default_tax_authority" that has a space in it. Therefore, check your tax authorities and remove spaces from the tax authority codes (e.g. change "VA TAX" to "VATAX").

    Here is an example for using the PostBooks demo database on Windows with Xalan installed in C:\xalan after making the change to the tax authority described in the previous paragraph:

         C:\xalan\xalan.exe -p customer_default_tax_authority VATAX %f %x

    Note:

    • "-p customer_default_tax_authority VATAX" - this tells Xalan to set the value of the customer_default_tax_authority to VATAX.
    • "%f %x" - this passes the name of the Yahoo! Store order file followed by the name of the stylesheet.


    Here is another example, this time using the xsltproc pre-installed on a Mac as part of the operating system, again using the demo database with the change to the tax authority described above:

         xsltproc -stringparam customer_default_tax_authority VATAX %x %f

    Note:

    • the use of "-stringparam" instead of xalan's "-p".
    • "%x %f" instead of "%x %f", since xalan and xsltproc take the file names in opposite order.

  9. Set the value of Default Import File Directories for your operating system to the "inbox" folder that was created by unzipping yahoo.zip.  As in step 7, click (once!) on the "inbox" directory, then click the Choose button.

    This is the directory xTuple ERP will check for new XML files every time you open the Import XML window or when the Import XML window automatically updates itself.
  10. Choose what you want xTuple ERP to do with successfully importe XML files.

    xTuple ERP gives you four options for what to do with XML files after they have been successfully imported:
    • a) Do nothing, in which case the files stay where they are, continue to appear in your list of files to import, and might be overwritten by future import files or imported a second time.
    • b) Append the suffix of your choice to the files, like ".done".
    • c) Delete the files, in which case the files are removed from the system forever (not moved to the Mac's Trash or Windows' Recycle Bin).
    • d) Move the files to another directory, which you name.


    xTuple suggests that you use option (d).  Under XML File Handling Options select "Move after successful import to:" and type in "processed" or "done". This will create a subdirectory in the platform-specific Default Import File Directory.  After a successful import the .xml file will be moved into this subdirectory.  If you type a full path (one starting with a "/" on Linux or Mac OSX or a drive letter, colon, and backslash on Windows, e.g. "D:\xtuple\yahoo") then the files will be moved to this other directory rather than to a subdirectory under the import file directory.

    xTuple ERP will slightly modify the file name when it moves a successful import if there is a conflict with an existing file. This is true whether you have configured it to add a suffix or move the file to another directory. For example, if you have the application configured to move successfully imported files to the directory "done" and you import a second file named "order.xml", the second file will be moved to the done directory and the name will have a datestamp added.

  11. Click Save
  12. Go to System > System Utilities > Import XML
  13. You should see the sample order file listed. Click "Process All".

Look in your Customer and Sales Order windows.  You should see a new customer with the number 'MDA' and a corresponding Sales Order for him.

 

mead