Boru Import User Guide

About

• This module was created with the idea of a faster and more efficient import utility for Vtiger. The standard VTiger import utility, as you may have already noticed, takes a long time to import large numbers of records and sometimes fails on imports with more than 200 records.
• The BoruImport Module does not hook into the standard VTiger libraries to process records; it uses direct database connections instead.
• At this time this module will not trigger any Event Handlers that may be present in Vtiger. This feature will be present in a future releases.

Using the Import GUI

Selecting a File

• Input a file in the designated input
• Has Header Row? If the first row in the CSV file is a header row, make sure this box is checked. This will force the GUI to use this row to try and pre-map fields, and skip this record when running the import.
• Select a module from the dropdown
• Press Map File

Mapping Fields

• This screen will present you with two tables. One for Dupe/Merge settings, and the other for field mapping with a preview.
• If your file had a header row, the GUI will try to pre-map fields based on the column name. Review the column labeled ‘Mapping’ and ensure all fields are mapped to your desire.

Dupe Checking

Dupe checking is run on import if you check ‘Check for Dupes’

• Any field in the Mapping Table that is checked will be used for identifying dupes. These are treated with ‘AND’ logic. If you have multiple fields selected, a record must have all selected fields identical to be considered a dupe.

Dupe Checking Options

• Update existing record with import record (only mapped fields will update)
  • This will import all records from your input file.
  • Any record that is considered a ‘dupe’ will have their fields updated to match those in the import file.
• Ignore the import record
  • This will skip any record that is considered a ‘dupe’.
• Replace one existing record with imported record.
  • This will import all records from your input file.
  • Any record that is considered a ‘dupe’ will have one record already in your database deleted, and this record will import.
• Delete all matching records and import records
  • This will import all records from your input file.
  • Any record that is considered a ‘dupe’ will have all matching records in your database deleted, and this record will import.
• Delete all matching records and skip import records that have no matches.
  • This is used for ‘purging’ records from your database.
  • No records will be imported. Instead, they will be used to identify records to remove from the database.

Setting Up a Password

• For your vtiger data security, the BoruImport Module API Wrappers for HTTP Post and SOAP Services are protected with a password.
• This will prevent unauthorized people or programs from modifying your vtiger data.
• The module comes with a blank password set which DISABLES the Post and SOAP API.
• This password can be adjusted in the Settings page of your module.

Post Wrapper

• To enable the POST endpoint, you must set a password.

EndPoint

• Your HTTP Post endpoint can be found in the Settings section of this module
• http://path/to/your/vtiger/modules/BoruImport/post.php

Required Fields

• apipassword
• apimethod
• apimodule

Special Fields

• assigned_user_id — Can be a vtiger user ID or a vtiger user name.
• _redirect_url — url to redirect the browser to after successful post. No data is passed to this redirected URL.

Methods

create

• Used to create a record. Accepts a POST or GET string in the format off &field=value.

update

• Used to update a record. Accepts a POST or GET string in the format off &field=value.
• Requires recordid to be passed in as a field.

get

• Used to retrieve a record. Accepts a POST or GET string in the format off &field=value
• Requires recordid to be passed in as a field.
• Exmple:

http://path/to/your/vtiger/modules/BoruImport/post.php?apimethod=update&apimodule=Contacts&recordid=123

Soap Wrapper

• To enable the SOAP endpoint, you must set a password.

EndPoint

• Your SOAP Service endpoint can be found in the Settings section of this module
• http://path/to/your/vtiger/modules/BoruImport/soap.php

Required Fields

• apipassword

Methods

createRecord

• note: assigned_user can be either a userid, user_name or blank for default (admin)
• input – expected XML in the following format:

• output – CDATA’d XML (Will have < > etc tags)

updateRecord

• note: assigned_user can be either a userid, user_name or blank for default (admin)
• input – expected XML in the following format:

• output – CDATA’d XML (Will have < > etc tags)
  • Error: <result>MESSAGE</result>
  • Success: recordid

getRecord

• input – expected XML in the following format:

• output – CDATA’d XML (Will have &lt; &gt; etc tags)
  • Error: <result>MESSAGE</result>
  • Success: XML with record block containing all record fields.

exportRecords

• input – expected XML in the following format:

• Query can be used to grab specific records instead of all records:

• output – CDATA’d XML (Will have &lt; &gt; etc tags)
  • Error: <result>MESSAGE</result>
  • Success: XML with record block containing all record fields.

Record Block

• A record block a comprised of field records that contain label and value tags. For how to get available fields

Direct PHP Access

• Documentation not yet public.

Available Fields

• Any field label or column name from inside the module entity.
• Tip: You can get a list of Fields that are available for the module you’re importing to by opening up phpmyadmin or a similar MySQL GUI Interface, and running the following query:
  • select columnname,fieldlabel from vtiger_field where tabid=((TABID))
• As a quick reference, Tabids are as follows:
  • For Accounts: 6
  • For Contacts: 4
  • For Invoice: 23
  • For Leads: 7
  • For Potentials: 2
  • For Products: 14
  • For Quotes: 20
  • For SalesOrder: 22
• Example query:
  • select columnname,fieldlabel from vtiger_field where tabid=4

Line Item Products/Services

• In addition to the fields directly associated with each module, certain modules (e.g., Quotes, Sales Orders, Invoices, etc.) can also have items (either ‘products’ or ‘services’) associated with them, which have field names in the format of lineitem_X_<FIELDNAME>

Line Item Required Fields

• In addition to the fields directly associated with each module, certain modules (e.g., Quotes, Sales Orders, Invoices, etc.) can also have items (either ‘products’ or ‘services’) associated with them, which have field names in the format of lineitem_X_<FIELDNAME>

Line Item Optional Attributes

• The remaining lineitem_X_<FIELDNAME> fields can optionally be used to set the relevant values for each product or service (such as price, quantity, description, comment, etc.). These optional fields correlate to fields in the vtiger_inventoryproductrel relation.

HSV Address Fields

• Address records are created at the same time as standard records (Contacts,Leads,etc)
  prefix any Address field with address_
  example: