Modules, acronyms, environment variables and paths in Pivotal

Every module in Pivotal is also known for its acronym. The most common modules, the base modules, are the Pivotal Customer Management (PCM) and the Customer Management System (CMS). These are probably the most known modules, but there are many others. There is no documentation or list that identifies all the acronyms, so I decided to summarize them here.

For developers it is very important to understand these acronyms, and also, to understand the effect that the installation of a module has on a development machine. So for example, a module installation creates an environment variable that points to the path where all the assemblies for such module are, which is relevant if we want to use Visual Studio to extend the module. I will explain this later in the article, but first let me explain all the modules available for a Pivotal system.

Pivotal modules

There are two possible base modules, the PCM and the CMS. The CMS is the old (5.x) base module containing Sales, Support and Marketing all in one package. Pivotal released PCM as the new base module, as a simpler and more elegant module for the pivotal 6.x version of the product. The following lists summarizes all the modules and their acronyms:

PCM

CMS

Notice that the CMS track doesn’t contain the Customer Service and Support, Sales Force Automation and Territory Management, but this is because, the CMS already contains these modules in the core. The only module that is not yet released for CMS is the Web Portal one (relevant if you use Thin Client). It is true that both PCM and CMS, although very similar, are not functionally equivalent, there might be some features in PCM that are not present in CMS (e.g. the integration with mapping services such as Google maps or Bing maps).

Environment variables

When you install a Pivotal module on a development machine, the following things occur:

• The module is installed by default in C:\Program Files[ (x86)]\CDC Software\Pivotal CRM\Applications
• Each module will create an Assemblies folder where all the .Net assemblies that implement the module will be placed. You will need these assemblies in case you want to extend the module and add references in Visual Studio.
• A system environment variable is created. This variable is created by the acronym of the module concatenated with the word Path at the end. So for example, if you install the SFA module an environment variable with the name SFAPath will be created. This variable will point to the path where the assemblies for such module are installed. So for example, the SFAPath variable will point to C:\Program Files[ (x86)]\CDC Software\Pivotal CRM\Applications\Sales Force Automation\Assemblies

In addition to the environment variables created by each module, there are some generic environment variables that you need to consider as well. These variables are automatically created when you install the PBS, Pivotal Client and Smart Client Framework. The following is the complete list of such environment variables:

So why you need to care about this? Because all the Pivotal source code, visual studio templates, etc. have references to these variables. If you open one of the projects (using a text editor) for one of the modules (the source code is installed as part of the module installation) you will notice that there are a bunch of references using this style:

<Reference Include="Applications.Core.Common, Version=6.0.6.0, Culture=neutral, PublicKeyToken=47e8a196c40562a5, processorArchitecture=MSIL">
  <SpecificVersion>False</SpecificVersion>
  <HintPath>$(COREPath)\Common\Applications.Core.Common.dll</HintPath>
  <Private>False</Private>
</Reference>
<Reference Include="Applications.Core.Data, Version=6.0.6.0, Culture=neutral, PublicKeyToken=47e8a196c40562a5, processorArchitecture=MSIL">
  <SpecificVersion>False</SpecificVersion>
  <HintPath>$(COREPath)\Common\Applications.Core.Data.dll</HintPath>
  <Private>False</Private>
</Reference>
<Reference Include="Applications.Core.Server, Version=6.0.6.0, Culture=neutral, PublicKeyToken=47e8a196c40562a5, processorArchitecture=MSIL">
  <SpecificVersion>False</SpecificVersion>
  <HintPath>$(COREPath)\Server Tasks\Applications.Core.Server.dll</HintPath>
  <Private>False</Private>
</Reference>
<Reference Include="Applications.Core.Server.InteractionServices, Version=6.0.6.0, Culture=neutral, PublicKeyToken=47e8a196c40562a5, processorArchitecture=MSIL">
  <SpecificVersion>False</SpecificVersion>
  <HintPath>$(COREPath)\Server Tasks\Applications.Core.Server.InteractionServices.dll</HintPath>
  <Private>False</Private>
</Reference>
<Reference Include="Css.Common.WorkingDaysCalendar, Version=6.0.8.0, Culture=neutral, PublicKeyToken=47e8a196c40562a5, processorArchitecture=MSIL">
  <SpecificVersion>False</SpecificVersion>
  <HintPath>$(CSSPath)\Common\Css.Common.WorkingDaysCalendar.dll</HintPath>
  <Private>False</Private>
</Reference>
<Reference Include="Css.Data, Version=6.0.8.0, Culture=neutral, PublicKeyToken=47e8a196c40562a5, processorArchitecture=MSIL">
  <SpecificVersion>False</SpecificVersion>
  <HintPath>$(CSSPath)\Common\Css.Data.dll</HintPath>
  <Private>False</Private>
</Reference>
<Reference Include="Css.Server.FormTasks.ServiceTicket, Version=6.0.8.0, Culture=neutral, PublicKeyToken=47e8a196c40562a5, processorArchitecture=MSIL">
  <SpecificVersion>False</SpecificVersion>
  <HintPath>$(CSSPath)\Server Tasks\Css.Server.FormTasks.ServiceTicket.dll</HintPath>
  <Private>False</Private>
</Reference>
<Reference Include="Pivotal.Core, Version=6.0.0.0, Culture=neutral, PublicKeyToken=1ef445b59b9ece60, processorArchitecture=MSIL">
  <SpecificVersion>False</SpecificVersion>
  <HintPath>$(LCSPath)\Pivotal.Core.dll</HintPath>
  <Private>False</Private>
</Reference>
<Reference Include="Pivotal.Core.Common, Version=6.0.0.0, Culture=neutral, PublicKeyToken=1ef445b59b9ece60, processorArchitecture=MSIL">
  <SpecificVersion>False</SpecificVersion>
  <HintPath>$(LCSPath)\Pivotal.Core.Common.dll</HintPath>
  <Private>False</Private>
</Reference>

Notice the highlighted lines, they have references to the environment variables mentioned before. So, if your development machine doesn’t have the environment variables configured then the project will not compile since Visual Studio will not be able to find those references.

The reference paths in the Toolkit

So, now that you understand all the environment variables, and how to make your projects compile, comes the time when you need to upload the assembly into the BM using the toolkit. You use the Code File Importer. But when importing you get an error saying that it is not able to find a particular assembly. This is because the Toolkit analyses the assembly and checks its references, so it needs to know where those references are. You need to tell the Toolkit where to find those assemblies. You do this using the Reference Paths tab in the Code File Importer:

You will need to add a reference path (a folder) to each of the assemblies’ directories you are referencing. The following is a list of all the folders you need to add:

$(LCSPath)
 $(COREPath)\Client Tasks
 $(COREPath)\Common
 $(COREPath)\Server Tasks
 $(PCMPath)\Client Tasks
 $(PCMPath)\Common
 $(PCMPath)\Server Tasks
 $(OIPath)
 $(SCCPath)
 $(SCCustomPath)
 $(SCClientPath)
 $(SCPBSPath)
 $(AWMPath)\Client
 $(AWMPath)\Common
 $(AWMPath)\Server
 $(CCPath)\Client
 $(CCPath)\Common
 $(CCPath)\Server
 $(CSSPath)\Client Tasks
 $(CSSPath)\Common
 $(CSSPath)\Server Tasks 
 $(DMMPath)\Client Tasks
 $(DMMPath)\Common
 $(DMMPath)\Data
 $(DMMPath)\Server Tasks
 $(EMPath)
 $(MRMPath)\Client Tasks
 $(MRMPath)\Data
 $(MRMPath)\Server Tasks
 $(PDMPath)\Application Pages
 $(PDMPath)\Client Tasks
 $(PDMPath)\Data
 $(PDMPath)\Server Tasks
 $(SCRMPath)
 $(SFAPath)\Client Tasks
 $(SFAPath)\Data
 $(SFAPath)\Server Tasks
 $(TMPath)
 $(WPPath)

Notice that each module specifies more than one folder. This is because some modules have different folders for client and server tasks.

Adding these folder one by one is a long task. The good news is that these folders are stored in the registry so you can create a .reg file to add them all at once. The registry path where these references are stores is the following:

For a 64bit OS: HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Pivotal\Relationship\Connections\CRM CM\Code File Importer\Search Folders

For a 32bit OS: HKEY_LOCAL_MACHINE\SOFTWARE\Pivotal\Relationship\Connections\CRM CM\Code File Importer\Search Folders

To add all them at once, just import this file (remove the Wow6432Node part if you’re using a 32bit OS):

Windows Registry Editor Version 5.00

[HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Pivotal\Relationship\Connections\CRM CM\Code File Importer\Search Folders]
"Folder0"="C:\\Program Files (x86)\\CDC Software\\Pivotal CRM\\Applications\\Application Workflow Module 6.0.9\\Assemblies\\Client"
"Folder1"="C:\\Program Files (x86)\\CDC Software\\Pivotal CRM\\Applications\\Application Workflow Module 6.0.9\\Assemblies\\Common"
"Folder2"="C:\\Program Files (x86)\\CDC Software\\Pivotal CRM\\Applications\\Application Workflow Module 6.0.9\\Assemblies\\Server"
"Folder3"="C:\\Program Files (x86)\\CDC Software\\Pivotal CRM\\Applications\\Contact Center 6.0.9\\Assemblies\\Client"
"Folder4"="C:\\Program Files (x86)\\CDC Software\\Pivotal CRM\\Applications\\Contact Center 6.0.9\\Assemblies\\Common"
"Folder5"="C:\\Program Files (x86)\\CDC Software\\Pivotal CRM\\Applications\\Contact Center 6.0.9\\Assemblies\\Server"
"Folder6"="C:\\Program Files (x86)\\CDC Software\\Pivotal CRM\\Applications\\Customer Service and Support 6.0.8\\Assemblies\\Client Tasks"
"Folder7"="C:\\Program Files (x86)\\CDC Software\\Pivotal CRM\\Applications\\Customer Service and Support 6.0.8\\Assemblies\\Common"
"Folder8"="C:\\Program Files (x86)\\CDC Software\\Pivotal CRM\\Applications\\Customer Service and Support 6.0.8\\Assemblies\\Server Tasks"
"Folder9"="C:\\Program Files (x86)\\CDC Software\\Pivotal CRM\\Applications\\Data Management Module 6.0.9\\Assemblies\\Client Tasks"
"Folder10"="C:\\Program Files (x86)\\CDC Software\\Pivotal CRM\\Applications\\Data Management Module 6.0.9\\Assemblies\\Common"
"Folder11"="C:\\Program Files (x86)\\CDC Software\\Pivotal CRM\\Applications\\Data Management Module 6.0.9\\Assemblies\\Data"
"Folder12"="C:\\Program Files (x86)\\CDC Software\\Pivotal CRM\\Applications\\Data Management Module 6.0.9\\Assemblies\\Server Tasks"
"Folder13"="C:\\Program Files (x86)\\CDC Software\\Pivotal CRM\\Applications\\Document Management 6.0.9\\Assemblies\\Application Pages"
"Folder14"="C:\\Program Files (x86)\\CDC Software\\Pivotal CRM\\Applications\\Document Management 6.0.9\\Assemblies\\Client Tasks"
"Folder15"="C:\\Program Files (x86)\\CDC Software\\Pivotal CRM\\Applications\\Document Management 6.0.9\\Assemblies\\Data"
"Folder16"="C:\\Program Files (x86)\\CDC Software\\Pivotal CRM\\Applications\\Document Management 6.0.9\\Assemblies\\Server Tasks"
"Folder17"="C:\\Program Files (x86)\\CDC Software\\Pivotal CRM\\Applications\\Email Marketing 6.0.10\\Assemblies"
"Folder18"="C:\\Program Files (x86)\\CDC Software\\Pivotal CRM\\Applications\\Marketing Resource Management 6.0.9\\Assemblies\\Client Tasks"
"Folder19"="C:\\Program Files (x86)\\CDC Software\\Pivotal CRM\\Applications\\Marketing Resource Management 6.0.9\\Assemblies\\Data"
"Folder20"="C:\\Program Files (x86)\\CDC Software\\Pivotal CRM\\Applications\\Marketing Resource Management 6.0.9\\Assemblies\\Server Tasks"
"Folder21"="C:\\Program Files (x86)\\CDC Software\\Pivotal CRM\\Applications\\Pivotal Contact Management 6.0.8\\Assemblies\\Core\\Client Tasks"
"Folder22"="C:\\Program Files (x86)\\CDC Software\\Pivotal CRM\\Applications\\Pivotal Contact Management 6.0.8\\Assemblies\\Core\\Common"
"Folder23"="C:\\Program Files (x86)\\CDC Software\\Pivotal CRM\\Applications\\Pivotal Contact Management 6.0.8\\Assemblies\\Core\\Server Tasks"
"Folder24"="C:\\Program Files (x86)\\CDC Software\\Pivotal CRM\\Applications\\Pivotal Contact Management 6.0.8\\Assemblies\\PCM\\Client Tasks"
"Folder25"="C:\\Program Files (x86)\\CDC Software\\Pivotal CRM\\Applications\\Pivotal Contact Management 6.0.8\\Assemblies\\PCM\\Common"
"Folder26"="C:\\Program Files (x86)\\CDC Software\\Pivotal CRM\\Applications\\Pivotal Contact Management 6.0.8\\Assemblies\\PCM\\Server Tasks"
"Folder27"="C:\\Program Files (x86)\\CDC Software\\Pivotal CRM\\Applications\\Sales Force Automation 6.0.8\\Assemblies\\Client Tasks"
"Folder28"="C:\\Program Files (x86)\\CDC Software\\Pivotal CRM\\Applications\\Sales Force Automation 6.0.8\\Assemblies\\Data"
"Folder29"="C:\\Program Files (x86)\\CDC Software\\Pivotal CRM\\Applications\\Sales Force Automation 6.0.8\\Assemblies\\Server Tasks"
"Folder30"="C:\\Program Files (x86)\\CDC Software\\Pivotal CRM\\Applications\\Social CRM 6.0.10\\Assemblies"
"Folder31"="C:\\Program Files (x86)\\CDC Software\\Pivotal CRM\\Applications\\Territory Management 6.0.11\\Assemblies"
"Folder32"="C:\\Program Files (x86)\\CDC Software\\Pivotal CRM\\Business Server"
"Folder33"="C:\\Program Files (x86)\\Grupo Lanka\\Pivotal CRM\\Framework Library\\Assemblies"
"Folder34"="C:\\Program Files\\CDC Software\\Smart Updater\\40\\Packages\\PivotalClient\\Client\\6.0.9.1\\bin\\standard"
"Folder35"="C:\\Program Files\\CDC Software\\Smart Updater\\40\\Packages\\PivotalClient\\Custom\\6.0.9.1\\bin\\standard"
"Folder36"="C:\\Program Files\\CDC Software\\Smart Updater\\40\\Packages\\PivotalClient\\PBS\\6.0.9.0\\bin\\standard"
"Folder37"="C:\\Program Files\\CDC Software\\Smart Updater\\40\\Packages\\PivotalOfficeIntegration\\OIRuntime\\6.0.9.2\\bin\\Standard"
"Folder38"="C:\\Program Files\\CDC Software\\Smart Updater\\40\\Packages\\Scc\\4.0.1.58"
"Folder39"="C:\\Program Files (x86)\\CDC Software\\Pivotal CRM\\Applications\\Web Portal 6.0.11\\Assemblies"

Notice that the paths I’m specifying above might not work in your particular case, so be careful when importing this file into your registry. At least check that the versions you have are the correct ones and if not modify the file to match your particular versions. Try to import it several times if it doesn’t work at the first try.

A healthy development machine

Although all the environment variables are automatically created by either the component or module installation (I’ve seen cases when this doesn’t happen though), the configuration of the development machine to take into consideration the right variables, the configuration of the Toolkit references, etc. is a hard and long task.

Fortunately, there is help. Grupo Lanka has created a set of development tools. One of these tools is the Environment Check tool, which takes care of checking that a development machine is well configured with all the environment variables. The cool thing about this tool is that it also creates and fixes the environment variables. The tool is smart enough to figure out the version of the component/module that is installed and creates the appropriate variables and reference paths in the Toolkit pointing to the right path. If you install a new version of the product (which changes the paths), the tool can automatically update your environment to match the new paths. I highly recommend it since it can save you a lot of headaches. Here is a screenshot of the tool: