Sage CRM V7.1 Developer Guide

Chapter 2CRM Application Server. The CRM Application Server comprises a number of subsystems, whichwork together to coordinate the delivery of information and functionality to clients. These includeobjects for checking user security, maintaining user persistence, getting information from thedatabase, generating Web pages from data, and processing business rules and logic. This guidedescribes each of these objects and outlines their properties and methods.Database. CRM has native support for Microsoft SQL Server and Oracle. The database is used tostore corporate data and metadata, which define the system customization, security, and businessrules.E-mail Server. The E-mail Management functionality enables the Application Server to be integratedwith the E-mail server to automate the sending of e-mails and SMS messages as part of the CRMimplementation. The CRMEmail object and the CRMMsgHandler object and it's child objects areused to customize the E-mail Management functionality. Note that the CRMMessageBlock objectcan also be used to send messages in SMS and e-mail format.As CRM is designed for a multi-tier environment, you can have all of the above components on thesame or separate machines.Note : IIS and the CRM DLL have to be on the same server, so as a general rule IIS andCRM are installed on the same server. We would recommend that the database isinstalled be on a dedicated database server.DLL. The CRM DLL (Dynamic Link Library) runs on a Windows Server with Microsoft InternetInformation Server (IIS) Web Server software. The IIS Web Server communicates with CRM throughthe CRM DLL and Internet Server Application Programming Interface (ISAPI) technologies.Apache Tomcat Redirector. The redirector in v7.1 is an ASP.NET Reverse Proxy, which is a 32bit/64-bit ASP.NET web application configured in standard Apache format. This ASP.NET rewriteruses the HTTP protocol instead of binary socket and can be accessed directly in a browser, so youcan easily check whether Tomcat is working. Please refer to the Installation and Upgrade Guide andthe latest articles on the Sage CRM Ecosystem for more information.Extensibility ArchitectureThe Extensibility Module ('EM') provides users with a range of powerful functions that allow them tocustomize and extend the existing CRM product.These functions are made available through the CRM ActiveX object, which is made up of a numberof CRM methods and properties. The CRM object components have a variety of functions, whichrender HTML and display Screen and List objects-previously defined in the CRM system itself.There are also a number of database connectivity options available. These include searching,inserting, updating, and deleting data to and from CRM data, as well as data from external tables anddatabases.2-2 Sage CRM

Chapter 2: OverviewExtensibility ArchitectureYou can establish if the Extensibility Module is present in your CRM installation asfollows: Select Administration Customization Company.If you have the Extensibility Module, you will see Blocks and TableScripts tabs:.NET ArchitectureAs the core of the Sage CRM solution is represented by an ActiveX component, Sage has leveragedMicrosoft’s Interop technology to expose this existing COM component to managed code (that iscode executed by Microsoft's .NET Framework Common Language Runtime).The process of exposing COM components to the .NET Framework can be challenging, involvingsteps such as converting the coclasses and interfaces contained in a COM type library to metadataand deploying Interop applications as strong-named, signed assemblies in the global assemblycache.The Sage CRM SDK for .NET handles these low-level implementation details by providing aredistributable package that installs the .NET component onto your system and makes it readilyavailable within the Visual Studio environment.The diagram below shows this architecture.Developer Guide 2-3

Chapter 2.NET Architecture1. CustomDotNetDll action calls Application extension.2. CustomDotNetDll action uses COM interop to trigger behaviour in CRM .NET Component.l Passes CRM Application Extension DLL name and session information.lCalls CRM Application Extension.3. CRM Application Extension processes data and generates and returns HTML.The Sage CRM .NET API conforms to the .NET 2.0 Framework. It provides a type library thatexposes the Sage CRM objects, properties, and methods. Through its core libraries the Sage CRM.NET Component manages both data access and web interface generation. Projects developedusing the Sage CRM .NET Component will be compiled into a dll and called directly from within SageCRM. By using Sage CRM meta data Application Extensions constructed using the Sage CRM.NET API will look, feel and perform exactly like core system pages.Reference to the Sage CRM .NET component from within ASP.NET projects is notsupported.Any programming language that conforms with the .NET 2.0 Framework can be used for thedevelopment of Sage CRM Application Extensions (e.g. J#, C# VB.NET etc).NET vs Classic ASPBefore the release of Sage .NET SDK, the main method for developers who wished to add custompages to the CRM environment was through the creation of ASP pages. As these pages were codedin simple text editors—typically Notepad or WordPad—developers could not use features offered byIDEs, such as IntelliSense (providing drop-down lists of available objects, properties, and methods),syntax checking, and debugging tools. The absence of IntelliSense, in particular, usually requireddevelopers accessing functionality provided by the Sage CRM API to refer repeatedly to the relevantdocumentation.In addition, the absence of meaningful syntax checking and debugging tools in text editors meant thatdevelopers could not gauge the correctness of their ASP coding until the page was upload to the Sage2-4 Sage CRM

Chapter 2: OverviewCRM environment and running in the context of new tab. Developers reload pages in the Sage CRM’sCustom Pages folder to check whether their ASP code is working as intended.The simplicity of the ASP/Sage CRM API/Text Editor combination makes it appropriate to solutionsthat require simple coding implementations and rapid deployment. However, given that codingseparate ASP pages is not conducive to best programming practice (specifically, OOP principles andassociated practices, such as refactoring) and that creating multi-file projects can demand moreadvanced project tools, developers should appreciate a more sophisticated solution for certaincustomization tasks.By allowing developers to access the Sage CRM through the .NET framework, several of the issuesassociated with earlier customization solutions are comprehensively addressed.Instead of coding in a basic text editor, developers can now use the suite of features provided byMicrosoft’s Visual Studio. With the Sage CRM .NET component properly referenced by theapplication, Visual Studio treats objects from the Sage CRM API in the same way as any otherinitialized C# object. This means when, for example, you are using a CRM object and are calling oneof its methods, the IntelliSense prompts you with a list of the object’s properties and methods whenyou type the “.” operator after the object name.Also, rather than coding in a scripting language that initializes and uses both ASP and Sage CRM APIobjects, the .NET framework enables developers to write in C# or Visual Basic.NET, highly objectoriented languages that can draw on the resources of .NET’s class library.In addition, whereas the source code in ASP pages can be accessed by users selecting the View–Source option from the browser menu, .NET applications are compiled into binary DLLs beforedeployment. Preventing access to source code means improved security and better protection ofintellectual property.SecurityCRM is modelled on an n-tier architecture. Each tier includes a number of security mechanisms.Application Level SecurityEvery user is assigned a valid username and password. The only person allowed to add or removeusers is the System Administrator. Within the system, each user can be assigned different levels ofaccess security depending on their job role. When IIS uses SSL encryption, the system is aware ofthis, and when the client attaches any documents to a form in the system, it sends it through theencrypted sessions.lUser Authentication/Password Setup. A user requires a Logon ID and password to accessthe system. The user's password is encrypted both within the system and in the database formaximum security.lTab and Team Restrictions. Access to individual tabs within CRM can be restricted by theSystem Administrator, as can the level of access that each user is allocated. The SystemAdministrator can also assign users to teams, which further categorizes and restricts levels ofaccess to individual tabs.lSecurity Profiles and Territories. The System Administrator can manage security accessrights across the organization by setting up Territory Profiles and, if required, securityTerritories. A Profile is a way of grouping users together when defining access rights (View,Update, Insert, Delete). A Territory is a way of further dividing user rights by location or othercriteria. For example, you may want users in the Europe territory to view all Opportunitieswithin the USA territory but not to be able to update them. Complex inter-territory securityrights and exception handling are also catered for using Territory Policies. Profiles andTerritories are set up from Administration Users Security, please refer to the SystemAdministrator Guide for more information.Server Level SecurityYou can use all three or a combination of the following methods to secure the CRM server:Developer Guide 2-5

Chapter 2lNT Challenge/Response. This allows access to clients with a valid domain login.lSSL Encryption. This secures your data sessions with client users.lA Firewall. This restricts unauthorized access from outside the network and allow onlyauthorized users through.Database Level SecurityCRM users do not have direct access to the database. The CRM DLL accesses the database byusing a predefined login. When a user requests data, the CRM DLL connects to the database usingMicrosoft Data Access Components (MDAC) and retrieves the required data. For extra security, theCRM DLL can be configured to access the database using a login with limited access.Customization OverviewSage CRM can be customized in a number of different ways:lBy development of custom ASP pages which can perform a wide variety of functions includingfor example displaying data entry screens or search and list pages.lBy using the system interface to add fields, tables, tabs etc (see table below).lThrough use of the .NET SDK.Extending CRM with Custom ASP PagesThe ability to add a custom ASP page to CRM and display that page on a user-defined tab allowsdevelopers to extend and modify system functionality. As well as allowing developers to leveragetheir expertise in technologies such as Active Server Pages (ASP), JavaScript, and W3C'sDocument Object Model (DOM), the Extensibility Module (EM) provides an extensive library ofexisting functionality represented by the classes, methods, and properties provided by the CRMBlock architecture.The Block architecture serves as a highly accessible and flexible SDK (Software Development Kit)by enabling the developer to use the CRM Object, which is initialized by standard CRM include filesreferenced at the top of a custom file. As well as providing a range of useful functions and methodsitself, the CRM Object allows you in turn to initialize further blocks that build up the screen interface,generate lists, manipulate database records, and modify scripts.As CRM blocks reside on the install server, code using the CRM SDK typically also has to run on theserver before the compiled page is dispatched to the client. ASP is the technology of choice forserver-side coding, as it is supported by Internet Information Services (IIS) and provides six built-inobjects that ease the creation of dynamic web pages.However, after the page has been downloaded from the server and displayed within the CRMsystem, it is possible to handle data and respond to user-generated events using client-sideJavaScript and the DOM.Server-side and client-side scripts can coexist in the same ASP file, with each approach playing tothe strengths of that particular technology. Server-side ASP code can be used to draw on the prebuiltfunctionality of the CRM Block architecture. In contrast, client-side JavaScript offers immediateresponses to user actions and enables you to access the DOM to navigate the screen interface.2-6 Sage CRM

Chapter 2: OverviewOverview of Customizable AreasAside from integrating ASP pages into CRM, you can also customize the following areas by using thesystem interface to enter scripts and change settings:Customizable Without EMAreaAdditionalCustomization with EMFieldsCreate new fields and customize existing ones.ScreensCustomize existing screens that are in the CRMdatabase. Add and remove fields that werecreated in the system.Add new screens.ListsCustomize existing lists that are in the CRMdatabase.Add new lists.TabsAdd new tabs to tab groups that are in the CRMdatabase. Customize main menu buttons.Add new tab groups.Link tabs to customfiles or URLs.Link tabs to runblockand runtabgroupfunctionality.ViewsAdd new views. Change some existing views.BlocksAdd Blocks.TableScriptsAdd Table and EntityScripts.Tables andDatabases*Connect to a newtable.Connect to a newdatabase.Create a new table.ButtonGroups*ComponentManager**Add new buttongroups.Upload a component.Record and scriptcomponents.* Tables And Databases and Button Groups are customized from Administration AdvancedCustomization.** Component Manager is accessed from Administration Customization.Database OverviewCRM EntitiesIn Sage CRM, an "Entity" is a representation of a real world entity such as a Company, a Person, or aSales Opportunity. The entity may have relationships with other Entities. For example, a Companycan have many People working for it. Each of these Entities may then have other entities inDeveloper Guide 2-7

Chapter 2relationships with them, for example People can have Communications and Sales Opportunitiesassociated with them.CRM entities are made up of information from several different tables linked in a logical way. Forexample, the Company entity is made up of information from the Company, Address, Phone, andPerson tables.CRM includes the following primary ationlLeadslQuoteslOrdersUnlike database entities, CRM entities are several tables linked together in a logicalbusiness grouping.MetadataIn CRM, Metadata encompasses all of the information that is required to make sense of the storedbusiness data. For example, there are metadata tables that contain field captions, or convert codevalues from drop-down fields into meaningful information.The system database contains CRM metadata tables. These are prefixed with the word 'custom'.Using SQL and TriggersYou can use the CRM Query object's SQL method to include SQL statements in an ASP page.You can also use SQL conditional clauses within the system in Administration Customization Entity Tabs. For more information please refer to the System Administrator Guide.CRM also includes Table and Entity level scripting functionality that you can include as an alternativeto SQL triggers.2-8 Sage CRM

Chapter 3: Getting StartedIn this chapter you will learn how to:lBuild an ASP page.lIntegrate an ASP page into CRM.lCreate custom queries.lUnderstand "Context" and the GetContextInfo method.lGet an overview of client-side scripting with JavaScript and DOM.lAccess user information.lEnter script in the CRM interface.lGet an overview of field-level scripting.lGet an overview of table-level scripting.Building an ASP PageSage CRM ASP pages leverage the properties and methods of the CRM object to connect to thesystem database and produce formatted output to the web browser. Standard ASP scriptingconventions are observed.To illustrate the creation of a simple ASP page, we will create a custom search page which will allowthe user to search contacts in the CRM database (the Person Entity) and display the results in a list.The first step in creating a page is to use an include statement to ensure that the CRM object isinstantiated: !-- #include file "sagecrm.js"-- Note that this Developer Help assumes that the CRM object will be instantiated as"CRM". In some older versions of the include file, the object is instantiated as "CRM"' or"eWare". If you are using an older version, simply use "eWare" when referring to theobject, or modify the include file to set: CRM eWare;Aside from instantiating and initializing the CRM Object, the include file also:lReferences the Sage CRM CSS StylesheetlDefines constantslChecks for errorsThe include file referenced in your file depends on the language you're scripting in:SAGECRM.JS - referenced in JavaScript-based ASP pages. This file sets the defaultlanguage to JavaScript.SAGECRMNOLANG.JS - this file does not set the default language.SAGECRM.VBS - referenced in Visual Basic-based ASP pages. This sets the defaultlanguage to VB Script.eWare.JS - for backward compatibility with pre 5.6 versions of CRM.ACCPACCRM.JS - for backward compatibility with pre 7.0 versions of CRM.ACCPACCRMNOLANG.JS - for backward compatibility with pre 7.0 versions of CRM.ACCPACCRM.VBS - for backward compatibility with pre 7.0 versions of CRM.Developer Guide 3-1

Chapter 3After the include file, you must open the ASP delimiters % % to tell the ISAPI.DLL that thecontained ASP code will execute on the server, and then call the CRM object methods required foryour page.In the example below, we call the CRM object's GetBlock method to initialize one of the child blocksthat implement core CRM functionality. This method is likely to feature at the start of most of yo

Sage.CRM.WebObjectNamespace 11-7 Sage.CRM.ControlsNamespace 11-7 DeveloperGuide Contents-ix. Contents Sage.CRM.DataNamespace 11-7 Sage.CRM.UtilsNamespace 11-7 Sage.CRM.BlocksNamespace 11-8 Sage.CRM.HTMLNamespace 11-8 Sage.CRM.UINamespace 11-8 Installingthe.NETSDK 11-8