Configuration
Note
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:
- Enter SOAP API user data.
- Enter client IDs.
- Start response data workflows.
- Assign Optimizely Campaign test lists
- 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.
configuration.mdxEntering 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.
Note
If you do not have a SOAP API user account, contact customer support.
- Log in to Microsoft Dynamics CRM with administrator rights.
- Open Microsoft Dynamics CRM and select Settings > API data.
Tip
The integration adds a new Episerver Campaign section to your CRM settings.
- Click New.
- For API User, enter your SOAP API user name.
- For API Password, enter your SOAP API password.
- Click Save & Close.
configuration.mdxEntering client IDs
To run campaigns, specify which Optimizely Campaign client you want to use in CRM for sending.
- Open Microsoft Dynamics CRM and select Settings > Clients.
- Click New.
- For Client ID, enter the ID of the client to use for sending campaigns.
Tip
You can find the client ID in the Optimizely Campaign menu under API Overview > REST API.
- For Description, enter the name of the client.
Tip
The name of client is displayed at top right in the menu bar in Optimizely Campaign.
- For API User, select your SOAP API user. See Enter SOAP API user data.
- Click Save & Close. To add more clients, repeat the steps for each additional client.
configuration.mdxStarting 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:
- Select the clients to start workflows for. If the list of clients does not open, go to Settings > Clients.
- Click Run Workflow.
- Select a workflow and click Add.
- Click OK to confirm.
- 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.
configuration.mdxAssigning 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:
- Go to Settings > Episerver Campaign > Episerver Campaign > Clients.
- Click Client.
- Click Add Testlist record.
- Enter a name for the test list.
- Enter the recipient list ID of the test list. To see the recipient list ID, open the Optimizely Campaign menu and select Administration > API overview > Recipient lists.
Tip
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.
- Click Save and close the window.
Tip
To assign more test lists, repeat the steps for each additional test list.
configuration.mdxCreating 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:
configuration.mdxCreating a bounce status field
- Log in to Microsoft Dynamics CRM with administrator rights.
- Go to Settings > Customizations.
- Click Customize the System.
- Use the side navigation to go to Components > Entities > Contact or Lead or Account > Fields.
- Click New.
- 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.
- Click Save and Close.
configuration.mdxAdding the bounce status field to a form
- Use the side navigation to go to Components > Entities > Contact or Lead or Account > Forms.
- Click the form for which you want to add the advertising consent presence field.
- 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.
- On the right, open the Field Explorer and browse for the field you created for the advertising consent presence.
Tip
You can filter the number of fields shown.
- Double-click the advertising consent field to add it to the selected area.
- Click Safe.
- Click Publish.
configuration.mdxCreating advertising consent and associating the bounce status field
- Open Microsoft Dynamics CRM and select Settings > Advertising Consents.
- Click New.
- 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.
- Optional: For Description, enter a description for the advertising consent.
- For Type, select the communication channel (email, SMS or print (Germany only)) to which the advertising consent applies.
- For Entity, select the customer type (Contact or Lead or Account) for which the advertising consent is used.
- 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.
- For Episerver Campaign client, select the client used for sending the advertising consent by clicking the magnifying glass symbol.
Note
The allocation of a client to an advertising consent cannot be changed.
- Click Save & Close. The new advertising consent is displayed in the overview list.
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.
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.
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.
Prerequisites:
- 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:
- In the Opt-in area, in the Synchronize Double Opt-in field, select Yes.
- 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 overview > Recipient lists.
- 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 overview > Opt-in processes.
- 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.
Note
The entry in <optinsource> is freely customizable. Note that the root node is named <episerver> here.
- Click 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:
- In Microsoft Dynamics, go to Settings > Customizations.
- Click Customize the System.
- Select Components > Entities > Campaign Activity > Forms.
- Click Campaign activity in the list to open the Campaign Activity form.
- 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.
- Drag the 13 fields into the Episerver Campaign area of the structure view of the form.
- 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.
Note
The integration transmits all values as a string, regardless of which data type is created in CRM.
configuration.mdxData 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) |
String | Email (required for email campaigns) | |
street | String | Street |
city | String | City |
state | String | State |
zip | String | Zip code |
country | String | Country |
configuration.mdxConfiguring 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.
configuration.mdxRemapping CRM fields
- Open Microsoft Dynamics CRM and select Settings > Mappings.
- Click New.
- For Entity, select the type Contact.
- In the Map From box, enter the name of the field in CRM.
- 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.
- Click Save.
Repeat steps 1–6 for type Lead (at step 3, select Lead under Entity).
configuration.mdxTransferring 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:
- Go to Settings > Episerver Campaign > Episerver Campaign Mappings in Microsoft Dynamics CRM.
- Click New.
- For Entity, select Contact.
- In the Map From box, enter the name of the CRM field.
- For Map To, select Custom.
- In the Field box, enter the name of the additional recipient list field requested.
- 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.
- If the Map From field is of the OptionSet type, use OptionSet Language to select the language to use to transfer the values.
- Click Save.
- Repeat steps 2–10 for type Lead (at step 4, select Lead under Entity).