• Updated

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

This topic describes how to configure the Microsoft Dynamics CRM integration, if you are using this with Optimizely Campaign.

The configuration includes these steps:

  1. Enter SOAP API user data.
  2. Enter client IDs.
  3. Start response data workflows.
  4. Assign Optimizely Campaign test lists
  5. Create advertising consents and link to client.

To transfer fields not included in the standard configuration, you must also configure the additional fields for your Optimizely Campaign recipient list.

Entering SOAP API user data

Communication and data exchange between Microsoft Dynamics and Optimizely Campaign uses the SOAP API. To link CRM with Optimizely Campaign via the interface, you must enter your SOAP API user data in Microsoft Dynamics.

If you do not have a SOAP API user account, contact customer support.

  1. Log in to Microsoft Dynamics CRM with administrator rights.
  2. Open Microsoft Dynamics CRM and select Settings > API data.

    The integration adds a new Episerver Campaign section to your CRM settings.

    Image: API data

  3. Click New.
  4. For API User, enter your SOAP API user name.

    Image: API User

  5. For API Password, enter your SOAP API password.

    Image: API password

  6. Click Save & Close.

Entering client IDs

To run campaigns, specify which Optimizely Campaign client you want to use in CRM for sending.

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

    Image: Clients

  2. Click New.
  3. For Client ID, enter the ID of the client to use for sending campaigns.

    Image: Client ID

    You can find the client ID in the Optimizely Campaign menu under API Overview > REST API.

  4. For Description, enter the name of the client.

    Image: Description

    The name of client is displayed at top right in the menu bar in Optimizely Campaign.

  5. For API User, select your SOAP API user. See Enter SOAP API user data.

    Image: API User

  6. Click Save & Close. To add more clients, repeat the steps for each additional client.

Starting response data workflows

To feed campaign response data from contacts and leads in Optimizely Campaign into CRM, start the response data workflows for each individual client. The workflows query and import recipient response data in 60-minute intervals.

These workflows are available for each response type:

Workflow Response type
Optimizely: Get opens Mailing opened
Optimizely: Get clicks Link clicked in the mailing
Optimizely: Get responses Direct reply to the mailing
Optimizely: Get unsubscribes Newsletter unsubscribes
Optimizely: Get outbounces Outbounce (the recipient has exceeded the bounce limit)

Do the following to start workflows:

  1. Select the clients to start workflows for. If the list of clients does not open, go to Settings > Clients.

    Image: Clients

  2. Click Run Workflow.

    Image: Run Workflow

  3. Select a workflow and click Add.

    Image: Add workflow

  4. Click OK to confirm.
  5. Repeat steps 1–4 for each workflow.

You can see workflow activity in the Information view for the client. Click the corresponding client ID in the list to open it. Under access data, you can see when the workflow was last run, and timestamp for the most recently imported data.

Assigning Optimizely Campaign test lists

To check the campaign mailings before dispatch, you can send them to an Optimizely Campaign test list. To do this, you must assign the Optimizely Campaign test list in Microsoft Dynamics CRM. Do the following:

  1. Go to Settings > Episerver Campaign > Episerver Campaign > Clients.
  2. Click Client.
  3. Click Add Testlist record.

    Image: Add Testlist record

  4. Enter a name for the test list.

    Image: Test list name

  5. Enter the recipient list ID of the test list. To see the recipient list ID, open the Optimizely Campaign menu and select Administration > API overviewRecipient lists.

    If you are missing the ID column, click the down arrow v in the upper right corner of the table header and activate the ID check box.

    Image: Test list ID

  6. Click Save and close the window.

    Image: Save

To assign more test lists, repeat the steps for each additional test list.

Creating consents and linking to client

To send mailings, you need advertising consent from contacts and leads. The consent protects recipients from unwanted omnichannel marketing. See also Opt-in. The integration checks two fields in Microsoft Dynamics for each contact and lead, to see if consent is given or withdrawn, and will not transfer recipients without consent.

Furthermore, you record the bounce status for the contact, lead or account, which makes a statement about the functionality of the advertising agreement.

Perform the following steps:

  1. Creating a bounce status field
  2. Adding the bounce status field to a form
  3. Creating advertising consent and associating the bounce status field

Creating a bounce status field

  1. Log in to Microsoft Dynamics CRM with administrator rights.
  2. Go to Settings > Customizations.

    Image: Customizations

  3. Click Customize the System.

    Image: Customize the System

  4. Use the side navigation to go to Components > Entities > Contact or Lead or Account > Fields.

    Image: Fields

  5. Click New.

    Image: New field

  6. Specify the following fields:

      • Display Name. Enter an intuitive name, for example EpiOutbounce E-Mail.
      • Name. Click into any other field. The entry is automatically copied to the Name box (without spaces or special characters), with the prefix new_ added. Change the automatically created entry in the Name box, such as changing it to new_epioutbounce eMail. Do not use spaces or special characters. Note the entry in the Name box, you will need this later for the advertising consent.

      • Field Requirement: Select Optional.
      • Searchable: Select Yes.
      • Field Security. Select Disable.
      • Auditing. Select Enable.
      • Description. Optional: Enter a field description.
      • Data Type. Select Two Options. A field containing the options No and Yes appears.

    • Field Type. Select Simple.
  7.  Click Save and Close.

Adding the bounce status field to a form

  1. Use the side navigation to go to Components > Entities > Contact or Lead or Account > Forms.

    Image: Forms

  2. Click the form for which you want to add the advertising consent presence field.

    Image: Select form

  3. Click the area, for example Marketing, where the field for presence of advertising consent should appear. When the area is selected, the surrounding dashed line becomes solid.

    Image: Select location of advertising consent

  4. On the right, open the Field Explorer and browse for the field you created for the advertising consent presence.

    You can filter the number of fields shown.

  5. Double-click the advertising consent field to add it to the selected area.

    Image: Select advertising consent

  6. Click Safe.
  7. Click Publish.

Creating advertising consent and associating the bounce status field

  1. Open Microsoft Dynamics CRM and select Settings > Advertising Consents.

    Image: Advertising Consents

  2. Click New.

    Image: New advertising consent

  3. For Opt-in-ID, enter a unique identifier. Do not use special characters or characters with accents. The Opt-in-ID should be intuitive, for example OptinProductNewsletterEmailContact. It will display, for example, when selecting advertising consent for sending a campaign.

    Image: Opt-in-ID

  4. Optional: For Description, enter a description for the advertising consent.
  5. For Type, select the communication channel (email, SMS or print (Germany only)) to which the advertising consent applies.

    Image: Consent type

  6. For Entity, select the customer type (Contact or Lead or Account) for which the advertising consent is used.

    Image: Select entity

  7. For Reference Bounce Field, enter the name of the field indicating the functionality of the advertising consent. This is the name that automatically had new_ added when creating the field.

    Image: Reference Bound Field

  8. For Episerver Campaign client, select the client used for sending the advertising consent by clicking the magnifying glass symbol.

    The allocation of a client to an advertising consent cannot be changed.

    Image: Episerver Campaign client

  9. Click Save & Close. The new advertising consent is displayed in the overview list.

    Image: New advertising agreement

Repeat steps 1–9 to add more advertising consents for the same channel. Additional advertising consents can refer back to the bounce status field that was already created. This applies to the entire channel, for example an Email channel.

You have successfully created an advertising consent. Irrespective of whether the agreements are obtained through an opt-in process in Optimizely Campaign or from another source, you will find the assignment of the advertising consents to the individual contacts, leads or accounts under the menu item Opt-in Histories.

Image: Opt-in Histories

In the Opt-in History Assigned View overview, you can see the advertising consents granted. If the advertising consent is withdrawn again, the entry can be deleted, or an Opt-out entry is created on basis of the unsubscribe response data. In this case, CRM uses the time stamp to recognize the current status of the withdrawn advertising consent. In both cases, no more mailings that require the corresponding consent are sent to this data record.

Image: Assigned View: Opt-In History

Connecting the advertising consent to an Optimizely Campaign opt-in process

On the configuration page of the advertising consent, you find another Opt-in area where you can connect the created advertising consent to the opt-in process in Optimizely Campaign. This enables you to send opt-in mailings with a confirmation link via Optimizely Campaign.


  • You completed configuring the integration, including an advertising consent.
  • You created an opt-in process. You require the ID of the opt-in process and the ID of the opt-in recipient list used in the process.

To connect an advertising consent to a double opt-in process:

  1. In the Opt-in area, in the Synchronize Double Opt-in field, select Yes.

    Image: Field Synchronize Double Opt-In

  2. In the Opt-in Recipient List ID field, enter the ID of the recipient list that is used in the opt-in process. To see the recipient list ID, open the Optimizely Campaign menu and select Administration > API overviewRecipient lists.

    Image: Field Opt-In Recipient List-ID

  3. In the Opt-in Process ID field, enter the ID of the Opt-in process from Optimizely Campaign. To see the opt-in ID, open the Optimizely Campaign menu and select Administration > API overviewOpt-in processes.

    Image: Field Opt-In Process-ID

  4. Optional: In the Konfiguration DOI field, enter a XML configuration that assigns information from the contact fields to the recipient list fields in the opt-in recipient list.

    The entry in <optinsource> is freely customizable. Note that the root node is named <episerver> here.

    Image: Field Konfiguration DOI

  5. Click Save & Close.

    Image: Save & Close

You have successfully combined an advertising consent in CRM with an opt-in process in Optimizely Campaign. You can now trigger the sending of an opt-in mailing via Optimizely Campaign by clicking the Send Opt-in Mail button in the respective entity.

Customizing the campaign activity form

To complete the configuration, update the campaign activity form adding fields from the Microsoft Dynamics integration. These fields are usually added when the integration is installed. However, depending on your CRM configuration, this step may have been missed.

The integration has these fields:

No. Field name
1 Recipients sent to Optimizely Campaign
2 Sent successful
3 Recipient Packages created
4 Mailing Description
5 Mailing ID
6 Mailing ID by Wave ID
7 Mailing name
8 Mailing Status
9 Optimizely Campaign client
10 Recipient Packages sent
11 Preprocessed recipients
12 Wave ID
13 Advertising Consent

Do the following:

  1. In Microsoft Dynamics, go to Settings > Customizations.
  2. Click Customize the System.
  3. Select Components > Entities > Campaign Activity > Forms.

    Image: Select Forms

  4. Click Campaign activity in the list to open the Campaign Activity form.
  5. In the field explorer, from the Filter drop-down list, select Custom Fields and clear the Only show unused fields check box. The 13 fields from the Microsoft Dynamics Integration are shown.

    Image: Select Custom fields filter

  6. Drag the 13 fields into the Episerver Campaign area of the structure view of the form.

    Image: Drag fields

  7. Click Save and Close.

Transferring data fields

When transferring data fields from the CRM to Optimizely Campaign, a distinction is made between data fields transferred by default and additional optional fields that must be configured.

The integration transmits all values as a string, regardless of which data type is created in CRM.

Data fields transferred by default

The default settings for the integration send the following data from Microsoft Dynamics to Optimizely Campaign:

Field name Date type Description
entityType String Indicates whether this is a lead or a contact
salutation String Title
firstname String First name
lastname String Last name
fullname String First name and last name
mobile String Mobile phone number (required for SMS campaigns)
email String Email (required for email campaigns)
street String Street
city String City
state String State
zip String Zip code
country String Country

Configuring additional fields for the recipient list


This configuration applies to both campaign management and synchronization of recipient lists and advertising consents (clients). Remember to consider this during planning to avoid costly reconfiguration and additional work. The field configurations must be identical for both leads and contacts. Changing only one type will cause the other to fail to send.

Options for custom configuration of recipient lists:

  • Remap a custom CRM field and write it to an existing standard field in the recipient list.
  • Transfer a custom CRM field to an additional field not in the standard configuration of the recipient list.

Remapping CRM fields

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

    Image: Mappings

  2. Click New.
  3. For Entity, select the type Contact.

    Image: Select Contact entity

  4. In the Map From box, enter the name of the field in CRM.
  5. For Map To, select the standard field in the recipient list into which the value of the CRM field should be written. For example, if you created a field called new_custom_country, then you can copy the value of this field into the Country field in the recipient list. The standard CRM Country field is no longer transferred to Optimizely Campaign.

    Image: Select Map to option

  6. Click Save.

Repeat steps 1–6 for type Lead (at step 3, select Lead under Entity).

Transferring CRM fields

Prior to transferring, contact customer support to add the additional fields to your recipient list. In the request, provide the fields in a consecutively numbered list starting at 1, including numbering and field names. Note the numbering and field names (do not change them), you will need these for the configuration.

Do the following when the fields have been added:

  1. Go to Settings > Episerver Campaign > Episerver Campaign Mappings in Microsoft Dynamics CRM.
  2. Click New.
  3. For Entity, select Contact.
  4. In the Map From box, enter the name of the CRM field.

    Image: Map from CRM

  5. For Map To, select Custom.

    Image: Map to options

  6. In the Field box, enter the name of the additional recipient list field requested.

    Image: Select Field recipient list

  7. In the Position box, enter the position number of the additional recipient list field. The position numbers are oriented to the order of the additional recipient list fields requested.

    Image: Enter position number

  8. If the Map From field is of the OptionSet type, use OptionSet Language to select the language to use to transfer the values.

    Image: Set language

  9. Click Save.
  10. Repeat steps 2–10 for type Lead (at step 4, select Lead under Entity).