Getting Started

Download and install the ALM Toolkit to your developer workstation.  This will extract the files to your hard drive.  Once the files are extracted, you can move them to any location in your environment.  They do not need to be locally installed to use them.

The advanced toolkit functions that involve SQL Server database management require the SQLPS module to be installed (on the machine running the scripts) from the Microsoft® SQL Server® 2012 Feature Pack. Under the Install Instructions, install the following packages (in order):
  1. Microsoft® System CLR Types for Microsoft® SQL Server® 2012 (SQLSysClrTypes.msi)
  2. Microsoft® SQL Server® 2012 Shared Management Objects (SharedManagementObjects.msi)
  3. Microsoft® Windows PowerShell Extensions for Microsoft® SQL Server® 2012 (PowerShellTools.msi)

If you posses a license key file (a text with .lic extension), place the file into the folder "${Env:ProgramFiles(x86)}\ADXSTUDIO\ALM Toolkit\1.0.00xx\Adxstudio.Xrm.PowerShell\" to enable the license key. The .lic file should share the same folder as the Adxstudio.Xrm.PowerShell.dll file. Restart the PowerShell console or ISE if it was loaded previously. Note that if the toolkit was installed under the Program Files folder, it is advisable to take a copy of the 1.0.00xx folder over to a separate folder (ex. C:\ALM\) to avoid file permission restrictions.

The ALM Toolkit is a set of PowerShell scripts and command line utilities.  If you are not familiar with PowerShell, please read the Microsoft documentation.  Here are some basic steps that you will need to do to first start using the scripts.

The scripts need to run in an elevated PowerShell execution policy.  You can check your current settings by running the powershell command Get-ExecutionPolicy.  It should return RemoteSigned or Unrestricted.  If it is anything else, please run the command Set-ExecutionPolicy RemoteSigned.

In order to use the Adxstudio ALM Toolkit PowerShell scripts, you will need to import the module.  In any of your scripts, simply add the following line to import the required module (where the current directory location is the "Scripts" folder of the installed files):

cd "${Env:ProgramFiles(x86)}\ADXSTUDIO\ALM Toolkit\1.0.00xx\Scripts\"

Import-Module ../Adxstudio.Xrm.PowerShell

Calling Import-Module ../Adxstudio.Xrm.PowerShell/Adxstudio.Xrm.PowerShell.psd1 produces the same result of loading the module.

The easiest way to get started with the ALM Toolkit is to view the commands that we have included in our libraries.  Execute the following PowerShell command to get a list of our CRM powershell scriptlets: 

Get-Command -Module Adxstudio.Xrm.PowerShell 

The commands that are available cover many CRM operations including managing your CRM organizations via the deployment service (creating, importing, deleting CRM organizations), working with solution files (importing, exporting, publishing changes), basic CRM data operations (create, read, update, delete), ALM data operations (import/export data), and the ability to call CRM services within the PowerShell environment.

To view the documentation for any command, simply execute the following command:  Get-Help <command name>

We ship a number of sample scripts that can be found in the Scripts folder.  Please review these to see examples of how to use the scripts.  You may have to adjust some variables in the scripts to suit your environment.

If you are using Windows 7, please be aware that the Powershell configuration uses the .Net Framework version 3.5.  Since our scripts use the .Net 4.0 framework, you will have to reconfigure PowerShell to use .Net 4.0.  The easiest way to do that is to execute the PowerShell command $pshome to locate the installation folder for PowerShell.  Once you locate the folder, please copy the powershell.exe.config file from the ALM Toolkit's bin folder to that folder.  This will enable PowerShell to use the .Net Framework version 4.0. To verify the .Net Framework version, run $PSVersionTable to check that the CLRVersion value is 4.0.

System Entities Not Supported by Data Copy

There are some system entities are excluded from the data export/import process. This applies to the Export-CrmContent, Import-CrmContent cmdlets as well as the CrmDataCopy.exe tool. If an entity is marked as not importable (ie. IsImportable = false), the entity is excluded from being exported. The "importable" flag for each system entity can be found in MSDN or with various tools. In addition to those entities, the following entities are not supported for data export/import:

  • activityparty
  • businessunitnewsarticle
  • license
  • msdyn_postalbum
  • msdyn_postconfig
  • msdyn_postruleconfig
  • msdyn_wallsavedquery
  • msdyn_wallsavedqueryusersettings
  • organization
  • post
  • postcomment
  • postfollow
  • privilege
  • queue
  • queueitem
  • ribboncommand
  • ribboncontextgroup
  • ribboncustomization
  • ribbondiff
  • ribbonrule
  • ribbontabtocommandmap
  • roletemplate
  • roletemplateprivileges
  • sitemap
  • systemform
  • systemuser
  • systemuserlicenses
  • systemuserprofiles
  • systemuserroles
  • team
  • teammembership
  • teamprofiles
  • teamroles

In many cases, it is possible to use other components of the ALM Toolkit to read and work with these entities for operations other than data coping.