Installation

When I try to install the software that I downloaded from the website, I am getting an error stating "Another version of this product is already installed. Installation of this version cannot be continue. " What should I do? 

You need to uninstall the previous version before installing a new version. To do so, use "Add/Remove Programs" or "Programs and Feature" on the Control Panel to select "SSIS Integration Toolkit for Salesforce" to remove it. 

Licensing

Do I need a trial license to evaluate the software? 

You do not need to acquire a license if you only want to test out the software functionality within the development tools (SSDT-BI, BIDS - Business Intelligence Development Studio, or Visual Studio). After installation, the software will operate under the free developer license by default. With the developer license, you can create and develop data flows within the development tools (SSDT-BI, BIDS, or Visual Studio), including executing test loads without requiring a commercial license. 

If you want to evaluate whether the software functions properly outside of the development tools (SSDT-BI, BIDS, or Visual Studio), you can acquire a trial license using the License Manager program which is installed along with the software. After you have acquired a trial license, you will be able to run SSIS packages on a scheduled basis, or from any other Windows process such as command line. The trial software will operate fully-functional for the trial period, which is generally 14 days. When the trial period expires, the software will revert back to the free developer license. 

What are the limitations of the free developer license? 

The free developer license is fully-functional within your development tools (SSDT-BI, BIDS, or Visual Studio). The main limitation is the inability to run the software outside your development tools. In addition, you should not use the free development license for production purposes (mainly production data extraction or data load).

What's the difference between subscription license and perpetual license? 

There is no functionality difference between subscription license and perpetual license. However, with a subscription license software, your capability to run the software outside the development tools (such as running SSIS packages on a scheduled basis) is limited to your subscription period. With the perpetual license, you can run the designated version of software within or outside the development tools (SSDT-BI, BIDS, or Visual Studio) for as long as you want.

Development

How do I upgrade the software? What precautions should I take?

We always recommend keeping our software up-to-date. There are new features and enhancements along with bug fixes that are implemented into our products every release. In order to upgrade a licensed system to the latest software release, you need to make sure that you have up-to-date software maintenance for that particular license, which you can find out by checking the Maintenance Expiry Date after launching the KingswaySoft License Manager program. You need to make sure that your maintenance date is greater than the release date of a particular version that you want to upgrade to. In case that your software maintenance has expired, you can reach out to us for a renewal quote, we will be happy to assist you. Note that software maintenance is only applicable to perpetual licenses, not subscription licenses, as software maintenance is always included in subscription license, in which case you can upgrade to any version as long as your subscription has not expired. For the free developer license, you have the same freedom to upgrade, but we typically recommend you stay with that same version that you use for your production environment to maintain the maximum compatibility when you deploy SSIS packages.

Once you have confirmed you have an up-to-date maintenance that qualifies you for the upgrade, then you can proceed with the upgrade process. Best practices would be to uninstall the old version before installing the new version (our software does support in-place upgrade without having to uninstall first, but there are cases the in-place upgrade doesn't clean up the old version properly). We usually try to maintain maximum backward compatibility so your packages will continue to work after the upgrade. However, you will want to pay attention to any Breaking Changes that may have been introduced between versions, in which case you may need to make changes to your SSIS packages to work with the new version that you are upgrading to. It is highly possible that those Breaking Changes (if any at all) may not even affect you, in which case you do not need to do anything with your packages to have them work with the newer version.

We generally recommend you try out our new release in a DEV or test environment before implementing the new version in your production environment.

Information on any Breaking Changes can be found on our Change Log page. Some of those changes can be addressed by simply refreshing the component, while the others may require some additional efforts.

How do I maximize the throughput when writing data to Salesforce?

The following are a couple of tips that can be used to help improve the performance of Salesforce destination component.

From SSIS development perspective, here are a few advices that might be helpful. 

  • Minimize the number of object fields that you want to write to Salesforce
  • Consider using a proper batch size
  • Consider using Salesforce Bulk API option in Salesforce destination component.
  • You may consider implementing BDD Functionality to write data to Salesforce in a parallel fashion
What else do I need to do if I want to use BDD? Anything else should I be aware? 

In the case that you use our software release v5.0 or earlier, you need to make a change to SSIS related .config files in order to overcome the default connection limit imposed by the Microsoft .NET framework, which is a maximum of 2 connections per host (e.g. server). In order to overwrite this limit, you must modify DTExec.exe.config and DtsDebugHost.exe.config files under DTS\binn folder by adding the following connectionManagement section.

<configuration>
  ...
  <system.net>
    <connectionManagement>
      <add address="*" maxconnection="100"/>
    </connectionManagement>
  </system.net>
</configuration>

The above configuration allows up to 100 connections per host at the same time. You may change the number based on your needs. If you are running a 64-bit system, you must make changes to the files under "Program Files" and "Program Files (x86)" folders. 

Note that the above changes are NOT necessary for our v5.1 release or later, as the limitation has been addressed in our software programmatically.

When you use BDD functionality, there are several things that you should be aware of. 

  • You may not want to use too many BDD distributions in your data flow tasks as it could overload your server. 
  • If using the BDD Component, it uses an internal buffer to manage the distribution, which is of a pre-set size. The default buffer size is 10,000 rows, which means BDD only starts to distribute incoming rows after one branch has used up the buffer. For instance, the BDD component's second output will not receive anything if you have less than 10,000 records (9,947 records actually), and the third output will not receive anything until you have more than 19,894 records. If you are working on a small load, you must change the data flow task's DefaultBufferMaxRows property and change it to a smaller number so that the BDD distribution happens sooner. To overcome this limitation you can implement BDD functionality using the SSIS Productivity Pack as discussed in this blog post.
How can I be productive when creating SOQL queries to be used for Salesforce source component?

You can use Force.com Explorer to build queries. Force.com Explorer is a free tool, which allows you to select fields visually in order to create queries. You can also use the tool to validate your queries, and preview your Salesforce data.

Where can I find the reference document of Salesforce Object Query Language (SOQL)?

You can find the SOQL's reference document at the following URL.
http://www.salesforce.com/us/developer/docs/soql_sosl/index.htm

I am running into an error saying "(NNNN) entity is deleted (StatusCode: ENTITY_IS_DELETED)" when I use the DELETE action along with the Text Lookup feature. Why so, what can I do to avoid this error? 

This error happens when you have more than one record that has the same text value, and when Text Lookup happens, the two input text values will be translated to the same Id at Salesforce side. When the second record is hit, it will throw this exception, since the record of that particular ID has already been deleted from your system.

When using Text Lookup feature to perform DELETE, you should make sure that you do not have any duplicates in the system which would cause the mentioned error.

If duplicates already exist, and you must use the Text Lookup feature for the DELETE action, you can possibly find a way to write your query in your source component so it only returns distinct records. For instance, if your source is Salesforce, and you want to delete all Salesforce contact records that have a LastName started with "Lastname", then you can use the following query.

SELECT Name
  FROM Contact
 WHERE LastName LIKE 'Lastname%'
 GROUP BY Name
 LIMIT 2000

Using this type of query, you would have to run the DELETE data flow task more than one time in order to complete the delete action.

Deployment

When I try to execute my SSIS packages as a SQL Agent job, I am getting the following error message. Why so? What should I do to fix this problem?Failed to decrypt protected XML node "Password" with error 0x8009000B "Key not valid for use in specified state.". You may not be authorized to access this information. This error occurs when there is a cryptographic error. Verify that the correct key is available.

The reason this is happening is related to the package protection level setting used when the SSIS package is saved. By default, SSIS package is stored using EncryptSensitiveWithUserKey option. This means that any sensitive data (such as Password in our case) is stored using the SSIS package author's user key. When the SSIS package is to executed by SQL Agent job engine, the package will be loaded using a user account that might be different from the package's original author, who would have a different user key. Therefore the encrypted sensitive data cannot be properly decrypted. To address this issue, you must configure your SSIS job by entering the password with SQL Server Management Studio (SSMS). Alternatively, you can use the following option.

  • Change the package's ProtectionLevel setting from EncryptSensitiveWithUserKey to EncryptSensitiveWithPassword and provide a PackagePassword. In the SQL agent job's SSIS package execution step, navigate to Command Line page to enter the package password when prompted.
When I attempt to deploy an SSIS package or when executing an SSIS Package on SQL Server Management Studio for SQL Server 2014, I receive the following error message 'Unexpected Termination' (or System.AccessViolationException).

When using SQL Server 2014, a cumulative update is required (cumulative update 2 or later, or any recent service packs if available). The following is the list for the download links.