v7.1 Developer Guide © Copyright 2011 Sage Technologies Limited, publisher of this work. All rights reserved. No part of this documentation may be copied, photocopied, reproduced, translated, microfilmed, or otherwise duplicated on any medium without prior written consent of Sage Technologies Limited. Use of the software programs described herein and this documentation is subject to the End User Licence Agreement enclosed in the software package, or accepted during system sign-up. Sage, and the Sage logo are registered trademarks or trademarks of The Sage Group PLC. All other marks are trademarks or registered trademarks of their respective owners. Contents Chapter 1: Introduction 1-1 Chapter 2: Overview 2-1 Web Architecture 2-1 Extensibility Architecture 2-2 .NET Architecture 2-3 .NET vs Classic ASP 2-4 Security 2-5 Application Level Security 2-5 Server Level Security 2-5 Database Level Security 2-6 Customization Overview 2-6 Extending CRM with Custom ASP Pages 2-6 Overview of Customizable Areas 2-7 Database Overview 2-7 CRM Entities 2-7 Metadata 2-8 Using SQL and Triggers 2-8 Chapter 3: Getting Started 3-1 Building an ASP Page 3-1 Integrating the ASP Page Into CRM 3-4 Creating Custom Queries 3-5 Understanding "Context" and the GetContextInfo Method 3-7 Client-Side Scripting with JavaScript and DOM 3-7 Accessing User Information 3-9 Scripting in the CRM Interface 3-10 Field Level Scripting 3-10 Table Level Scripting 3-12 Chapter 4: Customization Basics 4-1 CRM Blocks Overview 4-1 Block Naming and Custom Blocks 4-1 Adding Help to Custom Pages 4-3 Developer Guide Contents – i Contents Step 1: Create a Custom Help Page 4-3 Step 2: Add a Help Button to your Custom Page 4-3 Limitations 4-3 Lists 4-3 How to Create a List 4-3 How to Display a List 4-4 Display a List Using an ASP Page 4-4 Display a List using Runblock and the List Name 4-5 Screens 4-5 How to Create a Screen 4-5 How to Display a Screen 4-6 Display a Screen Using Runblock and Screen Name 4-7 Display a screen using Runblock with a Custom Block 4-7 Display a screen with an ASP page 4-7 Buttons 4-8 Creating Button Groups 4-8 Adding Buttons to Button Groups 4-8 Viewing Button Groups 4-9 Restricting Access to Button Groups 4-9 CRM Classic Dashboard 4-9 Customizing The Classic Dashboard 4-9 Adding a List Block To The Classic Dashboard 4-11 Adding a Content Block To The Classic Dashboard 4-11 Adding a Chart To The Classic Dashboard 4-12 CRM Interactive Dashboard 4-13 Customizing the Interactive Dashboard 4-13 Example: Adding a Content Block to the Interactive Dashboard using the Contents field 4- 13 Example: Adding a Content Block To The Interactive Dashboard based on an ASP page 4- 15 Adding a Third-party gadget to the Interactive Dashboard 4-16 scrmPublishEvent 4-17 scrmRegisterEvent 4-17 Contents – ii Sage CRM Contents scrmGetGadgetProperty 4-17 scrmSetGadgetProperty 4-18 scrmSaveGadgetProperties 4-18 scrmGetSageCRMOwner 4-18 Blocks 4-18 Creating a New Block 4-18 Customizing a Block 4-19 Displaying a Block 4-19 System Menus 4-20 Modifying System Menus 4-20 Creating a Main Menu Button 4-20 Creating an Admin Menu Button 4-21 Creating an External Link on the Main Menu 4-21 Tabs 4-24 Creating a New Tab Group 4-24 Editing the Main Menu Tab Group 4-25 Adding a Tab that Links to an ASP Page 4-25 Restricting Access to the Tab 4-26 Tab Actions 4-27 Chapter 5: Database Customization 5-1 Introduction to Database Customization 5-1 Creating a New Table 5-1 Creating a New Database Connection 5-3 Creating a New Table Connection 5-4 Example: Creating a Tab to Display a List of Invoices 5-4 Example: Displaying an Individual Invoice from a List 5-6 Example: Adding New Data Entry and Maintenance Screens 5-7 Table and Entity Scripts and Functions 5-12 Creating a Table Level Script 5-14 Detached Table Level Scripts 5-14 Creating an Entity Level Script 5-14 Example: UpdateRecord in an Entity Level Script 5-15 Example: InsertRecord 5-16 Developer Guide Contents – iii Contents Example: PostInsertRecord 5-16 Example: UpdateRecord 5-16 Example: DeleteRecord 5-17 Advanced Customization Wizard 5-17 Creating a New Main Entity 5-17 Advanced Customization Wizard Parameters 5-18 Enabling Company and Person Deduplication 5-21 Custom Files and Metadata 5-22 Making Custom Entities Available for Reassignment 5-24 Customizing a New Main Entity 5-25 Advanced Customization Wizard Example 5-26 Chapter 6: Component Manager 6-1 Introduction to Component Manager 6-1 Recording 6-1 Scripting 6-1 Installing 6-1 What Types of Customizations can be Recorded? 6-1 Recording Customizations 6-2 The Component Details Screen 6-2 Starting Component Manager 6-3 Stopping Component Manager 6-3 Adding Customizations to an Existing Component 6-3 Changing the Current Component 6-4 Scripting Customizations 6-4 Previewing Changes 6-4 Scripting Changes 6-4 Scripting Multi-Stage Customizations 6-5 Scripting Workflows 6-6 Saving a Component 6-7 Installing a Component 6-7 Component Manager Log File 6-8 Advanced Component Options 6-9 How to Generate a Component Script using Advanced Component Options 6-9 Contents – iv Sage CRM Contents How to Create a New Component Using Advanced Component Options 6-10 Modifying Component Manager Scripts 6-11 Error Handling 6-12 Referential Integrity 6-12 Script Parameters 6-13 Phone and E-mail Changes 6-14 Component Manager Methods 6-14 Component Manager Scripting Examples 6-36 Chapter 7: Graphics and Charts 7-1 Introduction 7-1 Charts Overview 7-1 Fusions Charts System Parameters 7-2 Pie Chart Only Effects 7-2 Special Effects For Charts 7-3 Using External Data for Charts 7-3 Chart Examples 7-4 Example: Adding a New Chart 7-4 Example: Organization Chart 7-6 Graphics Overview 7-8 Graphics Formats 7-8 Graphics Performance Tips 7-9 External Images 7-10 Graphics Examples 7-10 Example: Adding a New Graphic 7-10 Example: Pipeline 7-11 Graphic Effects Basics 7-14 Change Image Color 7-14 Clear An Image 7-14 Display Errors 7-14 Drawing Functions 7-14 Merging 7-16 Special Effects 7-17 Animation 7-17 Developer Guide Contents – v Contents Adding Frames 7-17 Delay 7-17 Loops 7-17 ASP Example 7-18 Chapter 8: ASP Object Reference 8-1 Introduction to the ASP Object Reference 8-2 Quick Reference Table 8-3 Examples 8-7 Sample CRMGridColBlock ASP page 8-7 Sample CRMListBlock ASP page 8-7 Using the New Workflow Properties in an ASP page 8-8 AddressList Object 8-9 Methods 8-9 Properties 8-10 Attachment Object 8-10 Methods 8-10 Properties 8-11 AttachmentList Object 8-11 Properties 8-11 Email Object 8-12 Methods 8-12 Properties 8-13 MailAddress Object 8-15 Properties 8-15 MsgHandler Object 8-15 Methods 8-16 Properties 8-16 CRM Object 8-17 Methods 8-17 Properties 8-22 CRMBase Object 8-22 Methods 8-23 Properties 8-27 Contents – vi Sage CRM Contents CRMBlock Object 8-27 Methods 8-28 Properties 8-29 CRMChartGraphicBlock Object 8-33 Methods 8-33 Properties 8-35 CRMContainerBlock Object 8-36 Methods 8-37 Properties 8-39 CRMContentBlock Object 8-43 Properties 8-43 CRMEntryBlock Object 8-43 Methods 8-44 Properties 8-44 CRMEntryGroupBlock Object 8-55 Methods 8-56 Properties 8-57 CRMFileBlock Object 8-57 Properties 8-58 CRMGraphicBlock Object 8-59 Methods 8-59 Properties 8-68 CRMGridColBlock Object 8-69 Properties 8-70 CRMListBlock Object 8-72 Methods 8-73 Properties 8-75 CRMMarqueeBlock Object 8-77 Properties 8-77 CRMMessageBlock Object 8-79 Properties 8-80 CRMOrgGraphicBlock Object 8-82 Methods 8-82 Developer Guide Contents – vii Contents CRMPipelineGraphicBlock Object 8-82 Methods 8-83 Properties 8-85 CRMQuery Object 8-85 Methods 8-86 Properties 8-87 CRMRecord Object 8-89 Methods 8-89 Properties 8-92 CRMSelfService Object 8-95 Self Service Method and Property Differences 8-95 Note on Instantiating the CRMSelfService Object 8-96 Methods 8-97 Properties 8-98 CRMTargetListField Object 8-99 Properties 8-99 CRMTargetLists Object 8-99 Methods 8-100 Properties 8-100 Example: Creating and Saving a Target List 8-102 Example: Retrieving a Target List 8-103 CRMTargetListFields Object 8-103 Methods 8-104 Properties 8-104 Chapter 9: Web Services 9-1 Introduction to Web Services 9-1 Setting Up CRM Web Services 9-2 Objects and Functions Overview 9-5 List of Web Services Functions 9-5 List of Web Services Objects 9-7 The CRM RecordType Object 9-10 Selection Fields in Web Services 9-11 Introduction to Web Services Examples 9-13 Contents – viii Sage CRM Contents Sample SOAP Requests 9-15 Chapter 10: SData Read-only 10-1 Introduction to SData 10-1 Overview of SData within Sage CRM 10-1 SData Prerequisites 10-2 Switching on SData 10-2 Constructing SData URLs 10-3 SData URL Examples 10-3 SData Authentication 10-3 Chapter 11: .NET 11-1 Extending Sage CRM With .NET 11-1 Sage CRM .NET API and ASP.NET 11-2 Programming Languages 11-2 Component Manager 11-2 Connection Pool 11-2 Using .NET Application Extensions 11-2 The CustomDotNet Folder 11-2 Changing the Build Location of the DLL 11-2 Copying the DLL file to the CustomDotNet Folder 11-3 Calling the .NET Application Extension 11-3 Calling the .NET Application Extension From Tabs/Menus 11-3 Calling the .NET Application Extension From List Block Hyperlinks 11-4 Calling the .NET Application Extension From Within Another Custom .NET Application 11- 4 Calling the .NET Application Extension From ASP Pages 11-4 .NET API Debugging 11-4 Method 1: Change IIS Security 11-5 Method 2: Use COM+ 11-5 Troubleshooting 11-6 .NET API Class Library Documentation 11-6 Sage Namespace 11-6 Sage.CRM.WebObject Namespace 11-7 Sage.CRM.Controls Namespace 11-7 Developer Guide Contents – ix Contents Sage.CRM.Data Namespace 11-7 Sage.CRM.Utils Namespace 11-7 Sage.CRM.Blocks Namespace 11-8 Sage.CRM.HTML Namespace 11-8 Sage.CRM.UI Namespace 11-8 Installing the .NET SDK 11-8 Pre-Installation Checklist 11-8 Installing the SDK and .NET Templates 11-9 Installation Troubleshooting 11-9 Manually registering the DLL 11-9 Manual Installation of the CRM Visual Studio .NET Templates 11-10 Uninstalling the .NET SDK 11-10 .NET Examples 11-10 Creating a Simple Sage CRM Interface 11-11 Creating a More Complex CRM Interface 11-12 Creating a Project Based on a Sage CRM Template 11-16 CRM Basic Template 11-16 CRM Entity Template 11-17 Index i Contents – x Sage CRM Chapter 1: Introduction This Developer Guide is for CRM Implementers and Programmers.