Extended recipient list connector

  • Updated

This topic is for administrators and developers with administration access rights in Microsoft Dynamics.

The documentation refers to connector version 1.584 and higher.

The current version of Microsoft Dynamics CRM cannot address more than 100,000 recipients per campaign. The extended recipient list connector for Optimizely Campaign is an external Windows service that removes the technical limitation and controls campaigns and the transmission of marketing lists with more than 100,000 recipients.

Prerequisites

  • Installation file. Contact customer support.
  • Microsoft Dynamics CRM online or on-premise (local)
  • SQL database, such as LocalDB or SQL Express.
  • Port reservation
    1. Open the command prompt as administrator.
    2. Run the netsh configuration program.
    3. Reserve the port using the prompt add urlacl url=http://+:20000/ user=domain\username.

      The specification of the port +:20000 must match the later port specification in the IntegrationService.config installation file.

Technical requirements

  • SQL server
    • Microsoft SQL Server 2008R2 (all versions with LocalDB) and later
    • Microsoft SQL Azure
  • Windows Identity Foundation 3.5 (Windows feature)
  • .NET Version 4.6.2

Installation

  1. Unzip the installation file that you have received from the customer support.
  2. Open the IntegrationService.exe.config file in a text editor.
  3. Optional: Configure the proxy settings.

     

    <add key="proxy.Domain" value= /><add key="proxy.UserName" value= /><add key="proxy.Password" value= /><add key="proxy.Protocol" value= /><add key="proxy.Host" value= /><add key="proxy.CredentialType" value= /><add key="proxy.Port" value= />

    The configuration does not replace the proxy configuration for the CRM. This is still necessary for functionalities such as double opt-in or transactional mails.

  4. Adjust the connectionStrings element as follows:

     

    <connectionStrings><add name="Hangfire.Storage" connectionString="Server= ; Database= ; Trusted_Connection=True; MultipleActiveResultSets=true" />
    <add name="CRM" connectionString="RequireNewInstance=true; Url={https://server/organization/}; Domain= ; Username= ; Password= ;" /></connectionStrings>

    Microsoft Dynamics CRM online

    • For the connectionString parameter, prefix the URL with the parameter AuthType=Office365; as follows:
      connectionString="AuthType=Office365;Url={https://server/organization/}; Domain= ; Username= ; Password= ;"
    • The parameters Username and Password are required.

    Microsoft Dynamics CRM on-premise

    • If you sign in using the following Windows services, the Domain, Username, and Password parameters are not required in the connectionString:
      • Microsoft Dynamics CRM Asynchronous Processing Service (MSCRMAsyncService)
      • Microsoft Dynamics CRM Sandbox Processing Service (MSCRM SandboxService)
  5. Save the IntegrationService.exe.config file.
  6. Open the Command Prompt as administrator.
  7. Enter the connector path and install the Integrationservice.exe file with the prompt integrationservice.exe install.

    Image: Command Prompt

  8. Open Windows Services and start Episerver Campaign Integration Service.

If you want to update or modify the configuration, you must first stop the connector via Windows Services.

Configuring the connector

In the IntegrationService.exe.config file, you can adjust the following parameters for the data transfer.

Parameter Description Default value
MaxSendRetries Number of attempts to transmit a recipient package when an attempt fails, for example, due to a timeout. 3
TimeoutCrmConnection Maximum time in seconds for the transmission of a recipient package from the CRM to the service before a timeout error occurs. 60
TimeoutEpiserverConnection Maximum time in seconds for the transmission of a recipient package from the service to Optimizely Campaign before a timeout error occurs. 120
UseSoapServiceForRecipientLists Choice between data transfer via SOAP or REST API. REST API is used by default. false
BatchSize Size of the recipient package when transferring from the service to Optimizely Campaign. When transferring using SOAP API, the maximum value is 1000. 5000
CrmBatchSize Size of the recipient package when transferring from the CRM to the service. 1000
MaxThreads Number of parallel threads when transferring via API. The maximum number is 6. 5

Configuration in Microsoft Dynamics CRM

  1. Open Microsoft Dynamics CRM and select Settings > Configurations.

    Image: Configurations

  2. Click New.
  3. Enter the name Use Windows Service.

    Image: Entering the name

    You can leave the Value field blank. No definition is required.

  4. Click Save & Close.

    Image: Saving the configuration

Troubleshooting

With the Hangfire tool you can view and manage planned, running and executed workflows. You install Hangfire automatically with the connector and access the tool in your web browser at the following address: http://localhost:20000/hangfire.

To view the log data of the service, open the logs.txt file in the installation directory. You can find the log data of the past days in the archives folder.

Uninstallation

To uninstall and completely remove the extended recipient list connector, do the following:

The extended recipient list connector must be inactive. Open Windows Services and stop Episerver Campaign Integration Service.

  1. Open the Command Prompt as administrator.
  2. Enter the connector path and uninstall the Integrationservice.exe file with the prompt integrationservice.exe uninstall.

    Image: Command Prompt

    The installation directory still remains. Delete the directory including the log data.

  3. Open Microsoft Dynamics CRM and select Settings > Configurations.Image: Configurations
  4. Select the Use Windows Service configuration data set and click Delete.

    Image: Deleting the configuration