This tutorial describes how to connect to ExactTarget.

In this walkthrough:

• Requirements
• General information
• Creating ExactTargetConnection
• Opening connection
• Closing connection
• Modifying connection

Requirements

In order to connect to ExactTarget you need to have the corresponding account, dotConnect for Salesforce Marketing Cloud installed and IDE running. You also have to know the required connection parameters described below.

Note that if you do not use design-time (specifically, if you do not place designer ExactTargetConnection component from the Toolbox to the form), you have to embed licensing information manually. This is described in topic Licensing.

Required Connection Parameters

To establish a connection to server you have to provide the required connection parameters to dotConnect for Salesforce Marketing Cloud. This information is used by ExactTargetConnection component to connect to ExactTarget. The parameters are represented as a connection string. You can compose the connection string manually or have dotConnect for Salesforce Marketing Cloud construct it for you.

The following connection string parameters are required:

• Authentication Type - determines the authentication method used - RefreshToken, UserNamePassword, ServerToServer, or AppCenterClient.
• Client Id - your client ID from the App Center. Required for RefreshToken, ServerToServer, and AppCenterClient authentication.
• Client Secret - your client Secret from the App Center. Required for RefreshToken, ServerToServer, and AppCenterClient authentication.
• Refresh Token - an OAuth refresh token to connect to Salesforce Marketing Cloud. Required for RefreshToken authentication.
• Subdomain - your tenant-specific subdomain of Marketing Cloud API endpoints. Required for RefreshToken and ServerToServer authentication.
• Host - URL of an ExactTarget instance for API UserNamePassword authentication. By default the S1 Instance address is used: https://webservice.exacttarget.com/Service.asmx . Required for UserNamePassword authentication.
• User Id - API User name to login using UserNamePassword authentication.
• Password - The password for UserNamePassword authentication.

Salesforce Marketing Cloud supports four kinds of authentication - username/password, app center client (deprecated), server to server, and OAuth (RefreshToken). By default username/password authentication is used. If you want to use this authentication, you need to set Host, User Id, and Password parameters.

For OAuth (RefreshToken) authentication, set the Authentication Type parameter to AuthenticationType.RefreshToken and specify values for Client Id, Client Secret, Refresh Token, and Subdomain parameters.

For ServerToServer authentication, set the Authentication Type parameter to AuthenticationType.ServerToServer and specify values for Client Id, Client Secret, Refresh Token, and Subdomain parameters.

For app center client authentication you need to set the Authentication Type parameter to AuthenticationType.AppCenterClient and specify values for Client Id and Client Secret parameters.

Note that AppCenterClient authentication is deprecated, and it is supported only for legacy packages. Since August 1, 2019, Marketing Cloud has removed the ability to create legacy packages, so any new packages are enhanced packages, not legacy packages, and they cannot use the App Center Client authentication. You can use this authentication only if you have a legacy package, created before August 1, 2019. For new packages, you need to use the RefreshToken authentication and provide the Refresh Token and Subdomain in addition to Client Id and Client Secret parameters.

Creating a Connection to ExactTarget

Design time creation

The following assumes that you have IDE running, and you are currently focused on a form designer.

1. Open Toolbox and find ExactTargetConnection component in dotConnect for Salesforce Marketing Cloud category.
2. Double-click the component. Notice that new object appears on the designer underneath the form. If this is first time you create the ExactTargetConnection in this application it is named exactTargetConnection1.
3. Click on the exactTargetConnection1 object and press F4 to focus on object's properties.
4. Enter the required connection string parameters, described above, to the corresponding boxes.
5. Notice that as you assign values to these properties the ConnectionString property is automatically updated to reflect your settings. Now it contains something like "user=MyCompanyAdmin;password=mypassword;url=https://webservice.s7.exacttarget.com/Service.asmx;".
6. If necessary, click the Advanced button and configure other connection string parameters. You can find the description of these connection string parameters in the ExactTargetConnection.ConnectionString topic.

Run time creation

You can also configure a connection at run-time by setting its ConnectionString property (note that you have to add references to Devart.Data.ExactTarget.dll, Devart.Data.SqlShim.dll, and Devart.Data.dll assemblies):

exactTargetConnection1.ConnectionString = "user=MyCompanyAdmin;password=mypassword;url=https://webservice.s7.exacttarget.com/Service.asmx;";

exactTargetConnection1.ConnectionString = "user=MyCompanyAdmin;password=mypassword;url=https://webservice.s7.exacttarget.com/Service.asmx;"

Using connection string builder

If you decide to setup connection by assigning values to several properties, consider using ExactTargetConnectionStringBuilder class. It has all of the possible connection settings exposed as properties, thus allowing to customize the connection at full extent.

ExactTargetConnectionStringBuilder connectionStringBuilder = new ExactTargetConnectionStringBuilder();

connectionStringBuilder.Url = "https://webservice.s7.exacttarget.com/Service.asmx";
connectionStringBuilder.User = "MyCompanyAdmin";
connectionStringBuilder.Password = "mypassword";

ExactTargetConnection myConnection = new ExactTargetConnection(connectionStringBuilder.ConnectionString);

Dim connectionStringBuilder As ExactTargetConnectionStringBuilder = New ExactTargetConnectionStringBuilder

connectionStringBuilder.Url = "https://webservice.s7.exacttarget.com/Service.asmx"
connectionStringBuilder.User = "MyCompanyAdmin"
connectionStringBuilder.Password = "mypassword"

Dim myConnection As ExactTargetConnection = New ExactTargetConnection(connectionStringBuilder.ConnectionString)

Notice that in this example we used ExactTargetConnection constructor that accepts connection string as argument.

For the information on arguments allowed in the connection string, refer to the description of the ExactTargetConnection.ConnectionString property.

Creating Connection in Server Explorer

To create a Server Explorer connection, you just need to:

1. Click Connect to Database on the Server Explorer toolbar
   
   
2. If the ExactTarget Data Source is not selected by default, click the Change button.
3. Select ExactTarget Data Source (dotConnect for Salesforce Marketing Cloud) and click OK.
4. URL of a Salesforce Marketing Cloud instance, your user id and password.

After this you can browse ExactTarget objects in Server Explorer.

Opening connection

Opening a connection is as simple as that:

myConnection1.Open();

myConnection1.Open()

Of course, the myConnection1 object must have a valid connection string assigned earlier. When you call Open, dotConnect for Salesforce Marketing Cloud tries to find the host and connect to ExactTarget. If any problem occurs it raises an exception with brief explanation on what is wrong. If no problem is encountered dotConnect for Salesforce Marketing Cloud tries to establish the connection during ConnectionTimeout interval. Finally, when connection is established, the Open method returns and State property is changed to Open.

In design time you can connect to server in few steps:

1. Right-click on the connection object in designer and then click Connect.
2. In the dialog window provide the required connection parameters.
3. Click on the connection object and press F4 to focus on object's properties.
4. If necessary, click the Advanced button and configure other connection string parameters. You can find the description of these connection string parameters in the ExactTargetConnection.ConnectionString topic.
5. Click Connect to establish connection.

Or you can simply change the State property to Open in the Properties window to establish a connection using the current connection string.

Closing connection

To close a connection call its Close method, or set its State property to Closed.

The following example summarizes aforementioned information and shows how to create, setup, open, use and then close the connection.

ExactTargetConnection myConn = new ExactTargetConnection();
myConn.ConnectionString = "user=MyCompanyAdmin;password=mypassword;url=https://webservice.s7.exacttarget.com/Service.asmx;";
myConn.Open();
MessageBox.Show(myConn.ServerVersion);
myConn.Close();

Dim myConn As ExactTargetConnection = New ExactTargetConnection()
myConn.ConnectionString = "user=MyCompanyAdmin;password=mypassword;url=https://webservice.s7.exacttarget.com/Service.asmx;"
myConn.Open()
MessageBox.Show(myConn.ServerVersion)
myConn.Close()

The sample code connects to server, shows its version and then closes the connection. This actually is a rare usage, because in real applications connections are used by other objects like ExactTargetCommand, ExactTargetDataReader and others. For more information on this please see corresponding tutorials or reference information.

Modifying Connection

You can modify connection by changing properties of ExactTargetConnection object. Keep in mind that while some of the properties can be altered freely, most of them close connection when new value is assigned.