Please find the full announcement and all the details here

This content pack comes with a template Dashboard, a rich set of reports and a data model that allows you to build further reports and customize your dashboard.

Enjoy!

Christian Abeln    
Senior Program Manager     
Microsoft Dynamics Marketing

Follow My Curah!s on Microsoft Dynamics Marketing

Dynamics Marketing is a great tool to capture, score and nurture leads in automated campaigns. You can build your campaigns and lead management processes which automatically invite your audience, capture registrations, send welcome emails register for your marketing events and trigger post event communication e.g. based on specific record of attendance.

While most of marketing processes are automated in Dynamics Marketing, often a lot of what is going on at an event is also in different systems or in real world – like the system that records attendees at an in person event when they enter the session room.

In such situations you have a simple goal: Log a record of attendance in Dynamics Marketing such that lead scoring and nurturing processes can pick up this information for example through Lead Interactions and leads that get created automatically. And because Dynamics Marketing offers API and OData endpoints, this sounds to be very feasible – doesn’t it?

Some background

With the SDK for Dynamics Marketing sample code ships that shows how to write an application that communicated through a Windows Azure Service Bus queues with the API endpoint of an Dynamics Marketing instance. The methods available on this endpoint focus creation and update of Contacts, Companies and Leads; also managing lists, sending transactional email marketing messages creation of event registrations and records of attendance and more.

A good way to learn about the capabilities of the API Endpoints is simply looking into the assembly from the SDK directly and exploring the available methods and messages:

If you are looking for a simple step by step guide on building an SDK client with Visual Studio you can download this document. It explains step by step how to build a simple application that communicates through the Service Bus queues.

The OData endpoint has a rich documentation of all tables and fields here. And if you want to see how you can write an application that makes use of the OData endpoint as coded client application you can review one of my past blog posts here.

But for various smaller operations and feasibility prototypes or if you want to design a business flow then instead of developing an application a scripting approach might simply be easier for you. And if you are not a developer who likes to mangle with authentication code or data querying and parsing in code, then this is another reason to look into scripting options.

First Step: Install the PowerShell cmdlets from here. There are version available for both 32- and 64-bit PowerShell.

Scripting the SDK endpoint

After you have installed the power shell cmdlets on your machine you can connect with PowerShell to the SDK endpoint with this:

Add-PSSnapIn Microsoft.Dynamics.Marketing.API
$SecureString=ConvertTo-SecureString "QUEUE ACCESS KEY GOES HERE =" -asplaintext -force
Connect-MDMApi MyServiceBus101 owner $securestring sdkRequest sdkResponse -verbose

You need to configure the SDK endpoint before: Configure Dynamics Marketing to communicate through queues. This involves creating an ACS enabled Azure ServiceBus namespace also using PowerShell commands. You only need to create the service bus and then leave it to the SDK configuration in the integration settings page to configure the service bus and ACS. After that only one little piece is missing: In the ACS portal we need to add a credential of type symmetric key for the service identity that has been created for us. The key we define here is the secret that will allow your PowerShell command let to authorize sending commands to the service bus and receive responses. The key if referred below as the IssuerKey.

With that in place you are ready to use one of the commands from the cmdlet. Type Get-Command -Module:Microsoft.Dynamics.Marketing.API to get a list of all commands contained. Use the command Get-Help to learn about the command parameters.. For example Get-Help -Name:Get-MDMLeads

The first command we use is  to connect to the API endpoint:

Connect-MDMApi [[-Namespace] <string>] [[-IssuerName] <string>] [[-IssuerKey] <securestring>]
[[-RequestQueueName] <string>] [[-ResponseQueueName] <string>] [[-SessionId] <string>]  [<CommonParameters>]

A fully qualified connection command has the syntax like:

Connect-MDMApi -Namespace:"MyMDMserviceBus" -IssuerName:"MDMServiceIdentity" -IssuerKey:$SecureString
-RequestQueueName:"sdkRequest" -ResponseQueueName:"sdkResponse" -VERBOSE

Please note that the -IssuerKey (the 256bit symmetric key) must be maintained in a secure string object of PowerShell scripting – meaning it will be encrypted and cannot be used & decrypted by anything than the user who has created the secure string – you.

Lets try few Hello World type of samples

1. Reading all Leads that have been updated in the last days and simply out put the leads.

Get-MDMLeads [-BelongsToCompanyId <guid>] [-FromUpdateDate <datetime>] [-MaxNumberOfRecordsToGet <int>]
[-OriginOfChange <string>] [-MaxResponseWaitTime <int>]  [<CommonParameters>]

$date = [System.DateTime]::Now.AddDays(-4).ToUniversalTime()
$leads = Get-MDMLeads -FromUpdateDate:$date
$leads

2. Adding a new marketing contact with parent marketing company under the assumption that we know the Id of the site company
(We assume knowledge of the External Id of the Site company. We will see later how to find the site company.)

Get-MDMCompany [[-CompanyId] <guid>] [-MaxResponseWaitTime <int>]

Add-MDMContact [[-Contact] <Contact>] [-DisableConcurrentRequestValidation <bool>] [-MaxResponseWaitTime <int>]

$SiteCompanyID="eddfce37-e3d9-4910-b0c4-f6979777dd07"
$belongsto = get-MDMCompany $SiteCompanyID -verbose

$error.Clear()
$contact = new-object Microsoft.Dynamics.Marketing.SDK.Model.Contact
$company = new-object Microsoft.Dynamics.Marketing.SDK.Model.Company
$company.Name = "Coolest Company On Planet Earth"
$company.IsMarketing = $true
$contact.BelongsToCompany = $belongsto
$contact.FirstName = "A First Name1"
$contact.LastName = "A Last Name1"
$contact.Company = $company
$contact.IsMarketing = $true
$newcontact = Add-MDMContact $contact -verbose
if($error.Count > 0)
{
    $error
}

3. Let’s add a new lead to a know contact (like created above) and under a campaign and program. This sample shows also how to set fields like priority, status, sales rating, a custom origin of change, dates and even defines an initial score. The latter sill be overwritten as soon as lead get scored – if then a scoring model has been defined in the marketing context where the lead lands.
(We assume knowledge of Campaign Id and Program Id. These are the External Id)

$sitecompany="eddfce37-e3d9-4910-b0c4-f6979777dd07"
$programid="fba68e22-e822-4097-a40f-f244bb401736"
$campaignid="fcac690f-af01-43c0-9c9b-fda3b5ca8a9c"
$contactid = "6346d0e5-ec1c-4931-b63b-2f24b8666c23"


$program = new-object Microsoft.Dynamics.Marketing.SDK.Model.Program
$program.id = new-object Guid($programid) 
$campaign = new-object Microsoft.Dynamics.Marketing.SDK.Model.Campaign
$campaign.id = new-object Guid($campaignid) 


$lead = new-object Microsoft.Dynamics.Marketing.SDK.Model.Lead
$lead.Name="SDK test Lead 123" 

$belongsto = Get-MDMCompany $sitecompany
$lead.BelongsToCompany = $belongsto

$contact = Get-MDMContact $contactid
$lead.Contact = $contact

$lead.Date=[System.DateTime]::Now.ToUniversalTime()
$lead.DueDate=$lead.Date.AddMonths(1)

$type = ("System.Collections.Generic.List"+'`'+"1") -as "Type"
$type = $type.MakeGenericType("system.string" -as "Type")
$origins = [Activator]::CreateInstance($type)
$origins.Add("Cool SDK")
$lead.OriginOfChanges=$origins

$lead.Score=999

$priorities = Get-MDMLeadPriorities
If ((-not ($priorities -eq $null)) , ($priorities.Count > 0))
{
    $lead.Priority=$priorities[0]
}

$statuses = Get-MDMLeadStatuses
If ((-not ($statuses -eq $null)) , ($statuses.Count > 0))
{
    $lead.Status=$statuses[0]
}

$salesRatings=Get-MDMSalesRatings
If ((-not ($salesRatings -eq $null)) , ($salesRatings.Count > 0))
{
    $lead.SalesRating=$salesRatings[0]
}

$lead.Program = $program;
$lead.Campaign = $campaign;

$newLead = Add-MDMLead $lead 
$newLead.Id 

Add-PSSnapIn Microsoft.Dynamics.Marketing.OData

Connect-MDMOData`
    -SeviceUrl:"https://YOURINSTANCE.marketing.dynamics.com"`
    -RedirectUrl:"https://localhost"`
    -OAuthTokenResourceName:"YOUR__REGISTERED_APPID" -verbose

$visits = Find-MDMAnyData -TableName:Visits -top:100 -OrderBy:"StartTime desc" –verbose 
$visits

$programs = Find-MDMAnyData -TableName:Programs -Expand:ProgramKPIs -verbose
$programs

$comps = Find-MDMCompanies -Filter:"substringof('Site', Type) eq true" -verbose
$site = $comps[0]
$siteId = $site.Id

$pagesize = 100
$skip = 0
do
{
    $contacts = Find-MDMContacts -BelongsToId:$siteId -Top:$pagesize -Skip:$skip
    $skip += $contacts.Count
    "Debug: Skip:" + $skip
    #ProcessContacts($contacts)
}
while ($contacts.Count -ge 0)

$siteId = '[Assign Company.ExternalId]'
$programId = '[Assign Program.ExternalId here]'
$campaignId = '[Assign Campaign.ExternalId here]'

$belongsTo = Get-MDMCompany $siteId -verbose

$program = New-Object  Microsoft.Dynamics.Marketing.SDK.Model.Program
$program.Id = $programId

$campaign = New-Object  Microsoft.Dynamics.Marketing.SDK.Model.Campaign
$campaign.Id = $campaignId

$pagesize = 5
$skip = 30
$max = 5
$index = 0
do
{
    $contacts = Find-MDMContacts -BelongsToId:$siteId -Top:$pagesize -Skip:$skip
    foreach ($contact in $contacts)
    {    
        $lead = new-object Microsoft.Dynamics.Marketing.SDK.Model.Lead
        $lead.BelongsToCompany = $belongsTo 
               $lead.Name = "Initiative Lead N0." + $index
        $ExId = $contact.Id
               $sdkContact = Get-MDMContact -ContactId:$ExId
               $lead.Contact = $sdkContact
        $lead.Program = $program
        $lead.Campaign = $campaign
        $lead.Date=[System.DateTime]::Now.ToUniversalTime()
        Add-MDMLead $lead
         $index++
    }
    
    $skip += $contacts.Count
    "Debug: Skip:" + $skip
    #ProcessContacts($contacts)
}
while ($contacts.Count -ge 0)

With this blog post I wanted to give a quick glimpse into what is possible with the cmdlets for Dynamics Marketing OData endpoint and SDK. This topic certainly calls for more blog posts with practical sample applications. Stay tuned.

Enjoy!

Christian Abeln
Senior

Follow My Curah!s on Microsoft Dynamics Marketing

Instead you can now use a NuGet Package in your Visual Studio solution and configure which projects in the solution shall make use of it. The library will be added as a reference and as soon as you compile the first time it will be downloaded, added to the package cache in the solution and deployed with your project.

Only check the solution with the package definition into your source management system. Any developer who downloads it will get the correct library version automatically deployed.

Find information on how to use the NuGet packages here.

Get the Microsoft Dynamics Marketing SDK NuGet package here.

Enjoy!

Christian Abeln
Senior Program Manager
Microsoft Dynamics Marketing

Follow My Curah!s on Microsoft Dynamics Marketing

The typical usage of the Dynamics Marketing feeds is through Power BI. A user would use Excel Pro and with the Power Query plugin he would connect to the OData endpoint of Dynamics Marketing.

e.g. “https://contoso.marketing.dynamics.com/analytics/”

But before the OData endpoint needs to be enabled in the Site Settings – look all at the bottom on that page.

“But is Power Query really the only way to access the OData feed endpoint?”
This question has reached my desk a few times now. First of all: The OData endpoint was designed for analytic reporting. Still it is technically possible to access the service endpoint by other dedicated clients as well. In this post I will lay out how that works and even provide a sample OData client application.

	This post is targeting the 3rd party developer who is comfortable with using .Net in order to create clients for Dynamics Marketing which communicate of protocol level with the data service. And you should look forward to configure Azure Active Directory and use authentication mechanics in your code.

Accessing the MDM OData endpoint with other tools than PowerQuery is not officially supported for the current releases of Dynamics Marketing.

For the restless reader (“in a few words”)

These are the steps needed to write your own client application that is permitted to connect, send data queries and process responses from the MDM OData endpoint.

Defining the application in WAAD

An application definition in Azure Active Directory provides the control of the consumers that may use the endpoint of a certain service in a specific subscription. This is used in addition of user credentials to sign in. You need to have an Azure subscription enabled for your organization. (The procedure described in this post will not introduce any costs in your subscription.)

Why do you need that? because as and administrator of Contoso you want to control explicitly which applications or services may access your Dynamics Marketing OData endpoint. PowerQuery in Excel is by default permitted to do so for every deployment of Dynamics Marketing.

Define an application in Azure Active Directory

Note the generated App ID. For the Redirect URI we use https://localhost. We actually doe not need a redirect URI on which we would receive responses to any request for OAuth requests. We are listening in the application directly.

Grant permissions to access the Dynamics Marketing service (to be updated…)

Now we need to grant the permissions to our new Azure app to access Dynamics Marketing.  For other services like Dynamics CRM the necessary steps have been take to show the service in the section “permissions to other applications”. But this not available for Dynamics Marketing yet. Therefore we need to take workaround through the so called Graph API. This API has been provided to configure the Active Directory programmatically.

!! Many have reported that Graph Explorer does not support setting the App permissions any longer. We are looking into other ways to allow this configuration !!

But no worries we do not need to write our own Graph API client application in order to do the missing step of granting permissions. The Azure team has provide a sample service called Graph Explorer, which we can use to configure the permissions. Lets open the too and Sign In with the account that can administer Azure account. You as well press then the “Get” button in order to then browse through the different configuration information in your Azure Directory.
You will see of course the address of your own Dynamics Marketing instance for Resource and the Responses below.

Click on “Add Application Permission” in order to establish the trust relationship between your application definition in Azure and the Dynamics Marketing service.

Write the basic code to access the MDM OData endpoint

Prerequisites: In order to build a OData client application you will need to install first the WCF Data Services 5.6.0 RTM Tools. Some of the libraries we need for our experiment are located then on your local machine: C:\Program Files (x86)\Microsoft WCF Data Services\5.6\bin\.NETFramework Notably it is the client library “Microsoft.Data.Services.Client.dll” to which we must add a reference in our project.

The sample client application that comes with this post does two things in order to authenticate:

1. It requests an authorization token by

• Using the correct Url that provides the authentication, which is:
  https://login.windows.net/common/
• Specifying the correct resource name for which the access token shall be issued:
  https://marketing-infra.dynamics.com/
• Requesting it for the client app ID from the Application registration in Azure
• Specifying the Redirect Uri that we had entered into the application registration (https://localhost/)

this._authenticationContext =new AuthenticationContext(OAuthUrl, false); var result = await this._authenticationContext.AcquireTokenAsync( MDMOAuthTokenResourceName, this.ODataClientAppID, this.RedirectUri, string.Empty, string.Empty);

In the process of getting an the authentication token, the authentication service at https://login.windows.net/common/ will request the user to sign in and provide respective UI
(Find the respective code in CurrentEnvironment.cs)

The authentication token will also be cached such that the user does not have to enter the credentials every time. Resetting the cache token will require the user to sign in again. The application can control that by simply calling:

(AuthenticationContext.TokenCache as DefaultTokenCache).Clear();

This is a typical activity if the user chooses to sign out or the connection parameters have changed.

2. For each request we send we need to make sure to include the authentication token into the request header.

// transmit the access token we have received earliervar headerVal =new AuthenticationHeaderValue("Bearer", this._environment.AuthenticationToken); args.Headers.Add("Authorization", headerVal.ToString());

The simple procedure is simply to add a header value of type Authentication to the http request where the Name is “Bearer” and the value is the authentication token that we have received.

Process data with the help of the data model

The easiest way to query and consume entities from a OData service is through a data model in your client application code. Visual Studio allows developers to connect to an OData service endpoint and generate code by adding a service reference. This generates code in form of a DataServiceContext class implementation. And that comes with a query for each entity, a class for each entity with all entity fields as properties, a queries or relations to other table (like Company.Leads).

With such a data model all we need to do is create an instance of the data model for our OData service end point address. Then we need to make sure to subscribe to any activity that builds the http requests for each OData query, so we can inject our authentication token. And with that we are ready to query data and bind the returned data filled with information to any UI we like or use the data in other business logic.

Unfortunately Visual Studio does not know how to use OAuth on the data service of Dynamics Marketing. Therefore I have provided a generated data model as part of this sample application.

You will find that in the source file MDMOData161.cs. This is for the version of the data model that currently is live in the production instances. The sample will need to be updated for future releases.

Try out the Sample App

After you start the OData application for MDM you need to enter the MDM Service Address (without the “/analytics” at the end). Also the reply URI and Client App Id from the definition of the application in Azure.

Next you will need to sign in.

After the Sign in succeeds you will be able to request entities for a few select types. In the sample these are just Contacts, Companies, Leads, Campaigns.

For the selected entity, the client app will retrieve all respective entities from the service.

The sample code shows how to authenticate against WAAD, and use the authentication token to run asynchronous queries on the OData endpoint and also bind the result to a simple generic data view in a Windows 8 Store application.

Download the sample code for Microsoft Dynamics Marketing 2016  (ver. 19.0) from HERE

Enjoy!

Christian Abeln
Senior Program Manager
Microsoft Dynamics Marketing

Follow My Curah!s on Microsoft Dynamics Marketing

Dynamics Marketing provides a rich set of OData feeds for he most important data entities in the system that can be used for analytic reports.

All feeds are read only and are especially targeting analytics with Microsoft Power BI. Therefore we have put focus on providing meaningful data together with special KPIs for Marketing Performance Measurement.

Download 18.0.4062 OData field documentation from HERE!

Download 17.2.0022 OData field documentation as mht file from HERE!

Christian Abeln
Senior Program Manager
Microsoft Dynamics Marketing

Follow My Curah!s on Microsoft Dynamics Marketing

OData Documentation - MDM 18.0.4062.0 - Spica.zip

Hi,

It is really overdue time that I start blogging on Microsoft Dynamics Marketing. I am looking forward to start sharing about various topics.

You can find general product documentation information here:

https://www.microsoft.com/en-us/dynamics/crm-marketing.aspx

Or follow my Curah!'s here (Link collections with essential information and materials):

My Curah!s on Microsoft Dynamics Marketing

Christian Abeln
Senior Program Manager
Microsoft Dynamics Marketing