Beruflich Dokumente
Kultur Dokumente
Salesforce.com
Version 1.5
SC19-3875-00
SC19-3875-00
Note
Before using this information and the product that it supports, read the information in Notices and trademarks on page
25.
Contents
IBM InfoSphere Information Server Pack
for Salesforce.com . . . . . . . . . . 1
Configuration prerequisites . . . . . . . . . 2
Installing and uninstalling the Pack. . . . . . 2
Salesforce.com object requirements for delta
extractions . . . . . . . . . . . . . . 3
Salesforce.com rules and guidelines. . . . . . 3
Connections and sessions . . . . . . . . . 4
Setting environment variables . . . . . . . 4
Connecting to Salesforce.com . . . . . . . . . 5
Saving design time connection properties . . . . 6
Loading connection properties at design time . . 7
Selecting metadata for load and extraction operations 7
Loading data into Salesforce.com . . . . . . . 8
Designing a load job . . . . . . . . . . . 8
Metadata display for selected write operations . 10
Saving rejected data and error information . . . 10
Querying bulk load status . . . . . . . . 11
Designing queries to extract data from
Salesforce.com . . . . . . . . . . . . . 14
.
.
.
. 14
. 15
. 16
iii
iv
Integration Guide for IBM InfoSphere Information Server Pack for Salesforce.com
Bulk load
This type of load uses the asynchronous bulk API and is suited for jobs
that load or update a large number of data records. With this approach, the
Pack organizes the data into a comma-separated values (.csv) file format,
and then uses the HTTPS Post method to send the comma-separated
values files to Salesforce.com. Each HTTPS post can send up to 10,000 rows
or 10 MB as a maximum. When you have hundreds of thousands or
millions of input records, you can use a bulk load to improve load
performance by reducing the number of round trips between InfoSphere
DataStage and Salesforce.com.
Important: For the latest information about known limitations, problems, and
workarounds, refer to the release notes for the Pack.
Configuration prerequisites
Before you can use the IBM InfoSphere Information Server Pack for Salesforce.com,
you must install or upgrade the Pack, and enable the metadata objects in your
Salesforce.com organization to support load and extraction operations by the Pack.
Procedure
1. If you have a previous version of the Pack for Salesforce.com installed, perform
the following steps before installing Version 1.5:
a. Back up the existing Salesforce folder in case you want to revert to the
previous version of the Pack: IS_InstallDir/ASBNode/lib/java/salesforce,
Integration Guide for IBM InfoSphere Information Server Pack for Salesforce.com
Operation
Supported in the
real-time or bulk
load
Object-level
permission required
Queryable
Upsert
Both
Updateable and
Creatable
Updateable and
Creatable
Upsert requires a
unique external ID
field to be selected as
the key column.
Update
Both
Updateable
Updateable
Create
Both
Creatable
Creatable
Delete
Real-time only
Deletable
GetUpdated
Real-time only
Replicatable
GetDeleted
Real-time only
Replicatable
Field-level
permission required
Other rules
Integration Guide for IBM InfoSphere Information Server Pack for Salesforce.com
Procedure
1.
2.
3.
4.
Description
Default value
CC_JVM_OPTIONS
-Xmx1G (1 GB)
CC_MSG_LEVEL
4 (warning)
3 (information)
Example value
/tmp
Connecting to Salesforce.com
At design time, you use an Internet connection to Salesforce.com to browse for and
select the metadata from your Salesforce.com organization to be used in your job.
At run time, you use the Internet connection to Salesforce.com to load data into or
extract data from your Salesforce.com organization.
Procedure
1. Create a Pack for Salesforce.com extraction job or load job and double-click the
stage to display the stage properties.
2. Enter your Salesforce.com user name in the Username field. The format of the
user name is username@domainname.
3. Enter your Salesforce.com password in the Password field.
4. Enter the Salesforce.com URL, for example, https://www.salesforce.com/
services/Soap/u/18.0, in the URL field. The Pack supports the Salesforce API
version 18.0.
5. Optional: To use a proxy server to connect to Salesforce.com, in the Proxy
Server field, click Yes, and enter the proxy server host name, port, user name,
and password.
6. Press Enter to set your credentials.
Note: Press Enter after making any change to your login credentials or to the
URL to reset the connection options.
7. To start the connection to Salesforce.com:
a. At design time, click Browse Objects to connect to Salesforce.com.
b. At run time, the Pack for Saleforce.com connects to Salesforce.com
automatically.
Procedure
1. Define your connection properties and connect to Salesforce.com to test the
connection.
2. Click Save.
3. In the Data Connection window General tab, type a name for the connection in
the Data Connection name field. The name must begin with an alphabetic
character and can contain only alphabetic, numeric, and underscore characters.
4. Optionally, add a short description and long description for the connection.
5. Click OK.
6. In the Save Data Connection As window, navigate to and open the Job folder in
the InfoSphere DataStage repository where you want to save the connection.
Integration Guide for IBM InfoSphere Information Server Pack for Salesforce.com
7. Click Save.
Procedure
1. In the IBM InfoSphere DataStage and QualityStage Designer client, create a
Pack for Salesforce.com load or extraction job.
2. Click Load.
3. Open the Job folder where you saved the connection.
4. Select the connection, and click Open.
Procedure
1. Create a Pack for Salesforce.com load job or extraction job.
2. Enter or load your Salesforce.com login credentials and URL.
3. Select the type of operation to use:
a. For a load job, select the Write operation and then select the Access Method.
b. For an extraction job, select the Read operation. The Access Method is
disabled for the Read Operation.
4. Click Browse Objects.
5. In the Metadata Explorer window, expand the metadata objects to display the
fields and, for extract operations, the child fields of the object.
6. When you select an object, all of its fields are also selected. To select only a
subset of fields, deselect the object, and then select only the fields and child
fields you want to load or extract.
7. Click Import.
v For a Get updated delta operation, Get deleted delta operation, or a load
operation, the selected object is added to the Business Object field.
v For a Query operation or a QueryAll operation, if the SOQL Query to
Salesforce field is empty, the metadata that you selected creates a SELECT
statement in this field. If the SOQL Query to Salesforce field contains a
SELECT statement already, selecting a new object through the Metadata
Explorer does not change the existing SELECT statement. To replace an
existing SELECT statement in the SOQL Query to Salesforce field, clear the
field before you click Browse Objects to select the metadata object.
Results
To display the selected metadata object fields, click the Columns tab. Note that
Salesforce.com indicates a parent-child or child-parent relationship with a period (.)
between the object name and the field name. The Pack for Salesforce.com uses an
underscore ( _ ) to separate the object name from the field name. The Pack also
uses the description field in the column definitions to track the child-to-parent
relationship.
Integration Guide for IBM InfoSphere Information Server Pack for Salesforce.com
Procedure
1. Create a Pack for Salesforce.com load job:
a. In the IBM InfoSphere DataStage and QualityStage Designer client, create a
new parallel job.
b. In the Designer client palette, click Packs and drag the Pack for
Salesforce.com icon to the parallel canvas.
2.
3.
4.
5.
6.
c. In the Designer client palette, click File and drag a sequential file to the
parallel canvas.
d. To define the job as a load job, draw a link from the sequential file to the
Salesforce.com icon. Right-click and drag the cursor to draw the link.
Double-click the Pack for Salesforce.com stage to open the link properties.
Specify your Salesforce.com login credentials, or load them from a saved
connection file.
In the Write Operation field, select a write operation.
In the Access Method field, select either Real-time load or Bulk load.
If Bulk load is selected as the Access Method, set up the following properties:
a. In the Job ID In File field, specify whether to save the Salesforce batch ID
to a file. For each bulk load operation, Salesforce returns a unique job ID.
Select YES if the job ID needs to be saved in a file.
b. In the Job ID file name field, specify the absolute file path for saving the
Salesforce bulk load job ID.
c. In the Salesforce.com Concurrency Mode field, select a concurrency mode.
The value of this property controls whether Salesforce loads the batches
asynchronously on its backend server in either parallel or sequential mode.
(The Pack uses "sequential mode" as a synonym for the Salesforce.com
term "serial mode.") The default value is Parallel.
d. Select Keep Temporary Files to keep the temporary files that are generated
on the disk during the processing of bulk load operations.
7. Click Browse Objects to connect to Salesforce.com and select the object that
you want to load, or type the name of the object in the field.
8. Expand the object to display the fields it contains. Select the fields you want
to load.
9. Configure the batch size:
IBM InfoSphere Information Server Pack for Salesforce.com
v For a real-time load, the batch size is 1-200 and the default is 200.
v For a bulk load job, the batch size is 1-10,000. Salesforce also has the
restriction that each bulk load batch cannot have more than 10 MB of data.
Click the input field to use the arrow keys to increase or decrease the batch
size by 1, or type the value in the field.
10. To save any value as a job parameter, double-click the Use Job Parameter
column to the right of the input field.
Procedure
1. Open the Pack for Salesforce.com stage.
2. On the Reject tab, select the reject link.
3. In the Filter rejected rows based on selected conditions field, select Salesforce
Write Error Row Rejected. If you do not select this option, no data is written to
the reject file.
4. Optional: You can choose to include the error information from Salesforce.com
in the reject file. Select ERRORCODE to include Salesforce.com return codes in
the reject file. Select ERRORTEXT to include Salesforce.com error messages in
the reject file.
10
Integration Guide for IBM InfoSphere Information Server Pack for Salesforce.com
To display details about the optional error information you selected, such as
data type and length, click the Columns tab.
5. Specify the error threshold. The job ends when it reaches this threshold. You
can specify the error threshold as a raw number of input rows or as a
percentage of input rows. When you specify a percentage, you specify how
many rows of input data must be processed before the error threshold is
reached and the job ends.
v
v
v
v
From the Salesforce.com portal by selecting Setup > Administration Setup >
Monitoring > Bulk Data Load Jobs.
SFDC batch ID: Data within an SFDC job can be split into multiple batches.
Salesforce.com assigns an ID to each batch. For example: 75170000000PIHFAA4.
SFDC record ID: Salesforce.com assigns an ID to each record it processes. For
example: a0370000006dZjmAAE.
SFDC job status: When Salesforce.com processes a job, it assigns one of the
following statuses to that job: Open, Closed, Aborted, or Failed.
SFDC batch status: When Salesforce.com processes a batch, it assigns one of the
following statuses to that batch: Queued, Completed, InProgress, Failed or Not
Processed.
SFDC record status: When Salesforce.com processes a batch, it assigns one of
the following statuses to the records in the batch: Success or Failed.
11
Description
example1
example2
example3
example4
example5
To query bulk load status, you can either use an imported example job, or design a
new job.
Tip: In general, you should consider placing your bulk load jobs and associated
queries within an InfoSphere DataStage sequence job. This allows you to easily
manage the workflow between the bulk load job and the status query. Specifically,
it makes it easy for you to have the bulk load job place an SFDC job ID in a
specific file, and then provide that file directly to the status query. (Of course, other
facilities are available in sequence jobs for error handling, conditional branching,
variable substitution, and so on.) For a basic example, see example5.
Procedure
1. Import the example for the type of query that you want to use:
v For a job status query, import example1.
v For a batch status query, import example2.
v For a record status query, import example3.
2. Double-click the Pack for Salesforce.com stage to open the stage editor.
3. Select the Properties tab.
4. Specify your Salesforce.com login credentials, or load them from a saved
connection file.
5. Optional: To use a proxy server to connect to Salesforce.com, in the Proxy
Server field, click Yes, and enter the proxy server host name, port, user name,
and password.
12
Integration Guide for IBM InfoSphere Information Server Pack for Salesforce.com
6. If the SFDC job ID will be provided in a file, select Yes in the Job ID in file
field, and provide the file name in the Job ID field. Otherwise, select No in
the Job ID in file field, and provide the SFDC job ID in the Job ID field.
7. In the Sleep field, specify how frequently the Pack should check for status.
The value is specified in seconds. For example, a value of 60 will cause the
Pack to poll for status every 60 seconds.
8. In the Tenacity field, specify how long the Pack should check for status. The
value is specified in seconds. For example, a value of 1800 will cause the Pack
to stop polling for status when 1800 seconds has elapsed.
9. Close the stage editor.
10. Either modify the properties of the sequential file, as necessary, or replace the
sequential file with any other suitable stage and configure it.
11. Compile and execute the job.
Procedure
1. Export the column schemas in the Pack stages contained in example1,
example2 and example3:
a.
b.
c.
d.
e.
13
10.
11.
12.
13.
Designing queries
You use the Query or QueryAll utility calls to extract all or some of the data from
your Salesforce.com organization. You can browse for and select Salesforce.com
metadata to automatically generate the SELECT statement used in the query. You
can add filtering and sorting to the query by editing the SELECT statement.
14
Integration Guide for IBM InfoSphere Information Server Pack for Salesforce.com
Procedure
1. Create a Pack for Salesforce.com extraction job:
a. In the IBM InfoSphere DataStage and QualityStage Designer client, create a
new parallel job.
b. In the Designer client palette, click Packs and drag the Pack for
Salesforce.com icon to the parallel canvas.
c. In the Designer client palette, click File and drag a sequential file to the
parallel canvas.
d. To define the job as an extraction job, draw an output link from the
Salesforce.com icon to the sequential file. Right-click and drag the cursor to
draw the link.
2. Double-click on the Pack for Salesforce.com stage to open the link properties.
3. Specify your Salesforce.com login credentials and URL, or load them from a
saved connection file.
4. In the Read Operation field, select a read operation.
5. Click Browse Objects to select a business object for a delta extraction or to
generate an SOQL SELECT statement for a query.
6. Specify the job details:
v For delta extractions, specify an extract ID. Enter the delta start and end
times, or accept the default values.
v For queries, optionally edit the SOQL SELECT statement to add a condition
expression (WHERE clause) and sorting (ORDER BY statement).
7. Configure the job to run sequentially. Extraction jobs must run sequentially to
avoid duplicate data.
a. Click the Advanced tab.
b. In the Execution mode field, click Sequential.
8. Optional: To extract Unicode data:
a. Click the Columns tab.
b. To specify that a field contains Unicode data, click the input field under the
Extended column and select Unicode.
9. Optional: To save any value as a job parameter, double-click the Use Job
Parameters column to the right of the input field.
15
Procedure
1. Connect to Salesforce.com and select the metadata objects for the query.
2. Click the SELECT statement in the SOQL Query to Salesforce field to display
the browse button.
3. Click the browse button to open the window in which to edit the query.
4. Add any conditions and sorting to the SELECT statement, and click OK to save
your changes.
The Pack for Salesforce.com does not parse the statements in the field. Ensure
that your changes are syntactically valid.
Results
When you run the job, the Pack for Salesforce.com sends the SELECT statement in
the SOQL Query to Salesforce field to Salesforce.com. The Program Generated
Reference SOQL Query field is intended for your reference during design time,
and is not sent to Salesforce.com.
Procedure
1. Create a Pack for Salesforce.com extraction job or load job.
2. The Use Job Parameter column is to the right of the input field that you want
to save. Double-click the column.
3. Click New Parameter.
4. In the New Parameter window:
a. In the Parameter Name field, accept the default parameter name or type a
different name. When you run the job, the parameter name is replaced by a
value that you supply or by the default parameter value, if you define one.
b. In the Prompt field, type the text that is to be the label of the field in which
you supply the parameter when you run the job.
16
Integration Guide for IBM InfoSphere Information Server Pack for Salesforce.com
c. The Type field displays the default data type of this parameter. When you
run the job, the IBM InfoSphere DataStage and QualityStage Designer client
or the InfoSphere DataStage and QualityStage Director client uses the data
type to validate the parameter. Accept the default data type or select
another data type from the drop-down menu.
d. Optional: In the Default Value field, type the value that you want Designer
client or Director client to use if you do not supply a different parameter
value when you run the job.
e. Optional: In the Help Text field, type the text that you want Designer client
or Director client to display when you click Property Help in the Job
Options window when you run the job.
5. Click OK to save the parameter.
17
18
Integration Guide for IBM InfoSphere Information Server Pack for Salesforce.com
IBM
IBM
IBM
IBM
InfoSphere
InfoSphere
InfoSphere
InfoSphere
Information Analyzer
Information Services Director
Metadata Workbench
QualityStage
For information about the accessibility status of IBM products, see the IBM product
accessibility information at http://www.ibm.com/able/product_accessibility/
index.html.
Accessible documentation
Accessible documentation for InfoSphere Information Server products is provided
in an information center. The information center presents the documentation in
XHTML 1.0 format, which is viewable in most Web browsers. XHTML allows you
to set display preferences in your browser. It also allows you to use screen readers
and other assistive technologies to access the documentation.
The documentation that is in the information center is also provided in PDF files,
which are not fully accessible.
19
20
Integration Guide for IBM InfoSphere Information Server Pack for Salesforce.com
Software services
My IBM
IBM representatives
21
22
Integration Guide for IBM InfoSphere Information Server Pack for Salesforce.com
23
24
Integration Guide for IBM InfoSphere Information Server Pack for Salesforce.com
Notices
IBM may not offer the products, services, or features discussed in this document in
other countries. Consult your local IBM representative for information on the
products and services currently available in your area. Any reference to an IBM
product, program, or service is not intended to state or imply that only that IBM
product, program, or service may be used. Any functionally equivalent product,
program, or service that does not infringe any IBM intellectual property right may
be used instead. However, it is the user's responsibility to evaluate and verify the
operation of any non-IBM product, program, or service.
IBM may have patents or pending patent applications covering subject matter
described in this document. The furnishing of this document does not grant you
any license to these patents. You can send license inquiries, in writing, to:
IBM Director of Licensing
IBM Corporation
North Castle Drive
Armonk, NY 10504-1785 U.S.A.
For license inquiries regarding double-byte character set (DBCS) information,
contact the IBM Intellectual Property Department in your country or send
inquiries, in writing, to:
Intellectual Property Licensing
Legal and Intellectual Property Law
IBM Japan Ltd.
1623-14, Shimotsuruma, Yamato-shi
Kanagawa 242-8502 Japan
The following paragraph does not apply to the United Kingdom or any other
country where such provisions are inconsistent with local law:
INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS
PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER
EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS
FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or
implied warranties in certain transactions, therefore, this statement may not apply
to you.
This information could include technical inaccuracies or typographical errors.
Changes are periodically made to the information herein; these changes will be
incorporated in new editions of the publication. IBM may make improvements
and/or changes in the product(s) and/or the program(s) described in this
publication at any time without notice.
Any references in this information to non-IBM Web sites are provided for
convenience only and do not in any manner serve as an endorsement of those Web
25
sites. The materials at those Web sites are not part of the materials for this IBM
product and use of those Web sites is at your own risk.
IBM may use or distribute any of the information you supply in any way it
believes appropriate without incurring any obligation to you.
Licensees of this program who wish to have information about it for the purpose
of enabling: (i) the exchange of information between independently created
programs and other programs (including this one) and (ii) the mutual use of the
information which has been exchanged, should contact:
IBM Corporation
J46A/G4
555 Bailey Avenue
San Jose, CA 95141-1003 U.S.A.
Such information may be available, subject to appropriate terms and conditions,
including in some cases, payment of a fee.
The licensed program described in this document and all licensed material
available for it are provided by IBM under terms of the IBM Customer Agreement,
IBM International Program License Agreement or any equivalent agreement
between us.
Any performance data contained herein was determined in a controlled
environment. Therefore, the results obtained in other operating environments may
vary significantly. Some measurements may have been made on development-level
systems and there is no guarantee that these measurements will be the same on
generally available systems. Furthermore, some measurements may have been
estimated through extrapolation. Actual results may vary. Users of this document
should verify the applicable data for their specific environment.
Information concerning non-IBM products was obtained from the suppliers of
those products, their published announcements or other publicly available sources.
IBM has not tested those products and cannot confirm the accuracy of
performance, compatibility or any other claims related to non-IBM products.
Questions on the capabilities of non-IBM products should be addressed to the
suppliers of those products.
All statements regarding IBM's future direction or intent are subject to change or
withdrawal without notice, and represent goals and objectives only.
This information is for planning purposes only. The information herein is subject to
change before the products described become available.
This information contains examples of data and reports used in daily business
operations. To illustrate them as completely as possible, the examples include the
names of individuals, companies, brands, and products. All of these names are
fictitious and any similarity to the names and addresses used by an actual business
enterprise is entirely coincidental.
COPYRIGHT LICENSE:
This information contains sample application programs in source language, which
illustrate programming techniques on various operating platforms. You may copy,
modify, and distribute these sample programs in any form without payment to
26
Integration Guide for IBM InfoSphere Information Server Pack for Salesforce.com
Trademarks
IBM, the IBM logo, and ibm.com are trademarks or registered trademarks of
International Business Machines Corp., registered in many jurisdictions worldwide.
Other product and service names might be trademarks of IBM or other companies.
A current list of IBM trademarks is available on the Web at www.ibm.com/legal/
copytrade.shtml.
The following terms are trademarks or registered trademarks of other companies:
Adobe is a registered trademark of Adobe Systems Incorporated in the United
States, and/or other countries.
Intel and Itanium are trademarks or registered trademarks of Intel Corporation or
its subsidiaries in the United States and other countries.
Linux is a registered trademark of Linus Torvalds in the United States, other
countries, or both.
Microsoft, Windows and Windows NT are trademarks of Microsoft Corporation in
the United States, other countries, or both.
UNIX is a registered trademark of The Open Group in the United States and other
countries.
Java and all Java-based trademarks and logos are trademarks or registered
trademarks of Oracle and/or its affiliates.
The United States Postal Service owns the following trademarks: CASS, CASS
Certified, DPV, LACSLink, ZIP, ZIP + 4, ZIP Code, Post Office, Postal Service, USPS
and United States Postal Service. IBM Corporation is a non-exclusive DPV and
LACSLink licensee of the United States Postal Service.
Other company, product or service names may be trademarks or service marks of
others.
27
28
Integration Guide for IBM InfoSphere Information Server Pack for Salesforce.com
Index
B
bulk load
Salesforce.com
11, 12, 13
trademarks
list of 25
C
CC_JVM_OPTIONS 5
CC_MSG_LEVEL 5
connection to Salesforce.com,
resetting 5
starting 5
customer support
contacting 21
Metadata Explorer
load operation 10
metadata requirements
delta extraction operations
load operations 3
U
3
O
Object field, metadata requirement 3
overview, Pack for Salesforce.com 1
D
delta extraction
default time frame 14
metadata requirements 3
E
environment variables
CC_JVM_OPTIONS 5
CC_MSG_LEVEL 5
setting for Salesforce.com 5
SF_BULKLOAD_TEMPDIR 5
error code from Salesforce.com 10
error message from Salesforce.com 10
error threshold, Salesforce.com load
operation 10
externalID field, metadata requirement 3
extractId field, metadata requirement 3
extraction job
designing 15
H
HTTPS requirement
I
installation prerequisites 2
Internet access requirement 2
J
job parameter
run time 16
L
lastextracttime field, metadata
requirement 3
legal notices 25
load operation
metadata object display 10
Copyright IBM Corp. 2007, 2013
P
parameter, job run time 16
privilege level 2
processing variable, defining
product accessibility
accessibility 19
product documentation
accessing 23
proxy servers 2
16
R
reject link
10
S
Salesforce.com
connections and sessions 4
environment variables 5
querying bulk load status 11, 12, 13
Salesforce.com connection properties
configuring 5
loading design-time 7
saving design-time 6
Salesforce.com Pack
Metadata Explorer 7
metadata, browsing and selecting 7
parent-child relationship indicator 7
session ID
Salesforce.com 4
SF_BULKLOAD_TEMPDIR 5
software services
contacting 21
SOQL statement,
generating automatically 7
support
customer 21
29
30
Integration Guide for IBM InfoSphere Information Server Pack for Salesforce.com
Printed in USA
SC19-3875-00