Get Started > Blackbaud CRM SDK Developer Environment Setup

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 that is supported by your version of the Blackbaud Infinity SDK

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

Article Link
Visual Studio 2008 http://msdn.microsoft.com/en-us/library/e2h7fzkw(v=vs.90)
Visual Studio 2010 http://msdn.microsoft.com/en-us/library/e2h7fzkw(v=vs.100).aspx
Visual Studio 2012 http://msdn.microsoft.com/en-us/library/dd831853(v=vs.110).aspx

Visual Studio 2013

 

http://msdn.microsoft.com/en-us/library/e2h7fzkw

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.

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 2008 > 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;
Article Link
Install SQL Server 2008 http://msdn.microsoft.com/en-us/library/ms143219(v=sql.100).aspx
Install SQL Server 2008 R2

http://msdn.microsoft.com/en-us/library/ms143219(v=sql.105).aspx or

https://www.blackbaud.com/files/support/infinityinstaller/infinity-installation.htm#installermaster/tkinstallsqlserver2008r2.htm

 

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 2008 > 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 Report Server Service 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 settings.

    1. INSTALL-2008 should be replaced with 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 server-side customization assemblies, and the bbappfx\vroot\browser\clientbin folder for client-side customization assemblies.

As a best practice, you should separate customization assembly files from standard assembly files so you can easily identify them. 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. Open the bbappfx\vroot\browser\clientbin folder and add a "custom" folder.

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

  4. Look for the following line that is commented out near towards the top of the file: <!--<probing privatePath="bin\custom" />-->.

  5. Un-comment this line and save the file: <probing privatePath="bin\custom" />.

The application now searches in bbappfx\vroot\bin\custom and bbappfx\vroot\browser\clientbin\custom for server-side and client-side customization 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 also match the version of Blackbaud CRM. For example, if you use Blackbaud CRM version 3.0, then install the 3.0 version of the SDK. 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. And starting with SDK version 3.0, 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: SDK versions 2.91 and higher have dependencies on .NET 4.0 and therefore will require Visual Studio 2010 or later. If you set references to any of Infinity SDK assemblies that have dependencies on the .NET Framework 4.0, we will need to utilize .NET Framework 4.0 and Visual Studio 2010.

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.. For example, to support versions 2.93 and 2.94 of Blackbaud CRM, a developer can have those two versions of CRM and SDK installed in two different folders.

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.

Starting with version 3.0, 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.

Step 13 -  Configure Insert GUID Macro

After you install the SDK, you receive an InsertGuid macro that you can configure within your Visual Studio development environment. The InsertGuid macro allows you generate and insert a new GUID valuees with a single keystroke or button press. This is an extremely useful macro because you will create a lot of new GUID values when you write your XML specs. More...

Note: Microsoft dropped macros after Visual Studio 10.