Blackbaud CRM SDK Developer Environment Setup

Overview

This guide is for third-party developers who work on Blackbaud CRM customizations. Developer machines must meet the installation requirements for Blackbaud CRM that are posted on the System Requirements page of the Blackbaud website.

Installation Instructions

Developers must install Internet Information Services (IIS), Visual Studio, SQL Server, Blackbaud CRM, Blackbaud CRM SDK, and SQL Server Reporting Services (SSRS) for reporting in the developer environment. To host CRM databases on local developer machines, developers must install SQL Server; otherwise, they must install SQL Server on separate development servers and install the SQL Server Management Studio client the developer machines. (These instructions assume a local install of SQL Server.)

Step 1 -  Install Internet Information Services (IIS)

Enable the Indexing Service and install Internet Information Services (IIS). Refer to the instructions specific to the developer environment's OS.

Windows Vista

1. Open Control Panel > Programs > Programs and Features.

2. Click Turn Windows features on or off.

3. Select Indexing Service.

4. Select and expand Internet Information Services.

5. Enable all features under Internet Information Services > World Wide Web Services.

6. Enable IIS 6 Management Compatibility and IIS Management Console under Internet Information Services > Web Management Tools.

Windows 2008 Server / Windows 7

1. Open Server Manager.

2. Right-click Roles and select Add Roles.

3. Add File Service and Web Service (IIS) Roles.

4. Ensure the following Web Service Role services are installed.

   1. Common HTTP Features (default sub options)

   2. Application Development (default sub option

   3. Health and Diagnostics (default sub options)

   4. Security - Check Windows Authentication

   5. Performance (default sub options)

   6. Management Tools (all sub options) (Ensure IIS 6 Management Compatibility is included) 

5. Ensure the following File Role Services are installed.

   1. File Server

   2. Window Server 2008 File Services (all sub options)

Windows XP / 2003 server

1. Open Control Panel > Add/Remove Programs.

2. Click Add/Remove Windows Components.

3. Select Indexing Service and Internet Information Services (IIS).

4. Install and register the latest ASP .NET.

5. Run the following command: %WINDIR%\Microsoft.NET\Framework\v2.0.50727\aspnet_regiis.exe /i.

Step 2 -  Install Developer Edition of Visual Studio

Install a developer edition of Visual Studio. The Blackbaud Infinity SDK supports professional editions and higher but does not support community editions. For Microsoft's guidance, refer to the table below.

Warning: Starting with Service Pack 33, the Infinity SDK only supports Visual Studio 2022 and later because of breaking changes in Visual Studio. Microsoft does not have a workaround, so you can't user older versions of Visual Studiowith Service Pack 33 or later. We strongly recommend upgrading to Visual Studio 2022 to continue using the most recent versions of Blackbaud CRM and the Infinity SDK.

Article	Link
Visual Studio 2022	https://visualstudio.microsoft.com/downloads/
Visual Studio 2019 (only supported in Service Pack 32 and earlier)	https://visualstudio.microsoft.com/vs/older-downloads//
Visual Studio 2017 (only supported in Service Pack 32 and earlier)	https://visualstudio.microsoft.com/vs/older-downloads//

Install Visual Studio in the default directory structure of <drive>:\Program Files (x86)\Microsoft Visual Studio\<year>\<version>. For example: C:\Program Files (x86)\Microsoft Visual Studio\2017\Enterprise. Note that item and project templates in these versions are handled on a user profile basis instead of being based on install location as in previous versions. Also, we changed how the SDK installer handles external tools for these versions, so if you configured other external tools, we recommend that you back up those settings before you install the SDK.

Note: For reporting and the data warehouse, the Data Storage and Processing workload in Visual Studio requires extensions to work as expected in Visual Studio 2022. For reporting, you must install Microsoft Reporting Services Projects 2022 and Microsoft RDLC Page Designer 2022. And for the data warehouse, you must install SQL Server Integration Services Projects 2022 and Microsoft Analysis Services Projects 2022. If you already have older versions of these extensions in place, they will no longer work with Visual Studio 2022.

Step 3 -  Install Microsoft SQL Server Enterprise

Install Microsoft SQL Server Enterprise on machines that host the Blackbaud CRM database and machines that host Reporting Services. SQL Server 2014 with the latest service pack is supported for Blackbaud CRM version 4.0, and SQL Server 2016 with the latest service pack is supported starting with Blackbaud CRM version 4.0 Service Pack 15 (hot fix 61).

The general install options are as follows:

1. Install a New SQL Server stand-alone installation

2. Select the following features.

   1. Database Engine Services

   2. Analysis Services

   3. Reporting Services

   4. Integration Services

   5. Business Intelligence Development Studio (BIDS)

   6. Both Management Tools

3. Select Default Instance if this is the only SQL Server version installed. Otherwise, create a named instance.

   Note: For the fewest conflicts, install as your default instance

4. Set the following Service Accounts (these settings in particular should NOT be used in Production).

   1. SQL Server Database Engine: NT AUTHORITY\SYSTEM

   2. SQL Server Analysis Engine: NT AUTHORITY\NETWORK SERVICE

   3. SQL Server Reporting Services: NT AUTHORITY\NETWORK SERVICE

   4. SQL Server Integration Services: NT AUTHORITY\NETWORK SERVICE

   5. SQL Server Agent: NT AUTHORITY\NETWORK SERVICE

5. Setup Collation

   1. In the same window as Service Accounts, click Collation tab.

   2. Click Customize button for Database Engine.

   3. Select Windows collation designator and sort order.

   4. Set Collation designator: Latin1_General.

   5. Check Accent-Sensitive.

6. SQL Server should be configured to allow both SQL Server and Windows authentication.

7. For Database and Analysis Account Provisioning, Click Add Current User

8. Select Install native mode for Reporting Services

9. Complete Installation

10. After Installation

    1. Open Start > All Programs > Microsoft SQL Server 2014 > Configuration Tools > SQL Server Configuration Manager.

    2. Select SQL Server Network Configuration.

    3. Select Protocols for MSSQLSERVER.

    4. Enable Named Pipes and TCP/IP connections.

    5. Restart SQL Server.

    6. Enable CLR.

    7. Open SQL Server Management Studio and execute the Enable CLR SQL snippet listed below.

       Exec sp_configure 'clr_enabled', '1'
       RECONFIGURE WITH OVERRIDE;
       EXEC sp_configure;

Step 4 -  Configure SQL Server Reporting Services (SSRS)

After you install SQL Server, you must configure Reporting Services using the following steps:

1. Open Control Panel > Administrative Tools > Configuration Tools > Services.

2. Ensure SQL Server Reporting Services (MSSQLSERVER) is present and started:

   

3. Open Start > All Programs > Microsoft SQL Server 2014 > Configuration Tools > SQL Server 2014 Reporting Services Configuration Manager.

4. Connect to the Reporting Services Instance.

   1. Server Name: <local_computer_name>

   2. Instance: MSSQLSERVER

5. Select Service Account from the sidebar menu. (Ensure Use built-in account is set to Network Service credentials.)

6. Select Database from the sidebar menu .

7. If no database is listed… (Otherwise skip step)

   1. Click Change Database.

   2. Select Create a new report server database.

   3. Server Name: local computer name .

   4. Authentication Type: Current User – Integrated Security

   5. Test the connection; troubleshoot any connections issues before continuing.

   6. Database Name: ReportServer

   7. Language: English

   8. Report Server Mode: Native Mode

   9. Credentials \ Authentication Type: Service Credentials

   10. Finish .

8. Verify your settings. "INSTALL-2008" in the screenshot should be your local computer name.

   

9. Select Web Service URL from the sidebar menu.

   1.  The virtual directory should be set to ReportServer.

      Note: For Windows XP the port may need to be set to 8080 to avoid conflicts with sites hosted by IIS on port 80. (See http://technet.microsoft.com/en-us/library/bb630449.aspx.)

   2. Do not configure SSL for now. (Disregard SSL settings in the screenshot below.)

   3. Click Apply Changes.

   

For Microsoft's guidance, refer to the following resources:

Article	Link
Reporting Services Configuration Manager	http://msdn.microsoft.com/en-us/library/ms156305.aspx

Step 5 -  Install Blackbaud CRM

The following steps outline the installation of Blackbaud CRM, including the necessary post-installation configurations.

Restore Blackbaud CRM Database

The Blackbaud CRM installer requires that a database be selected during installation. Therefore, prior to installing Blackbaud CRM, a Blackbaud CRM database must be restored in SQL Server. This database may be of sample data, or of the customer’s converted data; however, the version of the database must match the version of the installed Blackbaud CRM application. After the Blackbaud CRM is restored, the database encryption must be reset.

Refer to the table below for guidance on restoring a database in SQL Server, and resetting the database encryption.

Article	Link
Restore Blackbaud CRM Database in SQL Server	https://www.blackbaud.com/files/support/infinityinstaller/content/installermaster/tkrestorethenewdatabase.htm or http://msdn.microsoft.com/en-us/library/ms177429(v=sql.100).aspx
Reset Database Encryption	https://www.blackbaud.com/files/support/infinityinstaller/content/installermaster/coresetdatabaseencryption.htm
SQL Server and Database Encryption Keys (Database Engine)	http://technet.microsoft.com/en-us/library/bb964742.aspx

Install Blackbaud CRM

After the Blackbaud CRM database is restored and the encryption is reset, Blackbaud CRM may be installed using the Blackbaud Installer. When installing Blackbaud CRM, the user should elect to install the Blackbaud Core Components which installs the Infinity web application, which is used to access different areas and features of the program. The Core Components must be installed on a web server during new installations and upgrades.

Note: The Blackbaud CRM Installer may be downloaded from the Blackbaud.com web site. (Note: A password for the downloads page on Blackbaud.com is required. Only the downloads available to your organization appear. There may be multiple versions of Blackbaud CRM available.)

The Blackbaud CRM Installer is an executable file. When running the Installer, if your login does not run executables as an Administrator by default, right-click the executable and select Run as administrator.

After the Blackbaud CRM Installer is launched, you will be prompted to enter the unique client (site) ID you received from your Blackbaud account manager, and the email address associated with your account. The Blackbaud Installer uses these credentials to ensure the installation includes all features your organization purchased.

Instructions to install Blackbaud CRM core components may be found here.

Step 6 -  After You Install Blackbaud CRM

Check out the After You Install section within the installation instructions for items such as accessing the application, determining the version number and patch number, loading reports, adding application users and system roles, Active Directory Integration, Exchange Server Integration, and deploying the Data Warehouse.

Step 7 -  Set Up Customization Assembly Folders on the Blackbaud CRM Application Server

By default the Blackbaud CRM application looks within in the bbappfx\vroot\bin folder for its server-side assemblies. Your custom server-side assemblies should reside within the bbappfx\vroot\bin\custom folder.

As a best practice, you should separate customization assembly files from standard assembly files. You can set in the web.config file to prompt the application to look for folders named “custom” for customization assemblies. To enable this:

1. Open the bbappfx\vroot\bin folder in your installation directory and add a "custom" folder.

2. Go back to the bbappfx\vroot folder and open the web.config file.

3. Look for the following line that is commented out near the top of the file:.

4. Un-comment <!--<probing privatePath="bin\custom" />--> and save the file.

The application now searches in bbappfx\vroot\bin\custom for custom server-side assembly files.

Step 8 -  Add a Custom HTML Folder on the Blackbaud CRM Application Server

As a best practice, you should place HTML files that are used by features for user interface control layout in project subfolders within a \bbappfx\vroot\browser\htmlforms\custom folder in the installation directory. You should also place JavaScript files that provide user interface logic for features here. Add a "custom" folder to \bbappfx\vroot\browser\htmlforms add project subfolders as necessary.

1. On the application server, navigate to the \bbappfx\vroot\browser\htmlforms folder.

2. Add a "custom" folder to the \bbappfx\vroot\browser\htmlforms folder.

Customization projects that utilize HTML files for user interface layout and JavaScript for advanced user interface functionality should have subfolders for within the \bbappfx\vroot\browser\htmlforms\custom folder. For example, the UI Model project for the food bank code sample is named Blackbaud.CustomFx.FoodBank.UIModel. Therefore, a directory named blackbaud.customfx.foodbank has been added to the \bbappfx\vroot\browser\htmlforms\custom folder for the project. As a result, the .html and .js files for the food bank project should reside within the \bbappfx\vroot\browser\htmlforms\custom\blackbaud.customfx.foodbank folder.

Step 9 -  Update Web.Config Connection Strings

Blackbaud CRM allows a single application installation to connect to multiple databases. This provide users the option to access different databases from the drop-down menu on the ClickOnce Smart Client login screen:

And in the Web Shell user interface, you can specify different databases in the URL:

To Set Up a Single Database Connection String:

To associate a single database to the Blackbaud CRM install:

1. Open the web.config file in the \bbappfx\vroot folder.

2. In the <appSettings> tag look for a tag with the key “REDBList”, for example: <add key="REDBList" value="BBInfinity " />

3. Each entry in the “value” attribute corresponds to an entry in the <connectionStrings> tag found further down in the web.config file. For example, the above entry has this corresponding connection string:

   <connectionStrings>
   	<add name="BBInfinity" connectionString="Server=(local);database=BBInfinity;integrated security=sspi" />
   </connectionStrings>

To Set Up Multiple Databases:

To associate multiple databases to a single Blackbaud CRM installation:

1. Multiple entries can be set in the in the “value” attribute in the REDBList application setting, separated by a semicolon:<add key="REDBList" value="BBInfinity;Config" />

2. Each value will correspond to an entry in the <connectionStrings> tag found further down in the web.config file. For example, the above entry has this corresponding connection strings:

   <connectionStrings>
   	<add name="BBInfinity" connectionString="Server=(local);database=BBInfinity;integrated security=sspi" />
   	<add name="Config" connectionString="Server=(local);database=BBInfinity_Config;integrated security=sspi" />
   </connectionStrings>

Step 10 -  Reduce Spec Cache Timeout and Recycling the Application Pool

The Infinity platform employs caching at multiple levels to reduce spec retrieval times (since specs are not expected to change very often). However, during spec development, the XML will be reloaded often as changes are made and assessed. In order to avoid pulling cached copies of the spec after loading changes, the following changes should be made in the web.config file:

1. Open the web.config file in the “bbappfx\vroot” folder.

2. In the <appSettings> tag look for a tag with the key “MAX_METADATA_CACHE_SECONDS” that may be commented out, for example: <!--<add key="MAX_METADATA_CACHE_SECONDS" value="10" />-->

3. Un-comment this line, set the value to “0”, and save the file:<add key="MAX_METADATA_CACHE_SECONDS" value="0" />

4. Each Infinity application will be assigned to a specific Application Pool. Using the IIS Manager (INETMGR.exe), a developer can recycle the appropriate application pool to clear out the web cache on their development environment. Typically this is the DefaultAppPool unless specified otherwise during the install of the core components. In addition to recycling the application pool from the IIS Manager user interface, you can also recycle from Visual Studio by setting up some syntax as an external tool or adding the command syntax in the post-build event. For more details, see Recycle an Application Pool Using External Tools in Visual Studio.

   

Step 11 -  Install Blackbaud Infinity SDK

Each developer should install the Blackbaud Infinity SDK in order to build custom features. The Blackbaud Infinity SDK can be downloaded from the Downloads page of the Blackbaud website, and installation instructions are available at Blackbaud Enterprise SDK Installer.

Before you install the SDK, you must install a program on the Infinity platform such as Blackbaud CRM. If you don't have an Infinity program and database in place, the SDK installation will fail. The version of Blackbaud Infinity SDK must match the version of Blackbaud CRM. As part of the installation process, the Blackbaud Infinity SDK installation wizard associates the SDK with the SQL Server instance and database for your Infinity programs. The installation wizard also allows you to specify a default spec author for catalog items, a default prefix for the database artifacts, and default folders for creating projects and building projects.

Note: Starting with Blackbaud CRM 4.0 service pack 21, we recommend that you back up settings for external tools before you install the SDK because we changed how the SDK installer handles external tools for Visual Studio 2017 and Visual Studio 2019.

Switching Between Versions of Blackbaud Infinity SDK

A developer may have more than one version of Blackbaud CRM and SDK installed in different folders on the file system.

On the developer’s machine, use SetCurrentSDK.bat within the SDK folder to switch between the different SDK versions. The batch file is included with the SDK and may be found within the SDK folder. Navigate to the folder containing the version of the SDK you wish to switch to, and run the SetCurrentSDK.bat file as Administrator.

Step 12 -  Configure LoadSpec

LoadSpec is a utility to add Infinity catalog specs into an installation. It is installed in the Visual Studio Tools menu as an external tool when you install Blackbaud Infinity SDK.

UnloadSpec is a utility that removes Infinity catalog specs. It is also installed into the Visual Studio Tools menu when you install Blackbaud Infinity SDK.

For information about how to configure LoadSpec or UnloadSpec, see LoadSpec. If you use Visual Studio 2017 and Visual Studio 2019, we recommend that you back up settings for external tools before you install the SDK because we changed how the SDK installer handles external tools for these versions.