Simba ODBC Driver with SQL Connector for Salesforce

Transcription

1 Simba ODBC Driver with SQL Connector for Salesforce Installation and Configuration Guide Last Revised: May 28, 2013 Simba Technologies Inc.

2 Copyright Simba Technologies Inc. All Rights Reserved. Information in this document is subject to change without notice. Companies, names and data used in examples herein are fictitious unless otherwise noted. No part of this publication, or the software it describes, may be reproduced, transmitted, transcribed, stored in a retrieval system, decompiled, disassembled, reverse-engineered, or translated into any language in any form by any means for any purpose without the express written permission of Simba Technologies Inc. Trademarks Simba, the Simba logo, SimbaEngine, SimbaEngine C/S, SimbaExpress and SimbaLib are registered trademarks of Simba Technologies Inc. All other trademarks and/or servicemarks are the property of their respective owners. ICU License - ICU and later COPYRIGHT AND PERMISSION NOTICE Copyright (c) International Business Machines Corporation and others All rights reserved. Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, provided that the above copyright notice(s) and this permission notice appear in all copies of the Software and that both the above copyright notice(s) and this permission notice appear in supporting documentation. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT OF THIRD PARTY RIGHTS. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR HOLDERS INCLUDED IN THIS NOTICE BE LIABLE FOR ANY CLAIM, OR ANY SPECIAL INDIRECT OR CONSEQUENTIAL DAMAGES, OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. Except as contained in this notice, the name of a copyright holder shall not be used in advertising or otherwise to promote the sale, use or other dealings in this Software without prior written authorization of the copyright holder. All trademarks and registered trademarks mentioned herein are the property of their respective owners. i

3 OpenSSL Copyright (c) The OpenSSL Project. All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. 3. All advertising materials mentioning features or use of this software must display the following acknowledgment: "This product includes software developed by the OpenSSL Project for use in the OpenSSL Toolkit. ( 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to endorse or promote products derived from this software without prior written permission. For written permission, please contact 5. Products derived from this software may not be called "OpenSSL" nor may "OpenSSL" appear in their names without prior written permission of the OpenSSL Project. 6. Redistributions of any form whatsoever must retain the following acknowledgment: "This product includes software developed by the OpenSSL Project for use in the OpenSSL Toolkit ( THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. Expat Copyright (c) 1998, 1999, 2000 Thai Open Source Software Center Ltd Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, ii

4 and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NOINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. libcurl COPYRIGHT AND PERMISSION NOTICE Copyright (c) , Daniel Stenberg, <daniel@haxx.se>. All rights reserved. Permission to use, copy, modify, and distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT OF THIRD PARTY RIGHTS. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. Except as contained in this notice, the name of a copyright holder shall not be used in advertising or otherwise to promote the sale, use or other dealings in this Software without prior written authorization of the copyright holder. gsoap gsoap is copyrighted by Robert A. van Engelen, Genivia, Inc. Copyright (C) Robert A. van Engelen, Genivia, Inc. All Rights Reserved. Permission to use, copy, modify, distribute, and sell this software and its documentation for any purpose is hereby granted without fee, provided that the above copyright notice appear in all copies and that both that copyright notice and this permission notice appear in supporting documentation, and that the name of M.I.T. not be used in advertising or publicity pertaining to iii

5 distribution of the software without specific, written prior permission. M.I.T. makes no representations about the suitability of this software for any purpose. It is provided as is without express or implied warranty. Contact Us Simba Technologies Inc. 938 West 8th Avenue Vancouver, BC Canada V5Z 1E5 Telephone: +1 (604) Information and Product Sales: Extension 2 Technical Support: Extension 3 Fax: +1 (604) Information and Product Sales: solutions@simba.com Technical Support: support@simba.com Follow us on Printed in Canada iv

6 Table of Contents Introduction... 1 System Requirements... 1 Installing the Driver... 1 Creating a Data Source Name... 2 Configuring Advanced Options... 3 Testing the Salesforce Data Source... 5 Displaying a List of Salesforce Reports... 6 Displaying Results of a Salesforce Report... 7 Contact Us... 8 Appendix: Salesforce Object Query Language... 9 Unsupported SOQL Features... 9 Known issues v

7 Introduction Simba ODBC Driver with SQL Connector for Salesforce is used to access Salesforce.com. The driver enables Business Intelligence (BI), analytics and reporting on Salesforce.com data. ODBC is one the most established and widely supported APIs for connecting to and working with databases. At the heart of the technology is the ODBC driver, which connects an application to the database. For more information about ODBC, see For complete information on the ODBC 3.52 specification, see the ODBC API Reference at System Requirements Simba ODBC Driver with SQL Connector for Salesforce requires a Salesforce Enterprise Edition, Unlimited Edition or Developer Edition account. If you are an existing Salesforce customer and want to upgrade to either Enterprise or Unlimited Edition, please contact your Salesforce account representative. Note: You provide login credentials for your Salesforce account when the driver connects to Salesforce.com. You install the driver on client computers accessing Salesforce.com. Each computer where you install the driver must meet the following minimum system requirements: One of the following operating systems (32- and 64-bit editions are supported): o o o o Windows XP with SP3 Windows Vista Windows 7 Professional Windows Server 2008 R2 30 MB of available disk space Simba ODBC Driver with SQL Connector for Salesforce is based on Salesforce API version 27. Important: To install the driver, you need Administrator privileges on the computer. Installing the Driver On 64-bit Windows operating systems, you can execute 32- and 64-bit applications transparently. You must use the version of the driver matching the bitness of the client application accessing data on Salesforce.com: SimbaSalesforceODBC32.msi for 32-bit applications SimbaSalesforceODBC64.msi for 64-bit applications You can install both versions of the driver on the same computer. 1

8 Note: For an explanation of how to use ODBC on 64-bit editions of Windows, see To install Simba ODBC Driver with SQL Connector for Salesforce: 1. Depending on the bitness of your client application, double-click to run SimbaSalesforceODBC32.msi or SimbaSalesforceODBC64.msi 2. Click Next 3. Select the check box to accept the terms of the License Agreement if you agree, and then click Next 4. To change the installation location, click the Change button, then browse to the desired folder, and then click OK. To accept the installation location, click Next 5. Click Install 6. When the installation completes, click Finish 7. If you are installing a driver with an evaluation license and you have purchased a perpetual license, then copy the License.lic file you received via into the \bin subfolder in the installation folder you selected in step 4. Creating a Data Source Name After installing Simba ODBC Driver with SQL Connector for Salesforce, you need to create a Data Source Name (DSN). To create a Data Source Name: 1. On the Windows Start menu, click All Programs, then click the Simba Salesforce ODBC Driver 1.0 program group corresponding to the bitness of the client application accessing data on Salesforce.com, and then click ODBC Administrator 2. In the ODBC Administrator, click the Drivers tab, and then scroll down as needed to confirm that Simba Salesforce ODBC Driver appears in the alphabetical list of driver names. 3. To create a DSN on the computer that only the user currently logged into Windows can use, click the User DSN tab. OR To create a DSN on the computer that all users who log into Windows can use, click the System DSN tab. 4. Click the Add button. 5. In the Create New Data Source dialog, select Simba Salesforce ODBC Driver, and then click Finish 6. In the Data Source Configuration dialog, type a name for the data source in the Data Source Name field. 7. In the Description field, type relevant details about the DSN. 2

9 8. If you are using a proxy server, then select the Use Proxy Server checkbox. Type the host name or IP address of the proxy server in the Proxy Host field. Type the port number that the proxy server uses for client connections in the Proxy Port field. Type your login credentials in the Proxy Username and Proxy Password fields as needed. 9. To configure advanced driver options, click the Advanced Options button. For details, see the section Configuring Advanced Options on page Click OK in the Data Source Configuration dialog. 11. Click OK in the ODBC Data Source Administrator. Configuring Advanced Options Simba ODBC Driver with SQL Connector for Salesforce provides the following advanced options: Parse Method Metadata Optimization Using Salesforce Labels for Columns You can configure advanced options for a DSN using the following: Parse Method Advanced Options dialog Database connection string Windows Registry You can specify the query language used to parse queries. In dialog boxes, select the appropriate option in the Parse Method area to specify the query language. In a connection string or in the Registry, use the ParseMethod attribute. Table 1 lists settings available for specifying the query language via dialog boxes or the ParseMethod attribute. ParseMethod Attribute Value SOQL_FIRST SQL_FIRST SOQL_ONLY SQL_ONLY Option Attempt to parse queries as SOQL first, then SQL (Default) Attempt to parse queries as SQL first, then SOQL Attempt to parse queries as SOQL only Attempt to parse queries as SQL only Table 1 Query Language Settings SOQL is the Salesforce Object Query Language. For more information about SOQL, see the Appendix: Salesforce Object Query Language on page

10 Metadata Optimization You can specify the level of metadata inference that Simba ODBC Driver with SQL Connector for Salesforce performs for reports and stored procedures. In dialog boxes, setting the Enable Report Metadata Optimization check box sets the level of inference. Using a connection string or the Registry, the MetadataLevel attribute sets the level of inference. Table 2 describes the available levels of metadata inference. MetadataLevel Attribute Value Enable Report Metadata Optimization Check Box Value Description FULL Unselected Metadata is inferred based on all of the data. This is slower but more accurate. This is the default value. LIGHT Selected Metadata is inferred based on a small sampling of the data. This is faster but less accurate. Using Salesforce Labels for Columns Table 2 Levels of Metadata Inference In Salesforce, each field is assigned a unique identifying name as well as a field label. Salesforce displays the field label in the user interface. Simba ODBC Driver with SQL Connector for Salesforce can use the field name as the name as well as the label because some client applications require that the field name and field label match. In the Advanced Options dialog, set the option using the Use Salesforce Labels for Columns check box. Using a connection string or the Registry, use the UseLabel attribute to set the option. Table 3 describes settings related to field names and labels. UseLabel Attribute Value Use Salesforce Labels for Columns Check Box Value Description 0 Unselected The driver uses the field name as the name as well as the label for the DSN (Default). 1 Selected The driver uses the field name as the name and the field label as the label for the DSN. Using the Advanced Options Dialog Table 3 Using Salesforce Labels for Columns Settings The Advanced Options dialog is available from the ODBC Data Source Administrator and the Salesforce Connection Dialog. The Salesforce Connection Dialog appears when you connect to Salesforce.com from a client application using the DSN. 4

11 To set advanced options using dialog boxes: 1. In the ODBC Data Source Administrator where you created the DSN, select the DSN tab where the Data Source Name appears, then select the Data Source Name, and then click the Configure button. OR 2. Open the client application to use for connecting to Salesforce.com data, and then connect to Salesforce.com using the DSN. 3. Click the Advanced Options button. 4. In the Parse Method area, select the desired option. 5. In the Metadata Optimization area, set the Enable Report Metadata Optimization check box as needed. 6. Set the Use Salesforce Labels for Columns check box as needed. 7. Click OK Using a Database Connection String Here is an example connection string that sets advanced options: DSN=Sample Simba Salesforce DSN;uid= @company.com;pwd=<password>; MetadataLevel=FULL;ParseMethod=SQL_ONLY;UseLabel=1 Note: Connection string settings override registry settings. Using Windows Registry Settings The value names for advanced options are ParseMethod, MetadataLevel and UseLabel. For the 32-bit driver on 32-bit Windows and the 64-bit driver on 64-bit Windows, the values are set in the following key, where DSNName is the Data Source Name for which you want to configure advanced options: HKEY_LOCAL_MACHINE\SOFTWARE\ODBC\ODBC.INI\DSNName For the 32-bit driver on 64-bit Windows, the values are set in the following key, where DSNName is the Data Source Name for which you want to configure advanced options: HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432NODE\ODBC\ODBC.INI\DSNName Testing the Salesforce Data Source To test the Salesforce data source, you can use a client application like Excel or Crystal Reports. You can also use the ODBC Test tool, which is available in the Microsoft Data Access (MDAC) 2.8 Software Development Kit (SDK). You can download the SDK from de4329c8c850&displaylang=en 5

12 To test your Salesforce data source using ODBC Test: 1. Click the Start menu, then click Microsoft Data Access SDK 2.8, and then click the Unicode ODBC Test tool corresponding to the bitness of the ODBC Data Source Administrator where you created the DSN you want to test. 2. In ODBC Test, click Conn, and then click Full Connect 3. In the Full Connect dialog, scroll down as needed to the select the data source you want to test, and then click OK 4. In the Username field, type the user name for your Salesforce account. 5. In the Password field, type the password corresponding to the user name you typed in step If you need to provide proxy server settings, then select the Use Proxy Server checkbox. Type the host name or IP address of the proxy server in the Proxy Host field. Type the port number that the proxy server uses for client connections in the Proxy Port field. Type your login credentials in the Proxy Username and Proxy Password fields as needed. 7. To configure advanced driver options, click the Advanced Options button. For details, see the section Configuring Advanced Options on page In the Salesforce Connection Dialog, click OK If the connection is successful, then ODBC Test displays a message informing you that you successfully connected to the DSN. For example: Full Connect(Default) Env. Attr. SQL_ATTR_ODBC_VERSION set to SQL_OV_ODBC3 Successfully connected to DSN 'MySalesforceDSN'. Displaying a List of Salesforce Reports Important: Reports are implemented as stored procedures. Therefore, reports are only supported when queries are being parsed as SQL the Parse Method cannot be set to SOQL_ONLY. See the section Parse Method on page 3 for more details. To display a list of Salesforce reports using ODBCTest: 1. Follow the procedure in the section Testing the Salesforce Data Source on page 5 to connect to your Salesforce.com data. 2. In ODBC Test, click the Catalog menu, and then click SQLProcedures 6

13 3. In the SQLProcedures dialog, click OK. A message similar to the following appears in the Output window: SQLProcedures: In: StatementHandle = 0x005B32D0, CatalogName = SQL_NULL_HANDLE, NameLength1 = 0, SchemaName = SQL_NULL_HANDLE, NameLength2 = 0, ProcName = SQL_NULL_HANDLE, NameLength3 = 0 Return: SQL_SUCCESS=0 4. Click the Results menu, and then click Get Data All. The Output window displays a list of all stored procedures, which correspond to Salesforce reports. The list includes standard Salesforce reports as well as custom reports you create. For example: Get Data All: "PROCEDURE_CAT", "PROCEDURE_SCHEM", "PROCEDURE_NAME", "NUM_INPUT_PARAMS", "NUM_OUTPUT_PARAMS", "NUM_RESULT_SETS", "REMARKS", "PROCEDURE_TYPE" "Simba Technologies", "Simba Technologies", "API Usage Last 7 Days", -1, - 1, -1, <Null>, 1 "Simba Technologies", "Simba Technologies", "Account History Report", -1, -1, -1, <Null>, 1... "Simba Technologies", "Simba Technologies", "Web Lead Source", -1, -1, -1, <Null>, 1 "Simba Technologies", "Simba Technologies", "Web Lead Source by Date", -1, -1, -1, <Null>, rows fetched from 8 columns. Displaying Results of a Salesforce Report You run a report the same way you run a stored procedure. For example, to run the report named API Usage Last 7 Days using ODBC Test: 1. Follow the procedure in the section Testing the Salesforce Data Source on page 5 to connect to your Salesforce.com data. 2. In the ODBC Test Input window, type the following command: {call "API Usage Last 7 Days"} 3. Click the SQLExecDirect ( ) button in the toolbar. Results similar to the following appear in the Output window: SQLExecDirect: In: hstmt = 0x005B32D0, szsqlstr = "", cbsqlstr = -3 Return: SQL_SUCCESS=0 7

14 Contact Us 4. Click the Results menu, and then click Get Data All. The Output window displays the report results: Get Data All: "Name", "Client Id", "Day Of Week", "Call Count", "Username", " " "Simba Test", "", "Friday", 15, "Simba Test", "", "Wednesday", 2, "Simba Test", "", "Thursday", 644, 3 rows fetched from 6 columns. If you have difficulty using the driver, please contact our Technical Support staff. We welcome your questions, comments and feature requests. Technical Support is available Monday to Friday from 8 a.m. to 5 p.m. Pacific Time. Important: To help us assist you, prior to contacting Technical Support please prepare a detailed summary of the client and server environment including operating system version, patch level and configuration. You can contact Technical Support via: support@simba.com Web site: Telephone: (604) Extension 3 Fax: (604) You can also follow us on 8

15 Appendix: Salesforce Object Query Language For more information about the Salesforce Object Query Language (SOQL), refer to the SOQL Reference at: Unsupported SOQL Features Typeof Offset With Aliases Known issues Queries that contain errors in the following clauses could potentially succeed the prepare step and not fail until executed Restrictions using ToLabel() in filter clause Restrictions using fields in HAVING clause Data Type limitations: restrictions on Salesforce data types cannot be enforced at prepare time. For example, ORDER BY is not supported for: multi-select picklist, rich text area, long text area, and encrypted. GROUP BY returning large result sets When a query that contains a GROUP BY clause returns a result set exceeding 2000 rows, then you must change the filtering conditions to query data in smaller chunks. This is for efficiency because the driver will use the querymore() call and a server-side cursor to retrieve additional rows in 200-row chunks. However, if a query includes a GROUP BY clause, then querymore() cannot be used. 9