Online Management PS Module for Dynamics 365 CE – Part 2 (Provision Instance)

In the previous post I have showed you how to get started with the new Online Management PowerShell Module for Dynamics 365 Customer Engagement. I covered how you can easily backup your instance.

In this post I will cover the provisioning new instances. One reason why you may want to do this is if you want to setup an automated process where you can automatically spin new a CRM instance as part of a build and deploy the latest configuration for functional, performance or load testing. You could also automate the process for provisioning instances for your users or developers. I am sure there are other reasons too.

Let’s get started, first the standard setup as per the previous post where you will load the PS Module and define the ApiUrl and credentials. More details on this in my previous post.

$ErrorActionPreference = "Stop"

Import-Module "C:\Dev\PowerShell\Microsoft.Xrm.OnlineManagementAPI\0.0.1.0\Microsoft.Xrm.OnlineManagementAPI.dll"

$Username = "user@domain.com"
$Password = "*****"
$ApiUrl = "https://admin.services.crm11.dynamics.com"

#Create Credentials
$SecPassword = ConvertTo-SecureString $Password -AsPlainText -Force
$Cred = New-Object System.Management.Automation.PSCredential ($Username, $SecPassword)

Next you will need define the currency of your new instance as per below. I am selecting GBP in this case.

$instanceCurrency = New-CrmInstanceInfo -CurrencyCode GBP -CurrencyName "Pound Sterling" -CurrencyPrecision 2 -CurrencySymbol "£"

If you are not sure which values you need or which values are supported, you can use the Cmdlet below to get a list of all currencies

$Currencies = Get-CrmCurrencys -ApiUrl $ApiUrl -Credential $Cred
Foreach($currencyList in $Currencies)
{
    Write-Host("RegionCode`t:" + $currencyList.RegionCode)
    Write-Host("Name`t:" + $currencyList.Name)
    Foreach($currency in $currencyList.Currencies)
    {
        $currency | Format-List
    }
}

You will get something similar to the below. As you can see there are lots of variations even for GBP.

RegionCode	:GB
Name	:United Kingdom

Code      : GBP
Precision : 2
Symbol    : £
Name      : Punt Sterling y DU

Code      : GBP
Precision : 2
Symbol    : £
Name      : Punnd Sasannach na RA

Code      : GBP
Precision : 2
Symbol    : £
Name      : Pound Sterling

Next you will need the serviceVersionId (Guid). This is Id of the Dynamics release that you want your instance to be based on. Again there is an Cmdlets which lists all of the available versions.

$serviceVersions = Get-CrmServiceVersions -ApiUrl $ApiUrl -Credential $Cred
$serviceVersions | Format-List

Depending on your tenant you may see more or less options listed. Below is a list from a .crm4 instance. I had only Dynamics 365 from a .crm11 instance.

LocalizedName : Dynamics 365
LCID          : 1033
Version       : 8.2
Id            : 31cafafe-c6b1-4c0a-bb53-73927841bc5c
Name          : Dynamics 365

LocalizedName : Microsoft Dynamics CRM Online 2016 Update 1
LCID          : 1033
Version       : 8.1
Id            : aaf5fa67-3f34-835d-85bb-6c8eb44aff8d
Name          : Microsoft Dynamics CRM Online 2016 Update 1

LocalizedName : Microsoft Dynamics CRM Online 2016
LCID          : 1033
Version       : 8.0
Id            : 015e6a5c-2fa5-e411-80ce-00155db07c21
Name          : Microsoft Dynamics CRM Online 2016

LocalizedName : Microsoft Dynamics CRM Online 2015 Update 1 (May 2015)
LCID          : 1033
Version       : 7.1
Id            : 9f2caf05-45b9-e411-80ec-6c3be5a88dd4
Name          : Microsoft Dynamics CRM Online 2015 Update 1 (May 2015)

In this case all we need is the (Guid) so lets go with “Dynamics 365” for now.

$releaseId = ’31cafafe-c6b1-4c0a-bb53-73927841bc5c’

Next you will need to set the language of your instance. For this you will need the integer language Id.

$languageId = 1033

If you are not sure on the language Id or the languages that are supported, again there is another Cmdlet for that.

$languages = Get-CrmLanguages -ApiUrl $ApiUrl -ServiceReleaseId $releaseId -Credential $Cred
$languages | Format-Table

Below is the list of languages available on my instance.

LCID Name                                LocalizedName
---- ----                                -------------
1033 English                             English (United States)
1025 Arabic                              العربية (المملكة العربية السعودية)
1069 euskara (euskara)                   euskara (euskara)
1026 български (България)                български (България)
1027 Català (Català)                     Català (Català)
3076 Chinese (Hong Kong S.A.R.)          中文(香港特別行政區)
2052 Chinese (PRC)                       中文(中华人民共和国)
1028 Chinese (Taiwan)                    中文(台灣)
1050 hrvatski (Hrvatska)                 hrvatski (Hrvatska)
1029 Czech                               čeština (Česká republika)
1030 Danish                              dansk (Danmark)
1043 Dutch                               Nederlands (Nederland)
1061 eesti (Eesti)                       eesti (Eesti)
1035 Finnish                             suomi (Suomi)
1036 French                              français (France)
1110 galego (galego)                     galego (galego)
1031 German                              Deutsch (Deutschland)
1032 Greek                               Ελληνικά (Ελλάδα)
1037 Hebrew                              עברית (ישראל)
1081 हिंदी (भारत)                        हिंदी (भारत)
1038 Hungarian                           magyar (Magyarország)
1040 Italian                             italiano (Italia)
1041 Japanese                            日本語 (日本)
1087 Қазақ (Қазақстан)                   Қазақ (Қазақстан)
1042 Korean                              한국어(대한민국)
1062 latviešu (Latvija)                  latviešu (Latvija)
1063 lietuvių (Lietuva)                  lietuvių (Lietuva)
1044 Norwegian (Bokmål)                  norsk, bokmål (Norge)
1045 Polish                              polski (Polska)
1046 Portuguese (Brazil)                 português (Brasil)
2070 Portuguese (Portugal)               português (Portugal)
1048 română (România)                    română (România)
1049 Russian                             русский (Россия)
2074 srpski (Srbija i Crna Gora (Bivša)) srpski (Srbija i Crna Gora (Bivša))
1051 slovenčina (Slovenská republika)    slovenčina (Slovenská republika)
1060 slovenščina (Slovenija)             slovenščina (Slovenija)
3082 Spanish                             español (España, alfabetización internacional)
1053 Swedish                             svenska (Sverige)
1054 Thai                                ไทย (ไทย)
1055 Turkish                             Türkçe (Türkiye)
1058 українська (Україна)                українська (Україна)
3098 Serbian (Cyrillic)                  српски (Србија и Црна Гора (Бивша))
1086 Malay                               Bahasa Melayu (Malaysia)

Now you will need to select the templates that you need to apply on your instance. These are the different modules that you can install on your instance such as Sales or Customer Service. In this case I will select the Sales and Customer Service.

$templateNames = "D365_Sales", "D365_CustomerService"

If you are not sure on what are the different values and what is supported on your tenant, you can use the Cmdlet below to get a list of supported templates.

$templates = Get-CrmTemplates -ApiUrl $ApiUrl -Credential $Cred
$templates | Format-List

Below is a list of templates currently available in my tenant which is the output from the script above.

Name                     : D365_Sales
LocalizedName            : Sales
LocalizedDescription     : Manage leads, close deals and accomplish more.
SupportedServiceVersions : {bce9abbf-90fd-42e7-b0e5-1ced6df22fa1, 31cafafe-c6b1-4c0a-bb53-73927841bc5c}

Name                     : D365_CustomerService
LocalizedName            : Customer service
LocalizedDescription     : Resolve cases quickly and deliver amazing customer service.
SupportedServiceVersions : {bce9abbf-90fd-42e7-b0e5-1ced6df22fa1, 31cafafe-c6b1-4c0a-bb53-73927841bc5c}

Name                     : D365_FieldService
LocalizedName            : Field service
LocalizedDescription     : Optimize onsite customer care.
SupportedServiceVersions : {bce9abbf-90fd-42e7-b0e5-1ced6df22fa1, 31cafafe-c6b1-4c0a-bb53-73927841bc5c}

Name                     : D365_ProjectServiceAutomation
LocalizedName            : Project service automation
LocalizedDescription     : Complete projects on time and within budget.
SupportedServiceVersions : {bce9abbf-90fd-42e7-b0e5-1ced6df22fa1, 31cafafe-c6b1-4c0a-bb53-73927841bc5c}

Now that we have all the different parameters we can create an instance, we need to create a new instance object with the values as per below. The domain name is the name that will appear in the url (i.e. https://%5Bdomainname%5D.crm4.dynamics.com). Instance type will be one of: Production, Sandbox, Support, Preview, Trial


$instanceInfo = New-CrmInstanceInfo -BaseLanguage $languageId -DomainName "<span 				data-mce-type="bookmark" 				id="mce_SELREST_start" 				data-mce-style="overflow:hidden;line-height:0" 				style="overflow:hidden;line-height:0" 			></span>testpowershell<span 				data-mce-type="bookmark" 				id="mce_SELREST_end" 				data-mce-style="overflow:hidden;line-height:0" 				style="overflow:hidden;line-height:0" 			></span>" -FriendlyName "Test PowerShell" -InitialUserEmail "user@domain.com" -InstanceType "Sandbox" -ServiceVersionId $releaseId -Purpose "Testing PowerShell" -TemplateList $templateNames

Finally You need to call the Cmdlet to create your new instance. You will get the OperationId back along with the status including errors if any. You can use the OperationId query the status of creation operation and possibly wait until it completes. This can be as quick as a few seconds. In most cases the operation seems to return immediately which status of “Succeeded”.

$operation = New-CrmInstance -ApiUrl $ApiUrl -NewInstanceInfo $instanceInfo -Credential $Cred

$OperationId = $operation.OperationId
$OperationStatus = $operation.Status

You should now be able to view the instance in the admin portal.

InstanceCreated

I have published a simple script on GitHub which encapsulates all of this functionality and you can view it here.

If you need more information on creating instances you can visit the API documentation here. In the next post I will show you how to view your instance and also delete specific instances.

 

Advertisements

Online Management PS Module for Dynamics 365 CE – Part 1 (Backup Instance)

In this post I will provide you an introduction to the new Online Management PowerShell module and show you how to get started using it straight away.

Last month Microsoft released new documentation for the Online Management REST API which you can find here. There was mention of PowerShell Cmdlets but there wasn’t much information available. You can find more information about using the REST API in Marius’s blog. A few days ago I was browsing the PowerShell gallery and I came across the new PowerShell Module. You can find it here. I couldn’t find much documentation on using it but using the REST API documentation and inspecting the PowerShell module I was able to get it working within an hour.

Before going into how to get started, just want to highlight a few reasons why you may want to consider using this. Today the online way to manage CRM Online instances is to login to the Admin portal and manage it manually. The PowerShell module opens up a lot of opportunities.

  1. You script any administrative tasks that you perform regularly on your CRM instances
  2. You can use this as part of your Continuous Integration/Delivery pipeline, so you can automatically backup/restore your environment during a release
  3. You can automatically spin up, configure and delete environments as required

Let’s go through how you can backup a CRM instance. To get started you will need to save the module to a local folder.

PS> Save-Module -Name Microsoft.Xrm.OnlineManagementAPI -Path "C:\Dev\PowerShell"

Now you need to load the module that contains the Cmdlets

Import-Module "C:\Dev\PowerShell\Microsoft.Xrm.OnlineManagementAPI\0.0.1.0\Microsoft.Xrm.OnlineManagementAPI.dll"

Next you need to define the backup information. I have only listed the required parameters to do the backup.
You can find more information on the rest of the parameters using the API Reference documentation here. You can find your instance Id by logging in to your CRM instance and going to the developer resources page.


$backupInfo = New-CrmBackupInfo -InstanceId "[GUID]" -Label "Test Backup" -IsAzureBackup $false -Notes "Just testing..."

Next is setup your credentials.


$Username = "user@instancename.onmicrosoft.com"
$Password = "password"

#Create Credentials
$SecPassword = ConvertTo-SecureString $Password -AsPlainText -Force
$Cred = New-Object System.Management.Automation.PSCredential ($Username, $SecPassword)

Now the final step is to call the Cmdlet to do the backup. Note if you don’t supply the credentials, you will be prompted to enter these. ApiUrl will differ based on location. You can find your ApiUrl here.


$backupOutput = Backup-CrmInstance -ApiUrl "https://admin.services.crm4.dynamics.com" -BackupInfo $backupInfo -Credential $Cred

$OperationId = $backupOutput.OperationId
$OperationStatus = $backupOutput.Status

Write-Output "OperationId = $OperationId"
Write-Output "Status = $OperationStatus"

You can then use the OperationId to query the status of your backup and wait until it completes if needed. To make it easy for you I have written a script that does exactly that. You can find it as part of the XrmCIFramework on GitHub.

And here is the backup that was just created 🙂

You should be able to get the other Cmdlets working in a similar way. Hope you find this useful.

Stay tuned for more posts on DevOps and Dynamics 365…

Journey to Implementing Continuous Delivery for Dynamics CRM

In this post I will show you how you can implement Continuous Delivery for your Dynamics CRM solutions. Using the latest version of Team Foundation Server (TFS), Visual Studio Release Management and xRM CI Framework you will be able to implement one-click automated deployments across all your environments including production. This will enable you provide continuous business value to your stakeholders by releasing small changes more frequently, consistently and reliably. This is very much inline with Agile methodologies of software delivery.

Stage 1: Automate your Builds

Before you can automate your deployment and release processes you need to have an automated consistent way of building your Dynamics CRM components. In terms of deployment your components will be artifacts like CRM Solutions, Configuration Data, CRM Deployment Packages and others. Team Foundation Server provides an excellent Build Automation and Continuous Integration Engine that you can use for this.

Using xRM CI Framework you can easily create automated builds for your Dynamics CRM solutions with a few clicks. Follow the documentation on codeplex to create your build. The build will generate your CRM components and place them in the designated drop location. This can now be picked up by your Release Automation tool which in this case will be Visual Studio Release Management.

Stage 2: Automate your Deployments

Having a consistent build process in place, you can now move into automating the deployment of the components produced above. You will use PowerShell scripts to automate the deployment process. The latest Sdk for Dynamics CRM 2013 comes with PowerShell extensions that allow you deploy CRM Deployment Packages.

The xRM CI Framework comes with two generic PowerShell Scripts. The first one allows you to import CRM Solutions and the second one allows you to deploy a CRM Deployment Package. Depending your scenario you can get started by using either of these scripts and tweak them to your needs. Note the xRM CI Framework also contains many custom PowerShell Cmdlets (Commands) that you can use in your scripts. Check out the documentation on codeplex for more information.

Now you should have some scripts that you can run on to deploy your automated Build outputs.

Stage 3: Automate your Testing

You should be really thinking about this from the start and writing automated tests as requirements come in. The reason I put this at this stage is because as far as Continuous Delivery is concerned you can’t execute your automated tests without having first build and deployed your application to your stage or testing environment. Ideally you want to run Unit Tests during each Check-In and Integration and functional tests in your Continuous Integration and Nightly builds. Finally sanity tests can be run after deployment to your UAT & Production environments.

The xRM Test Framework contains lots of utility classes and productivity tools to allow to easily create Unit and Integration Test for your Dynamics CRM deployments. Check out the detailed documentation and webinars on codeplex. These tests can then be executed during your builds and post your release using Visual Studio Release Management.

Stage 4: Automate your Releases

Once you have your automated builds and deployment scripts ready, you can start thinking about release automation. Release automation allows you to do one click deployments across all your environments. Visual Studio also includes cool features such as security, audit, configuration and environment management and most importantly an easy visual tool to allow you to model your release process using workflows.

In the following post I will show you on how to use Release Management with Dynamics CRM.

Hope you found this post useful.

 

xRM CI Framework for Dynamics CRM 2013 SP1 is now available

The xRM Continuous Integration (CI) Framework is a set of tools that makes it easy and quick to automate the builds and deployment of your CRM components.

Implementing continuous integration is always a nice to have feature on Dynamics CRM projects which in most cases gets left for various reasons even though having this setup will save lots of time long term, reduce therisk and improve productivity. Using xRM CI Framework you can quickly implement a build->deploy->test workflow with a few clicks. This is achieved by providing easy to use templates and sample scripts. These can also be easily extend to meet any complex or specific scenarios you might have.

Dynamics CRM 2013 SP1 has been recently released and come with lots of new exiting features and capabilities. This includes an updated SDK. To compliment this release I have updated the xRM CI Framework to take advantage of these new capabilities. Hopefully this will allow you to put in these best practices and automation in place as you start your new Dynamics CRM 2013 projects.

Below is a list of updates from the CRM 2013 version:

  • Support for Dynamics CRM 2013 SP1 Online/OnPremise
  • Uses the latest Dynamics CRM 2013 SP1 SDK
  • Ability to Build and Deploy CRM Deployment Packages
  • Integration with Visual Studio Release Management
  • More Sample Scripts
  • More PowerShell Cmdlets
  • New custom Dynamics CRM Build Template  for TFS 2013 (see process below)

 

BuildTemplate

I have uploaded the source code to codeplex with lots of steps by step instructions to get your started quickly. This will also allow you to extend the framework to meet your needs.

Please post any feedback, comments, issues, discussion on the codeplex site.

Feel free to get in touch if you would like to contribute with ideas, enhancements and new features.

I have also created a download to the new Framework from the Visual Studio Gallery here.

I am presenting @CRMUG UK Regional Chapter (July 2014)

CRMUG Logo

Join me for the next meeting of the CRMUG UK Regional Chapter Meeting on Thursday, July 17th at Microsoft Cardinal Place Victoria, London. The July meeting will focus on using Microsoft Dynamics CRM for managing Customer, Citizen, and other kinds of “Service”. Don’t miss this opportunity to experience what CRMUG has to offer you and fellow Dynamics CRM users in your area!

I will be presenting a session about “One-Click Dynamics CRM Deployments ” at 11:15 AM.

“Find out how you can automate the build and deployment processes for your CRM solutions. The session will demonstrate how the latest tools from the CRM SDK, TFS 2013, Visual Studio Release Management & xRM CI Framework can work together to implement end to end one-click deployments of your enterprise Dynamics CRM Solutions across all your environments. This will allow you to deliver CRM more frequently in a consistent and reliable way.

Don’t forget to take a look at the full Agenda in here. There will be multiple tracks with a range of topics to suite all roles.

Looking forward to seeing you all in there.

xRM Test Framework for Dynamics CRM 2013 is now available

The xRM Test Framework  is a set of tools that allows you easily and quickly create automated units and integration tests for your Dynamics CRM extensions.

Testing plug-ins and custom workflow activities can be quite challenging and time consuming using standard approaches. This sometimes discourages developers from writing automated tests for Dynamics CRM extensions. This can lead to quality issues and wasted effort and time down the line. The framework attempts to encourage the adoption of testing best practices in Dynamics CRM projects.

Below is what the framework provides.

Base Test Library

  • Bases classes for testing Plug-ins and Custom Workflow Activities. All tests extend from these classes.
  • These cover your Unit & Integration Tests
  • These do most of the ground work and allow you to focus on writing your test scenarios in your tests.
  • Available via NuGet
  • Support for Microsoft Fakes & Moq

Below is a high level diagram for the base classes.

TestBaseClasses

To add the Xrm.Framework.Test assembly to your existing Test project.

  1. In your existing test project – Right click on References -> Manage NuGet Packages…
  2. Click on Online in the left tree and then search for “Xrm.Framework.Test”
  3. Click install – this will add the assembly and the NuGet package to your project

You should be able to see the below:

NuGetXrmTest

Productivity Tools

  • These provide templates to enforce standard patterns and best practices
  • Templates allow you to easily and consistently create your tests
  • Visual Studio Project Templates for creating Test Projects
  • Visual Studio Templates for creating Tests for different extensions
  • Available via the Visual Studio Gallery

To get start just install the extension from the visual studio.

  1. Open Visual Studio
  2. From the menu bar click on Tools -> Extensions & Updates…
  3. Click on Online in the left tree and then search for “xRM”
  4. Download and install the extension

You should be able to see the below:

DownloadXrmTestFramework

You can also download it from Visual Studio Gallery directly.

After you install the extension you should be to create a new Test project by going into the “Dynamics CRM” category in Visual Studio. Below is what you should be able to see in addition to the CRM Developer Toolkit templates.

NewXrmTestProject

After you create the project you should be able to add new Tests to your project using the Framework templates. Again these will be in the “Dynamics CRM” category as you can see below.

NewTest

Finally I would like to thank Ramon Tebar (MVP) for his help and contributions especially in making this Framework work with Microsoft Fakes and Dynamics CRM 2013.

So whats next? In future posts I will show how to create different types of tests for your CRM extensions.

I am presenting at extremeCRM 2014 Barcelona

Barcelona%20Signature_CRM%20Im%20Speaking%20at

eXtremeCRM is the hub where Microsoft Dynamics CRM partners come together to forge business relationships, gain knowledge from real-world experiences and dive deep into current and future technologies.  For Microsoft Dynamics CRM partner organizations, it is the annual conference to attend to nurture best practices, facilitate business growth, and educate each organization member.  The highly anticipated conference will be held in Barcelona, Spain, 9 – 12 February, 2014.

Join me on Tuesday 11 Feb at 16:45 in room H3 for my session on “Continuous Delivery – Deliver CRM More Frequently in a Consistent and Reliable Way“. Summary of the session below. You can find all the details in here.

“In this session I will show you what it takes to achieve Continuous Delivery in an enterprise environment through automating the build, deployment and testing of your CRM solutions. I will include a demo of an end to end journey of taking a requirement from definition all the way into production using the latest Automation Tools and best practices (Team Foundation Server 2013, Release Management for Visual Studio, PowerShell & xRM CI Framework for Dynamics CRM 2013). I will discuss suitable implementation options for your target infrastructure to cover on-premise and cloud implementation.

This session will be particularly useful for delivering Dynamics CRM into organizations where there is demand for quick results, quality, efficiency, controlled processes and audit.”

Looking forward to seeing you all in there. Don’t forget to take a look at the full Agenda in here.