Qlik Salesforce Connector Installation and User...

13
Copyright © QlikTech International AB 2015, All Rights Reserved Under international copyright laws, neither the documentation nor the software may be copied, photocopied, reproduced, translated or reduced to any electronic medium or machine-readable form, in whole or in part, without the prior written permission of QlikTech International AB, except in the manner described in the software agreement. QlikTech®, Qlik® and QlikView® are registered trademarks of QlikTech International AB. All other company names, products and services used herein are trademarks or registered trademarks of their respective owners. Qlik Salesforce Connector Installation and User Guide Qlik Salesforce Connector Version 13.1 Newton, Massachusetts, September 2015 Authored by QlikTech International AB

Transcript of Qlik Salesforce Connector Installation and User...

Page 1: Qlik Salesforce Connector Installation and User Guideda3hntz84uekx.cloudfront.net/SFConnector/13.10/5/... · 1 Qlik Salesforce Connector The Qlik Salesforce Connector provides a means

Copyright © QlikTech International AB 2015, All Rights Reserved Under international copyright laws,

neither the documentation nor the software may be copied, photocopied, reproduced, translated or

reduced to any electronic medium or machine-readable form, in whole or in part, without the prior

written permission of QlikTech International AB, except in the manner described in the software agreement.

QlikTech®, Qlik® and QlikView® are registered trademarks of QlikTech International AB. All other

company names, products and services used herein are trademarks or registered trademarks of their respective owners.

Qlik Salesforce Connector Installation

and User Guide

Qlik Salesforce Connector Version 13.1

Newton, Massachusetts, September 2015

Authored by QlikTech International AB

Page 2: Qlik Salesforce Connector Installation and User Guideda3hntz84uekx.cloudfront.net/SFConnector/13.10/5/... · 1 Qlik Salesforce Connector The Qlik Salesforce Connector provides a means
Page 3: Qlik Salesforce Connector Installation and User Guideda3hntz84uekx.cloudfront.net/SFConnector/13.10/5/... · 1 Qlik Salesforce Connector The Qlik Salesforce Connector provides a means

3

Contents

1 Qlik Salesforce Connector ................................................................... 4

1.1 What’s new ....................................................................................................... 4

2 Install the Qlik Salesforce Connector ............................................... 4

2.1 System requirements ...................................................................................... 4

2.2 Installing the Qlik Salesforce Connector ...................................................... 4

3 Create a Salesforce connection .......................................................... 5

3.1 Specifying Salesforce.com account credentials ................................................ 5

3.2 Setting data load properties ............................................................................... 7

3.3 Changing the default proxy setting ................................................................... 8

4 Select and load data ............................................................................ 9

4.1 Selecting data .................................................................................................... 9

4.2 Renaming fields ............................................................................................... 11

4.3 Load Salesforce objects with relationship queries .......................................... 11

5 Locate the Salesforce connector log file ......................................... 13

6 Supported data types ........................................................................ 13

Page 4: Qlik Salesforce Connector Installation and User Guideda3hntz84uekx.cloudfront.net/SFConnector/13.10/5/... · 1 Qlik Salesforce Connector The Qlik Salesforce Connector provides a means

4

1 Qlik Salesforce Connector

The Qlik Salesforce Connector provides a means for the Qlik visual analytics platform to efficiently load

data into a QlikView application from a Salesforce.com dataset. The metadata is used by the Create Select

Statement dialog box to specify the table and columns to select for the SOQL SELECT statement.

Note: When loading data (sending a query to Salesforce.com), you cannot send more

than one query at a time in the same user account. The first query to finish loading

closes the Salesforce session and then the remaining queries cannot be completed.

1.1 What’s new

Version 13.1 of the Salesforce Connector adds support for Microsoft .NET Framework 4.5.2., which is

required to connect with Salesforce.com’s TLS 1.1 and 1.2. Salesforce.com is deprecating support for SSLv3

and TLS 1.0.

2 Install the Qlik Salesforce Connector

2.1 System requirements

Version 13.1 of the Qlik Salesforce Connector runs only on systems with 64-bit processors. It can be

installed on 64-bit systems that run QlikView. Those systems include:

Microsoft Windows Server 2008 R2

Microsoft Windows Server 2012

Microsoft Windows Server 2012 R2

Microsoft Windows 7

Mircrosoft Windows 8.1

Version 13.1 also requires Microsoft .NET Framework 4.5.2 or later version.

Version 13.1 supports up to Salesforce API version 29.

2.2 Installing the Qlik Salesforce Connector

1. Download the QlikSalesforceConnector_setup.exe file from the Qlik download site.

2. Run the QlikSalesforceConnector_setup.exe.

The Qlik Salesforce Connector InstallShield Wizard sets up the installation environment and

completes the installation.

The Connector is then available from the QlikView Desktop with the name

“QvSalesforceConnector.exe.”

3. Open the QlikView11 Desktop application.

If QlikView is open when you install the Salesforce Connector, you must close and reopen it in

order for QlikView to recognize the Connector.

Page 5: Qlik Salesforce Connector Installation and User Guideda3hntz84uekx.cloudfront.net/SFConnector/13.10/5/... · 1 Qlik Salesforce Connector The Qlik Salesforce Connector provides a means

5

3 Create a Salesforce connection

QlikView applications connect to data sources through the Script Editor.

3.1 Specifying Salesforce.com account credentials

1. Open a new or existing QlikView application.

2. Click Edit Script... on the File menu in the main QlikView window.

3. Select QvSalesforceConnector.exe from the drop-down list next to Connect... on the Data tab in

the lower part of the Edit Script dialog.

Page 6: Qlik Salesforce Connector Installation and User Guideda3hntz84uekx.cloudfront.net/SFConnector/13.10/5/... · 1 Qlik Salesforce Connector The Qlik Salesforce Connector provides a means

6

4. Click Connect... to open the Salesforce Connection dialog.

5. Enter the user name and password for the Salesforce account.

Salesforce user names are email addresses. If you intend to connect to a sandbox (Step 7), you

must append the name of the sandbox to your user name. For example,

[email protected].

6. Enter the security token assigned to the account.

If you connect to Salesforce.com from an IP address that is in the Trusted IP Ranges in Salesforce,

the security token is not required.

7. Enter the URL for an alternative Salesforce.com environment you want to connect to.

By default, the Salesforce Connector connects to your account’s production organization.

Depending on the type of account you have (for example, Enterprise, Performance or Unlimited

Edition), there may also be a sandbox, which is a testing environment you can work in while

preserving the stability of the production organization. The sandbox URL can be entered,

optionally, in the URL text box to direct the Salesforce Connector to open the sandbox instead of

the default production organization.

To access your sandbox, use the following URL:

https://test.salesforce.com/services/Soap/u/29.0

The Salesforce Connector supports the SOAP API version 29.0. You might encounter problems

using another version of the SOAP API.

8. Click Test Connection to verify that a connection can be made with the account properties

entered.

Page 7: Qlik Salesforce Connector Installation and User Guideda3hntz84uekx.cloudfront.net/SFConnector/13.10/5/... · 1 Qlik Salesforce Connector The Qlik Salesforce Connector provides a means

7

3.2 Setting data load properties

1. Select the type of interface to use with the connection: SOAP API Query, SOAP API QueryAll, or

Bulk API.

If you use the SOAP API to connect to Salesforce, you can read all records in the Salesforce object

that have not been marked as deleted (Query). Or you can read all records in the Salesforce

object including those that have been marked as deleted (QueryAll).

Note: When choosing between SOAP and Bulk APIs, you must know whether or not you

need to load multiple Salesforce objects with a relationship query (see Load Salesforce

objects with relationship queries below.) The SOAP API is required when loading data

with relationship queries.

The Bulk API provides faster transmission than the SOAP API. It is particularly useful when you

load entire tables.

Note: The Bulk API does not support aggregation functions or grouping.

Note: If you use Bulk API, the Salesforce Bulk API must be enabled for the account that is

reading the data on Salesforce.com.

2. Specify the timeout period in seconds for connections that use the SOAP API.

The timeout value sets a limit on the amount of time the connector waits for a response from

Salesforce.com when it requests a batch of data. The timeout applies to loading each batch of

data. It does not apply to the time it takes to parse, convert and write the data to QlikView.

This is used only for connections that use the SOAP API. When Bulk API is selected (Step 1), the

Timeout field does not appear.

3. Specify the batch size, which is the maximum number of rows written to the data target in one

batch.

The batch size can be used to control the speed at which QlikView and Salesforce.com

communicate. If a batch size is not specified or Salesforce.com does not accept the set batch size,

the Connector tries to use the maximum allowed batch size of 2000 and then increments down in

steps using the following predefined batch sizes:

2000, 1000, 500, 200, 100, 50, 20, 10, 5, 2, 1

Bulk API is selected (Step 1), the Batch size field does not appear.

4. Select Convert SQL dates to convert dates entered in the format YYYY-MM-DD hh:mm:ss to the

SOQL format.

The SQL date-time data type is often used in WHERE clauses, but that data type format does not

match date-times in a Salesforce object. If the Convert SQL dates box is selected, date-time

values entered in the YYYY-MM-DD hh:mm:ss format are automatically converted to the SOQL

format used for the date-time data type.

If Convert SQL dates is not selected, date-time values submitted to Salesforce.com in SQL

format would not match any date-time values in the Salesforce.com object database. See the

discussion of the WHERE clause in the section below on creating a load statement.

5. Select Boolean as strings to return Boolean values as “true” or “false” strings.

If Boolean as strings is not selected, Boolean values are returned as “0” or “1.”

6. Select Convert UTC to local time to convert date-time values returned by the Connector to the

local time of the computer the Connector is running on.

If Convert UTC to local time is not selected, the Connector returns date-time values from

Salesforce.com in Coordinated Universal Time (UTC).

Page 8: Qlik Salesforce Connector Installation and User Guideda3hntz84uekx.cloudfront.net/SFConnector/13.10/5/... · 1 Qlik Salesforce Connector The Qlik Salesforce Connector provides a means

8

3.3 Changing the default proxy setting

By default, the Salesforce Connector uses the proxy settings defined in the Windows Proxy settings,

which can be accessed in Internet Options in the Control Panel. The proxy setting can be changed to

use a host other than the default.

The proxy parameter must be set as described in the Microsoft article “Enabling Internet

Functionality.” To change the proxy setting, use the Proxy fields at the bottom of the Salesforce

Connection dialog as follows:

1. Specify the name or IP address of a proxy host in Proxy section of the Salesforce Connection

dialog.

2. Specify the port number for the Proxy on the machine running the host.

3. Select the authentication required by the Proxy host from the Enable authentication drop-

down menu.

The Enable authentication drop-down menu does not appear until you start to enter a name

or IP address in the Proxy host field.

4. If Enable authentication is set to Yes, enter the user name and password for the Proxy host.

The User name and Password fields do not appear until you select Yes from the Enable

authentication drop-down menu.

After the account credentials have been entered and the connection tested, the data load properties set,

and the proxy settings changed if necessary:

Click OK to create the connection string used when sending the load statement to

Salesforce.com.

The Salesforce Connection dialog closes and the connection string is inserted in the Edit Script

dialog.

Page 9: Qlik Salesforce Connector Installation and User Guideda3hntz84uekx.cloudfront.net/SFConnector/13.10/5/... · 1 Qlik Salesforce Connector The Qlik Salesforce Connector provides a means

9

4 Select and load data

Once a connection to Salesforce.com has been established, you can select data and load it into a QlikView

application.

4.1 Selecting data

1. Click the enabled Select... on the Data tab in the lower part of the Edit Script dialog.

The Edit Script dialog has two Select… buttons when the Salesforce Connector has been

connected but only the bottom button is enabled.

2. Select a database table from the Objects list in the Create Select Statement dialog.

3. Select the fields to load from the Fields list.

Press the Control (Ctrl) key to select multiple fields.

The SELECT statement that will be used to load data from the Salesforce.com database displays

under the Script tab in the bottom portion of the dialog. If you want to rename a selected field,

see Renaming fields.

The SELECT statement does not include a WHERE clause, but one can be added in the text box

under the Script tab. The SELECT statement for the Salesforce Connector supports the addition

of WHERE clauses. If the selected field uses a date or date-time data type, the date-time format

YYYY-MM-DD hh:mm:ss is automatically converted to the SOQL date-time (YYYY-MM-

DDThh:mm:ssZ) if Convert SQL dates is selected in the connection dialog. SOQL uses "Z" on the

time to indicate that the time is to be read as absolute, with no time zone offset. In SOQL, “Z” can

be substituted with an offset value. For example, the date “2009-02-24 23:01:01” in Eastern US

time zone would be “2009-02-24T23:01:01-05:00” in SOQL. Because the YYYY-MM-DD hh:mm:ss

format has no offset value, the date-time is converted to Coordinated Universal Time (UTC).

Note: The Convert UTC to local time setting does not affect the time zone in date-time

values sent to Salesforce.com in WHERE clauses. The Convert UTC to local time setting

handles the display of date-time values returned from Salesforce.com, not the values sent

to Salesforce.com.

The SELECT statement for the Salesforce Connector also supports:

SELECT * statement: The Salesforce Connector allows you to use the SELECT *

statement to select all fields in the table. You add the SELECT * statement manually in

the text box under the Script tab.

Page 10: Qlik Salesforce Connector Installation and User Guideda3hntz84uekx.cloudfront.net/SFConnector/13.10/5/... · 1 Qlik Salesforce Connector The Qlik Salesforce Connector provides a means

10

The SOQL query language does not support the SELECT* statement, but the Salesforce

Connector has been enhanced to recognize that syntax. Only asterisks (*) and simple

field names can be used in the SELECT * statement.

The SELECT * statement can only be used when Bulk API is selected in the Salesforce

Connection dialog. See Bulk API.

String escape characters: The Salesforce Connector uses the single quotation mark

character as an escape character instead of the back slash (\) used by SOQL. To include

a single quotation mark in a query string, it must be prefaced by another single

quotation mark. For example, the following string encloses “Captain Awesome” in single

quotation marks.

Devon ‘’Captain Awesome’’ Woodcomb

The SELECT statement for the Salesforce Connector does not support:

Qualified field names: Field names cannot be prefixed by table table names. For

example, “Contact.FirstName” is not permitted.

Salesforce prefix: It is not permissible to prefix the table name with the string

“Salesforce.” For example, “Salesforce.Contact” is not allowed.

Bracketed names: Table and field names cannot be put in brackets. For example, the

following SELECT statement is not valid:

SELECT [FirstName] FROM [Contact]

SOQL aliases: The syntax for creating aliases in SOQL cannot be used. For example, the

following SOQL syntax is not valid for the Salesforce Connector:

SELECT Id BusinessID FROM Contact

Note: Changes entered manually in the text box under the Script tab will be lost if new

selections are made in Objects or Fields. Changes entered manually are also lost when you

select Preceding load Select all tables and fields as well as Preceding load before editing

the script manually.

4. Select Preceding load to create a LOAD statement before the SELECT statement.

This step is optional.

Note: The Preceding load check box is not available when the connection is made with

SOAP mode. See Setting data load properties.

The preceding load feature allows the LOAD statement to use the SELECT statements as input.

Basically, it is a LOAD statement that loads from the LOAD or SELECT statement below, without

specifying a source qualifier, such as From or Resident, as you would normally. You can stack any

number of LOAD statements this way. The statement at the bottom will be evaluated first, then

the statement above, and so on until the top statement has been evaluated.

Another advantage of preceding load is that you can keep a calculation in one place and reuse it

in LOAD statements placed above. For example, when you load data from a database using a

SELECT statement, you cannot use QlikView functions to interpret data in the SELECT statement.

The solution is to add a LOAD statement and perform data transformations above the SELECT

Page 11: Qlik Salesforce Connector Installation and User Guideda3hntz84uekx.cloudfront.net/SFConnector/13.10/5/... · 1 Qlik Salesforce Connector The Qlik Salesforce Connector provides a means

11

statement. In this example, string data is interpreted with the QlikView Date# interpretation

function in a LOAD statement, using the SELECT statement as source:

LOAD Date#(orderDate, ‘YYYYMMDD’) as OrderDate;

SELECT OrderDate FROM _;

The preceding LOAD statement created under the Script tab is the simple version illustrated in

the screen above. To create the LOAD statement in this example, you would edit the script in the

text box under the Script tab.

5. Click Validate to verify that the SELECT statement query is valid.

If you click OK before Validate, the statement is validated before it is added to the load script.

6. Click the Preview tab to see data that will be loaded with the SELECT statement displayed under

the Script tab.

Previewing the data is optional. By default, 25 rows are displayed. More rows can be displayed by

selecting a higher number from the Maximum rows drop-down menu.

Note: You cannot preview data if the load script contains more than one SELECT statement.

7. Click OK when you are finished making your selections.

Note: When loading data (sending a query to Salesforce.com), you cannot send more

than one query at a time in the same user account. The first query to finish loading

closes the Salesforce session and then the remaining queries cannot be completed.

4.2 Renaming fields

To rename a field, you create an alias in the LOAD statement. This can be done in the Edit Script dialog

after the load script has been inserted. For example:

When using Bulk mode with Preceding load, you can create the alias in the text box under the Script tab.

SOAP mode does not allow Preceding load, so the LOAD statement does not appear in the text box under

the Script tab. In SOAP mode, renaming must be done in the Edit Script dialog.

4.3 Load Salesforce objects with relationship queries

SELECT statements can be written to load Salesforce objects with relationship queries. Such statements

must be entered directly in the text box under the Script tab. They cannot be created by selecting multiple

objects and fields from the Objects and Fields lists. Each time you select an object from the list, that

selection replaces any existing SELECT statement under the Script tab. To include multiple objects in the

query, you must add them manually.

Note: SOAP mode is required for relationship queries. See Setting data load properties.

In the following example, the SELECT statement includes fields from multiple objects in a relationship

query.

Page 12: Qlik Salesforce Connector Installation and User Guideda3hntz84uekx.cloudfront.net/SFConnector/13.10/5/... · 1 Qlik Salesforce Connector The Qlik Salesforce Connector provides a means

12

Note: When loading multiple objects in a relationship query, you must use a relationship name

instead of a table name. For standard tables the relationship name is the plural of the table object

name. In the illustration above, “Contacts” and “Cases” are used instead of “Contact” and “Case,”

which are the object names.

From this SELECT statement, the Connector creates separate load statements for each of the related

tables.

Page 13: Qlik Salesforce Connector Installation and User Guideda3hntz84uekx.cloudfront.net/SFConnector/13.10/5/... · 1 Qlik Salesforce Connector The Qlik Salesforce Connector provides a means

13

The resulting load produces three related tables.

5 Locate the Salesforce connector log file

The Salesforce Connector’s log file is located at:

{ProgramData}\QlikTech\Custom Data\QvSalesforceConnector\Log

Where {ProgramData} is %ALLUSERSPROFILE%.

6 Supported data types

The following Salesforce.com data types are supported by the Salesforce connector. Fields with supported

data types are the only fields that display for selection in the Create Select Statement dialog. Fields

containing unsupported data types are not displayed.

Auto Number Lookup Relationship Text Area

Checkbox Number Text Area (Long)

Currency Percent Text Area (Rich)

Date Phone Text (Encrypted)

Date/Time Picklist URL

Email Picklist (Multi-Select)

Formula Text