SnapLogic Salesforce Snap Reference

Transcription

1 SnapLogic Salesforce Snap Reference Document Release: October 2012 SnapLogic, Inc. 71 East Third Avenue San Mateo, California U.S.A.

2 Copyright Information 2012 SnapLogic, Inc. All Rights Reserved. Terms and conditions, pricing, and other information subject to change without notice. SnapLogic and SnapStore are among the trademarks of SnapLogic, Inc. All other product and company names and marks mentioned are the property of their respective owners and are mentioned for identification purposes only. SnapLogic is registered in the U.S. and Trademark Office

3 Table of Contents SnapLogic Salesforce Snap Reference 1 Table of Contents 3 Preface 7 Salesforce Snap Salesforce Snap Salesforce Java Snap Salesforce Java Snap What Are Snaps? 8 About SnapLogic 8 About This Guide 8 Overview 9 Time Zone Handling 9 Salesforce Wizard Properties 11 Properties 12 Views 13 Developing with SnAPI 13 Salesforce Connection Properties 15 Views 18 Developing with SnAPI 18 SOQL Query Reader Properties 19 Views 21 Preview 21 s 21 Developing with SnAPI

4 SnapLogic Salesforce Snap Reference Object Read Properties 23 Views 25 Preview 25 s 25 Developing with SnAPI 26 Create Properties 27 Views 29 Preview 29 Developing with SnAPI 29 Delete Properties 31 Views 33 Preview 33 Developing with SnAPI 33 Lookup Properties 36 Views 39 Preview 39 s 39 Developing with SnAPI 40 Salesforce Undelete Properties 41 Views 42 Preview 42 Developing with SnAPI

5 Table of Contents Update Properties 43 Views 45 Preview 45 Developing with SnAPI 45 Upsert Properties 47 Views 49 Preview 50 Developing with SnAPI

6 SnapLogic Salesforce Snap Reference - 6 -

7 4 Preface The Salesforce Snap Reference is a listing of all the Components that come packaged with the Salesforce Snap. The Python Salesforce Snap was deprecated with the release of SnapLogic and replaced with the Salesforce Java Snap 1.5. The Python Snap functionality has been preserved. Salesforce Snap 1.8 The Salesforce Java Snap 1.8 focused on improving the quality of the Snap. In addition, the following feature was added: Batch Sizes are now configurable on the Components Salesforce Snap 1.7 The Salesforce Java Snap 1.7 added the following features: Asynchronous mode support was added to the Create, Delete, Update, and Upsert Components. The Undelete Component property of Batch Size now only lets you select a value of 200. This version of the Snap works with 3.4 and Salesforce Java Snap 1.6 The Salesforce Java Snap 1.6 added the following features: Performance improvements by multi-threading batch reads in SOQL Read, Object Read and LookUp component. Performance improvements in LookUp and SOQL Read component (when using an input view) by rewriting the query to allow multiple records being fetched at once for several input records to reduce component execution time and number of API calls. Enhanced SOQL Read and LookUp component output view generation to allow generation of output fields from functions and aliases in the SELECT clause. SOQL Read and lookup component allow generation of input view in case a WHERE clause is defined that contains input variables. As an example the query Select count(id)ct from Account where LastModifiedDate < ${curdate} will generate an input view providing the curdate field of type date and an output view providing the Ct field of type number. Lookup component allows to define a SOQL query similar to the SOQL Read component

8 SnapLogic Salesforce Snap Reference All remaining components got enhanced in regards to validation, suggest and error handling functionality to allow verification/generation of the in-/output views on the Components. This version of the Snap works with 3.4 and Salesforce Java Snap 1.5 The Salesforce Java Snap 1.5 added the following features: Performance improvements using multi-threaded reads in the Object Read Component. API call reduction in wizards and Components by caching metadata and connections for the duration of the process/pipeline execution. SOQL query builder that allows to build queries using drop-down functionality. This version of the Snap works with What Are Snaps? Snaps are Components that enrich the existing product functionality. About SnapLogic SnapLogic is a data integration platform with an innovative, open, and extensible data flow architecture and straightforward subscription model. SnapLogic connects to almost any SaaS, Cloud, Web, or enterprise application or data source via Snaps and Pipelines, providing information as a utility to business users and applications. SnapLogic is an alternative to closed, proprietary, client/server based integration solutions and the massive amount of hand coding still being done to accomplish data integration in the marketplace today. About This Guide This manual is a reference guide for Snaps. This guide lists their properties and attributes, along with any administrative instructions. The content in this manual is addressed to data integration developers using either the SnapLogic Designer or SnAPI

9 5 Overview The Salesforce Snap consists of a wizard (as of version 1.6) and the following Components: Salesforce Connection - used by other Salesforce Components to allow their binding against a specific Salesforce connection. Salesforce Query Reader (SOQL Query Builder) - provides Salesforce object query language (SOQL) functionality to retrieve object records from Salesforce. Salesforce Object Reader - provides Salesforce object retrieval functionality by defining the Salesforce object name. Salesforce Create - create object records in Salesforce. Salesforce Delete - delete object records in Salesforce. Salesforce Lookup - lookup object records in Salesforce. Salesforce Undelete - reverse the deletion of object records in Salesforce. Salesforce Update - update object records in Salesforce. Salesforce Upsert - upsert object records in Salesforce. Time Zone Handling Date and time are stored in Salesforce in GMT. When the Salesforce Snap extracts the data from Salesforce, the Snap converts it using the time zone of the system running the SnapLogic Server or Sidekick. For example, a T00:05:17.000Z create time stamp for an object in Salesforce will be converted to :05:17.0 using the system's PST time zone. Windows and UTC Time Zones Windows supports four different UTC Time Zones: UTC UTC/London UTC/Monrovia, Reykjavik UTC/Caracas. When switching between the time zones UTC/Monrovia, Reykjavik and UTC, the Windows system time won't change but the Java time conversion will treat both time zones differently. UTC/Monrovia, Reykjavik has an 4:30 hour offset, which will be visible when creating the objects using UTC/Monrovia, Reykjavik time zone and then attempting to read the objects out - 9 -

10 SnapLogic Salesforce Snap Reference with setting to the UTC time zone. This then will produce the 4:30 hour offset in the Designer when using any of the read components. Note: Changing the system's time zone requires a restart of the Java CC/Sidekick

11 6 Salesforce Wizard This Component provides the ability to retrieve objects from Salesforce and creates Snap- Logic Components (such as SOQLRead, Create, Upsert, etc.) for each object in the library. As an example: Selecting the Account object will create the Components in the library folder /Salesforce/Main/Account. There the SOQLRead, ObjectRead, Create, Upsert and Update Component will be created that use the Account object. The Component requires either an existing connection reference or allows creating a new connection to a Salesforce account. Note: This functionality is available as of version 1.6 of the Salesforce Snap. The initial step allows to select or create a Salesforce connection. Step 0 a) I already have a connection resource This allows you to choose an existing connection from the library by selecting the database icon on the right hand of the Reference to Salesforce Connection property field. Step 0 b) I would like to create a new connection This allows you to create a new connection by setting the connection properties as defined in the Salesforce connection component page. You can define a folder in the Library where connection will be created during the wizard process. Step 1: Setting the creation properties Properties Folder in Library where resources will be created: This property allows you to define the root folder in the library where all Components will be created. The path is relative and does not include the server url. /Salesforce /Salesforce String BaseFolder Objects pre-selected for resource creation: This property allows you to define if all objects of the Salesforce

12 SnapLogic Salesforce Snap Reference account should initially be selected for creation or not. You can manually modified the selection in Step 2. None (manually select) All (manually deselect) LOV initially_selected Resource Creation Settings This property allows you to define if existing resources in the library with the same name should be overwritten or being skipped during wizard execution. Overwrite resource if exists. Skip creation if resource exists. LOV ResourceExists Step 2: Selecting the objects from Salesforce This step allows you to select the objects from Salesforce that are going to be created as Components in the library. Properties Confirm selection of objects for resource creation This property allows to select the objects from Salesforce. The list contains all objects that are available on the Salesforce account. You can manually select or de-select the objects that are going to be created as Components in the Library. Account = LOV LOV sobjs_to_install

13 Salesforce Wizard Step 3: Finalizing the creation This step allows you to execute the Component creation by clicking Finish. The wizard will run for some time, depending on how many objects were selected. You can use the Components for each selected object in the library once the wizard finished. See General Information for basic properties common to all Components and Pipelines. Views Inputs This Component does not have an input view. Outputs This Component does not have an output view. Pass-Through This Component does not support pass-through. Developing with SnAPI Identifier Java Component: com.salesforce.components.wizard

14 SnapLogic Salesforce Snap Reference

15 7 Salesforce Connection This Component provides the ability to connect to Salesforce. The Component is used as a reference in all Salesforce Components to allow them access to a specific Salesforce account. Properties API Token The API token is optional and is only needed in the case that the access is requested from a non-trusted IP address. The request would be issued from where the SnapLogic Server/Sidekick is installed. For more details please refer to: Salesforce API Concepts and Security. qwiueoqwe qwedip No Null String token Force Login? This property allows to force the creation of a new connection for each request. Internally all Salesforce Components retrieve the connection from a connection pool to increase performance and to reduce the number of API calls against Salesforce during Component execution. Per default this option is set to false which allows the Component to retrieve the connection from the pool. In some cases a new connection is needed to retrieve updated metadata from the Salesforce account. This may apply for cases where updates were made to Salesforce object definitions and the existing object definition in the Components in/output views became stale. For these cases the force login can be set to true but requires to update the in/output views of the affected Components using the Suggest functionality. False False

16 SnapLogic Salesforce Snap Reference Boolean force_login Salesforce Objects This property stores the metadata of the Salesforce account by pressing the Suggest button. The definition is obfuscated and used internally for the query builder functionality that is provided by the SOQL Query Reader Component and should not be modified by the user. Internal Use only No Internal Use only Json SalesForce Objects Salesforce EndPoint This property defines the end point for the Salesforce account against which the SOAP requests will be executed. In case you are working with a test account you can change the endpoint to, for example For more details please refer to Identity and Service providers. String endpoint Salesforce Password This property defines the password for the Salesforce account. The password is obfuscated. abc Null String password

17 Salesforce Connection Salesforce Username This property defines the user name for the Salesforce account. abc Null String username Advanced Properties This property defines advanced properties for the connection Maximum queue size This property defines the maximum number of response locators that can be stored internally while continuing to submit requests to SalesForce. This property is only used when the delete/create/update or upsert component are set to use a batch size Non Zero Non Negative Number MaxQueueSize Response polling interval This property defines the response polling interval. Starting with each interval a request is made against SalesForce to determine if the response for the request has been execurted on the SalesForce account. This property is only used when the delete/create/update or upsert component are set to use a batch size. 10 Non Zero Non Negative Number. The value is expected as seconds. PollingInterval Retry maximum attempts This property defines the retry capability of the connection in case a session timeout exception is received from SalesForce. When receiving such exception another attempt can be made to execute the operation

18 SnapLogic Salesforce Snap Reference 1 3 The value of this property defines how many attempts are being made prior to failing execution Non Zero Non Negative Number MaxRetry Retry sleep interval This property defines the retry sleep interval in seconds inbetween the retry attempts in case a session timeout exception is received from SalesForce. When receiving such exception another attempt can be made to execute the operation. The value of this property defines how much time shall be waited before executing another attempt. Non Zero Non Negative Number. The value is expected as seconds. SleepInterval See General Information for basic properties common to all Components and Pipelines. Views Inputs This Component does not have an input view. Outputs This Component does not have an output view. Pass-Through This Component does not support pass-through. Developing with SnAPI Identifier Java Component: com.salesforce.components.connection

19 8 SOQL Query Reader This Component provides the ability to retrieve object records from Salesforce using a SOQL query. The component requires the definition of a connection resource. To define a connection resource reference you need to have one defined in the Library or need to instantiate one using the Foundry, define its properties, save it and then select it from or drag it from the Library into the SOQLRead Component's References property section. Properties Batch Size Large record sets require reads in so called batches. Each batch read requires an API call against Salesforce to retrieve the set of records. Increasing the batch size will increase the amount of memory used during retrieval. Decreasing the batch size will increase the number of API calls against Salesforce. Set to 500 or lower for synchronous execution; set to more than 500 but less than or equal to 2000 for asynchronous. 500 Currently the property definition is not verified if the values are within the given boundaries. They will however be converted into the defined minimum/maximum values during the API call by Salesforce if the definitions are outside of the boundaries. 500 Number batch_size Include Deleted Salesforce allows to retain deleted records in a recycle bin. The deleted records can be retrieved as long as they reside in the recycle bin. For more details please refer to Salesforce's recycle bin. You

20 SnapLogic Salesforce Snap Reference need to set this option to true if you want to retrieve deleted records from the recycle bin and include them in the output view. Each Salesforce object has an attribute "IsDeleted" which indicates if the record was deleted previously. Hint: The Undelete Component can be used to reverse the delete operation of a record. True False Boolean include_deleted 1 4 Number of threads The Component can issue multiple batch request against Salesforce by running multiple threads concurrently. A thread number setting of one will preserve the order of the objects as their order is defined in Salesforce. A thread number setting larger then one will not preserve the order. Increasing the thread number will increase the memory consumption of the Component. Please refer to the memory guide to understand the implications. String number SOQL Query This property allows to define the SOQL query. A query builder can be launched with CTRL+Space. The query builder will provide attributes and query expressions in a drop down box. You can use the Suggest method to generate the output view of the Component once the query has been defined. Select count(id)ct from Account null String soql_query

21 SOQL Query Reader SObject This property allows you to define the name of the Salesforce object, such as Account. You can use this property to fully generate the SOQL query from the object name using the Suggest button once the object name has been defined. You can also use the Suggest button without defining the object name, this will then populate the dropdown list of the property value with available object names on the Salesforce account. Account No null String s_object See General Information for basic properties common to all Components and Pipelines. Views Inputs The Component allows the definition of a single optional input view. The input view can in some case be suggested from the SOQL query if variables are defined in the where clause. The input view is optional, meaning the component can be executed without it. In the case an input view is defined, one or more fields from the input view can be used in the SOQL Query such as " Select Id From Account where LastModifiedDate > ${MyInputDateField}". MyInputDateField then needs to exist as a field in the input view definition. Outputs This Component allows the definition of a single output view. The output view can be suggested from the SOQL query. Pass-Through This Component supports pass-through. Preview The preview functionality allows to preview a sample of the SOQL query once the output view has been defined. s Use Case in Designer The following example allows you to read a sample from a Salesforce account and preview its data using the SOQL Read Component

22 SnapLogic Salesforce Snap Reference You will need to have access to a Salesforce account to be able to specify the Salesforce connection. 1. Create a SOQL Read Component from the Foundry. 2. In the SOQL Read Component properties section, specify the SQL Statement property as Select count(id)ct from Account. 3. Specify the Connection Resource by selecting the database icon on the right hand of the reference property field (The reference property is defined on the top of the Properties tab). This will allow you to browse for a Salesforce connection resource of your choice. You can also define the property by providing the URL of the connection resource directly, such as /sfconnection/mysfconnection, which then is to be expected to exist in the root folder of your Library. 4. Validate the component by clicking Validate. This will validate the referenced connection and ensure a connection to Salesforce can be established. A full query syntax validation is currently not supported. Salesforce will validate the query during query execution and return any errors back to the designer. 5. Click Suggest. This will generate the output view. The count(id)ct field name will be resolved into the output field name Ct since this is the alias name for the field in the query. Expected fields are: Ct of type Number 6. Save the Component by clicking Save. 7. Preview the data by using the preview functionality. Developing with SnAPI Identifier Java Component: com.salesforce.components.soqlread

23 9 Object Read This Component provides the ability to retrieve all records for all fields of the Salesforce object from Salesforce by defining the Salesforce object name. The Component requires the definition of a connection resource. To define a connection resource reference you need to have one defined in the Library or need to instantiate one using the SFoundry, define its properties, save it and then select it from or drag it from the Library into the SOQLRead Component's 'References' property section. Properties 500 Batch Size Large record sets require reads in so called batches. Each batch read requires an API call against Salesforce to retrieve the set of records. Increasing the batch size will increase the amount of memory used during retrieval. Decreasing the batch size will increase the number of API calls against Salesforce. Set to 500 or lower for synchronous execution; set to more than 500 but less than or equal to 2000 for asynchronous. A minimum batch size is 200 which is defined by Salesforce. The maximum batch size depends on the amount of object attributes retrieved from Salesforce and can not exceed Currently the property definition is not verified if the values are within the given boundaries. They will however be converted into the defined minimum/maximum values during the API call by Salesforce if the definitions are outside of the boundaries. 500 Number batch_size

24 SnapLogic Salesforce Snap Reference Include Deleted Salesforce allows to retain deleted records in a recycle bin. The deleted records can be retrieved as long as they reside in the recycle bin. For more details please refer to Salesforce's recycle bin. You need to set this option to true if you want to retrieve deleted records from the recycle bin and include them in the output view. Each Salesforce object has an attribute "IsDeleted" which indicates if the record was deleted previously. Hint: The Undelete Component can be used to reverse the delete operation of a record. True False Boolean include_deleted 1 4 Number of threads The Component can issue multiple batch request against Salesforce by running multiple threads concurrently. A thread number setting of one will preserve the order of the objects as their order is defined in Salesforce. A thread number setting larger then one will not preserve the order. Increasing the thread number will increase the memory consumption of the Component. Please refer to the memory guide to understand the implications. String number SObject This property allows to define the name of the Salesforce object, such as Account. You can use the Suggest button without defining the object name, this will then populate the drop-down list of the property value with available object names on the Salesforce account. Account null String s_object

25 Object Read See General Information for basic properties common to all Components and Pipelines. Views Inputs This Component does not allow an input view. Outputs This Component allows the definition of a single output view. The output view can be suggested from the object name. Pass-Through This Component does not support pass-through. Preview The preview functionality allows to preview a sample of the records on the object once the output view has been defined. s Use Case in Designer The following example allows you to read a sample from the Salesforce account object and preview its data using the Object Read Component. You will need to have access to a Salesforce account to be able to specify the Salesforce connection. 1. Create an Object Read Component from the Foundry. 2. In the Object Read Component properties section, specify the SObject property as Account. 3. Specify the Connection Resource by selecting the database icon on the right hand of the reference property field (The reference property is defined on the top of the Properties tab). This will allow you to browse for a Salesforce connection resource of your choice. You can also define the property by providing the URL of the connection resource directly, such as /sfconnection/mysfconnection, which then is to be expected to exist in the root folder of your Library. 4. Validate the Component by clicking Validate. This will validate the referenced connection and ensure a connection to Salesforce can be established. It will further validate that a) the specified object exists on the SalesForce account and b) the columns that are defined on the output view match all columns (in name and data type) that are defined for the Salesforce object

26 SnapLogic Salesforce Snap Reference 5. Click Suggest. This will generate the output view. The Account object name will be resolved and all fields on the object will be created as output field names on the output view. 6. Save the Component by clicking Save. 7. Preview the data by using the preview functionality. Developing with SnAPI Identifier Java Component: com.salesforce.components.objectread

27 10 Create This Component provides the functionality to create object records in Salesforce. The Component requires the definition of a connection resource. To define a connection resource reference you need to have one defined in the Library or need to instantiate one using the Foundry, define its properties, save it and then select it from or drag it from the Library into the SOQLRead Component's 'References' property section. The Component supports two modes (starting with version 1.7, prior to 1.7 only synchronous mode was supported): Synchronous and Asynchronous: The synchronous mode can be enabled by setting the Batch Size value to less than or equal to 200. The Component will then attempt to create that number of objects in Sales- Force for a single batch execution before it submits the next batch. The asynchronous mode can be enabled by setting the Batch Size value more than 200 but less than or equal to The Component will attempt to create that number of objects in SalesForce per batch execution. The Component will continue to submit batches to SalesForce while waiting asynchronously for the response of each batch execution. The component will start writing records to the output view once the first response is received from SalesForce. Properties Batch Size Large record sets require writes in so called batches. Each batch write requires an API call against Salesforce to write the set of records. You can set this value up to Set to 200 or lower for synchronous execution; set to more than 200 but less than or equal to for asynchronous. 200 Number batch_size

28 SnapLogic Salesforce Snap Reference Insert Null Values You can enable this option if null values need to be set for fields that have no value definition. True False Boolean quit_on_error Quit on error An error during the create operation will be logged if any exception occurred. In addition the output view will provide information about all object id's that either failed or succeeded the create operation. You can set this option to true so that the execution of writes that follow the failed write operation will be terminated. True False Boolean insert_null_values Related Objects A write operation of a Salesforce object might contain related objects whose id's need to be included in the record information. As an example the Account object requires the Owner Id which needs to exist in the User object. You can use the Suggest button to populate this property. OwnerId Null LOV related_objects SObject This property allows to define the name of the Salesforce object, such as Account. You can use the Suggest button without defining the object name, this will then populate the drop-down list of the

29 Create property value with available object names on the Salesforce account. Account Null String s_object See General Information for basic properties common to all Components and Pipelines. Views Inputs The component allows the definition of a single input view. The input view can be generated using the Suggest button. The defined SObject name will be used to retrieve the metadata of the object from Salesforce to generate the corresponding input fields on the input view. The input fields will then represent valid field names and data types. As an example, the following SObject name Account would result in an input view with all the required fields of type createable for the Account object. Modifying the input view manually should be avoided. The validation functionality will ensure the input view is correctly defined. Outputs The Component has one predefined output view which allows the determination of success or failure for object id's that were created or attempted to be created. You can use this output view to handle errors or success criteria for the records by defining post processing Components. Pass-Through This Component supports pass-through. Preview The preview functionality is only supported within the context of a Pipeline using the Pipeline preview mechanism. Developing with SnAPI Identifier Java Component: com.salesforce.components.create

30 SnapLogic Salesforce Snap Reference

31 11 Delete This Component provides the functionality to delete object records in Salesforce. The Component requires the definition of a connection resource. To define a connection resource reference you need to have one defined in the Library or need to instantiate one using the Foundry, define its properties, save it and then select it from or drag it from the Library into the SOQLRead Component's 'References' property section. The component supports two modes (Starting with version 1.7, prior to 1.7 only synchronous mode was supported): Synchronous and Asynchronous: The synchronous mode can be enabled by choosing 200 as the batch size value. The component will then attempt to delete 200 objects in SalesForce for a single batch execution before it submits the next batch. The asynchronous mode can be enabled by choosing as the batch size value. The component will attempt to delete objects in SalesForce per batch execution. The component will continue to submit batches to SalesForce while waiting asynchronously for the response of each batch execution. The component will start writing records to the output view once the first response is received from SalesForce. Note: A potential issue with the asynchronous mode occurs when dealing with exceptions that contain non-escaped characters in the returned exception from SalesForce, such as ampersand (&). This issue occurs when attempting to delete an object P that contains references to other objects R. In the case that P has nonescaped characters in its object name then exception can not be parsed and the component will throw an exception. Properties Batch Size Large record sets require writes in so called batches. Each batch delete requires an API call against Salesforce to delete the set of records. You can set this value up to Set to 200 or lower for synchronous execution; set to more than 200 but less than or equal to for asynchronous

32 SnapLogic Salesforce Snap Reference 200 Number batch_size Delete forever You can enable this option if you want to permanently delete the records without retaining them in the recycle bin. For more details please refer to Salesforce's recycle bin. True False Boolean insert_null_values Quit on error An error during the delete operation will be logged if any exception occurred. In addition the output view will provide information about all object id's that either failed or succeeded the delete operation. You can set this option to true so that the execution of deletes that follow the failed delete operation will be terminated. True False Boolean insert_null_values SObject This property must be defined when using the component in asynchrous mode. In synchronous mode the property is optional and will be ignored. It defines the name of the Salesforce object, such as Account. You can use the Suggest button without defining the object name, this will then populate the drop-down list of the property value with available object names on the Salesforce account. Account (asynchronous), No (synchronous) Null

33 Delete String s_object See General Information for basic properties common to all Components and Pipelines. Views Inputs The input view is predefined and provides the Id field. The Id of the object identifies the object record in Salesforce deleted during Component execution. Outputs The Component has one predefined output view which allows the determination of success or failure for object id's that were deleted or attempted to be deleted. You can use this output view to handle errors or success criteria for the records by defining post processing Components. Pass-Through This Component supports pass-through. Preview The preview functionality is only supported within the context of a Pipeline using the Pipeline preview mechanism. Developing with SnAPI Identifier Java Component: com.salesforce.components.delete

34 SnapLogic Salesforce Snap Reference

35 12 Lookup This Component provides the ability to retrieve object records from Salesforce by using a SOQL query with a whereclause. The whereclause can be configured to support the substitution of the predicates with values of input records during Component execution. As an example the query Select Id, Owner.Id from Account where Owner.Id = ''${ownerid)will allow to use values of the input record field ownerid at execution time. The input records coming into the Salesforce LookUp component might contain values such as ownerid= ['005A ixsZIAO','005A ixsZIBO',...]at runtime. The query will then be executed as Select Id, Owner.Id from Account where Owner.Id = '005A ixsZIAO' or Owner.Id = '005A ixsZIBO' or...depending on what the value of the input record field ownerid is for each incoming record. The Component allows you to define the following policies for exception cases. 1. If no rows match: This option allows the handling of no rows being returned for a query. In the above example, if Select Id, Owner.Id from Account where Owner.Id = '005A ixsZIAO' is being executed for an incoming record but the User object does not contain any entry for the id '005A ixsZIAO', then you need to define one of the two options: Fail or Ignore. Fail: In this case, the Component will fail during execution and discontinue any further processing. Ignore: In this case, the Component will skip the incoming record and not create an output record for it. 2. If multiple rows match: This option allows the handling of multiple rows being returned for a query. In the above example, if Select Id, Owner.Id from Account where Owner.Id = '005A ixsZIAO' is being executed for an incoming record and multiple rows are being returned from Salesforce for this query (which is unlikely in this case, since Id is unique), then you need to define one of the four options: Skip, Fail, Accept first record only or Accept all records. Fail: In this case, the Component will fail during execution and discontinue any further processing. Skip: In this case, the Component will skip the incoming record and not create an output record. Accept first record only: In this case, the Component will only accept the first the row of the query result and create an output record on the output

36 SnapLogic Salesforce Snap Reference Accept all records: In this case, the Component will accept all rows of the query result and create a new output record for each row. The Component requires the definition of a connection resource. To define a connection resource reference you need to have one defined in the Library or need to instantiate one using the Foundry, define its properties, save it and then select it from or drag it from the Library into the SOQLRead Component's 'References' property section. Properties Batch Size Large record sets require reads in so called batches. Each batch read requires an API call against Salesforce to retrieve the set of records. Increasing the batch size will increase the amount of memory used during retrieval. Decreasing the batch size will increase the number of API calls against Salesforce. A minimum batch size is 200 which is defined by Salesforce. Set to 500 or lower for synchronous execution; set to more than 500 but less than or equal to 2000 for asynchronous. 500 The maximum batch size depends on the amount of object attributes retrieved from Salesforce and can not exceed Currently the property definition is not verified if the values are within the given boundaries. They will however be converted into the defined minimum/maximum values during the API call by Salesforce if the definitions are outside of the boundaries. 500 Number batch_size If multiple rows match This property defines the handling of cases where multiple rows are being retrieved during query execution. Keep in mind that each incoming record will result in a query execution using the values of the input record. The available options are Fail, Skip, Accept first record only, Accept all records. Fail: In this case the component will fail during execution and discontinue any further processing

37 Lookup Skip: In this case the component will skip the incoming record and not create an output record. Accept first record only: In this case the component will only accept the first the row of the query result and create an output record on the output. Fail Accept all records: In this case the component will accept all rows of the query result and create a new output record for each row. Accept first record only LOV MultipleRowsPolicy If no rows match This property defines the handling of cases where no rows are being retrieved during query execution. Keep in mind that each incoming record will result in a query execution using the values of the input record. The available options are Fail and Ignore. Ignore Fail LOV Fail: In this case the Component will fail during execution and discontinue any further processing. Ignore: In this case the Component will skip the incoming record and not create an output record. IgnoreMultipleRows Include Deleted Salesforce allows to retain deleted records in a recycle bin. The deleted records can be retrieved as long as they reside in the recycle bin. For more details please refer to Salesforce's recycle bin. You need to set this option to true if you want to retrieve deleted records from the recycle bin and include them in the output view. Each Salesforce object has an attribute "IsDeleted" which indicates if the record was deleted previously. Hint: The Undelete Component can be used to reverse the delete

38 SnapLogic Salesforce Snap Reference operation of a record. True False Boolean include_deleted 1 4 Number of threads The Component can issue multiple batch request against Salesforce by running multiple threads concurrently. A thread number setting of one will preserve the order of the objects as their order is defined in Salesforce. A thread number setting larger then one will not preserve the order. Increasing the thread number will increase the memory consumption of the component. Please refer to the memory guide to understand the implications. String number SOQL Query This property allows to define the SOQL query. A query builder can be launched with CTRL+Space. The query builder will provide attributes and query expressions in a drop- down box. You can use the Suggest method to generate the output view of the Component once the query has been defined. Select count(id)ct from Account null String soql_query SObject This property allows to define the name of the Salesforce object, such as Account. You can use this property to fully generate the SOQL query from the object name using the Suggest button once the object name has been defined. You can also use the Suggest button

39 Lookup without defining the object name, this will then populate the dropdown list of the property value with available object names on the Salesforce account. Account No null String s_object See General Information for basic properties common to all Components and Pipelines. Views Inputs The component allows the definition of a single optional input view. The input view can in some case be suggested from the SOQL query if variables are defined in the where clause. The input view is optional, meaning the component can be executed without it. In the case an input view is defined, one or more fields from the input view can be used in the SOQL Query such as " Select Id FROM ACCOUNT where LastModifiedDate > ${MyInputDateField}". MyInputDateField then needs to exist as a field in the input view definition. Outputs This Component allows the definition of a two output views. The output views can be suggested from the SOQL query. The matched output view will contain all records that satisfy the lookup condition, The unmatched output view will provide the records that do not satisfy the lookup condition. Pass-Through This Component supports pass-through. Preview The preview functionality allows to preview a sample of the SOQL query once the output view has been defined. You need to use the Pipeline preview functionality if you define an input view (using a where clause in the SOQL query). s Use Case in Designer The following example allows you to read a sample from a Salesforce account and preview its data using the LookUp Component. You will need to have access to a Salesforce account to be able to specify the Salesforce connection

40 SnapLogic Salesforce Snap Reference 1. Create a LookUp Component from the Foundry. 2. In the LookUp Component properties section, specify the SOQL Query property as Select count(id)ct from Account where LastModifiedDate < :00: Specify the Connection Resource by selecting the database icon on the right hand of the reference property field (The reference property is defined on the top of the Properties tab). This will allow you to browse for a Salesforce connection resource of your choice. You can also define the property by providing the URL of the connection resource directly, such as /sfconnection/mysfconnection, which then is to be expected to exist in the root folder of your Library. 4. Validate the Component by clicking Validate. This will validate the referenced connection and ensure a connection to Salesforce can be established. A full query syntax validation is currently not supported. Salesforce will validate the query during query execution and return any errors back to the designer. 5. Click Suggest. This will generate the output view. The count(id)ct field name will be resolved into the output field name Ct since this is the alias name for the field in the query. Expected fields are: Ct of type Number 6. Save the Component by clicking Save. 7. Preview the data by using the preview functionality. Developing with SnAPI Identifier Java Component: com.salesforce.components.lookup

41 13 Salesforce Undelete This Component provides the functionality to undelete object records in Salesforce. The Component requires the definition of a connection resource. To define a connection resource reference you need to have one defined in the Library or need to instantiate one using the Foundry, define its properties, save it and then select it from or drag it from the Library into the SOQLRead component's 'References' property section. Properties 200 Batch Size Large record sets require writes in so called batches. Each batch undelete requires an API call against Salesforce to write the set of records. You can set this value up to Set to 200 or lower for synchronous execution; set to more than 200 but less than or equal to for asynchronous. 200 Number batch_size Quit on error An error during the undelete operation will be logged if any exception occurred. In addition the output view will provide information about all object id's that either failed or succeeded the undelete operation. You can set this option to true so that the execution of undeletes that follow the failed undelete operation will be terminated. True False

42 SnapLogic Salesforce Snap Reference Boolean insert_null_values See General Information for basic properties common to all Components and Pipelines. Views Inputs The input view is predefined and only provides the Id field. The Id of the object identifies the object record in Salesforce which is going to be restored from the recycle bin. Outputs The Component has one predefined output view which allows the determination of success or failure for object id's that were undelete or attempted to be undeleted. You can use this output view to handle errors or success criteria for the records by defining post processing components. Pass-Through This Component supports pass-through. Preview The preview functionality is only supported within the context of a Pipeline using the Pipeline preview mechanism. Developing with SnAPI Identifier Java Component: com.salesforce.components.delete

43 14 Update This Component provides the functionality to update object records in Salesforce. The component requires the definition of a connection resource. To define a connection resource reference you need to have one defined in the Library or need to instantiate one using the Foundry, define its properties, save it and then select it from or drag it from the Library into the SOQLRead Component's References property section. The component supports two modes (Starting with version 1.7, prior to 1.7 only synchronous mode was supported): Synchronous and Asynchronous: The synchronous mode can be enabled by choosing 200 as the batch size value. The component will then attempt to create 200 objects in SalesForce for a single batch execution before it submits the next batch. The asynchronous mode can be enabled by choosing as the batch size value. The component will attempt to update objects in SalesForce per batch execution. The component will continue to submit batches to SalesForce while waiting asynchronously for the response of each batch execution. The component will start writing records to the output view once the first response is received from SalesForce. Properties 200 Batch Size Large record sets require writes in so called batches. Each batch update requires an API call against Salesforce to write the set of records. You can set this value up to Set to 200 or lower for synchronous execution; set to more than 200 but less than or equal to for asynchronous. 200 Number batch_size

44 SnapLogic Salesforce Snap Reference Insert Null Values You can enable this option if null values need to be set for fields that have no value definition. True False Boolean quit_on_error Quit on error An error during the update operation will be logged if any exception occurred. In addition the output view will provide information about all object id's that either failed or succeeded the update operation. You can set this option to true so that the execution of updates that follow the failed update operation will be terminated. True False Boolean insert_null_values Related Objects A write operation of a Salesforce object might contain related objects whose id's need to be included in the record information. As an example the Account object requires the Owner Id which needs to exist in the User object. You can use the Suggest button to populate this property. OwnerId Null LOV related_objects SObject This property allows you to define the name of the Salesforce object, such as Account. You can use the Suggest button without defining the object name, this will then populate the drop-down list of the

45 Update property value with available object names on the Salesforce account. Account Null String s_object See General Information for basic properties common to all Components and Pipelines. Views Inputs The Component allows the definition of a single input view. The input view can be generated using the Suggest button. The defined SObject name will be used to retrieve the metadata of the object from Salesforce to generate the corresponding input fields on the input view. The input fields will then represent valid field names and data types. As an example, the following SObject name Accountwould result in an input view with all the required fields of type updateable for the Account object. Modifying the input view manually should be avoided. The validation functionality will ensure the input view is correctly defined. Outputs The Component has one predefined output view which allows the determination of success or failure for object id's that were updated or attempted to be updated. You can use this output view to handle errors or success criteria for the records by defining post processing components. Pass-Through This Component supports pass-through. Preview The preview functionality is only supported within the context of a Pipeline using the Pipeline preview mechanism. Developing with SnAPI Identifier Java Component: com.salesforce.components.update

46 SnapLogic Salesforce Snap Reference

47 15 Upsert This Component provides the functionality to upsert object records into Salesforce. The component requires the definition of a connection resource. To define a connection resource reference you need to have one defined in the Library or need to instantiate one using the Foundry, define its properties, save it and then select it from or drag it from the Library into the SOQLRead Component's 'References' property section. The component supports two modes (Starting with version 1.7, prior to 1.7 only synchronous mode was supported): Synchronous and Asynchronous: The synchronous mode can be enabled by setting the Batch Size value to less than or equal to 200. The component will then attempt to create that number of objects in Sales- Force for a single batch execution before it submits the next batch. The asynchronous mode can be enabled by setting the Batch Size value more than 200 but less than or equal to The Component will attempt to upsert that number of objects in SalesForce per batch execution. The Component will continue to submit batches to SalesForce while waiting asynchronously for the response of each batch execution. The component will start writing records to the output view once the first response is received from SalesForce. Properties 200 Batch Size Large record sets require writes in so called batches. Each batch upsert requires an API call against Salesforce to write the set of records. You can set this value up to 10000; toggle the mode of the Component as described above. 200 Number batch_size

48 SnapLogic Salesforce Snap Reference External ID Field Name An external id field represents the unique externalized key of the object. The external ID determines the locator of the object on the Salesforce object instead of using the ID field on the object. MyExternalID Id String external_id_field_name Insert Null Values You can enable this option if null values need to be set for fields that have no value definition. True False Boolean quit_on_error Quit on error An error during the upsert operation will be logged if any exception occurred. In addition the output view will provide information about all object id's that either failed or succeeded the upsert operation. You can set this option to true so that the execution of upserts that follow the failed upsert operation will be terminated. True False Boolean insert_null_values Related Objects A write operation of a Salesforce object might contain related objects whose id's need to be included in the record information. As an example, the Account object requires the Owner ID which needs to exist in the User object. You can use the Suggest button to populate this property

49 Upsert OwnerId Null LOV related_objects SObject This property allows you to define the name of the Salesforce object, such as Account. You can use the Suggest button without defining the object name, this will then populate the drop-down list of the property value with available object names on the Salesforce account. Account Null String s_object See General Information for basic properties common to all Components and Pipelines. Views Inputs The Component allows the definition of a single input view. The input view can be generated using the Suggest button. The defined SObject name will be used to retrieve the metadata of the object from Salesforce to generate the corresponding input fields on the input view. The input fields will then represent valid field names and data types. As an example, the following SObject name Accountwould result in an input view with all the required fields of type createable and updateable for the Account object. Modifying the input view manually should be avoided. The validation functionality will ensure the input view is correctly defined. Outputs The Component has one predefined output view which allows the determination of success or failure for object IDs that were upserted or attempted to be upserted. You can use this output view to handle errors or success criteria for the records by defining post processing components. Pass-Through This Component supports pass-through

50 SnapLogic Salesforce Snap Reference Preview The preview functionality is only supported within the context of a Pipeline using the Pipeline preview mechanism. Developing with SnAPI Identifier Java Component: com.salesforce.components.upsert

51 Index C Components Connection 15 Create 27 Delete 31 Lookup 35 Object Read 23 Salesforce Wizard 11 SOQL Query Reader 19 Undelete 41 Update 43 Upsert 47 Snap 1.5 features 8 Snap 1.6 features 7 S T time zone handling

52 SnapLogic Salesforce Snap Reference