SugarCRM ODBC driver

The SugarCRM ODBC driver enables you to work with SugarCRM data outside of the SugarCRM web interface. The driver allows you to use SugarCRM data in any application that supports ODBC. For example:

• Access
• Excel
• SQL Server
• Oracle
• Perl

You can query SugarCRM as well as adding and updating SugarCRM records.

Installing the SugarCRM ODBC driver

1. Install and license the SugarCRM ODBC driver on the machine where your client application is installed.

   For example, if you want to work with SugarCRM data in Excel, install the SugarCRM ODBC driver on the machine where Excel is installed.

   To do this, execute the file distribution that you obtained in the previous step, and follow the on screen instructions.

   The install program starts the Easysoft License Manager, because you cannot use your Easysoft product until a license is obtained.

   The following types of license are available:

   • Free time-limited trial license, which gives you free and unrestricted use of the product for a limited period (usually 14 days).
   • Full license if you have purchased the product. On purchasing the product, you are given an authorization code, which you use to obtain a license.
2. In Easysoft License Manager, enter your details.

   Complete the Name, E-Mail Address, and Company fields.

   The E-Mail Address must be the same as the address used to register and download from the Easysoft web site or you will be unable to obtain trial licenses.

3. Choose Request License.

   You're asked for a license type.

4. Do one of the following:
   • For a trial license, choose Time Limited Trial and then choose Next.

     The License Manager asks what software you are licensing. Select your product from the drop-down list and then choose Next.

   • If you have obtained an authorization code for a purchased license, select Non-expiring License and then choose Next.

     The License Manager requests your authorization code.

     Enter the authorization code and then choose Next.

5. The License Manager displays a summary of the information you entered and allows you to choose the method of applying for your license.
6. Do one of the following:
   • Choose On-line Request if your machine is connected to the internet and can make outgoing connections to port 8884.

     The License Manager then sends a request to the Easysoft license server to activate your license key automatically. This is the quickest method and results in your details being entered immediately into our support database.

   • The remaining three options (Email Request, Print Request, and View Request) are all ways to obtain a license if your machine is off-line (does not have a connection to the internet).

     Each of these methods involves providing Easysoft with information including your machine number (a number unique to your machine) and then waiting to receive your license key.

     Instead of emailing your details to Easysoft, you can enter them directly at the Easysoft web site and your license key will be emailed to you automatically.

     To use this method, choose View Request, and then visit:

     • Trial license page
     • Full license page

     In the licensing page, enter your machine number (and authorization code for a purchased license), choose Submit and your license key will be emailed to you.

     When you receive the license key, you can activate it either by double-clicking the email attachment or by choosing Enter License on the License Manager main screen and pasting the license key into the dialog box.

7. Choose Finish to exit the License Manager.

   The installation is complete.

Configuring an ODBC data source

Before you can use the SugarCRM ODBC driver to connect your application to SugarCRM, you need to configure an ODBC data source. An ODBC data source stores the connection details for the target database (in this case, SugarCRM) and the ODBC driver that is required to connect to it (in this case, the SugarCRM ODBC driver).

You configure ODBC data sources in ODBC Data Source Administrator, which is included with Windows. How you run ODBC Data Source Administrator depends on whether your application is 32-bit or 64-bit:

• My application is 32-bit

  In the Windows Run dialog box, enter:

  %windir%\syswow64\odbcad32.exe

• My application is 64-bit

  Open System and Security > Administrative Tools in Control Panel, and then open ODBC Data Sources (64-bit). (On Windows Server 2003 and earlier, the Control Panel applet that launches ODBC Data Source Administrator is labelled Data Sources.)

The following table shows the architecture of some popular applications.

select SERVERPROPERTY('edition')

In ODBC Data Source Administrator:

1. Choose the System DSN tab, and then choose Add.
2. In the Create New Data Source dialog box, choose Easysoft ODBC-SugarCRM Driver, and then choose Finish.
3. Complete these fields in the Easysoft ODBC-SugarCRM Driver DSN Setup dialog box:

   Setting	Value
   DSN	SugarCRM
   User Name	The name of your SugarCRM user. For example, admin.
   Password	The password for your SugarCRM user.
   Logon Uri	The URI of the SugarCRM instance that you want to connect to. For example: https://sg-richarddemo.demo.sugarcrm.eu/ The Easysoft ODBC-SugarCRM Driver can connect to a SugarCRM instance both over https and http

4. In your application, connect to your newly configured data source and run a sample query. For example:

   select top 10 * from Accounts

Connect to SugarCRM from Perl

Strawberry Perl is a Perl distribution for Windows that includes the necessary middleware layers (Perl DBI and Perl DBD::ODBC) to enable the SugarCRM ODBC driver to connect your Perl applications to SugarCRM.

1. On your Strawberry Perl machine, create a new Perl script with the following contents:

   #!/usr/bin/perl -w
   use strict;
   use DBI;
   my $dbh = DBI-> connect('dbi:ODBC:MySugarCRMODBCDataSource');
   
   my $sql = "select * from Products";
   
   # Prepare the statement.
   my $sth = $dbh->prepare($sql)
       or die "Can't prepare statement: $DBI::errstr";
   
   # Execute the statement.
   $sth->execute();
   
   while ( my @row = $sth->fetchrow_array ) {
         #print "@row\n";
         print DBI::neat_list(\@row), "\n";
   }
   
   $dbh->disconnect if ($dbh);

2. Run the Perl script, which will then retrieve records from the Products table.

Connect Microsoft Access to SugarCRM

Microsoft Access uses an ODBC driver to interact with an external data source. ODBC is a data access technology, the Microsoft implementation of which is included with Windows. You can use the SugarCRM ODBC driver to connect Microsoft Access to a SugarCRM instance, enabling you to query and update SugarCRM data from a Microsoft Access frontend.

1. Open your Microsoft Access database.
2. Do one of the following:
   • For Microsoft Access 2003 and earlier, on the File menu, choose Get External Data > Link Tables.

     The Link dialog box is displayed.

   • For Microsoft Access 2007, on the External Data tab, choose More > ODBC Database.

     The Get External Data wizard starts.

   • For Microsoft Access 2010 and later, on the External Data tab, choose ODBC Database.

     The Get External Data wizard starts.

3. Do one of the following:
   • For Microsoft Access 2003 and earlier, choose ODBC Databases from the Files of type list.
   • For Microsoft Access 2007 and later, choose Link to the data source by creating a linked table, and then choose OK.

   The Select Data Source dialog box is displayed.

4. Choose your SugarCRM ODBC data source from the Machine Data Source list, and then choose OK.

   The Link Tables dialog box is displayed.

5. Choose the table that you want to link and then choose OK.
6. Choose the linked table in Microsoft Access, and then choose Return to work with the linked data.

Connecting Excel to SugarCRM

Follow these steps to return data from SugarCRM to Microsoft Excel by using Microsoft Query:

1. Do one of the following:
   • For Excel 2007 and later, on the Data tab, choose Get External Data. In the From Other Sources group, choose From Microsoft Query.
   • For Excel 2003 and earlier, on the Data menu, choose Import External Data, and then choose New Database Query.

   The New Database Query command uses Microsoft Query to import data. Microsoft Query is an optional feature, which by default is not installed. If you do not have Microsoft Query installed, choosing New Database Query will prompt you to install it. To do this, in Control Panel, choose Programs and Features (or Add or Remove Programs). Choose Microsoft Office (if you installed Excel as part of Office) or Microsoft Excel, and then choose Change. Follow the instructions on screen. Select Choose advanced customization of applications during the Setup wizard if this option is present for your version of Office or Excel. Microsoft Query is located under Office Tools.

   When you have installed Microsoft Query, repeat step 1.

2. In the Choose Data Source dialog box, choose your SugarCRM ODBC driver data source from the list, and then choose OK.
3. In the Query Wizard, choose the columns that contain the data you want to retrieve, and then click Next.
4. If you want to return a subset of the data, use the Filter Data screen to filter the results of your query (this is the equivalent of a SQL WHERE clause), and then click Next.
5. If you want to change the sort order of your data, use the Sort Order screen to sort the results of your query (this is the equivalent of a SQL ORDER BY clause), and then click Next.
6. On the File menu, choose Return data to Excel.
7. Choose a location for the data on your worksheet when prompted.

   Note If nothing appears to happen at this final stage, the target table has more columns than can be retrieved in one Microsoft Query session. Microsoft Query will be running in the background. Switch to Query and reduce the number of columns to retrieve. Repeat the above steps to retrieve the additional columns. (In other words, you may need to split the table over multiple Query sessions to retrieve all the data it contains.)

Connect to SugarCRM from Oracle

1. Create a DG4ODBC init file on your Oracle machine. To do this, change to the %ORACLE_HOME%\hs\admin directory. Create a copy of the file initdg4odbc.ora. Name the new file initsugar.ora.

   Note In these instructions, replace %ORACLE_HOME% with the location of your Oracle HOME directory. For example, C:\oraclexe\app\oracle\product\11.2.0\server.

2. Ensure these parameters and values are present in your init file:

   HS_FDS_CONNECT_INFO = my_sugarcrm_odbc_dsn

   Replace my_sugarcrm_odbc_dsn with the name of a SugarCRM ODBC driver data source that connects to the target SugarCRM instance. For example:

   HS_FDS_CONNECT_INFO = "SugarCRMSystemDSN"

3. Comment out the line that enables DG4ODBC tracing. For example:

   #HS_FDS_TRACE_LEVEL = <trace_level>

4. Add an entry to %ORACLE_HOME%\network\admin\listener.ora that creates a SID_NAME for DG4ODBC. For example:

   SID_LIST_LISTENER =
    (SID_LIST =
      (SID_DESC=
        (SID_NAME=sugar)
        (ORACLE_HOME=%ORACLE_HOME%)
        (PROGRAM=dg4odbc)
      )
    )

5. Add a DG4ODBC entry to %ORACLE_HOME%\network\admin\tnsnames.ora that specifies the SID_NAME created in the previous step. For example:

   SUGAR =
     (DESCRIPTION =
       (ADDRESS = (PROTOCOL = TCP)(HOST = oracle_host)(PORT = 1521))
       (CONNECT_DATA =
         (SID = sugar)
       )
       (HS = OK)
     )

   Replace oracle_host with the host name of your Oracle machine.

6. Start (or restart) the Oracle Listener:

   cd %ORACLE_HOME%\bin
   lsnrctl stop
   lsnrctl start

7. Connect to your Oracle database in SQL*Plus.
8. In SQL*Plus, create a database link for the target SugarCRM instance. For example:

   CREATE PUBLIC DATABASE LINK sugarlink CONNECT TO "mysugarcrmuser" IDENTIFIED BY "mysugarcrmpassword" USING 'sugar';

9. Try querying your SugarCRM data. For example:

   SELECT * FROM "Categories"@SUGARLINK;

Notes

• If you have problems connecting to SugarCRM from Oracle, enable DG4ODBC tracing and check the trace files written to the %ORACLE_HOME%\hs\trace directory. To enable DG4ODBC tracing, add the line HS_FDS_TRACE_LEVEL = DEBUG to initsugar.ora and then start or restart the Oracle listener. If the trace directory does not exist, create it.
• If you enable ODBC Driver Manager tracing, but do not get a trace file or get an empty trace file, change the trace file location to the Windows TEMP directory. For example, C:\Windows\Temp\SQL.log.